v1 to v2 Migration

Headline changes

The migration guide identifies four changes that matter immediately: headers, network format, version field, and packages. v1 examples often use X-PAYMENT and X-PAYMENT-RESPONSE. v2 uses PAYMENT-SIGNATURE and PAYMENT-RESPONSE, and adds PAYMENT-REQUIRED for server-to-client requirements.

Network names moved from friendly strings to CAIP-2 identifiers. If an old tutorial says base-sepolia, a v2 implementation should expect eip155:84532. If it says Base mainnet, the v2 identifier is eip155:8453.

v1 payment header:      X-PAYMENT
v2 payment header:      PAYMENT-SIGNATURE

v1 response header:     X-PAYMENT-RESPONSE
v2 response header:     PAYMENT-RESPONSE

v1 network example:     base-sepolia
v2 network example:     eip155:84532

Package map

v2 split the SDK into modular packages. That is good architecture, but it makes copy-paste errors more likely. A server using Express needs @x402/express plus core and scheme packages. A client using fetch needs @x402/fetch plus the scheme packages it can sign for.

The repository README shows a broad package surface across core, EVM, SVM, AVM, Aptos, Stellar, TVM, Hedera, Keeta, Axios, Fastify, fetch, Express, Hono, Next, paywall, extensions, and MCP. Choose the smallest set that matches the networks and runtime you actually need.

Compatibility gotchas

v2 libraries may read both v1 and v2 headers for compatibility, but servers should not emit legacy headers for new clients unless they have an explicit backwards-compatibility requirement. Mixed examples are a source of hard-to-debug 402 loops.

Facilitators also have version and network coverage. The migration guide lists the public x402.org facilitator as testnet-oriented and CDP as a recommended production facilitator with broader network support. Treat that as a provider-specific fact to re-check before launch, because coverage can change.

• Search old tutorials for X-PAYMENT before copying code.
• Convert network aliases to CAIP-2 identifiers.
• Confirm facilitator support for the protocol version and network.
• Run a negative test for wrong-network and wrong-amount payloads.