The x402 Field Guide: Selling Your API to AI Agents

In July 2026 we added x402 payment endpoints to three production data products: The Vault Report (precious metals), Mining Incidents (MSHA mine safety), and Safety Incidents (OSHA workplace safety). An AI agent can hit any of those catalogs right now, read the price list, and buy a page of query results for a cent or two in USDC. No API key, no signup, no invoice.

Most writing about x402 stops at "HTTP 402 is back" and a hello-world snippet. This guide is the rest of it: what to sell, how to price it, the implementation traps that only show up once real money settles, and the telemetry you should ship on day one. Every rule below traces to something that actually happened while we built the same surface three times.

What is the x402 protocol?

x402 is an open payment protocol, started by Coinbase, built on the status code HTTP reserved in the 1990s and then never used: 402 Payment Required. The loop works like this:

• An agent requests a paid route. The server answers 402 with a machine-readable challenge: the price, the asset, the network, and the seller's receiving address.
• The agent signs a USDC payment authorization with its wallet and retries the same request with a payment header attached.
• A facilitator verifies the payment before your handler runs, then settles the transfer on-chain after your handler returns success. We use Coinbase's CDP facilitator.

Payments are USDC on Base. USDC has 6 decimals, so a $0.01 price rides the wire as the string 10000. The whole design exists because the buyer is not a human who will tolerate a signup form. It is an agent in a loop, deciding in milliseconds whether your data is worth one more cent.

The honest economics: distribution, not revenue

Before you build, size the prize. While researching ours, we pulled 30-day gross figures for the top data sellers on x402 discovery surfaces: they ranged from a few hundred dollars to roughly $12,000 a month, and those are the winners. A niche data product should expect on the order of $100 a month at best, at least today.

So why bother? Because listing is free distribution on every agent-discovery surface at once: the Coinbase Bazaar indexes your endpoints automatically after your first settlement, and registries like x402scan list your catalog for any agent that shops there. You are buying a storefront on the machine web for a few days of work. Budget days, not weeks. And resist the urge to build an aggregator or a directory: be the supply.

Sell answers, not rows

Raw facts get commoditized instantly. An agent can get a spot gold price from a dozen free sources; it will not pay you for row storage. What it will pay for is the thing only you can compute:

• Sell your proprietary computed signals, priced a tier up. Our two best precious-metals endpoints are not raw tables. One is an anomaly board that scores every series we track by how far it sits from its own history. The other splits a venue's price premium into the embedded import-duty and tax wedge versus the real ex-tax premium, a number nobody else publishes. Both are computed on read from data we already had, so they carry no extra cost. They are the actual moat.
• Design each endpoint around the question an agent asks, not around your table. A raw regional gold price is useless to a procurement agent; the tax-adjusted premium is the decision input. Put the derived meaning in a self-describing field so the model consuming it uses it correctly.
• Give endpoints descriptive slugs. We renamed one route from /board to /anomalies because "board" tells an agent nothing. Agents find endpoints by reading catalogs. The slug is your ad.

Pricing rules that trace to real client code

None of these are taste. Each exists because of how actual x402 clients and the facilitator behave.

• Fixed price per route, exact scheme only. Discovery surfaces index the price straight out of your 402 challenge, and agents filter on it. Dynamic pricing breaks the deployed clients.
• Never price above $0.10. The widely deployed x402-fetch and x402-axios clients ship with a $0.10 auto-pay cap and throw above it. A $0.25 endpoint does not look premium to an agent. It looks broken.
• Never price below $0.005. The CDP facilitator charges $0.001 per settlement after your first 1,000 each month. A $0.001 call hands 100 percent of the revenue to the facilitator. Half a cent is the floor where the math still works.
• Ship a free count companion for every query endpoint. Ours return the total match count, the column schema, and exactly one sample row. This is the most important endpoint you will ship: it lets an agent size a query, learn your data shape, and see a real example before spending anything. One free row, never a free page, and never the top result of a ranked endpoint, where the single best row is the product.
• A paid query that matches zero rows returns 404, not an empty 200. The payment middleware settles only on success statuses, so a 404 costs the agent nothing. Never charge for an empty result.
• Cap pages at 25 rows. The next page is another paid call.
• Advertise the next purchase in every paid response. Include the total match count, the next-page pointer, and one or two related endpoints. Your customer is a loop; make the marginal cent a no-brainer.
• Attach a provenance envelope to every paid response: source, source URL, attribution, license, schema version, and a generated-at timestamp. Agents feeding LLMs prefer data they can cite.

The five gotchas that cost us real hours

These are the ones the docs do not lead with.

• The 402 challenge lives in a response header, not the body. x402 v2 puts the challenge JSON, base64-encoded, in the PAYMENT-REQUIRED header; the body is empty unless you configure one. If your test asserts on the body it sees an empty object, and you will chase a bug that does not exist. Decode the header.
• The wrong route-parameter syntax silently bypasses payment. Our Go router writes path parameters as {id}; the x402 middleware expects Express-style :id. A gate pattern written with {id} gets regex-escaped into a literal that never matches a real path, and the paid route serves its data for free without logging a single error. Write a regression test asserting that a wildcard paid route returns 402 unpaid, and keep it forever.
• Register the payment scheme on the concrete network. A wildcard like eip155:* looks reasonable and yields a runtime 500, because the scheme registry matches exact keys. Base mainnet is eip155:8453. While you are there, skip the SDK's boot-time facilitator sync: it makes a blocking network call on every boot, which slows each deploy by seconds and fails your whole payment gate whenever the facilitator is slow. A locally registered scheme resolves prices without the round-trip; verification and settlement still happen per request.
• Fail closed, always. Missing facilitator credentials, a missing receiving address, or a gate that fails to build must yield 503 on paid routes, never the data. A paid route reachable without a live payment layer in front of it is a silent free tier.
• The dependency tree is heavy. The Go SDK's payment scheme pulls in go-ethereum and friends: about 200 new lines of go.sum and measurably slower Docker builds. Accept it knowingly, and keep your import surface to the middleware, the one scheme you use, and nothing else.

Wallet setup: what is secret and what is not

The receiving address (payTo) is public by design. It ships in every 402 challenge and is listed by explorers and registries, so commit it to your repo as a constant with an environment override. Only the facilitator API credentials are secrets. Two rules we learned setting this up across multiple brands:

• One receiving address per product. Discovery surfaces identify sellers by address. Two products sharing a payTo get merged into one listing.
• The server never needs spending keys. Receiving USDC requires no key material on the box at all. The wallet secret that can move funds stays offline, used only to sweep revenue out. A compromised server cannot lose you a cent of settled revenue.

If you sell reports, guard the boundary

If your product also sells anything expensive (one of ours sells a $149 compliance-history report), the penny API must not sell that product's ingredients. An agent that can buy the inputs for 30 cents will not buy the report, and neither will its operator. Our rule: facts and single-entity totals are fair game for x402; interpretation, benchmarks, cross-entity scale, and portable artifacts stay behind the real price. Watch denominators especially. Selling a cheap feed of hours-worked lets an agent compute the very injury-rate benchmarks the paid product sells.

Then enforce it in code, not discipline: our CI runs a blocking test that greps the x402 handlers' SQL for forbidden tables and fields and fails the build if one appears. A boundary that lives in a doc gets crossed by a future refactor that never read the doc.

Log demand before you guess

Your access log almost certainly strips query strings, which means it cannot tell you what agents are actually asking for. That is the only signal worth having when deciding what to build next. Ship a dedicated request log with the x402 surface itself: endpoint, full query parameters, a paid flag, status, and user agent.

The detail that matters: wrap the logging middleware outside the payment gate, so it also records the 402 challenges agents received and declined to pay. Attempted-but-unpaid demand is your product backlog, ranked by the market, for free.

The launch checklist

• Write down what the API may sell and what it must never sell.
• Wire the payment middleware with fail-closed behavior; pin the SDK version.
• Build four or five endpoints over data you already serve free to humans. Narrow supply beats a directory.
• Add the free count companions, each with one sample row.
• Tests: boundary audit (blocking), unpaid request returns 402, wildcard routes are gated, page caps hold.
• Ship the request log in the same change, wrapped outside the gate.
• Create a dedicated receiving wallet per product; commit the address; keep spending keys offline.
• Deploy, then verify with an unpaid curl: you want a 402 whose decoded challenge shows the right price, asset, and address.
• Register your catalog with the discovery surfaces. The Bazaar lists you automatically after your first settlement.

The catalogs this guide came from are live: thevaultreport.com/api/x402, miningincidents.org/api/x402, and safetyincidents.org/api/x402. Curl any of them, hit a count endpoint for free, and watch a 402 challenge come back off a paid route. That round-trip is the whole protocol, and it is the closest thing the machine web has right now to walking into a shop and reading the price tags.