How x402 works

HTTP 402 has been in the specification since 1997 and has never meant anything. RFC 9110 §15.5.3 still says it is "reserved for future use". x402 is a convention for what that future use looks like: the server answers with a machine-readable price, and the client pays and retries inside the same conversation.

The exchange

1. The call

GET /x/acme-weather/current?city=Zagreb HTTP/1.1
Host: gw.route402.dev
Accept: application/json

Nothing about this request is special. The caller has no account with the API, no key, and no prior relationship with its owner.

2. The price

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: {"x402Version":2,"accepts":[…]}

The accepts array is the quote. Each entry names a scheme, a CAIP-2 network, an asset, an amount in atomic units, the address to pay, and how long the quote holds:

{
  "scheme": "exact",
  "network": "eip155:14",
  "asset": "0xe7cd86e13AC4309349F30B3435a9d337750fC82D",
  "amount": "1000",
  "payTo": "0xa2477E16dCB42E2AD80f03FE97D7F1a1646cd1c0",
  "maxTimeoutSeconds": 60
}

A server may offer several entries. A client picks whichever it can pay.

3. The signature

GET /x/acme-weather/current?city=Zagreb HTTP/1.1
PAYMENT-SIGNATURE: eyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsi…

The client signs an authorization for the amount it was quoted and retries the identical request with the signature attached. No wallet pop-up, no redirect, no checkout page — which is exactly why an autonomous agent can complete it.

4. The response

HTTP/1.1 200 OK
Content-Type: application/json

{"city":"Zagreb","tempC":21,"sky":"clear"}

What the gateway does in between

Between legs 3 and 4, in order:

1. Send the signature to the facilitator's /verify. If it does not verify, answer 402 again.
2. Inject the publisher's upstream credential and call the origin. The buyer never sees that credential; the origin never sees the buyer's payment.
3. Return the origin's response.
4. Ask the facilitator to settle — immediately, or into a batch.

Verify before the origin is called; settle after it succeeds. The ordering is the whole failure policy:

v2, not v1

x402 v2 uses CAIP-2 network identifiers and the PAYMENT-REQUIRED / PAYMENT-SIGNATURE headers. Most tutorials still in circulation describe v1, which used X-PAYMENT. If a guide mentions X-PAYMENT, it is describing the old protocol.