# How x402 works

> The four-leg HTTP exchange that turns 402 Payment Required into a completed call.

Source: https://route402.dev/docs/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

```http
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
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:

```json
{
  "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

```http
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
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:

| What happened | What the caller is charged |
|---|---|
| Upstream returned 5xx or timed out | Nothing. The upstream status is returned as-is. |
| Upstream returned 4xx | The call. It was served exactly as requested. |
| Verified, but settlement failed later | The call is served; settlement retries. |
| The facilitator is unreachable | Nothing — the gateway answers `402`. Failing open would give the API away. |

## 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.