x402 v1 to v2 Migration: What Changed and What Breaks

TL;DR

• x402 v2 shipped on December 11, 2025, after v1 processed more than 100 million payments in its first several months.
• The five big shifts: a unified multi-chain payment interface, a plugin-driven SDK, wallet-based reusable sessions, automatic service discovery, and modernized HTTP headers.
• Reference SDKs stay backward-compatible with v1, so existing integrations keep working — but hand-rolled middleware, legacy X-* headers, and per-request billing logic will need attention.
• The real unlock is not multi-chain. It's reusable sessions, which finally make high-frequency agent workloads economical.
• Running both versions yourself is expensive. A v1/v2 gateway (FluxA is one example, listed on the official x402 ecosystem page as deferred payment rails) is usually the cheaper path.

Why x402 Needed a V2

x402 is the HTTP-native payment protocol built on the 402 "Payment Required" status code. Launched by Coinbase Developer Platform in May 2025, it crossed 100M+ processed payments before the end of the year — fast enough that the original spec started leaking at the edges.

Three pressure points forced a rewrite. First, every call required a fresh signed payment, which made LLM inference and multi-step agents prohibitively slow. Second, while v1 was primarily limited to USDC on Base, each chain beyond that required bespoke integration rather than a shared interface — ecosystem fragmentation at the SDK level. Third, the custom X-PAYMENT header family sat outside standard HTTP header conventions, which v2 replaces with IETF-aligned names.

x402 v2, released on December 11, 2025, addresses all three without forcing a rewrite. The spec is now cleaner, modular, and — crucially — backward-compatible with v1.

What Changed in v2

Here's the concrete diff, mapped to what an API provider or MCP server operator actually sees:

Most ecosystem coverage leads with multi-chain support. That framing is wrong for API providers. The feature that actually changes unit economics is reusable sessions: once a wallet proves control, subsequent requests skip the full payment round-trip. For an agent calling the same inference API forty times in a workflow, that's the difference between v2 being usable and unusable.

The wallet-based session model also rewrites the cost math for something v1 quietly failed at: subscriptions. Per-request stablecoin settlement was never going to compete with Stripe on a $9.99/month plan. With v2 sessions, the same endpoint can serve one-off agents via per-call payment and retained users via a signed session token — without forking the API.

Note: v2 shipped the session architecture at launch; the full SIWx wallet identity header followed as an immediate fast-follow release.

What Breaks in Migration

Backward compatibility protects your existing traffic, not your code. Five specific things tend to break during a v1-to-v2 migration:

1. HTTP header names.

v2 deprecates the custom X-* payment header family and introduces PAYMENT-SIGNATURE, PAYMENT-REQUIRED, and PAYMENT-RESPONSE. Reference SDKs handle both, but any middleware, reverse proxy, or API gateway you wrote by hand will need to accept both header formats during the transition.

2. SDK import paths.

v2 consolidates reference SDKs under the @x402 npm organization. Projects that imported from the original scattered packages need path updates — a mechanical change, but every import statement counts.

3. Billing logic tied to request count.

v1 assumed one signed payment per request. v2 reusable sessions mean a single wallet can make many calls without re-signing. If your billing logic charges per HTTP request without checking session state, you will double-charge returning clients.

4. Facilitator compatibility.

Not every facilitator supports both versions. The official x402 ecosystem page marks facilitators that handle v1 and v2 — Primer and Heurist are two examples. Migrating your server to v2 without verifying your facilitator's version coverage will silently break settlement.

5. Hardcoded service catalogs.

If you published a manual API catalog for agent discovery, v2's Discovery extension expects facilitator-crawlable metadata. The old catalog format still works for direct calls, but v2-native clients will bypass it.

Header comparison, for reference:

http

`# v1 X-PAYMENT: <signed_payload>

v2

PAYMENT-SIGNATURE: <signed_payload> PAYMENT-REQUIRED: <offer_metadata>`

The Migration Path We Recommend

There are three ways to migrate. Only one of them scales.

Option 1: Big-bang rewrite.

Drop v1, ship v2. Fast for early-stage projects with low traffic. Unacceptable for anyone with production integrations — you'll lose every v1 client that hasn't upgraded their SDK.

Option 2: Dual-stack by hand.

Run v1 and v2 in parallel, route based on headers. Technically correct, operationally expensive. You own two codepaths, two sets of bugs, and two facilitator integrations.

Option 3: Gateway-backed migration.

Put a gateway in front of your API that negotiates v1 or v2 per client. Your origin server stays on one version. Clients migrate at their own pace.

Gateway-backed is the only option that scales past a handful of endpoints. FluxA, listed on the official x402 ecosystem page as deferred payment rails for x402, is one implementation of this pattern — it speaks both v1 and v2 to clients while giving API providers a single integration surface. For workloads where even v2's per-call signing is too slow, FluxA's AEP2 protocol layers authorize-first-settle-later payment mandates on top of x402, MCP, and A2A calls. If you're deploying agents that transact autonomously at scale, the five spending controls every agent deployment needs covers the governance layer that sits above the payment protocol itself.

Pick the gateway approach unless you have a strong reason not to.

Conclusion

x402 v2 is a better-designed protocol than v1, and the backward compatibility guarantees mean you can migrate on your timeline — not the ecosystem's. The real decision isn't whether to move, but how: rewrite, dual-stack, or gateway. For anything beyond a toy project, pick the gateway.

If your goal is to ship agent-native payment infrastructure without owning the v1/v2 translation layer yourself, FluxA Monetize handles both protocol versions and adds AEP2 mandates for workloads that need authorize-first-settle-later semantics.

Frequently Asked Questions

Is x402 v2 backward compatible with v1?

Yes. The official x402 v2 launch announcement states reference SDKs are fully backward-compatible with v1. Existing v1 integrations keep processing payments after servers upgrade to v2.

Do I need to change my facilitator when migrating to v2?

It depends on your facilitator. The x402 ecosystem page marks facilitators that support both versions — CDP and Heurist are confirmed examples. Primer's current SDK targets v2 only (Base networks); verify your specific facilitator's version coverage directly before upgrading.

What's the difference between x402 v1 and v2 HTTP headers?

v1 uses the custom X-PAYMENT header family. v2 replaces these with PAYMENT-SIGNATURE, PAYMENT-REQUIRED, and PAYMENT-RESPONSE to align with IETF header conventions. Reference SDKs parse both during migration.

Does x402 v2 support MCP servers?

Yes. Cloudflare's Agents SDK v0.4.0 explicitly migrated its MCP payment integration to @x402/core and @x402/evm v2 packages, handling both v1 X-PAYMENT and v2 PAYMENT-SIGNATURE headers simultaneously.

When should I migrate from v1 to v2?

Migrate now if you run high-frequency workloads, multi-chain services, or LLM inference APIs where reusable sessions cut costs. Otherwise, there's no rush — v1 keeps working, and v2 adoption compounds through 2026.

Can a v2 server still accept payments from v1 clients?

Yes. According to Coinbase's official migration guide, v2 servers continue accepting v1 client payments during transition. Coinbase recommends upgrading clients to v2 eventually for full feature access.