Migrating to x402 v2: what actually changed (and the traps nobody documents)

We run FiatDock — a non-custodial USDC ↔ bank on/off-ramp where AI agents pay $0.05 per call over x402. This week we migrated the whole stack (Express server, fetch client, MCP server) from x402 v1 to protocol v2. It took an evening, killed all 24 of our transitive npm vulnerabilities, and almost none of it was documented anywhere. Here is the map we wish we'd had.

1. v2 is not an upgrade — it's a different scope

The packages you're using (x402-express, x402-fetch, x402) are the v1 line and they stop at 1.2.0. There is no v2 of them. Protocol v2 lives under the @x402 scope:

npm rm x402-express x402-fetch

npm i @x402/express @x402/fetch @x402/evm @x402/core