DEV Community: SWARM operator

x402 seller gotchas, part 4: one payment, five deliveries, and first buyers that were robots

SWARM operator — Wed, 21 Oct 2026 08:10:12 +0000

In part 1 we listed what broke while selling small services over x402 (pay per request, USDC on Base). Part 2 put the shop behind an MCP server, and part 3 was about numbers that counted the wrong thing.

This week we launched two new services at $0.002 each: one checks whether a URL is up, the other returns the readable text of a web page. Launching them surfaced six gotchas. Three are bugs that would have cost money. Three are about who shows up once you are listed.

The lesson that matters most: test your payment path with the same tools a stranger would use, at your real price, and several requests at once. Most of our bugs only showed up that way.

One signed payment, five deliveries

We read Ishween Kaur's "Your Agent Paid. That Does Not Mean It Should Have." (Daily Context, on DEV) and tried the obvious attack on our own shop: send the same signed payment five times, at the same moment.

We got five full answers and one charge. Our shop wrote the payment's nonce down only at the end, after settling. Five copies all passed the "not seen before" check before the first one finished.

Fix: reserve the payment the moment it arrives, before doing any work. The first copy gets the work. The others get a 409 Conflict and nothing else. We tested it on a copy of the shop the same day: five requests, one delivery, one charge.

A price of 0.2 cents rounded to free

Our shop stored prices in whole US cents. That was fine at $0.02 and up. The new services cost $0.002, which is 0.2 cents, and in an integer field 0.2 becomes 0.

We caught it while building the new routes, before launch. Had it shipped, the route would have quoted a price of zero.

Fix: we now convert prices with fractions instead of whole cents. If you are starting fresh, keep prices in the asset's atomic units (USDC has 6 decimals, so $0.002 is 2000), and check at startup that no paid route quotes 0.

The official buyer library refused to pay us

Our own test purchase of the new routes failed, and not on our side. The buyer library we used, @x402/core 2.28, has a spending check that is on by default. It rounds amounts to two decimals, so it read our $0.002 as $0.00 and refused to pay, with an error that showed the amount as $0.00.

Any agent using that library with its defaults would have failed at our price, and the error points nowhere useful.

Fix: on the buyer side, client.setSpendControls(false) turns it off. Only do that if you keep your own price check. We did both in our MCP server, so its users can pay sub-cent routes. On the seller side: buy from yourself with the libraries your buyers use, at your real price, before you announce anything.

Your first buyers are robots

Our first paid call from outside came 3.5 hours after the new route appeared in Coinbase's catalog. It looked like a customer. Then we read the wallet's history: 1,000 payments to 973 different addresses in four days. It was a sweeper that pays every new listing once.

The next two paid calls, eight hours later, came from a client that names itself lumiere-paycheck-prober: it buys to check that sellers charge and deliver. In the same 24 hours we received 9 to 14 payments built wrong on purpose, mostly from one wallet: a missing field, a header that is not base64, 1 unit instead of 2,000, the wrong payTo, an authorization already expired or not yet valid. We rejected all of them without charging.

On 20 Oct a client called x402-list-unfunded-study tried four of our services from two wallets that had never paid anyone. In three days the two new routes answered about 2,600 price requests. Every top requester was a monitor, a probe, or our own script.

Fix: before you count a buyer, check how many sellers that wallet pays (100+ addresses means a sweeper), read the client's User-Agent, and keep a list of known probes. A listing gets robots within hours. Customers are a different question.

Failed payments left no trace

If someone paid and our shop refused (bad signature, short amount, a repeated nonce), the buyer got an error and we got nothing. No log line, no counter. A real customer could have tried and failed, and we would never have known.

We noticed this reading Payload's "Paid and blocked" on DEV.

Fix: every refused payment now goes to a log with the time, route, reason and payer address. It shows in our morning report, and a wallet we have never seen before triggers a Telegram alert. That alert is how we caught the unfunded study above in three commands, instead of mistaking it for a buyer who could not pay.

Registered is not found

We registered the shop with AgentCash, an agent wallet with its own search. Its validator reads our six routes, prices and guidance with no warnings. We still appear zero times in its search, even for "check if a website is up".

One of its maintainers explained it to another seller with the same problem: a listing only starts showing in search after it gets some use through trusted sources such as their own wallet. Meanwhile the listing that ranks first for that query shows zero purchases in the directory, while on-chain it has been paid by 72 different addresses in three months.

Fix: none on our side. The listing was never broken. We stopped editing it, made it easy for anyone who already finds us elsewhere to call us through that wallet, and count our buyers on-chain instead of trusting any directory's numbers.

Where it stands

Customer sales are still zero. Every outside payment so far has been a sweeper, a probe or an inspector. The new routes stay up until 30 Oct, and they stay after that only if two or more outside wallets pay and come back.

If your agent buys x402 services, we'd like to know what it pays for twice: contact@swarm-agent.net.

The shop: swarm-agent.net · the MCP server is open source (MIT): github.com/swarm-agent-operator/swarm-x402-mcp.

One month of an AI agent trying to pay its own way: 0 sales, and the numbers behind it

SWARM operator — Thu, 15 Oct 2026 11:59:09 +0000

SWARM is an AI agent that runs 24/7 on a small rented server and sells tiny services to other AI agents at swarm-agent.net. It gets paid per request with x402: the server answers "402 Payment Required" with a price, the client pays in USDC on Base, and gets the result. No accounts, no contracts.

The goal from day one was an agent that "works alone, finds its own way and pays its own bills". This is the honest report of month one.

Short version: the hard technical part is done and it works. In a month, no outside buyer has paid for anything. So the project has moved from "build the shop" to "find out what the market actually buys".

Where it stands

The shop works end to end: quote, payment check, work, charge only if the work succeeds, receipt. Four services, from $0.02 to $0.99: small utilities, a GitHub repo health check, and two web-research reports with linked sources.
It's listed almost everywhere an agent might look: Coinbase's Bazaar, x402scan, AgentCash, x402-list, Glama, mcprush, the official MCP registry, and npm (we wrap the shop in an MCP server so Claude or Cursor can use it).
Cost: thinking costs about $1.5 a day (hard cap $2). Server and domain, about €7.50 a month. The owner pays both, for now.

The numbers, and how they add up

Every morning a small script counts what happened. After a reader's comment on Moltbook, we changed it so the buckets visibly add up to the total. "We filtered out our tests" is a claim. A sum that closes is something you can check.

BALANCE: 18 payments in the book (since day one)
        = 0 sales + 17 our own tests + 1 inspector

0 sales to anyone else.
17 test purchases from our own wallet. They're not income. We make them to test the shop, and because Bazaar delists services after 30 days without payments.
1 inspector: on 1 Oct, vet402, an automated checker, bought a $0.02 call to verify that our shop delivers. We count it as a quality signal, not a sale.

Traffic, last 7 days:

BALANCE: 21,316 requests = 19,371 from known bots + 1,945 from unknown clients

Almost all of it is directories, monitors and crawlers. There are about 500 MCP downloads a week, mirrors included, and zero purchase attempts through the MCP.

What went wrong (the short list)

The full details are in the x402 seller gotchas series. The ones that shaped the month:

The agent believed false things and acted on them, rationally. Its own prompt told it it had $0.51 left and was about to die, so it went to sleep for 4 hours to save money. The data was wrong, not the reasoning.
It shipped a paid endpoint that could be bypassed with one word in the URL. In production. We caught it in review. Since then, we assume internal rules are advice. The real controls are outside the agent: firewall, signed spending caps, human review.
The first products did nothing a buyer couldn't get for free. The "report" was one model call with no web search. We rebuilt them with real search and sources.
The shop charged before checking it could do the job. Fixed before it cost anyone money. Now it charges on delivery: if the work fails, you don't pay.
The API key expired after 30 days and no alert fired. The agent was up but couldn't think for about 30 hours.

What we learned about demand

Visibility is not demand. Being in many directories brings bots, not buyers.
Thinking is the expensive part, not selling. With the agent idle, about 14 sales of $0.02 a day would cover the fixed cost. With it thinking at full speed, you'd need twenty times that.
The market is small and concentrated. graded.sh's August report counted 292,967 paid calls in 30 days. The top ten services took about 80% of them, and the median price was $0.01. What sells are small pieces an agent uses mid-task: search, page reading, chain reads.
Our demand data was worse than we thought. Many sellers use one wallet for their whole catalog, so their buyer counts don't tell you which product sells. And "unique buyers" fields are often cumulative, not last 30 days.

The decision: measure before building

The plan was to pick a new product on 16 Oct. To choose, we ran an "arena": a group of AI agents competing to propose the best next step, judged against our own rules. The first round (9 Oct) picked a US trademark checker. When we looked at the evidence again, it didn't hold up, so that one is dropped.

The second round didn't pick a product. It picked a rule:

Build nothing until a comparable x402 seller shows real buyers on-chain: 5 or more distinct buyers in the last 30 days who come back, with our own probes and sweeper wallets excluded.
If one passes, build it at no more than that seller's price, at a cost under a third of the price, as a 14-day trial.
Note which chain that seller is paid on. A lot of x402 volume today is on Solana, and we only accept Base.

So we wrote a small reader that pulls each candidate seller's payments straight from the chain, keeps only real x402 settlements at the listed price, and drops one-off wallets. We tested it on our own shop first. It found our test payments and, with our own wallets excluded, correctly scored us as a fail.

What the chain says

We measured three candidates on Base, 15 Sep to 15 Oct:

Candidate	Paid at its price	After removing sweepers	Result
Site check (is this URL up?)	465 payments, 32 wallets	7 buyers who come back, ~23 payments each	PASS
Wallet sanctions check	159 payments, 12 wallets	1 buyer	FAIL
Page scrape	could not measure	public RPC rate limits and timeouts	unknown

Two things stand out.

Sweepers are most of the "buyers". Of 12 wallets paying for sanctions checks, 4 were sweepers: wallets that pay 100 or more different addresses, which is not how a buyer with one job behaves. Only one real buyer was left. For site checks, 5 of 12 went the same way.

Passing is not the same as money. The site-check seller uses one wallet for many products, with at least 10 different prices. So we can't be sure every $0.002 payment is a site check. And the 7 buyers paid about 200 times at $0.002. That's around $0.40 a month. The whole seller, all products together, took in roughly $15 a month in what we could see.

We also owe a correction. In part 3 we called this seller "single-product" with 35 buyers. Both were wrong: it sells many products, and once you keep only its listed price and remove sweepers, 7 buyers are left. We wrote about that exact trap, and then fell into it.

So the market for site checks is real, small, and paid by machines that check often. That fits our pilot goal: "someone pays once, even if it's cents". A site check needs no model call, so it costs almost nothing to run. Before building it, we'll put it on trial, the same way we tried the project. If it survives, it ships at $0.002 or less, as a 14-day test.

One more gap: our reader only reads Base. A lot of x402 volume is on Solana, and we couldn't see any of it. So we're also adding Solana as a second way to pay, next to Base, on all our services.

What's next

Track B starts on 26 Oct: the same agent, same rules, selling to people instead of machines. That's where the owner thinks the business is today. Track A (agent to agent) stays open. We think it will grow and we want to be there early.
Review on 15 Nov. It's a checkpoint, not a stop: outside sales, the new product (if any), track B, and how to split the budget.
Still not measured, and it should be: total spent since day one, and the owner's hours per week. A simulated "trial" of the project on 11 Oct flagged both as the costs that weigh most.

The agent always identifies itself as an AI, doesn't contact anyone who hasn't contacted it, and doesn't spend money or buy from other sellers. Outreach is done by me, by hand. If you build agents and one of these services would be useful to you, or if you think we're measuring the wrong thing, I'd like to hear it.

x402 seller gotchas, part 3: miscounted buyers, and an API key that expired quietly

SWARM operator — Wed, 14 Oct 2026 12:52:17 +0000

In part 1 we listed what broke while selling four small services over x402 (pay per request, USDC on Base). In part 2 we wrapped the shop in an MCP server. Part 2 ended with a promise: who actually buys in x402, once we have numbers we trust.

This part is about why that took longer than planned. Our numbers were wrong three times in one week: twice about other sellers, once about ourselves. There is also one gotcha that has nothing to do with payments, and it took our agent offline for 30 hours.

The lesson that matters most: before you trust a number, ask what it counts: which product, which time window, which files. Every number below was right about something. Just not about what we had asked.

A seller's buyers are not a product's buyers

Before building a new service, we check for demand. Our rule: a similar x402 service must already have 5 or more distinct buyers in the last 30 days, not counting probes. The obvious source is on-chain. x402 payments land on the seller's payTo address, and explorers count buyers per address.

The catch is that many sellers use one wallet for their whole catalog. A candidate looked like it had real buyers. But the wallet behind it also took payments for security scans, trademark checks and other products. Those buyers proved the seller sells something. They said nothing about that one product.

Fix: a seller only counts as evidence for a product when it sells just that product, or when the calls can be split by route. The clearest example we found was a single-product site-checking service: 35 buyers, about 41 payments each. That is demand you can read.

Cumulative is not "last 30 days"

Same week, second trap. The stats snapshot we used gives three fields per address:

recipient -> tx_count, unique_buyers, latest_block_timestamp

We asked for buyers in the last 30 days, and the snapshot can't answer that. unique_buyers counts from the address's first payment, and the timestamp is only the latest one. 500 buyers could be 500 in the first month and none since. Nothing in the field names tells you which.

Our agent answered "not computable from this data" instead of making up a number. That was the right answer. If you need a time window, you need the payments themselves, each with its timestamp, not a summary.

For the wider picture, per-service numbers do exist. graded.sh's August report,, built from its own probes, counted 292,967 paid calls in 30 days. The ten biggest services took about 80% of them, and one domain alone took 41%. 81% of the services with any demand had fewer than 10 calls. The median price was $0.01. So who buys in x402? A few agents, buying a few cheap things many times.

Read every log file, not just the newest

Then our own numbers were wrong, in the other direction. On 10 Oct our agent reported that no payment had ever completed on our shop: 568 quotes, 0 paid calls. It had read nginx's access.log. But logrotate had moved older days to access.log.1 and compressed the rest. The paid calls were in those files.

What it read (result: 0):

grep ' /services/' /var/log/nginx/access.log | awk '$9 == 200' | wc -l

What it should have read:

zcat -f /var/log/nginx/access.log* | grep ' /services/' | awk '$9 == 200' | wc -l

Now the less flattering part. All 8 paid calls in those files were ours (test purchases from our own wallet) or from an inspector checking that payment works. Not one customer. So "no customer has paid yet" was true. "No payment ever completes" was false. The difference matters: the first is a demand problem, the second a broken checkout. Had we believed it, we would have spent days fixing a checkout that works.

Fix: count across every rotated file, and take out your own wallet's payments before you count anything. Better still, count settled payments on-chain, which never rotate.

The API key expired, and nothing alerted

This one isn't about x402. SWARM thinks through the Anthropic API. When we created its key, we set it to expire after 30 days. That's a sensible precaution, until you forget it. On 11 Oct it expired, and every model call returned:

401 authentication_error: invalid x-api-key

The server stayed up, the shop kept answering, and the agent's process kept running and retrying. It just couldn't think, for about 30 hours. We have a Telegram alert for model calls failing, but it only matches one error: out of credit. An invalid key is a different error, so the alert stayed silent. We only noticed at the next morning's check.

Fix: a new key, with its expiry date in the calendar and a reminder a few days before. The sturdier fix is to alert when success stops, as in "no successful model call in N hours", instead of matching error messages one by one. We haven't built that: for a hobby project, the calendar reminder is enough. If your agent earns money while it thinks, build the heartbeat first.

Where it stands

Customer sales are still zero. Every paid call on our shop so far was ours or an inspector's. What changed is that we now trust that zero, and we know what the numbers about other sellers mean. We're choosing the next product by per-product demand.

If your agent buys x402 services, we'd like to know what it pays for: contact@swarm-agent.net.

The shop: swarm-agent.net · the MCP server is open source (MIT): github.com/swarm-agent-operator/swarm-x402-mcp.

x402 seller gotchas, part 2: putting a paid API behind an MCP server

SWARM operator — Thu, 08 Oct 2026 10:07:56 +0000

In part 1 we listed every error we hit selling four small services over x402 (pay per request, USDC on Base). That was about being found, getting paid and delivering.

This one is about the next step. Most people who could buy from us are building agents, and agents increasingly pick their tools from MCP directories. So we wrapped the shop in an MCP server, swarm-x402-mcp, and shipped it to npm, the official MCP Registry, GitHub, Glama and mcprush. It took three releases in four days to get the directories to show it correctly. These are the gotchas, in the order we hit them.

The lesson that matters most: most directories never run your server. They read your package, your repo or a registry record, and each one reads a different source. If your tools only exist at runtime, a directory can't see them.

Tools that only exist at runtime

Our first two versions built the tool list from the live shop: on startup (0.1.0) or on the first tools/list (0.1.1), they fetched /offers and /openapi.json and turned each offer into a tool. It felt right. Add a service to the shop and every client gets it, no release needed.

A directory that reads the published package saw this:

0 tools

mcprush, for one, reads tools from the published source when it can't query a running server. There was nothing to read: the tools were a loop over a fetch.

Fix: declare each tool in the code, with its schema and price in the description. We lost "new services appear by themselves"; now a new service needs a release. That's the right trade: a buyer's agent should know what it's installing.

server.registerTool("utilities", {
  title: "SWARM utilities",
  // abridged
  description: `UUIDs, hashes, base64, URL encoding, passwords, timestamps. Price: $0.02 per call. ${PAID}`,
  inputSchema: { op: z.string().describe("Operation, e.g. uuid, hash, base64"), /* ... */ },
  annotations: { title: "SWARM utilities", ...REACH },
}, (args) => call("/services/utilities", args));

Paid tools are not read-only

Our tools don't change anything for the caller, so it's tempting to call them read-only. They aren't: every call goes over the network and, with a wallet configured, spends money. MCP has annotations for exactly this, and a client deciding whether to ask its user before a call reads them:

// Every tool reaches the network and may spend USDC: not read-only, open world.
const REACH = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };

After 0.1.2, mcprush still showed all four tools as "read". We opened a ticket. Their answer, the next day: the fault was theirs. Their source reader dropped annotations declared beside each tool, including a shared constant spread in like our REACH, and guessed the kind from the tool name. They fixed the reader, and the tools now show as "write", their highest kind, which includes reaching the network. Credit to them for a fast, clear reply.

Two takeaways. Declare the annotations even if nobody reads them yet. And if a directory shows them wrong, check your code, then report it: in our case the directory was wrong, and fixed it for everyone.

Check the quote before you pay

An MCP client can call a tool without a human looking at the price. So the server reads the 402 quote first, without paying, and refuses anything off Base mainnet or above a cap the user sets (SWARM_MAX_USD, default $1). Only then does it pay with the official client:

const q = await fetch(BASE + route, init);                       // no payment yet
if (q.status !== 402) return text(`Expected a 402 quote, got HTTP ${q.status}`, true);
const accept = ((await q.json()).accepts ?? []).find((a) => a.network === "eip155:8453");
if (!accept) return text("No payment option on Base mainnet; not paying.", true);
const usd = Number(accept.amount) / 1e6;                         // atomic units → dollars
if (!(usd <= MAX_USD)) return text(`Price $${usd.toFixed(2)} is above SWARM_MAX_USD; not paying.`, true);
const r = await pay(BASE + route, init);                         // now pay

!(usd <= MAX_USD) rather than usd > MAX_USD on purpose: if the amount is missing or garbage, usd is NaN, every comparison is false, and the first form refuses while the second would pay.

No wallet is a normal state, not an error

Most people who install the server won't have a wallet key set. If the tool just fails, their agent learns nothing. So without a key it quotes and explains:

This tool costs $0.02 per call, paid in USDC on Base via x402. Set SWARM_WALLET_KEY to the
private key of a wallet holding a little USDC on Base (use a dedicated wallet with only a few
dollars) and call again.

Every directory reads a different source

This is what we had to push on each release:

Where	What it reads	What a release takes
npm	the package	`npm publish` (2FA)
Official MCP Registry	a `server.json` record pointing at the npm package	`mcp-publisher publish`
GitHub	the repo	push + a Release
Glama	the repo, built in a Docker sandbox	in our case, by hand: sync, then Build & Release
mcprush	the npm package (when it can't run the server)	cut the release in their studio, then "Read the tools again"
PulseMCP	the official registry	nothing: submissions are paused, and they say they'll pick up registry entries when they reopen
Smithery	for a local stdio server, an `.mcpb` bundle	not done yet

Two of these caught us out.

Glama kept building the old commit. Its last sync was days old and a pinned commit SHA was set, so "new version" meant "the version we already had". Syncing the repo and clearing the pinned SHA fixed it. Its first rebuild then failed with an internal error on their side; the retry passed.

Versions are spent once. npm and mcprush both refuse a version number that has shipped. mcprush's release form even comes pre-filled with the next minor (0.2.0 for us) instead of the next patch, so read it before you press publish.

Count calls, not reads

We log requests from our own MCP server by its User-Agent. The day after 0.1.2 shipped, the counter for the past week said 44 requests from 11 different addresses. It looked like eleven people using our tools.

It was zero. Grouping by version:

     34 swarm-x402-mcp/0.1.0
     10 swarm-x402-mcp/0.1.1

All of it was the old versions fetching /offers and /openapi.json at startup: old installs, and directories starting the server to inspect it. None of the eleven called a paid route. The fix is in what we count: requests to /services/*, not catalog reads.

Keep the 2FA in the loop

People who use the server put a wallet's private key in its environment. Whoever can publish a new version of our package can read that key on the user's next npx. So we don't keep an npm automation token anywhere: every publish goes through 2FA on a phone. It makes releases slower and we're keeping it that way.

Where it stands

The server is live everywhere above except PulseMCP (paused) and Smithery (bundle not done yet). Sales through it so far: zero, same as through the shop directly. Being listed is not being bought, and part 3 is about who actually buys in x402, and why our first numbers were wrong.

The server is open source (MIT): github.com/swarm-agent-operator/swarm-x402-mcp.

We put our x402 shop behind an MCP server

SWARM operator — Mon, 05 Oct 2026 08:00:31 +0000

After quite a lot of research and testing, we've come to one conclusion: x402 buyers don't show up on their own. Behind every agent that buys, there's a person who set it up. That's why we've published an MCP server, so any agent can use our services and pay per use, with no account and no API key.

Before signing anything, it reads the price and compares it with the limit set by the wallet's owner. It pays on Base, and if no wallet is configured it doesn't pay, it only shows the price. The tools are read live from the shop, so a new product shows up without updating anything.

As of today we haven't made a real sale, one that isn't a test, but the experiment is on the right track, and that's why we're sharing how the process is going.

To try it, just follow this link: https://swarm-agent.net/mcp/

Source code: https://github.com/swarm-agent-operator/swarm-x402-mcp

Previous post: what broke our x402 shop and how we fixed it → https://dev.to/swarmagentoperator/x402-seller-gotchas-what-broke-our-402-and-how-we-fixed-it-2ao1

x402 seller gotchas: what broke our 402, and how we fixed it

SWARM operator — Mon, 28 Sep 2026 15:11:20 +0000

Updated 2 Oct 2026: three new gotchas, all ours — why we were never listed in the Coinbase Bazaar, an expiry check this article recommended that rejected the official client, and a quote that grew too big for nginx.
We run SWARM, an autonomous agent that sells four small services over x402, paid per request in USDC on Base. We spent a month getting it right. By the end it was listed on x402scan and graded A on x402-list, 14 of 14 checks.

And on the morning we sat down to write this up, we found that a buyer using the official x402 v2 client could not pay us at all. Grade A and all. This is every error we hit, with the exact message where we have it, what was actually going on, and the fix.

The lesson that matters most: directories don't pay. They check your quote, not your checkout. The only test that catches payment bugs is buying from yourself, with the official client, the way a stranger would. Our own test buyer didn't catch them either, because we wrote it in the same outdated dialect as our server.

Being found
x402scan finds no discovery document
The first thing x402scan told us when we registered: it couldn't find a discovery document, a machine-readable list of what you sell. A working 402 on its own isn't enough to be listed.

Fix: serve /openapi.json describing each paid route, with an x-payment-info block per operation. We also serve /.well-known/x402. Generate both from the same list of offers your 402 uses, so they can never disagree with it.

Two warnings x402scan shows once it does find it, both worth fixing:

Add info.contact.email to your openapi.json to verify ownership and let users contact you.
Serve a /favicon.ico at your API root to display an icon.
[404] No valid x402 response found
Our paid routes were POST-only. The prober asked with a different method and got a 404, so as far as it was concerned the route wasn't there.

Fix: answer the 402 quote on GET and HEAD too, not only on the method that does the work. Quoting a price costs nothing, so there's no reason to hide it behind a method.

[402] No valid x402 response found
The confusing one: the tool tells you it found no valid 402 while your server is returning a 402. Ours had the payment requirements in the JSON body only. x402 v2 puts them in a header. From the x402 docs:

PAYMENT-REQUIRED: Contains the Base64-encoded payment requirements from the server. This header is returned alongside the 402 status code.

Other people hit the mirror image: requirements in the header only, empty body, and clients that read the body can't pay. Send both. And expose the header, or browser-based clients can't read it:

js
const body = JSON.stringify(paymentRequired);
res.writeHead(402, {
"Content-Type": "application/json",
"PAYMENT-REQUIRED": Buffer.from(body, "utf8").toString("base64"),
"Access-Control-Expose-Headers": "PAYMENT-REQUIRED",
});
res.end(body);
Dollars in one place, atomic units in the other
The same price is written two different ways, and mixing them up gets you flagged as a malformed amount:

Where 0.02 USDC is written as
openapi.json → x-payment-info.price.amount "0.020000" (US dollars, decimal)
the 402 → accepts[].amount "20000" (atomic units, USDC has 6 decimals)
json
"x-payment-info": {
"price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" },
"protocols": [{ "x402": {} }]
}
Relative resource URLs
Behind a reverse proxy, our server only saw its own path and put /services/summary in the 402's resource field. Anything that indexes your 402 needs the full address. Build it from your public base URL (or X-Forwarded-Proto + Host if you trust your proxy), never from what the app sees locally.

Let the prober call you
x402scan's own hint when an endpoint fails is worth reading closely:

They need to return a 402 payment challenge — ensure the x402 paywall runs before request validation, or mark the required parameters in your OpenAPI spec so we can probe automatically.

Two fixes in one sentence. Quote before you validate: a request with no payment and no body should get the 402, not a 400 about missing fields. And describe your inputs (an input schema and a real example per offer) so a prober, or a buyer's agent, knows how to call you.
Settled, but never in the Coinbase Bazaar

Twelve test purchases settled through Coinbase's facilitator, and the Bazaar never listed us. There are open issues from other sellers in the same spot, so for a week we called it Coinbase's bug and stopped looking. Two of the causes were ours.

One: our discovery extension was incomplete. It had info.input but no schema. Coinbase's own validator (agentic.market/validate) said so plainly:

invalid discovery configuration
v2 discovery extension validation failed: [Schema validation failed: schema is invalid]

Two: the indexer reads it from the payment, not from your 402. At settle time it looks in PaymentPayload.resource and PaymentPayload.extensions. The official client doesn't copy them there, and our hand-written adapter to the facilitator only passed x402Version, accepted and payload. A perfect 402 never reached the indexer.

Fix: generate the extension with the official helper instead of writing it by hand, and attach resource and extensions to the payload you hand the facilitator. That doesn't touch the buyer's signature, which only covers the transfer authorization.

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

const extensions = declareDiscoveryExtension({
  method: "POST", bodyType: "json",
  input: { op: "uuid", n: 2 },          // a real example request
  inputSchema: { /* JSON Schema of the body */ },
});
// in the 402:   { x402Version: 2, accepts: [...], resource: {...}, extensions }
// at verify/settle:
facilitator.settle({ ...paymentPayload, resource, extensions }, requirements);

Then validate (the validator probes with GET by default; pick your route's method or it flags a mismatch) and make one real purchase. Ours was listed the next morning. Each route needs its own settlement: only the one we had paid for showed up.

Your quote outgrows nginx

x402 v2 sends the whole quote twice: in the JSON body and, base64-encoded, in the PAYMENT-REQUIRED header. Everything you add to the quote, like the discovery extension from the section above, makes that header bigger, and base64 adds a third on top.

We added a real response example to each route's discovery extension, so buyers and inspectors can see what they get before paying. On three of our four routes that pushed the quote header past 4,000 characters (the largest was 4,504). nginx reads an upstream's response headers into one buffer of 4 KB or 8 KB by default, one memory page, and those three routes stopped answering:

upstream sent too big header while reading response header from upstream

The route with the smallest example still fit, so it looked fine. The other three were down for about eight minutes, until we checked all four from outside. Our handler for nginx errors turned it into a polite 503 saying nothing was charged, which was true. Nobody could buy anything either.

Fix: give nginx room for the header, and after any change to what the quote carries, check every paid route from outside, not one:

proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;

And keep the quote lean: short examples, and anything long belongs in /openapi.json, not in every 402. Other proxies in the chain have header limits of their own.
Getting paid
X-PAYMENT header is required
Our 402 said "x402Version": 2. Our server read the payment from X-PAYMENT, which is the v1 name. A v2 client takes you at your word and sends the payment in PAYMENT-SIGNATURE. We didn't see it, answered with another 402, and the buyer was stuck in a loop: pay, get asked to pay. Nothing was charged, but nothing was sold either.

v1 v2
buyer sends payment in X-PAYMENT PAYMENT-SIGNATURE
seller returns receipt in X-PAYMENT-RESPONSE PAYMENT-RESPONSE
Source: x402 migration guide, v1 to v2.

Fix: accept both, new name first. And allow it through CORS, or a browser won't even send it:

js
const raw = req.headers["payment-signature"] ?? req.headers["x-payment"];
// Access-Control-Allow-Headers: Content-Type, PAYMENT-SIGNATURE, X-PAYMENT
Quick way to check your own server without spending anything: send garbage in each header and compare the errors. If the new one says the header is missing while the old one says it's malformed, you're only reading the old one.

bash
curl -s -X POST -H "X-PAYMENT: junk" https://your-api/paid-route
curl -s -X POST -H "PAYMENT-SIGNATURE: junk" https://your-api/paid-route
unsupported scheme: undefined
Fixing the header name isn't enough, because the payload changed shape too. In v1, scheme and network sat at the top of the payment payload. In v2 they live inside accepted, the option the buyer picked from your quote. From the type in @x402/core 2.25.0:

ts
type PaymentPayload = {
x402Version: number;
resource?: ResourceInfo;
accepted: PaymentRequirements;
payload: { [key: string]: unknown };
extensions?: { [key: string]: unknown };
};
A hand-written v1 decoder looks for p.scheme, finds nothing, and rejects a perfectly good payment. The signature and authorization inside payload are the same in both versions for the exact scheme, so the fix is small:

js
const p = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
const scheme = p.accepted?.scheme ?? p.scheme; // v2 : v1
const network = p.accepted?.network ?? p.network; // v2 : v1
paymentStatus: none
After fixing the two above, a purchase with the official client worked: 200 in 1.1 s, the USDC moved. And the client reported:

paymentStatus = none
The buyer paid, and their software believes they didn't. We were settling, writing the transaction to our own ledger, and returning only the product, with no receipt. An agent keeping its own books records $0 spent, and its owner later finds a charge the agent says it never made. That's the opposite of trust.

Fix: return the settlement as a receipt, base64 JSON, in both header names:

js
const receipt = Buffer.from(JSON.stringify({
success: true,
transaction: settle.transaction,
network,
payer, // authorization.from
}), "utf8").toString("base64");
res.setHeader("PAYMENT-RESPONSE", receipt); // v2
res.setHeader("X-PAYMENT-RESPONSE", receipt); // v1
res.setHeader("Access-Control-Expose-Headers", "PAYMENT-RESPONSE, X-PAYMENT-RESPONSE");
Same purchase afterwards: paymentStatus = settled.

A bad signature returns 500
Given a malformed signature, the facilitator doesn't always answer "not valid". It can throw, and if nothing catches it, your buyer gets a 500, which tells them your server is broken. What we got back from a deliberately fake signature:

invalid_exact_evm_payload_signature: invalid signature: public key recovery code 44 is not in the valid range [27, 34]
Fix: catch it, and tell the two cases apart. A payment problem is a 402 with the reason. Anything else (the facilitator being down) is a 503: telling a buyer "your payment is bad" when the problem is on your side makes them re-sign in a loop.

js
try {
result = await facilitator.verify(payload, requirements);
} catch (e) {
const msg = String(e?.message ?? e);
if (/invalid|insufficient|expired|mismatch/i.test(msg))
return send402(facilitator rejected payment: ${msg});
return send503("payment verifier unavailable. Nothing was charged; retry later.");
}
Delivering what was paid for
Promising 360 s behind a 300 s proxy
Two separate clocks, both ours. First, we built payment requirements without maxTimeoutSeconds, so every offer promised the 60-second default. Our full report takes two to four minutes. Second, once we fixed that to 360 s, nginx in front of it was still set to cut upstream responses at 300 s. We found this one by reading the config, before it caught a buyer, but it would have been the worst kind: payment settled, nothing delivered.

Fix: set maxTimeoutSeconds per offer to what the work really takes, say it in the description, and keep every proxy in front above it:

nginx
location /services/ {
proxy_pass http://127.0.0.1:8004;
proxy_read_timeout 420s; # above the longest promise (360 s)
proxy_send_timeout 420s;
}
Charging before delivering
Our first flow was verify, settle, do the work, respond. If the work failed or the buyer's client gave up waiting, they had paid for nothing, and the only remedy was a manual refund.

Fix: verify, do the work, settle, respond. Verification already proves the payment is good, so a fake signature still can't make you work for free. If the work fails, you don't settle: the buyer keeps their money and you lose the compute. That's the right way round.

verify → do the work → settle → respond with product + receipt
└─ work failed? don't settle. They keep their money.
Signatures that expire mid-job

Settling last creates its own trap. The buyer's authorization has a validBefore. If it expires while you're still working, you deliver and then can't collect, every time, from that buyer.

Our first fix was wrong, and for three days this article recommended it. We refused any authorization that didn't live at least as long as the job could take:

const need = requirements.maxTimeoutSeconds;
if (Number(auth.validBefore) < now + need) return send402(...);   // don't copy this

It rejects the official client. The client signs validBefore = now + maxTimeoutSeconds, exactly what you quote. By the time the payment reaches you a second has passed, so it is always one second short:

payment authorization expires too soon: valid for 59s, but this offer can take up to 60s to deliver.

It slipped past us because our first test purchase happened to land inside the same second. The next one didn't. The refusals were in our logs the whole time; nobody was reading them. (We checked the full log: the only buyer it ever turned away was our own test.)

Fix: keep the check, with a margin for network latency and clock skew, and keep it above what the job really takes. Don't drop it to a flat 30 s: if you settle last, a three-minute job accepted with 35 s of validity is a job delivered for free.

const now = Math.floor(Date.now() / 1000);
const quoted = requirements.maxTimeoutSeconds;                // what you advertised
const need = quoted - Math.min(30, Math.floor(quoted / 2));   // margin: latency + skew
if (Number(auth.validBefore) < now + need)
  return send402(`payment authorization expires too soon. ` +
    `Re-sign with validBefore >= ${now + need}. Nothing was charged.`);

With our quotes that is 60 → 30 s, 180 → 150 s, 360 → 330 s, each still above how long the job really takes. And log every refusal somewhere you actually read.
And one that was ours alone
The field we made up
While building the discovery files we copied the shape of a field from another project's manifest instead of from the spec, and shipped it in a form the spec doesn't define. Nothing complained. It was just wrong. Validate your discovery files against the spec, not against somebody else's JSON, however well that project seems to be doing.

Buy from yourself, the way a stranger would

Four of the bugs above (the header name, the payload shape, the missing receipt, our own expiry check) were invisible to every directory, because none of them pays, and invisible to our own test buyer, because we'd written it in the same old dialect as the server. They showed up the first time we paid with the official client. Use a separate test wallet, not the one that receives the money.

This is the whole buyer, from the x402 quickstart. By default the official client refuses to pay more than $1 per request.

bash
npm install @x402/fetch @x402/evm viem
js
import { wrapFetchWithPayment, x402HTTPClient } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const pay = wrapFetchWithPayment(fetch, client);
const res = await pay("https://your-api/paid-route", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ /* your input */ }),
});

const result = await new x402HTTPClient(client).processResponse(res);
console.log(res.status, result.paymentStatus); // want: 200 settled
If you want a live v2 seller to point a client at while you build one, ours answers at https://swarm-agent.net/services/utilities, and the cheapest call is $0.02.

Originally published at swarm-agent.net/x402-seller-gotchas, where it gets updated as we hit new ones.

This article was written with AI assistance. The errors, outputs and fixes above come from our own server and were checked before publishing.