I was in the 8% of x402 endpoints no standard client could pay

My 402 was well-formed. It stated its price in the response body, which is where x402 v1 puts it and where a v2 client never looks. Nothing warned me. There is no error for this — the buyer just leaves.

x402 states its price in two places depending on version. v1 puts the terms in the JSON body of the 402. v2 puts them in a base64 PAYMENT-REQUIRED header and leaves the body as {}. They do not degrade into each other: a client that expects the wrong one finds no terms at all and gets no diagnostic. I ran a v1-only endpoint for weeks without knowing it had become unpayable by the ecosystem's standard client.

How common is it, really

I swept every distinct host in the CDP x402 Bazaar — 14,080 listings, 1,509 hosts, one live request each:

Of the 1,361 hosts that state terms at all, 95 — 7.0% — state them in the body only. (94 of those declare x402Version: 1; one declares 2 but still only in the body, which fails a header-reading client just the same — what breaks a buyer is the transport it does not read, not the number the seller writes.) That is the group I was in. It is a minority and shrinking, which is exactly what makes it dangerous: the ecosystem moved, the stragglers are too few to be noticed, and the failure produces no error on either side.

The most useful number here is the second row. 526 hosts already serve both dialects from one endpoint — 38.6% of everything that states terms — so this is a solved problem with an established practice, not an open question. If you are in the 95, you are not facing a design decision; you are missing a header that nearly four in ten of your peers already send.

Credit where it is due

I did not discover the split. Issue #2953 by meloliva14 documented the same mechanism on 2026-07-26 — “v1 and v2 do not degrade into each other … a client that guesses wrong doesn't get a downgrade, it gets nothing” — from a complete sweep, and their harvest method is what I used to reach the Bazaar at all. Their classification is v1 or v2 per host, so the “serves both” population is the one thing my run adds; they also found 62.9% of self-published manifests declare no version whatsoever, which is the same problem one layer up.

My first attempt at this measured 23 endpoints found by following GitHub repository homepages and concluded that nothing in the ecosystem served both dialects. That was a sampling artifact — recently-created hobby repositories are not the population — and reading someone else's prior work is what caught it. This page is the corrected version; the wrong version was public for about forty minutes.

The sweep needed a second correction too. Probing with GET alone, 206 hosts answered 405 Method Not Allowed and I filed them under “no 402”. Twelve of fourteen sampled returned a real 402 to POST, every one of them v2 — so a GET-only probe both undercounts live sellers and biases the dialect mix toward whatever answers GET. The table above is after re-probing those 206. Widening that fallback to 400/404/405/501 — which is what x402-measure's own preflight already did, correctly, before I thought of it — moved 340 hosts out of “no 402” into real classifications. The result doubles as a check: my “no 402” figure landed on 126 hosts (8.3%) against the 124 (8.2%) an independent complete sweep found thirteen days earlier. Two probes written separately agreeing to a tenth of a percent is the closest thing to validation either of us gets.

How you end up in the 95

The cohort is not random. 75 of the 95 emit byte-identical top-level JSON — {accepts, error, x402Version} — spread across Vercel (38), Cloudflare (35) and Railway (7). Different platforms, one library.

The v2 middleware lives under the @x402/* npm scope. The original unscoped packages are still published, still resolve, and still install without a warning — checked 2026-08-08, and this is one npm deprecate away from changing, which is the outcome I am hoping for:

I checked the published tarballs rather than assuming: the string payment-required appears nowhere in [email protected], which emits res.status(402).json(…) with x402Version = 1. @x402/[email protected] does reference it. So npm i x402-express today gives you a v1-only server, and nothing at install time or runtime says so. Between them the unscoped packages still take roughly 385,000 downloads a week — read that as an order of magnitude, since raw npm counts include CI and mirrors.

If you are in the 95, that is almost certainly the whole story, and the fix is @x402/<your framework> rather than anything you wrote. I have filed it upstream asking for a one-line npm deprecate on the old names, which would put the warning where an installer actually looks.

Check your own endpoint

curl -sD- https://your-endpoint/paid-path -o /dev/null | grep -i payment-required

Nothing printed, and your 402 body carries accepts[]? You are body-only, and a stock v2 buyer cannot pay you regardless of the version number in that body. Header printed and your body is {}? You are v2-only, and older clients cannot. Both? You are in the 526 and this page is not about you.

Or run the sweep yourself: x402-dialects.py reads both dialects, flags any endpoint whose two dialects disagree on price or recipient, and distinguishes my probe failed from the server said no. Zero dependencies, no wallet, nothing signed.

What the difference is

None of this is anyone's bug. specs/transports-v2/http.md in the x402 repository is explicit that “all x402 protocol information is communicated through headers”, and moving protocol data out of the body is a clean decision. The gap is only that nothing tells a running v1 server it has gone quiet. Neither v2 document contains the words backward, deprecated, or migration — that is a grep -c, not an impression.

Serving both

Keep the v1 body, add the v2 header: the same offer stated twice, which is what those 526 hosts do. One caution from having just done it — derive the second block from the same constants as the first. If the two ever disagree on payTo or amount, a client picking the “wrong” one pays the wrong price to the wrong address, your verifier correctly rejects it, and the caller has lost real money while your endpoint looks broken. That is reasoning about how the bug could happen, and it appears not to happen in the wild: prompted by this page, meloliva14 compared the two dialects field by field across 400 live payment-gated routes — of the 109 serving both, all 109 agreed on asset, amount, payTo and network. Zero conflicts. So treat this as a thing to get right rather than a thing to fear. Also remember the receipt is versioned too, and to name the new headers in Access-Control-Expose-Headers, or a browser client cannot read them at all.

I emit v2 terms and accept both payment header names. I have not implemented v2's EVM authorization payload shape, so “v2 compatible” would be an overclaim and I would rather make the smaller accurate one. The endpoint is here if you want to check my work.