DEV Community: Frits Zwager

The seven most common x402 seller mistakes, and how to fix them

Frits Zwager — Sun, 18 Oct 2026 20:29:55 +0000

An x402 API asks for payment with an HTTP 402 Payment Required answer, and an AI agent pays it per call in stablecoins. That only works when the 402 is exactly what the agent's client expects. x402 Doctor calls every paid endpoint it can find once a day, about 50,000 of them, the way a paying agent would. On 17 October, 93% were payable as listed. These are the mistakes behind most of the rest, with the fix for each.

2,009 endpoints whose 402 names another URL
1,042 listed URLs that don't answer 402 at all
206 offer only a testnet
7% of Stellar endpoints can't be paid by the official client

1. The 402 names another URL (resource mismatch)

2,009 endpoints. The resource.url in the 402 is not the URL the agent called: a relative path, another host, or http:// instead of https://. Clients and indexes that check the resource refuse the challenge, and the CDP Bazaar may not list the route. The usual cause is a proxy that ends TLS (Render, Fly, Railway, Heroku), so the app builds an http URL.

// Express behind Render, Fly, Railway or Heroku: the proxy ends TLS, so without this
// req.protocol is "http" and the 402 names http://… instead of your public URL.
app.set("trust proxy", 1); // before paymentMiddleware

Or set the field yourself, with the full public URL of the route:

"resource": { "url": "https://api.example.com/v1/price" }

2. The listed URL doesn't answer 402

1,042 endpoints. The URL in the listing answers 404, 401, a login page, or 200 for free. Often the route answers 402 only on POST while the listing says GET, an API-key check runs before the paywall, or the payment middleware is registered after the handler. Agents and indexes only see a paid resource when the first answer to the listed method is a 402.

app.use(paymentMiddleware({
  "GET /v1/price": {
    accepts: [{ scheme: "exact", price: "$0.01", network: "eip155:8453", payTo: process.env.PAY_TO }],
    description: "Latest price for a symbol",
    mimeType: "application/json",
  },
}, resourceServer));

app.get("/v1/price", handler); // after the payment middleware

Register the payment middleware before the handler and before any API-key check (the payment is the authorization), list the method the route really uses, and let a request without input reach the paywall instead of failing validation first.

3. Only a testnet is offered

206 endpoints. The 402 offers only Base Sepolia or another testnet. Agents with real USDC on mainnet can't pay, so the endpoint is invisible to them. A testnet option next to a mainnet one is fine; 4% of payable endpoints do that.

accepts: [
  { scheme: "exact", price: "$0.01", network: "eip155:8453", payTo: process.env.PAY_TO },   // Base mainnet
  // { scheme: "exact", price: "$0.01", network: "eip155:84532", payTo: ... },             // Base Sepolia: test only
],

4. The MPP challenge names another host as its realm

102 endpoints. On endpoints that also take MPP (the Machine Payments Protocol), the WWW-Authenticate: Payment challenge has a realm that is not the service's own host, often a leftover from a template or a gateway domain. Clients may refuse a challenge for another domain. Set it to your own host (or its base domain):

WWW-Authenticate: Payment id="…", realm="api.example.com", method="tempo", intent="charge", request="…"

5. The 402 asks more than the listing says

73 endpoints. The price in the 402 is higher than the price in the listing the agent found. A careful agent stops there: x402 Doctor's preflight says caution for a higher price and no_go from ten times the listed price. Keep one source for the price:

const PRICE = "$0.01"; // one source for the route config and for every listing that shows the price

6. Stellar: the asset is a name, not the token contract

47 of 631 Stellar endpoints (7%), from 3 sellers. The asset field says "USDC" or "USDC:G…", but the official @x402/stellar client expects the address of the USDC token contract. Its payments fail before they start. With a dollar price ("$0.01") the SDK fills in the right asset; otherwise:

"network": "stellar:pubnet",
"asset": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75"  // USDC (Soroban token contract), not "USDC"

Every Stellar endpoint and its status: x402-doctor.fizzl.eu/stellar. More in x402 on Stellar.

7. The Bazaar example has no input that works

The discovery extension in the 402 tells agents how to call the route. When its example has no parameters, or parameters the route rejects, an agent that found the route through the Bazaar sends a bare request, pays, and gets an error back. In x402 Doctor's spot-buy of 18 October, 3 of 27 purchases ended with an error after paying: 404, 404, and a 400 that said missing_required_parameters. None of them charged, but the agent got nothing. Declare a real example, and check input before you settle the payment:

import { declareDiscoveryExtension } from "@x402/extensions/bazaar";

const discovery = declareDiscoveryExtension({
  method: "GET",
  input: { symbol: "BTC" },                                   // a real request that works
  inputSchema: { properties: { symbol: { type: "string" } }, required: ["symbol"] },
  output: { example: { symbol: "BTC", price: 67000 } },
});
// In the route config: extensions: discovery

And one security bug: HEAD gets the paid answer for free

A bug in the x402 SDKs (x402-foundation/x402#3796) let some paid GET routes answer a HEAD request with 200 and the full work behind it, without payment. Anyone can make such a server do paid work for free. Update @x402/core and your framework adapter to a release with the fix, or refuse HEAD on paid routes until then. x402 Doctor's web check flags it as head-unpaid.

// Until your @x402 packages include x402-foundation/x402#3796: refuse HEAD on paid routes.
app.use((req, res, next) => (req.method === "HEAD" ? res.sendStatus(405) : next())); // before paymentMiddleware

Check your endpoint

Free web check: x402-doctor.fizzl.eu reads your 402 the way a paying agent does, flags every problem above and gives the fix as code for your stack.
In CI: npx github:Fizzl13/x402-doctor <url> (exits 1 on failures), or the GitHub Action Fizzl13/x402-doctor-action@v1.
For the CDP Bazaar: Coinbase's free validate API. How it compares to six other checkers: x402 endpoint checkers compared.

How we measure

Every endpoint listed in the CDP Bazaar, Circle's Agent Marketplace, the MPP directory and other public x402 indexes is called once a day without paying, and its 402 is checked the way a paying agent would. Counts are endpoints in the scan of 17 October 2026 with that problem; one endpoint can have more than one. The weekly spot-buy pays up to 30 random endpoints that look payable, at most $0.05 each. The whole index is an open dataset on Hugging Face (CC BY 4.0), and the overall picture is in We check 50,000 paid x402 endpoints every day.

Questions

What is a resource mismatch in x402?

The 402's resource.url names another URL than the one the agent called: a relative path, another host, or http instead of https. Clients and indexes that check it refuse the challenge. On 17 October 2026 it was the most common problem among paid x402 endpoints, on 2,009 of them.

Why doesn't my x402 endpoint show up in the CDP Bazaar?

The Bazaar indexes a route after its first payment settles through the CDP facilitator, and only when the 402 is valid: resource.url must be the exact public https URL, the listed method must answer 402, and the discovery extension should declare an example request that reaches the paywall. Coinbase's free validate API and x402 Doctor's free web check show which of these fails.

Why does an agent get a 402 again after paying?

Usually the seller's facilitator could not settle the payment (the 402 or its PAYMENT-RESPONSE header then carries an error such as settlement_failed), or the server did not see the payment: x402 v2 clients send it in the PAYMENT-SIGNATURE header, v1 clients in X-PAYMENT. Check the facilitator's logs and that the payment middleware runs on the paid route for that method.

How can I test my x402 endpoint for free?

x402 Doctor's web check at https://x402-doctor.fizzl.eu reads your 402 the way a paying agent does and gives each problem with the fix as code for your stack; npx github:Fizzl13/x402-doctor <url> and a GitHub Action run the same check in CI. Coinbase's validate API checks whether the CDP Bazaar can index the route.

Originally published at fizzl.eu.

We check 50,000 paid x402 endpoints every day. Here's what works and what breaks.

Frits Zwager — Sat, 17 Oct 2026 21:06:34 +0000

x402 lets an API ask for payment with an HTTP 402 Payment Required answer, so an AI agent can pay per call in stablecoins without an account or API key. Before an agent pays an endpoint it has never seen, it wants to know two things: will the payment go through, and will it get what it paid for? x402 Doctor checks that for every paid endpoint we can find, every day. This is what the October data shows (scan of 17 October 2026, live numbers).

In short:

50,373 paid endpoints checked on 17 Oct (x402 and MPP)
93% payable as advertised
41% of all payable endpoints belong to one seller
$0.01 median price per call

1. Most endpoints work

Of the 50,373 endpoints that answered on 17 October, 46,906 (93.1%) were payable as listed. 2,392 (4.7%) got a caution, usually a detail that some clients refuse, and 1,074 (2.1%) a no_go: an agent should not pay them. 49,955 were x402 endpoints and 418 MPP (Machine Payments Protocol) endpoints.

The scan has grown fast: from 16,598 endpoints on 23 September to over 50,000 now, as new sellers list their APIs in the CDP Bazaar and in Circle's Agent Marketplace.

2. One seller holds 41% of the market

The index counts 61,860 payable endpoints. They come from 2,034 sellers, who sell 25,273 distinct services: many sellers publish the same service under thousands of URLs, one per ticker, city or query. The largest, datapackvibe.com, alone has 25,621 endpoints (41%) for 1,174 services. The ten largest sellers together hold 60% of all payable endpoints.

For an agent that means a catalog of "60,000 APIs" is closer to 25,000 services, and that one seller's uptime moves the whole market's numbers.

3. Base carries almost everything

Network	Share of payable endpoints
Base	97%
Solana	21%
Polygon	11%
Arbitrum	8%
Tempo	6%
Algorand	5%
XRP Ledger	4%
Arc (Circle)	4%

30% of payable endpoints accept more than one network, so the shares add up to more than 100%. 4% also offer Base Sepolia, a testnet, next to mainnet.

On Stellar we find 631 endpoints from 6 sellers. 47 of them (7%), from 3 sellers, can't be paid by the official @x402/stellar client: they give the asset as "USDC" or "USDC:G…" instead of the USDC token contract (every Stellar endpoint).

4. Prices: a cent is the norm

The median price is $0.01 per call. 80% of payable endpoints charge $0.01 or less, and under 1% charge $1 or more.

5. What breaks, and how to fix it

The problems we see most on 17 October, with the fix (the free web check gives the exact code per endpoint):

Problem	Endpoints	What it means, and the fix
Resource mismatch	2,009	The 402 names another URL than the one called (a relative path, another host, http instead of https). Clients and indexes that check the resource refuse it. Put the full public https URL of the route in `resource`.
No 402	1,042	The listed URL doesn't answer 402 at all (404, 401, a login page, or a 402 only on POST while the listing says GET). Answer 402 on the listed method, or fix the listing.
Testnet only	206	Only a testnet is offered, so mainnet agents can't pay. Add a mainnet option.
MPP realm mismatch	102	An MPP challenge names another host as its realm. Use the service's own host.
Price above advertised	73	The 402 asks more than the listing says. Keep listing and 402 in sync.
Invalid challenge	20	The 402 can't be parsed as x402 (missing fields, wrong types). Use the official SDK's middleware.

6. We paid 27 random endpoints

A valid 402 doesn't prove the seller delivers. Every week x402 Doctor buys 30 random endpoints that look payable, one per host, with its own wallet and their declared example input (at most $0.05 each), and records what comes back. In the run of 18 October, 3 endpoints were no longer payable when we got to them, so we didn't pay them; of the 27 we bought:

20 delivered a proper answer;
4 answered 402 again after our payment, and didn't charge;
3 answered with an error and didn't charge;
0 took the money without answering.

That is 74.1% paid and delivered, for $0.38 in all. The week before, on 12 October, 24 of 29 delivered (82.8%), and nobody took the money without answering then either. Results of every run: the Trust Index.

7. Bait and sanctions

An AI check reads every service's description for lures aimed at agents, such as promises no API can keep or impersonation of another brand. Of 7,890 services checked, 6 were flagged, for example "real-time guaranteed-profit racing arbitrage across all bookmakers".

Every payout address is screened against the OFAC SDN list (1,050 crypto addresses, published 15 October). None of the sellers' payout addresses is on it.

How we measure

Sources: the CDP Bazaar, Circle's Agent Marketplace, the MPP directory, GoPlausible and other public x402 indexes, read every day.
The check: each endpoint is called once without paying. Its 402 is parsed and checked the way a paying agent would: a valid challenge, the price against the listing, the network and token, whether the payout address can receive (USDC trustline on Stellar, opt-in on Algorand), the OFAC list, and testnet-only offers. Nothing is paid.
The purchases: only the weekly spot-buy pays, 30 endpoints at most $0.05 each.
Open data: every endpoint's 30-day record is free at GET https://x402-doctor.fizzl.eu/api/trust?url=<endpoint>, and the whole index is an open dataset on Hugging Face (CC BY 4.0, updated daily).

Check an endpoint yourself

Sellers: the free web check diagnoses your 402 and gives the fix as code.
Agents: before paying an unknown endpoint, GET https://x402-doctor.fizzl.eu/api/v1/preflight?url=… answers go, caution or no_go for $0.001, also as an MCP tool. Instructions for agents: skill.md.

Originally published at fizzl.eu.