What stayed the same?#
The whole shape of the exchange, which is why most v1 code still runs.
A request arrives unpaid. The server answers 402 with an accepts array. The client picks terms, signs an authorisation, and resends the identical request with an X-PAYMENT header. The server verifies, serves and settles. Nothing in that sequence changed between versions.
The x402Version field was in the protocol from the start precisely so this transition could happen without silent breakage. A server and a client that disagree about version can detect it rather than failing at the signature.
What changed?#
The parts that had quietly assumed Ethereum.
Networks became general. In v1 the network field was effectively an EVM chain name, and client libraries mapped it to an eip155 chain id. v2 treats the network as an identifier that may name a chain with an entirely different account and signing model. A client that parses the network field by looking it up in an EVM table will fail on anything that is not one.
Assets stopped being ERC-20 addresses. A token on Solana is an SPL mint, not a contract with an ERC-20 interface. Code that validated the asset field as a 20-byte hex address rejects valid v2 terms.
Authorisation became scheme and chain specific. EIP-3009 is an Ethereum token standard. The equivalent on Solana is a different construction, so the payload inside the payment header has a different shape depending on the network. The envelope around it, naming the scheme and network, is what tells a server how to read it.
| Assumption in v1 code | Still safe in v2? |
|---|---|
| Network name maps to an EVM chain id | No |
| Asset is a 20-byte hex address | No |
| Payload contains an EIP-3009 authorisation | Only on EVM networks |
| Amount is a decimal string in smallest units | Yes |
| Payment travels in one base64 header | Yes |
Server answers 402 with an accepts array | Yes |
What should I actually change?#
Three things, in this order.
Read the envelope before the payload. The scheme and network fields in the payment header exist to tell you how to interpret what follows. Code that reaches straight into payload.authorization is assuming an EVM payment.
Validate assets by network, not by format. A hex-address check is a network-specific rule that got written into generic code. Move it behind the network.
Prefer CAIP-2 identifiers for anything machine-read. Chain names are ambiguous across testnets and forks in a way that eip155:8453 and solana:5eykt4... are not. If you are storing settlements, store the canonical identifier and derive the display name, never the other way round.
Warning
The failure mode of a v1 assumption in v2 code is usually not an exception. It is a successful parse of the wrong thing: an asset address read as if it were on the wrong chain, or a network name silently defaulting to the one you built first. Those produce records that look correct and are not.
Does v2 change what an indexer sees?#
Substantially, and this is the part the specification does not cover.
On EVM chains, an x402 payment is identifiable because it is a gasless authorised transfer relayed by a facilitator. That signature is EVM-specific. A Solana x402 payment settles through a different instruction with a different marker, and a different set of relayers.
So an index that handles both is not running one detector over two chains. It is running two detectors whose outputs have to be comparable, which is harder than it sounds and is the main reason cross-chain x402 figures disagree so widely between trackers. Why x402 transaction counts disagree is the longer version.
For a seller this matters in one specific way: if you want your activity to be visible and checkable, the chain you choose determines how well anyone can see it.
Frequently asked questions#
Do I have to migrate?#
Not to keep working on EVM chains. You have to migrate to accept payment on anything that is not one, and to stop your client silently mishandling terms it does not understand.
Can a server advertise both versions?#
A server advertises an x402Version and a set of terms. Supporting clients at both versions in practice means keeping your terms within the intersection, which for EVM-only sellers is most of them.
Which facilitators support v2?#
Coverage differs per facilitator and per chain, and it changes. Check your facilitator's documentation rather than the specification, because the specification describes what is possible and the facilitator decides what is available.
Does v2 change the price format?#
No. The amount is still a decimal string in the asset's smallest unit. That convention survived both versions and remains the field most likely to be misread by a factor of a million.
Is there a v3?#
Not as of October 2026. Work continues in public in the foundation's repository, including replay-protection extensions arising from the 2026 security findings. Who governs x402 covers how changes land.
Where to check this yourself#
Schemes and networks lists what Roundhouse's facilitator accepts today, per chain, which is a concrete answer where the specification gives a general one. For which chains are actually carrying settled volume rather than merely being supported, /stats breaks the indexed record down by chain with the window it was measured over.