# Kenward payable API (x402)

> Pay-per-call settlement data for agent marketplaces. No account, no API key,
> no subscription, no human. Payment settles in USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) on Base
> (`eip155:8453`) via x402.

## Bahasa Indonesia / Indonesian
> Data penyelesaian untuk pasar kerja agen, bayar per panggilan.
> Tanpa akun, tanpa API key, tanpa langganan. Pembayaran otomatis via x402
> (USDC di jaringan Base). Cocok untuk agen otonom yang perlu memeriksa:
> apakah uang benar-benar berpindah di sebuah pasar, dan apakah poster/job
> tertentu pernah membayar.
> Endpoint gratis untuk melihat kartu dataset: GET /v1/preview?market=dealwork

## Free
- GET /v1/preview?market=<market> — dataset card: as_of, coverage, counted entities, and the schema of the paid answer (no verdict).
- GET /health — liveness (holds_keys=false).
- GET /openapi.json — full contract. GET /.well-known/x402 — offer. GET /llms.txt — this file.

## Paid (x402)
- GET /v1/buyer?job_id, market — 0.02 USD per call (x402, base, USDC) — Per-buyer payment record: has this poster ever paid anyone?
- GET /v1/payability?market — 0.025 USD per call (x402, base, USDC) — Market queue analytics + settlement verdict: how crowded is this marketplace (bids per job, measured) and has money ever actually moved here (payer share, buyer behaviour, freshness)? For agents deciding where to spend effort.
- GET /v1/pdf?url, urls — 0.02 USD per call (x402, base, USDC) — PDF extraction to text: give a PDF URL, get the text layer page by page (reports, filings, invoices, papers) - ready for indexing or summarising. Batch mode: repeat urls= up to 5 times in one call.
- GET /v1/readable?url, urls — 0.005 USD per call (x402, base, USDC) — URL to clean LLM-ready text (readable extraction): fetched server-side, boilerplate/ads/nav stripped, returned as title + headings/paragraphs/lists plus the plain text - for RAG ingestion, LLM prompts and indexing. Batch mode: repeat urls= up to 5 times in one call.
- GET /v1/transcript?url — 0.01 USD per call (x402, base, USDC) — Video transcript with timestamps (YouTube): the spoken content as machine-readable text, segment by segment - for summarising, indexing, subtitling and RAG ingestion.
- GET /v1/uptime?url — 0.025 USD per call (x402, base, USDC) — Endpoint uptime/latency attestation: is this service reachable, and how fast?
- GET /v1/venue?venue — 0.025 USD per call (x402, base, USDC) — Agent-venue status: is this marketplace paying today?

## Markets covered
- clawtasks — agent-to-agent bounty marketplace (measured: onchain)
- dealwork — agent job marketplace (measured: snapshot)
Ask for another market: the free dataset card at /v1/preview?market=<market> says whether
it is measurable. Unmeasured markets answer UNKNOWN — never a guess.

## How to pay (machine, no human)
1. GET a paid endpoint without payment -> HTTP 402 with the x402 challenge
   (`accepts[]`: exact scheme, network `eip155:8453`, asset `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`,
   payTo `0x351eb3679f817ea7de8baeCbaF3Bd5120200eadc`, validity window 60s).
2. Sign the EIP-3009 authorization (EIP-712, USDC domain) and POST/GET again with the
   payload in the PAYMENT-SIGNATURE header. The facilitator verifies and settles on-chain.
3. Trade-off to expect: the endpoint never invents values; every answer carries
   `as_of`, `coverage_pct` and a `boundary` statement. If a market was not measured,
   the answer is UNKNOWN — not a guess.

## Launch price (honest discount, published)
- Verdict calls cost **0.025 USD** (list price 0.05, i.e.
  50% off) for the **the first 100 unique paying wallets (excluding the operator's own wallet)**.
- How it is counted: on-chain USDC transfers to the payee address — you can verify the progress at the payee address.
- After that: the operator sets the fixed price (0.025 or 0.05 USD) — not changed automatically. The price never changes retroactively for a payment already made.

## Exact payment details (so a signature never fails the first time)
- Protocol: x402 v2, EIP-3009 `TransferWithAuthorization` (EIP-712 over the USDC domain).
- Network: `eip155:8453` (Base mainnet). Asset: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (USDC, 6 decimals).
- Challenge validity window: 60 seconds - sign inside it, with a fresh nonce.
- Header on retry: `PAYMENT-SIGNATURE` (base64 of the signed payload). `X-PAYMENT` is accepted too.
- **Amounts are atomic units, not dollars**: 25000 = 0.025 USDC, 20000 = 0.02 USDC.
  Copy `amount`, `asset`, `network`, `payTo` and the validity window EXACTLY from the
  challenge you just fetched - do not reuse a cached challenge or an earlier signature.
- payTo: `0x351eb3679f817ea7de8baeCbaF3Bd5120200eadc` (the only address we ever ask you to pay).

## If a payment is refused (troubleshooting, learned from real failures)
1. Fetch a FRESH 402 for every attempt. A cached challenge can carry a stale nonce or window.
2. Re-read the error body: our 402 always lists `accepts[]`; a 200 with `charged: false`
   means the payment was NOT taken (see "Unmeasured" below) - never retry that blindly.
3. Sign inside the challenge validity window with a NEW authorization nonce.
4. Check the signing wallet holds base assets: the asset above, plus a little native ETH on
   base for gas - an underfunded wallet fails AFTER signing, which looks like our fault.
5. If verification fails, do not replay the same signature: fetch a new 402 and sign again.
6. After a successful call, the settlement response travels back in the response headers of
   that same call.

## Error shapes
- `402` - payment required; body is the x402 v2 challenge (`accepts[]`). Paid routes only.
- `200` with `"charged": true` - delivered.
- `200` with `"charged": false` + `reason` - we could not measure the target (unknown market,
  unknown venue, or a private/loopback url). **No settlement happens**, so you were not charged.
- `500` - our side failed; **no settlement happens**. Safe to retry with the same payment.
- Free routes never return 402.

## Performance (measured, not claimed)
Measured 2026-10-05 — 20 requests per endpoint, from a datacenter VM over the public internet.
End-to-end p50:
- free preview: p50 105 ms
- 402 challenge: p50 102 ms
- llms.txt: p50 104 ms
- openapi.json: p50 89 ms
End-to-end p95:
- free preview: p95 315 ms
- 402 challenge: p95 251 ms
- llms.txt: p95 455 ms
- openapi.json: p95 148 ms
Our own handling cost (X-Kenward-Serve-Ms header): p50 2.8 ms, max 33.6 ms.
End-to-end includes TLS, edge and tunnel. Server-side handling is reported per response in the X-Kenward-Serve-Ms header, so any caller can verify what our own code costs.

## Safety (checkable by the caller)
- holds_keys: false — the resource server holds no private key and cannot move funds.
- No account, no API key, no signup: there is no credential to leak.
- Payment is verified by an external facilitator and settled on-chain: the tx hash is public.
- One signed payload is delivered once (replay protection) — a re-used payment is refused.
- Never invents values: a market that was not measured answers UNKNOWN, with the reason.
- Fail-closed: without a configured payee address the process refuses to start.
- No custody, no refunds, no claims about the future — only what the data shows.
- Bounded by design: 120 requests/60s per client IP and request bodies capped at 64 KiB (HTTP 429/413 otherwise).
- Freshness is declared, never implied: every answer carries the data's age, and anything older than 7 days is flagged with a staleness_warning.
- Fail-closed pricing: a market we cannot measure answers immediately with charged:false and NO payment request — you cannot pay for a verdict we do not hold.
These are properties of the running service, not promises: /health reports holds_keys=false and the code path never signs or submits a transaction.

## Contact
https://pay.kenwardai.my.id — operator: Kenward (owner-governed agent).