For agents and bot builders

Pay a dime, get a fantasy verdict.

Every paid endpoint speaks x402 V2 over plain HTTP. No API key, no signup, no rate-limit negotiation: call it, get a 402 with machine-readable payment requirements, pay, call again. Responses are typed JSON with the verdict block at the root.

The 402 handshake

  1. Call the endpoint normally. No payment header on the first request. You get 402 Payment Required.
  2. Read the payment requirements. The V2 PaymentRequired object is at the root of the 402 JSON body (camelCase), and is also base64-encoded in the PAYMENT-REQUIRED response header. It carries accepts[] — scheme, CAIP-2 network, USDC asset id, amount in atomic units as a string, and payTo.
  3. Pay, then retry the identical request with a PAYMENT-SIGNATURE header: base64 of the JSON PaymentPayload ({ x402Version: 2, payload, accepted, resource, extensions }). Echo extensions back — that is how the facilitator catalogs the resource for Bazaar discovery.
  4. Read the receipt. A successful response carries the settlement receipt in the PAYMENT-RESPONSE header, base64 JSON: {success, transaction, network, payer}. It is listed in Access-Control-Expose-Headers, so browsers can read it too.

Headers, V2

Client sends PAYMENT-SIGNATURE. The 402 carries PAYMENT-REQUIRED. The receipt comes back in PAYMENT-RESPONSE. The V1 names X-PAYMENT/X-PAYMENT-RESPONSE are still accepted inbound and mirrored outbound for older clients.

Idempotency

A verified payment is remembered for 60 seconds, keyed by endpoint plus a hash of the payment header. Retrying inside that window re-serves the original receipt instead of settling twice — safe to retry on a timeout.

curl

Replace the host with your deployment; everything else is verbatim.

1 — see what it costs

curl -s https://api.example.com/v1/catalog | jq .

# or ask one endpoint directly and read its 402:
curl -s -D - -o /dev/null \
  -X POST https://api.example.com/v1/player \
  -H 'Content-Type: application/json' \
  -d '{"name": "Bijan Robinson", "week": 5}'
# HTTP/1.1 402 Payment Required
# payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0cyI6W3sic2NoZW1lIjoi...

2 — pay and retry

# PAYMENT_SIGNATURE = base64(JSON PaymentPayload) built by your x402 client
curl -s -D headers.txt \
  -X POST https://api.example.com/v1/player \
  -H 'Content-Type: application/json' \
  -H "PAYMENT-SIGNATURE: $PAYMENT_SIGNATURE" \
  -d '{"name": "Bijan Robinson", "week": 5}' | jq .

# settlement receipt:
grep -i '^payment-response:' headers.txt | cut -d' ' -f2 | base64 -d | jq .
# { "success": true, "transaction": "…", "network": "algorand:…", "payer": "…" }

3 — against a mock-mode server (no chain)

A deployment running X402_MODE=mock accepts the literal header value mock-paid. This is how the demo and this web UI are tested end to end without touching a wallet. 

curl -s -X GET 'https://api.example.com/v1/trending?lookback_hours=24' \
  -H 'PAYMENT-SIGNATURE: mock-paid' | jq .verdict

Paid endpoints

Live from /v1/catalog. Prices are USDC, 6 decimals.

Response contract

Every paid body extends the same base, so one parser handles all eight endpoints: verdict, confidence (high|medium|low), reasoning, stats_cited[], sources[], and meta (generated_at, data_freshness, model, cache, attribution). Endpoint-specific fields sit alongside those at the root.

Free endpoints need no payment at all: GET /v1/health, GET /v1/catalog, GET /v1/trending/preview.

Discovery & specs

OpenAPI

Interactive docs at /docs, raw schema at /openapi.json. Every request and response model is documented there, field by field.

llms.txt

A compact, agent-first description of the service at /llms.txt — what each endpoint answers, what it costs, and how to pay for it.

Catalog

/v1/catalog is the machine-readable price list: paths, methods, prices, schema names, cache TTLs, network, payTo and facilitator URL.

Bazaar discovery

Every 402 carries an extensions.bazaar block: a working request example, the input JSON Schema, and an example response body. Echo extensions back in your PaymentPayload and the facilitator catalogs the resource when your payment settles — that is how this service becomes discoverable to other agents. There is no /.well-known step; discovery is in-band.

Algorand x402 Challenge

Payments settle in USDC on Algorand through the GoPlausible facilitator, and each payment requirement carries the challenge tag in accepts[].extra.tag for leaderboard attribution. Current deployment values: