# What changed between x402 version 1 and version 2?

> 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:8453` is an unambiguous, standard identifier. A name like `base` only 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-REQUIRED` header means version 2.
- No such header, and a JSON body containing `"x402Version": 1` and an `accepts` list, means version 1.

The [402 checker](https://www.ask402.ai/tools/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](https://docs.x402.org/guides/migration-v1-to-v2)
- [x402 version 2 launch post](https://www.x402.org/writing/x402-v2-launch)
- [x402 version 1 specification](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md)
- [x402 version 2 specification](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md)

---

Facts checked against the sources above on 2026-11-20. Canonical page: https://www.ask402.ai/x402/x402-v1-vs-v2
