x402 basics

x402 lets any HTTP endpoint charge per request in stablecoins, with no accounts or API keys. That makes it a natural way for AI agents to pay for tools.

One paid call, step by step

1. The agent calls the toolA normal POST to the worker URL, without payment.
2. The worker answers 402Any request without a payment gets 402, whatever its body says. That is how agents and indexers discover the price. The PAYMENT-REQUIRED header carries the terms: price, token (USDC), network, and the payTo address.
3. The agent signsIts wallet signs an EIP-3009 "transfer with authorization" as EIP-712 typed data. This is a signed permission slip. No transaction is sent yet.
4. The agent retries with the signatureThe same request again, now with a PAYMENT-SIGNATURE header.
5. The worker checks the request before chargingCheap checks only: is the body valid, is it under the size limit, is the target URL allowed. A bad request gets a 400 here and the payment is never settled. See "Order of operations" below.
6. The facilitator verifies and settlesThe worker sends the signature to a facilitator (/verify, then /settle). The facilitator submits the transfer on-chain and pays the gas.
7. The worker does the work and responds200 with the result, plus a PAYMENT-RESPONSE header holding the settlement receipt.

The pieces

USDC, EIP-3009 and EIP-712

USDC implements EIP-3009, which allows a transfer to be authorized by signature and submitted by someone else. The signature follows EIP-712, a standard for signing structured data. It includes a "domain" naming the token contract. That domain caused our first real bug. The token's name is "USD Coin" on Base mainnet but "USDC" on the Base Sepolia testnet. We had copied the mainnet value from a GitHub issue, and the testnet facilitator rejected every payment. We fixed it by reading name() directly from the contract. From then on, facts involving money were checked on-chain rather than taken from docs or forum posts.

Facilitators

A facilitator is the service that verifies a payment and settles it on-chain. Which one you use matters more than it seems, because facilitators also run the discovery catalogs agents search. We used three:

We switched because x402scan data showed that 474 of the top 496 sellers settle through CDP and only one through Primer. Our tools were invisible in every catalog that agents search. The workers now try CDP, then PayAI, then Primer. More in Distribution →

Bazaar: how a tool gets listed

There is no submission form. A tool is listed when a real payment settles while carrying discovery metadata (description, input schema, example output) in paymentPayload.extensions.bazaar. So to get listed we made one small real payment to each tool per facilitator, a process we call "seeding". One surprise: CDP rejects the whole payment if the resource description is over 500 characters. We found the limit by testing lengths until one failed.

Order of operations

A paid endpoint must decide what happens before payment and what happens after. We settled on two rules:

• 402 first, then validate, then settle. A request without payment always gets the 402, so discovery works. We briefly validated first, and x402scan rejected a tool for answering 400. A request with a payment attached is validated before the payment is settled, using cheap, bounded checks (schema, size cap, blocked URLs), so honest mistakes cost nothing. Expensive work, like launching a browser, runs only after settlement so nobody can trigger it for free. We got this wrong twice in every tool. See Verification →
• Pay per attempt. Once a payment settles, a failure inside the tool (for example, the target site returns 404) is still charged. This is simpler and is documented in each tool. We chose to keep it for now.

Builder Codes

Base Builder Codes (ERC-8021) attach a short attribution tag to the end of a settlement transaction's data. The facilitator adds it, so no special wallet is needed. Our code rides on every CDP settlement, and base.dev counts those transactions. This is useful as evidence for grants and leaderboards, not as income.

Testnet and mainnet

Every tool is tested on Base Sepolia first. That testnet has worthless USDC and a free public facilitator at x402.org/facilitator. Only then does it move to Base mainnet with real USDC. The pipeline's automatic checks only ever spend testnet money.

The pipeline

A folder-based assembly line. A proposal moves from folder to folder, and at each step an AI model or a script works on it. Cheap models draft, a stronger model judges, and plain scripts test against real infrastructure.

Stages at a glance

Why each stage exists

Which model does what

The rule: a stage that only gathers or drafts uses a cheap Z.ai model. A stage that gives the final go or no-go uses Claude. A cheap model confidently approving something wrong is worse than no check at all. This also keeps Claude's weekly usage for the steps that need it. QA, publishing and MCP generation use no model at all. They are plain code that either passes or fails.

One lesson along the way was to confirm which model actually answers. Z.ai quietly served glm-4.6 requests with glm-5.3-flash. A benchmark comparing the two was really comparing one model with itself.

Making Pass 1 fast

Pass 1 took 11–16 minutes per build. Timing each call showed the prompt was small (about 2,700 tokens) and the time to first byte was under 1% of the total. Nearly all the time went to generation, which pointed at hidden reasoning tokens. The command-line path has no cap on output tokens, so we turned thinking off and asked for shorter output. Pass 1 dropped to about 115 seconds, roughly 8 times faster. While investigating, we also fixed a parser bug that could throw away a full 16-minute generation because of a single line break.

The architectural audit

On 20 Sep, four parallel reviewers each audited one part of the repository: the MCP layer, the worker template and tools, the orchestration scripts, and the agent prompts. The verdict was that the security engineering was strong but the product and process layer was weaker.

• P0, fixed 21 Sep: publish without QA; a stateful check nobody ran; a deploy script that no longer matched the config format and flattened every price to 0.01.
• P1, fixed 21 Sep: automatic MCP regeneration; removing triplicated helper code; no longer resending the full template in every prompt (cut 44–80% of that text).
• External second opinion: 2 of its 5 points were real and fixed (the MCP spending ceiling and facilitator retries). The other 3 were wrong when checked against the code.

The full report lives in the repo at pipeline/reports/architectural-audit.md.

What is still weak

• Scout still cannot see demand, and the Demand Scan is blocked. Tool results (buyers or none) never flow back to Scout.
• There is no CI and no spending ceiling across the pipeline as a whole.
• The deeper lesson: every gate protects build quality, and none protects against building something nobody needs. See Market & demand →

Verification

Most of the important bugs this week passed type checks and unit tests. They only showed up when the code ran against real infrastructure with real payments. Each one became a check, so it cannot come back.

The verification ladder

1. Type check and unit teststsc --noEmit and npm test. Necessary, but a model that writes both the code and its tests can repeat the same wrong assumption in both.
2. Local workerwrangler dev, the real Cloudflare runtime on your machine. This catches missing files, bad config and libraries that break in Workers.
3. Real testnet paymentSign, settle on Base Sepolia, and check the result. Automated in Pass 3 and costs nothing.
4. Real mainnet paymentA few cents of real USDC, then the transaction receipt read from a public Base RPC instead of trusting the facilitator's reply.
5. Check the bodyA 200 is not proof. geotiff's default format returned 500 after payment for days, and only a check of the actual response caught it.

Bugs that shaped the pipeline

The payment-ordering fix, in detail

The shared worker template checked for a payment and settled it before it ever looked at the request body. So a caller who sent a valid payment with a malformed request paid in full and then got a 400. The bug was in all four live tools.

The fix had one condition from the operator: it must not open a way to run up costs. We moved only cheap validation ahead of payment: pure functions with no network calls and a hard byte limit on the body. Expensive work (browser rendering, encryption and storage) stayed behind payment. Three of the four tools had no body size limit at all, so the fix also closed an unbounded-input gap. We verified it with one real mainnet payment per tool and read each receipt from the chain.

The first version of the fix went one step too far. It validated the body before even checking for a payment, so an unpaid probe with an empty body got 400 instead of the 402 price terms. x402scan rejected a tool for exactly that. The x402 v2 spec is clear: no payment means 402, whatever the body. The final order is to check for a payment (none means 402), then validate (invalid means 400, nothing settled), then settle, then do the work.

The tools

Five tools are live on Base mainnet as Cloudflare Workers. Four more ideas were rejected, three before building and one after. The main question for each was whether an agent could get the same result for free.

Live

All five also offer free GET routes (docs, /openapi.json, /.well-known/x402) so agents can inspect them before paying.

Rejected

The four questions every tool must answer

These came out of the rugcheck post-mortem and are now built into the Viability Review:

1. Is there a real cost basis: a paid upstream, metered compute, or genuine multi-source work?
2. Could the agent get the same output with one more fetch of its own? If so, what extra work changes that?
3. Do live competitors already exist on x402scan, GitHub or the web, and what do they do better?
4. At this price, is the number of calls needed for meaningful revenue remotely plausible?

Every successful x402 business we found (LLM proxies, RPC gateways, crawl compute, pay-per-crawl) had a real cost basis or an existing paying product before it added x402. None repackaged a free API.

Distribution

Once the tools worked, the question was how agents would find them. We tried every channel we could verify: an MCP server, registries, facilitator catalogs, AgentCash, a grant and a blog. The tools were visible everywhere, and still nobody bought.

Channels, in the order we tried them

Why the facilitator switch mattered

Agents find tools through catalogs, and each facilitator runs its own catalog. Primer, our only facilitator at first, has none. On-chain data showed the market settles almost entirely through CDP. Adding CDP and PayAI (with Primer as the last fallback) put our tools in both catalogs within minutes. It also let every CDP settlement carry our Builder Code. The rollout used real deployments and real seed payments, and it surfaced two real bugs. How catalogs work →

Grants and visibility

Base Builder Grants

A research document the operator shared suggested integrating Coinbase's developer stack to win a grant. Checking the sources showed it mixed up two programs:

• Base Builder Grants: retroactive, 1–5 ETH, for anything live on Base mainnet. We already qualified.
• CDP Builder Grants: small, round-based, and it does require integrating Coinbase's developer stack. No round was open.

We took the free path: a short terminal demo video, a security section in the README, a self-nomination through the real form, and the project's first posts on X and Farcaster. The demo command briefly showed a wallet key on screen, so that wallet was emptied and retired and a new one was created. Selection is discretionary, with no timeline.

Builder Codes

We first ruled this out because it seemed to need a Coinbase smart wallet. Reading the extension's source showed the facilitator adds the tag itself, so it works with our plain EIP-3009 payments. We confirmed that our CDP settlements already carried the facilitator's own tag. Now every CDP settlement carries our code, base.dev counts those transactions, and publishing refuses a future tool without it.

The blog post

The buyer analysis was new enough to publish. It is live at jannis-e.github.io/x402-mcp-server/blog/x402-buyer-anatomy.

Market & demand

This is the central story of the week. We first tried to find demand through web search, then through seller statistics, and finally by analysing every buyer on Base for a month. The answer changed the direction of the project.

Step 1: web search (didn't work)

The Demand Scan stage asked a model to search the web for evidence of unmet demand. DuckDuckGo blocked most queries, and later all of them. The model did the right thing: it reported "inconclusive" and suggested no topics rather than inventing some. One run did return results. Its two suggestions failed a manual source check: a free tool already existed for one, and the other rested on filler content.

Step 2: seller statistics (x402scan)

x402scan indexes every x402 payment and has a public API. Its 30-day seller list showed how crowded each category was:

• Markdown extraction: 33 sellers. Crypto data: 166. Company registries: saturated.
• The burn-once and GeoTIFF niches were nearly empty. Emptiness can mean either an opportunity or a lack of demand.
• Almost all active sellers settle through CDP, which led to the facilitator switch. See Distribution →

Step 3: buyer anatomy

We had been asking which tools agents want. The better question: do buyers shop around at all, or does each seller bring its own users? If buyers don't shop, then building and listing a tool can't work, however good the tool is.

Method: pull every buyer on Base over 30 days (18,285 of 18,291) and every seller they paid. First remove a six-wallet wash ring that sent about $139k back and forth, and payments over $5 per call. Then sort buyers into three groups:

• Captive: pays exactly one operator.
• Open market: pays two or more operators, with some repeat use.
• Probe: pays five or more operators, mostly once each. These look like indexers and QA wallets.

The open-market money is also concentrated:

Where open-market buyers go: paid-API resellers (stableenrich, socialx402, twit.sh), large tool catalogs (agent402, ottoai, 2s.io), and a few data brands (Nansen, Exa). The stable* family belongs to Merit Systems, which also runs x402scan and AgentCash. That is why AgentCash became our one distribution experiment.

Step 4: market outlook

• Direction: flat to declining through 2026. Independent sources agree. Artemis estimates about half of x402 transactions are gamed (CoinDesk), Helios reports settlement volume down 93% year to date (Yahoo Finance), and American Banker reported a volume decline.
• Infrastructure is ahead of demand: an x402 Foundation under the Linux Foundation; a no-code Cloudflare Monetization Gateway; Stripe's parallel protocol (MPP), which also supports x402.
• "x402 integration as a service" is commoditized: it's one line of middleware, Cloudflare does it without code, and we found no hiring demand.
• Trust tools (burn-once's niche): about two dozen sellers. The best has 48 buyers and $32 in 30 days.
• What earns: reselling paid APIs that normally need an account.

The decision (23 Sep)

1. Stop building new tools. Keep the five running, since they cost almost nothing.
2. Run one cheap distribution experiment (AgentCash), then re-run the buyer analysis on 23 October and decide per tool.
3. Publish the analysis as a blog post.
4. Don't expect near-term income from x402 revenue. The asset is the skill set: agent pipelines, Workers, on-chain payments, market analysis.
5. Build one paid-API-reseller tool only if the review shows life.

Rejected options: an integration service, more trust-primitive tools, more listings without a channel on the wallet side.

Postscript: the first outside payer (24 Sep)

Hours after the AgentCash re-registration, a new wallet paid three of our tools. The on-chain history showed an automated sweeper: about 2,000 USDC transfers to 632 different x402 sellers since early September, in bursts two seconds apart. It is an indexer or crawler, not demand. We are watching whether it repeats.

Lessons

What to repeat, what to do first next time, and what carried over to the next project.

The big one: measure demand before building

The factory made building the hardest-guarded step, with review, two-pass code generation, smoke tests, QA and a publish gate. The real bottleneck was demand, and the pipeline had no reliable way to see it. The only demand signal that ever worked was on-chain data, and we pulled it by hand after five tools were already live. Next time, the first step is a demand map from a source with real usage numbers. The idea comes second.

Engineering habits worth keeping

• Run it for real. Every serious bug this week passed static checks. A real runtime plus a real (testnet) payment is part of the build, not an optional extra.
• Turn incidents into gates. When a class of bug appears, add an automated check. Don't rely on memory.
• Verify money facts at the source. Contract values come from the contract, payments from the transaction receipt, and responses are checked by their body.
• Cheap models draft, a strong model judges. Put the expensive model only where a wrong "yes" is costly.
• Confirm what actually answered. Model names can be rerouted, and a 200 can hide a failure.
• Bound automated cost. Any automated stage must be impossible to abuse into spending real money. Automated tests only spend testnet funds.

Ways of working that held up

• Dry-run before anything that spends money or deploys. Show the plan or file list, then wait for a go-ahead. Each escalation (testnet to mainnet) gets its own check-in.
• Ask on judgment calls. If a decision with no clear default comes up mid-task, stop and ask instead of choosing silently.
• "Propose" means describe. A request for a proposal gets a plan in words, not a pile of diffs.
• Check research against the source. The grant document mixed up two programs, a marketplace's signup didn't match its docs, and an external critique was wrong on three of five points.
• End each session with proof. Commit, run a small paid sweep of every live tool with bodies checked, refresh the numbers, and update the notes.
• Keep commits atomic. One logical change per commit, even when the working tree has changes mixed together.

What carried over to the Apify project

The Apify Store's public API shows users, runs and failures for every tool over 7, 30 and 90 days. That is the demand map x402 never had. The project started from that data, not from an idea. We picked a category with a proven leader (1,222 users a month) and built a cheaper and broader alternative with the same habits: SSRF guard, charge only on success, a budget reserved before each scan, live platform test runs, and listing text treated as part of the product.

Open threads

• 23 Oct review: re-run the buyer analysis and AgentCash search, then retire or keep each tool based on outside buyers.
• Check now and then whether AgentCash search shows our GeoTIFF tool, which has no real competitor there.
• Small backlog item: the shared btoa() fix for non-Latin-1 text in 402 headers.
• Parked: a remote MCP transport (needed for Smithery), an ElizaOS plugin, community posts.

Glossary

Short definitions for the terms used on these pages.

Protocol and payments

x402

An open protocol for paying per HTTP request with stablecoins, built on the 402 Payment Required status code. Started by Coinbase, now under the x402 Foundation.

402 challenge

The server's reply to an unpaid request. Its PAYMENT-REQUIRED header lists price, token, network and payTo.

payTo

The wallet address that receives payments. All our tools share one.

USDC

A dollar stablecoin. Prices here are in USDC; 0.01 USDC is one cent.

Base / Base Sepolia

Coinbase's Ethereum layer-2 network (chain 8453) and its testnet (chain 84532), where test USDC is worthless.

EIP-3009

A token standard that lets a holder authorize a transfer by signature, which someone else submits and pays gas for.

EIP-712

A standard for signing structured data. Its "domain" names the contract, and a wrong token name there makes every signature invalid.

Facilitator

A service that verifies and settles x402 payments on-chain and pays the gas. Ours: Coinbase CDP, PayAI, Primer.

Verify / settle

The two facilitator calls. Verify checks a signed payment without moving money. Settle puts it on-chain.

Bazaar

The x402 discovery extension. Metadata sent with a payment gets the tool listed in that facilitator's catalog.

Seeding

Our term for one small real payment per tool per facilitator, made to get listed.

Builder Code (ERC-8021)

An attribution tag added to settlement transaction data. base.dev counts transactions carrying ours.

Pay per attempt

Once payment settles, the call is charged even if the tool then fails.

Infrastructure and tooling

Cloudflare Workers

Serverless functions at the edge, where all five tools run. 128 MB of memory on every plan.

wrangler

Cloudflare's command-line tool. wrangler dev runs a worker locally in the real runtime; wrangler deploy ships it.

Durable Object

A Cloudflare primitive with single-threaded state. It is what makes burn-once's "exactly once" guarantee hold.

SSRF

Server-side request forgery: tricking a server into fetching internal addresses. Every URL-fetching tool blocks it.

MCP

Model Context Protocol, how AI clients such as Claude call external tools. Our server runs locally over stdio, not as a hosted HTTP endpoint.

OpenClaw

The local agent runtime the pipeline uses to call models (openclaw capability model run).

Z.ai GLM

The cheaper model family used for Scout, Demand Scan and Pass 1.

Market analysis

x402scan

An explorer that indexes x402 payments, with a public API. Run by Merit Systems.

AgentCash

Merit Systems' agent wallet and tool-discovery plugin. It reads /openapi.json with x402-specific fields.

Captive buyer

A wallet that pays exactly one operator. It looks like that operator's own users or app.

Open-market buyer

A wallet that pays two or more operators with repeat use. It looks like an agent that shops around.

Probe wallet

A wallet that pays many operators once each, like an indexer, QA bot or sweeper.

Moat

What makes a tool hard to replace with the agent's own code or a free API.