Ask402

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 1Version 2
Where the price isJSON response bodyPAYMENT-REQUIRED header, base64 JSON
Header carrying the paymentX-PAYMENTPAYMENT-SIGNATURE
Header carrying the receiptX-PAYMENT-RESPONSEPAYMENT-RESPONSE
Network namesPlain names: base, base-sepolia, avalancheCAIP-2: eip155:8453, eip155:84532
Price fieldmaxAmountRequiredamount
Resource detailsRepeated inside every offerOne resource object at the top
Payment echoes the chosen offerNoYes, in accepted
ExtensionsNoneAn extensions object, used for things like discovery
npm packagesx402, x402-express, x402-fetch and othersThe @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 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

Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.

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.