x402 payments

x402 lets an agent pay for a single API call with an on-chain transfer instead of an API key: the server answers an unpaid request with a 402 challenge, the client signs a payment built from that challenge, and the same request is retried with proof of payment.

  • Challenge: send with no payment headers and redirect: "manual"; a payable route returns 402 with a PAYMENT-REQUIRED header.
  • Offers: the accepts array lists x402Version: 2, scheme exact, Base USDC (eip155:8453) or Robinhood Chain USDG (eip155:4663), the asset contract, payTo, and amount in 6-decimal atomic units.
  • Pay: select an offer your wallet supports; before signing, check scheme, network, asset contract, payee, amount, and maxTimeoutSeconds ≤ 300 against the pinned constants.
  • Sign with a managed signer or keystore, never a raw private key in an environment variable.
  • Retry: resend the identical request, with the same path, query, and body, adding the PAYMENT-SIGNATURE header.
  • Verify: decode the PAYMENT-RESPONSE header (base64 JSON) and confirm success, network, payer, and transaction hash.
GET /api/v1/markets/mispriced HTTP/1.1
Host: quotient-api-gateway.onrender.com

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: {"x402Version":2,"accepts":[{"scheme":"exact",
  "network":"eip155:8453",
  "asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "payTo":"0xC3d01FD2F79d4c57aD106AB8ecc12a5dE24F97cB",
  "amount":"20000","maxTimeoutSeconds":300,
  "extra":{"name":"USD Coin","version":"2"}}]}

GET /api/v1/markets/mispriced HTTP/1.1
Host: quotient-api-gateway.onrender.com
PAYMENT-SIGNATURE: <base64 signed payment payload>

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <base64 JSON: success, network, payer, transaction>

The 402 challenge is what a call costs at request time. Pricing publishes the reference prices; a challenge's amount should never exceed them. The alternative to paying per call is a prepaid API key, issued in the console.