- [ OK ]phosphor terminal ready — amber, 80×24, no mouse required
- [ OK ]mounted spec tree x402-foundation/x402:/specs
- [ OK ]loaded 8 chapters · rev 2026-08-22
- [ WARN ]two protocol versions present: v1, v2 — not a superset relationship
- [ OK ]13 claims could not be traced to a primary source; all 13 left flagged
- [ INFO ]this terminal speaks for nobody. see :about
reader@x402:~$cat CONTENTS
| № | Chapter | Ver | What it is for | Open |
|---|---|---|---|---|
| 01 | The 402 handshake | v1 v2 | Two HTTP requests, one signature, and a third party that touches the chain so the client never has to. | :e 1 |
| 02 | Payment requirements | v1 v2 | The 402 body is a menu. This is what every item on it means, and which fields do not exist despite what you might expect. | :e 2 |
| 03 | Facilitators | v1 v2 | The only party that touches the chain. What it can do to you, what it cannot, and why /settle timing out is the worst answer you can get. | :e 3 |
| 04 | Schemes and networks | v2 | A scheme decides what the signature promises. A network decides what the signature looks like. Getting either wrong produces a valid-looking payload nobody can settle. | :e 4 |
| 05 | Gate an endpoint | v2 | The server half is base64, two HTTP calls to a facilitator, and one decision about where to put settle. | :e 5 |
| 06 | Paying as an agent | v1 v2 | An agent that can pay is an agent that can be drained. The protocol part is fifty lines; the policy part is the part that matters. | :e 6 |
| 07 | Failure modes | v1 v2 | The error strings are an open set, one of them is non-terminal, and the most dangerous outcome is not an error at all. | :e 7 |
| 08 | Spec changelog | v1 v2 | The protocol is not finished. This page is regenerated from the specs/ tree of the specification repository so the primer can be checked against what actually moved. | :e 8 |
reader@x402:~$
x402 revives HTTP 402 Payment Required as a working status code. A server answers an unpaid request with a price; the client signs a transfer for exactly that price and repeats the request; a third party called a facilitator checks the signature and moves the money. No accounts, no API keys, no invoice — the credential is the payment.
These eight chapters are the fundamentals, written from the wire format rather than from marketing. Every JSON body, header name and field list here was read out of the specification and the reference implementations, and where a detail could not be traced to a primary source it is labelled unconfirmed instead of guessed.
:e 1 — start with the handshakeread the specification source ↗
Two protocol versions, not one protocol
The reference repository ships x402Version: 1 and x402Version: 2 side by side. They are not a superset relationship: the field names differ, the HTTP header names differ, and the network identifiers differ. v1 puts the price in the response body and signs into X-PAYMENT; v2 puts the price in a PAYMENT-REQUIRED header and signs into PAYMENT-SIGNATURE. Code that assumes one shape and receives the other fails at the parser, not at the payment. Every page here says which version it is describing.
──how to read this────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Chapters 1 through 4 are the model: what the round trip looks like, what the server puts in the 402, what the facilitator is actually for, and how schemes and networks vary. Chapters 5 and 6 are the two implementations you are likely to write — the server that charges and the agent that pays. Chapter 7 is the one to read before you ship: every documented failure mode and what each error string really means. Chapter 8 tracks what has been changing in the specification itself.
Sample values throughout are Base Sepolia testnet values taken from the specification and from a live capture of the public reference server. They are illustrative, not an endorsement of any deployment, and nothing here is financial, legal, or security advice. Verify against the specification before you move real funds.
live x402 ecosystem stats, with every source named
x402.info — What HTTP 402 does, in plain language — plus live ecosystem stats and a verified ecosystem map.
x402.blog — Engineering notes on paying for HTTP: agent payments, paid-API ordering, and code that runs.