The x402 flow

The on-the-wire shape of the request, the 402, and the paid retry.

x402 is HTTP-native. Every paid endpoint follows the same three-message dance:

  1. Probe — client sends the request with no payment header. Server responds 402 Payment Required with a JSON PAYMENT-REQUIRED body that lists the supported payment schemes, prices, networks, and the receiving address.
  2. Sign — client picks one of the accepts[] entries, builds a payment payload (for EVM upto: a Permit2 authorisation), signs it, and base64-encodes the result.
  3. Retry — same request, this time with PAYMENT-SIGNATURE: <base64-payload>. Server verifies with the facilitator, runs the handler, settles, and returns 200 with the data plus a PAYMENT-RESPONSE header.

PAYMENT-REQUIRED shape

{
  "x402Version": 2,
  "resource": { "url": "https://api.bazaar.tools/v1/flights/search" },
  "accepts": [
    {
      "scheme": "upto",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "100000",
      "payTo": "0x...",
      "maxTimeoutSeconds": 60,
      "extra": {
        "unitMeaning": "one flight itinerary",
        "pricePerUnit": "1000",
        "maxUnits": 100,
        "minCharge": "100000"
      }
    }
  ],
  "extensions": { "bazaar": { /* discovery extension — for agent discovery */ } }
}

The extra block is machine-readable pricing metadata: pricePerUnit and minCharge are atomic-unit strings (6-decimal USDC). minCharge is the per-call settlement floor — every response that returns rows settles at least this much ($0.10), on every freshness tier.

PAYMENT-RESPONSE shape

{
  "success": true,
  "transaction": "0x...",
  "network": "eip155:8453",
  "payer": "0x...",
  "amount": "100000"
}

The amount field reflects what was actually settled on-chain, not what was authorised. For an upto scheme like ours, that means max(rows × pricePerUnit, minCharge): if you asked for 5 itineraries at $0.001 each, the raw row cost is $0.005, so the $0.10 minimum charge applies and amount is 100000 atomic units. A larger call settles for its actual row cost — 6 fundamentals rows at $0.05 each settles 300000 ($0.30) — never more than the ceiling you authorised.