Skip to content
shipx402.comWalk the loop →
Ship x402
shipx402.com

Guide · Intermediate · 2026

x402 v1 vs v2: what changed and how not to crash a tester

x402 V2 shipped in December 2025. V2 is the recommended baseline in 2026. Older tutorials still show V1 shapes. Mixing them is the fastest way to fail a 402 checker or a modern client.

Quick comparison

AspectV1V2
Version fieldx402Version: 1x402Version: 2
Payment header (client → server)X-PAYMENTPAYMENT-SIGNATURE (often still accept X-PAYMENT)
Requirements header (server → client)mostly body onlyPAYMENT-REQUIRED (base64) + body
Response headerX-PAYMENT-RESPONSEPAYMENT-RESPONSE (+ legacy mirror OK)
Network idstrings like base-sepolia, solana-devnetCAIP-2: eip155:84532, solana:EtWTRAB…
Resource metadataoften inside each accepts[] itemtop-level resource { url, description, mimeType }
Amount fieldmaxAmountRequiredamount (+ keep maxAmountRequired for compat)
Packagesx402, x402-express, …@x402/core, @x402/express, @x402/svm, …

Solana CAIP-2 IDs you will actually use

  • Devnet: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
  • Mainnet: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

Some docs still show shorthand like solana:devnet. Prefer the genesis-hash form from current docs.x402.org and re-check before production.

What breaks testers

  • Advertising solana-devnet while a V2-only client expects CAIP-2.
  • Returning 200 with no payment middleware (looks “open,” grade fails).
  • Missing payTo, empty accepts[], or wrong address format (0x on Solana).
  • Using the public test facilitator URL on mainnet.
  • Clients sending only X-PAYMENT to a server that only reads PAYMENT-SIGNATURE (or the reverse). Accept both during migration.

Compat recipe used on this site

Our lab and donate endpoints advertise v2 envelopes and still mirror useful v1 fields:

  • Top-level resource + x402Version: 2
  • amount and legacy maxAmountRequired
  • CAIP-2 network in accepts
  • Accept inbound proofs with either modern headers or X-PAYMENT

That way humans, older scripts, and current agents can all complete the loop.

Migration checklist

  1. Bump packages to @x402/* v2 line.
  2. Switch middleware to routes-config + x402ResourceServer + scheme register (ExactSvmScheme / ExactEvmScheme).
  3. Replace network strings with CAIP-2.
  4. Add PAYMENT-* headers; keep X-* during a transition window.
  5. Validate with the 402 Checker and a known-good endpoint like this site’s donate route.
Generate v2 middlewareRun 402 CheckerShip on Solana

Always re-check docs.x402.org before production — package APIs evolve. Ship x402 is independent and not financial advice.