x402 is an HTTP payment protocol for machine-to-machine payments. When a direct API key exhausts its monthly quota and credit balance, the backend can answer 402 Payment Required with an x402 offer instead of failing.

Offer

GET /payment/x402/config advertises the current offer template:

{
  "data": {
    "enabled": true,
    "payment": {
      "chainId": "8453",
      "asset": "USDC",
      "amount": "0.01",
      "recipient": "0x..."
    },
    "verifier": "https://x402.org/verifier"
  }
}

Flow

1. A request with exhausted quota returns 402 plus the X-Payment-Required header (base64url-encoded JSON offer) and a payment_required body.
2. The client (wallet/agent) pays the offer on-chain.
3. The client obtains a receipt from the verifier and retries with:

X-Payment-Receipt: <base64url JSON receipt>

4. The backend verifies the receipt once, matches the offer reference, records it, and serves the request.

Guarantees

• Offers expire after 15 minutes.
• Receipts are single-use (receipt_id unique); replay is rejected.
• The receipt must reference an offer issued to the same user.
• Failed verification returns a fresh 402 with a new offer.

Notes

• x402 is an alternative to credit billing; while included quota or credits remain, x402 is not triggered.
• The verifier URL and API key are configurable via X402_VERIFIER_URL and X402_VERIFIER_API_KEY.