Skip to main content
This guide helps you migrate from x402 V1 to V2 on Polygon. The V2 protocol introduces standardized CAIP-2 network identifiers, updated HTTP headers, and a modular @x402/* package layout.
Polygon facilitators on mainnet and Amoy run x402 v2. V1 clients and middleware will not work against these endpoints.
For Go, Python, and full upstream details, see the official migration guide.

Overview

For buyers

Before (V1)

After (V2)

Key changes

  1. Package rename: x402-fetch@x402/fetch
  2. Wallet setup: Use x402Client with .register() instead of passing a chain-bound walletClient
  3. Environment variable: PRIVATE_KEYEVM_PRIVATE_KEY
  4. Receipt header: Read PAYMENT-RESPONSE via x402HTTPClient.getPaymentSettleResponse(), not decodeXPaymentResponse() on x-payment-response

For sellers

Before (V1)

After (V2)

Key changes

  1. Package rename: x402-express@x402/express
  2. Configuration structure: Route config uses an accepts array with explicit scheme, network, and payTo
  3. Network format: polygon-amoyeip155:80002, polygoneip155:137
  4. Resource server: Create x402ResourceServer with a facilitator client and register schemes with .register()
  5. Middleware signature: Pass (routes, server) instead of (wallet, routes, facilitatorConfig)

Network identifier mapping

Package migration reference

Install examples:

Header changes

If you implement custom HTTP handling, update header names:

Troubleshooting

Payment verification failures

  • Use CAIP-2 network identifiers (eip155:80002 or eip155:137), not polygon-amoy or polygon
  • Verify your payTo address is correct
  • Confirm the facilitator URL matches the network:
    • Amoy: https://x402-amoy.polygon.technology
    • Mainnet: https://x402.polygon.technology

”Cannot find module” errors

Ensure you installed all V2 packages:

Mixed V1/V2 compatibility

During migration, update both buyers and sellers to V2 when targeting Polygon facilitators. Legacy V1 network strings and headers will fail against v2-only endpoints.

Next steps