HTTP 402 is one of the original HTTP status codes from the 1992 spec, marked "Payment Required." It sat unused for thirty years because there was no payment rail fast or cheap enough to make per-request payments practical. Stablecoins + L2s changed that.
The x402 protocol is a small, open convention:
- Client hits
GET /api/something-paid - Server returns HTTP 402 with
WWW-Authenticate: x402 chain=base asset=USDC price=0.05 receiver=0x… - Client pays on-chain, signs a receipt
- Client retries the request with
X-X402-Receipt: <base64-encoded-signed-receipt> - Server verifies the receipt + the on-chain tx, returns the actual response
It's HTTP-native; no auth tokens to manage, no API keys to rotate. Anyone with a wallet can use any x402-paid endpoint.
What the receipt actually carries
A receipt is JSON, canonicalised (sorted keys, no whitespace), and signed with the wallet's ed25519 audit key. The fields:
| Field | What it is |
|---|---|
wallet |
The user's pubkey |
tx_hash |
The on-chain payment tx hash |
chain |
The chain the payment was made on |
asset |
The asset (USDC, EUR, XRP…) |
amount_eur_cents |
Amount in EUR cents |
service_url |
The exact URL being paid for |
issued_at |
ISO-8601 timestamp |
The server verifies (a) the signature is valid for the user's wallet pubkey, (b) the on-chain tx matches the receipt, (c) the receipt hasn't been replayed (one-shot), (d) the amount meets the price.
What goes wrong
Three things to know:
The server can lie about its receiver. If the WWW-Authenticate header points to an attacker-controlled address, you pay them and they never serve content. Mitigation: the agent's validator checks the receiver against a deny-list and (in future iters) against domain-receiver consistency.
Server doesn't verify the on-chain tx. Some sloppy implementations accept any signature-valid receipt without confirming the tx actually settled. Don't rely on receipt-only verification for high-value services — the receipt is proof of intent, the on-chain tx is proof of settlement.
Replay attacks. A receipt is single-use. If a server doesn't enforce that, an attacker who steals one receipt can reuse it indefinitely. Gopnik's server-side implementation marks receipts as used in the database at first presentation.
The agent's role
The agent doesn't need your help to handle 402. When you authorise an x402 use case, the agent:
- Watches for 402 responses
- Reads the WWW-Authenticate header
- Checks the price against your per-tx cap
- If allowed, sends the on-chain payment and signs a receipt
- Re-issues the request with the receipt presented
- Logs everything to
agent_action_log
You can take the agent out of the loop and use x402 directly via the gopnik.x402.client Python module — same protocol, manual auth.
What you commit to
- x402 receipts are wallet-signed; treat them as identity in addition to payment proof
- A 402 response is not a refusal; it's a price quote
- The agent will pay up to your per-tx cap automatically; receipts you didn't authorise should never appear in the action log
- Receipt-only verification is weaker than receipt + on-chain verification