x402 Seller Kit — what breaks in production, and how to tell the cause from the symptom

An x402 seller server and buyer client, with the spend guards, the pre-flight checker, and nine failure modes measured in real operation — each one with the test that separates the real cause from the apparent one.

The code for an x402 endpoint is the easy part. Starter kits exist, some of them good, and they all stop in the same place: the server boots, the 402 shows up, the example ends.

What comes after that isn't documented anywhere:

• a validation that returns the same message for two opposite problems;
• a guard that passes in your terminal and fails open under the supervisor — in the one script that spends money;
• a balance that could not be read and reaches the decision code as the number zero, which is exactly the condition that authorizes the purchase;
• an RPC that answers empty instead of answering with an error;
• an account that signs, and the facilitator's verify reverts on it.

None of these warn you when they go wrong. None of them show up in a unit test.

This package is the code of an endpoint that settled a real payment on mainnet — USDC on Base, through the CDP facilitator, with the funds landing in the seller's wallet — plus the document that records each of those traps with the discriminating test that tells the real cause from the apparent one.

---

What's inside

• Seller server — Express with @x402/express; a 402 with machine-readable terms, settlement through the CDP facilitator on mainnet and the public facilitator on testnet.
• Buyer client — dry-run by default; nothing is signed without --confirm, and --confirm is refused when the advertised destination can't be indexed.
• Spend guards — payTo mismatch (the server aborts at boot), shared-tunnel domain, unknown balance. In the right order, and the order is deliberate.
• Pre-flight checker — identity, payTo, advertised price against configured price, endpoint, public reachability; it prints the origin of every value and warns citing both when the environment and the file disagree.
• Unified configuration — one module reads the config, with a declared precedence. No guard reads process.env directly.
• RPC layer — Multicall3 that cuts the burst from 70 requests to 17, endpoint failover, and backoff retry on 429.
• 19 test files, 211 tests — including one that crosses the full paid path (402 → signature → middleware → facilitator → paid response) and two structural guards that reject whole classes of defect.
• PITFALLS.md — nine sections, each with "what it looks like", "what it is", and "how to tell them apart".

Who it's for

For anyone putting an x402 endpoint on mainnet who would rather not discover these things the way they were discovered here — one at a time, each costing a day or a payment.

It also helps if you already have an endpoint live and can't explain why it isn't indexed, why the purchase fails, or why the number the checker prints isn't the one the server advertises.

Assumes TypeScript and Node ≥ 20. Assumes no prior experience with x402.

What this package is NOT

• Not a trading bot, not a strategy, not a market signal.
• No revenue promise. There is no projection, forecast, or sales figure anywhere in the package or on this page.
• No wallet, key, credential, or account included — you use your own.
• Not a framework. These are files you read, understand, and edit.
• No guarantee of Bazaar indexing: the indexing policy belongs to a third party and can change. What the package gives you is the method to find out why it wasn't indexed, not a guarantee that it will be.

License and delivery

MIT. Derivative work of Conway-Research/automaton, with the original copyright notice and license text kept inside the package (LICENSE + NOTICE). You may use, modify, and redistribute it, including commercially.

One .zip, 55 files. pnpm install && pnpm test runs the whole suite with no network and no paid service.