true402
protocol reference

How 402 works.

One status code, one header. Below is the full handshake, the shape of a 402, and where to point a machine. The complete, machine-readable contract is the OpenAPI spec.

§01 · the handshake

Seven steps, two round-trips.

  1. 01 Agent sends a request with no payment.
  2. 02 Service returns 402 with payment requirements (EVM and/or Lightning).
  3. 03 Agent signs the payment with its wallet (USDC EIP-3009).
  4. 04 Agent retries with the X-PAYMENT header.
  5. 05 Service verifies via the facilitator (EVM) or LND (Lightning).
  6. 06 Service processes the request and responds.
  7. 07 Settlement happens asynchronously — the response never waits on it.
§02 · anatomy of a 402

Everything needed to pay.

A 402 carries one or more accepts entries. Each says how much, in which asset, on which network, to whom, and via which facilitator — enough for an agent to pay without ever talking to a human.

402 body 
HTTP/1.1 402 Payment Required

{
  "x402Version": 2,
  "error": "Payment required to access this resource",
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",              // Base mainnet (84532 = Sepolia)
    "maxAmountRequired": "495",            // atomic USDC, 6 decimals
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xFe25…A9C4",
    "facilitatorUrl": "https://open.x402.host",
    "maxTimeoutSeconds": 60,
    "resource": { "url": "https://true402.dev/api/v1/chat/completions", "method": "POST" },
    "extra": { "name": "USDC", "version": "2" }   // EIP-712 domain
  }]
}
§03 · the rails

USDC on Base. Lightning optional.

  • EVM: USDC via EIP-3009 transferWithAuthorization — the payer signs, the facilitator submits. Receiving is keyless.
  • Networks: eip155:8453 (Base mainnet), eip155:84532 (Base Sepolia).
  • Lightning: an optional BTC rail via LND, advertised alongside EVM when enabled.
  • Settlement: asynchronous — verified before the response, submitted after.
§04 · for machines

Discover without docs.