Learn / Spec

x402 v1 vs v2: what changed

Version 2 of x402 moved the payment terms into headers and switched to standard chain identifiers. Most of the changes are names, but a client built for one version can fail on the other.

The main differences

v1v2
402 termsJSON body, acceptsPAYMENT-REQUIRED header
Payment headerX-PAYMENTPAYMENT-SIGNATURE
Receipt headerX-PAYMENT-RESPONSEPAYMENT-RESPONSE
Networkbaseeip155:8453 (CAIP-2)
Amount fieldmaxAmountRequiredamount

Why it matters

A current v2 client reads the header and expects CAIP-2 networks. A seller that only speaks v1 can look fine in a browser and still be unpayable by that client. Our public probe-pass grade treats v1-only as a fail for exactly that reason.

Serving both

Many sellers send the v2 header and keep a v1-shaped body for older clients. That is fine as long as the two carry the same terms. Our facilitator accepts both: base in v1 and eip155:8453 in v2.

Common questions

Is x402 v1 still supported?

Many facilitators, including ours, still accept v1 payments on Base, but new clients target v2.

What is CAIP-2?

A chain-agnostic way to name a blockchain network: eip155:8453 is Base mainnet, and solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp is Solana mainnet.

Do I need an X-402-Price header?

No. It is not part of the x402 specification. The price lives in the payment requirements.

Keep reading

The x402 402 response, field by fieldHow x402 works, step by stepHow to accept x402 payments on your APIAll x402 guides
See what our facilitator supports
LearnDocsSettlement policyEndpoint report