Field notes · The x402 SDK went v2. The client everyone installs didn’t. Your endpoint may be unpayable.
In December 2025 the x402 server SDK, @x402/core, shipped a v2 major version — the correct move, and the one every current guide tells you to make. x402-fetch, the most-installed x402 client on npm, last published on April 16, 2026. It has only ever spoken v1. No v2 build of x402-fetch exists today. Build a server on the current SDK, the choice every tutorial recommends, and you are speaking a dialect the most common client in the ecosystem cannot hear.
The numbers
@x402/core ships v2 — the server SDK every current guide tells you to build on
last publish date of x402-fetch, the most-installed x402 client on npm — still v1 only, no v2 release exists
silent wire-format breaks between the two dialects, and not one of them raises an error on either side
the settlement collapse our own fleet’s analytics showed over two months, while 402 challenge volume held steady in the hundreds of thousands a month
Four breaks, and every one of them is quiet
None of these throws an exception. None returns a status code that says what went wrong. Each one is a place where the v1 client and the v2 server each do exactly what their own spec says, and simply stop understanding each other.
the 402 payment challenge moved from the JSON response body to a base64-encoded header. The v1 client reads bodies. It sees a 402 with nothing in it to parse.
networks went from plain names like "base" to CAIP-2 identifiers like "eip155:8453". The v1 client’s own validation rejects the new format outright — a well-formed v2 challenge fails before it reaches the wallet step.
maxAmountRequired became amount, and resource metadata moved from a flat structure to nested. A client reading the old field names finds nothing there and treats the requirement as missing.
even when a v1 client assembles a valid payment, it sends it back in a header the v2 server never reads. The payment is real and correctly signed. The server just re-serves the paywall.
The failure is silent on both sides
An agent running the stock client hits a v2 endpoint, gets a 402 it can’t fully parse — or sends a payment that never lands — and does exactly what it’s built to do: treats the resource as unavailable and moves to the next supplier. No error surfaces anywhere in its logs. On the seller’s side, the dashboard looks healthy: the challenge fired, the request was answered, the endpoint is up. The only place the problem shows up is the one number nobody watches closely enough — settlements, quietly cratering while challenge traffic stays flat. That is exactly what our own fleet analytics showed: challenge volume steady in the hundreds of thousands a month, settlements down roughly 98% over two months, and nothing in any log to explain why.
How we found it
We found this the way most sellers won’t: we tried to pay our own endpoint with the stock client. Off-the-shelf x402-fetch, no modifications, against our own v2 server. The payment attempt produced no error — it just didn’t settle. Tracing it meant capturing the raw request and response on both sides of the exchange and diffing them field by field against the v1 and v2 specs. That’s the whole methodology, and it’s one any seller can run against their own endpoint: log the raw wire traffic a stock client actually sends, log what your server actually reads, and look for the gap.
What we did, and the proof
We rebuilt all 19 services in our fleet to answer both dialects on the same endpoint — a v1 request gets a v1-shaped response, a v2 request gets v2, and a payment sent either way actually gets read and settled. Then we proved it rather than assumed it: a real $0.05 USDC payment on Base, initiated by unmodified stock x402-fetch 1.2.0, settled on-chain, with the receipt correctly decoded by that same client. Transaction: 0x30101fb985fb33334e494dc536b09566fa518a28f50faf99bf79ab20cd6b5633. No custom client, no patched SDK — the exact library the widest slice of the agent economy already has installed, paying an endpoint built on the newest server SDK, settling and reconciling cleanly.
You can outrun the market
Building on the current spec was the right call by every engineering standard we know. It also made our fleet technically correct and commercially invisible for two months, because protocol correctness and payability are not the same property, and nothing in a passing test suite tells you which one you have. The fix isn’t choosing the older, safer SDK — it’s serving both: ship current because that’s where the protocol is going, keep answering legacy because that’s who’s actually knocking today, and test payability with the clients your buyers run, not the ones already sitting in your own stack. You will not catch this bug by testing against tooling that already agrees with your server about the spec version.
The same shape of problem is showing up one layer over, with MPP as a second payment rail growing alongside x402 — about 15% of Bazaar sellers already answer both challenge types on the same 402, for the identical reason: the buyer you can’t see is running something other than what you built against.
Check your own door
We turned the diagnostic above into a free scan — it checks whether stock clients can actually pay you, not just whether your server statuses look right. If it finds you’re v1-blind, the fix is in the x402 Server Starter Kit: the settlement-proven dual-dialect middleware plus MPP dual-stack support, with updates dropped into buyers’ Discord as the ecosystem shifts again — because it will.