What changed between x402 version 1 and version 2?
Short answer
Version 2 moved the payment details out of the response body and into HTTP headers, renamed those headers, switched network names to the CAIP-2 format such as eip155:8453, renamed maxAmountRequired to amount, and added extensions. The reference SDKs still read version 1, so older endpoints keep working.
Side by side
| Version 1 | Version 2 | |
|---|---|---|
| Where the price is | JSON response body | PAYMENT-REQUIRED header, base64 JSON |
| Header carrying the payment | X-PAYMENT | PAYMENT-SIGNATURE |
| Header carrying the receipt | X-PAYMENT-RESPONSE | PAYMENT-RESPONSE |
| Network names | Plain names: base, base-sepolia, avalanche | CAIP-2: eip155:8453, eip155:84532 |
| Price field | maxAmountRequired | amount |
| Resource details | Repeated inside every offer | One resource object at the top |
| Payment echoes the chosen offer | No | Yes, in accepted |
| Extensions | None | An extensions object, used for things like discovery |
| npm packages | x402, x402-express, x402-fetch and others | The @x402/* scope |
The version 2 specification is dated December 9, 2025.
Why the changes were made
- Headers instead of body. In version 2 all protocol information travels in headers, which leaves the response body free for whatever the server wants to say to a person or a non-paying client.
- CAIP-2 network names.
eip155:8453is an unambiguous, standard identifier. A name likebaseonly works if every implementation agrees on the same list of names. - Extensions. New features such as the Bazaar discovery listing can be added without changing the core format.
How to tell which version an endpoint uses
Make an unpaid request and look at the reply:
- A
PAYMENT-REQUIREDheader means version 2. - No such header, and a JSON body containing
"x402Version": 1and anacceptslist, means version 1.
The 402 checker reports the version for you.
Do old clients and servers still work?
The reference SDKs are described as fully backward compatible with version 1, so a version 2 client can pay a version 1 endpoint. The reverse is not guaranteed: a client that only knows version 1 will not find the price in a version 2 reply, and some services state that they accept version 2 only. If you are starting today, build on version 2.
One thing that catches people out
Because version 2 puts its three headers outside the small set browsers expose by default, a server that wants to be called from a web page must list them in Access-Control-Expose-Headers and Access-Control-Allow-Headers. Without that, browser code cannot read the price even though the server sent it.
Sources
- Migration guide, version 1 to version 2
- x402 version 2 launch post
- x402 version 1 specification
- x402 version 2 specification
Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.
Related questions
Who writes this. Ask402 is published by Havok Holdings LLC, which also runs Agent402, one of the x402 services covered here. Agent402 is labelled wherever it appears. Everything else is described from each project’s own documentation, and nobody pays to be listed.