agent payments / x402

x402 Route Planner

Sketch a paid API route that speaks HTTP 402 cleanly: challenge header, retry header, settlement response, and the boring production checks that stop tiny payments from becoming tiny fires.

GET /api/research-brief$0.05 · test USDC · exact

Headers to implement

PAYMENT-REQUIREDServer → client with Base64 JSON requirements on 402.

PAYMENT-SIGNATUREClient → server on retry after authorizing payment.

PAYMENT-RESPONSEServer → client with structured settlement result.

PaymentRequired payload before Base64

{
  "x402Version": 2,
  "route": "GET /api/research-brief",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "asset": "test USDC",
      "price": "$0.05",
      "payTo": "0xYourTreasuryAddress"
    }
  ],
  "description": "One compact research brief with cited sources",
  "mimeType": "application/json",
  "maxTimeoutSeconds": 30
}

Middleware sketch

paymentMiddleware({
  "GET /api/research-brief": {
    accepts: [{
      scheme: "exact",
      price: "$0.05",
      network: "eip155:84532",
      asset: "test USDC",
      payTo: "0xYourTreasuryAddress"
    }],
    description: "One compact research brief with cited sources",
    mimeType: "application/json"
  }
})

before launch

Production gut check

x402 removes account setup. It does not remove product judgment. If this route cannot survive duplicate retries, failed settlements, or hostile unpaid probes, it is not ready for agents with wallets.

Toggle the guardrails you actually haveRequires an idempotency key on paid retriesHas a free preview or metadata routeDocuments failed-settlement/refund handlingRate-limits unpaid 402 probes

Minimum test runbook

Unauthenticated request returns 402 Payment Required, not a generic 401 or HTML paywall.
The 402 includes PAYMENT-REQUIRED with price, scheme, network, asset, destination, and description.
Paid retry includes PAYMENT-SIGNATURE and never executes the expensive job twice for the same idempotency key.
Server returns PAYMENT-RESPONSE with success or failure details, then serves the resource only after validation.
Logs record route, amount, facilitator response, and customer-safe correlation ID. No private keys. Obviously.

Sources used today

x402 docs: HTTP 402 and V2 payment headers x402.org: standard overview and seller middleware shape Stripe docs: x402 lifecycle, testing notes, supported stablecoin rails