Table of Contents
AI crawlers read your pages for free, and robots.txt can only ask them to stop. Agent402 Tollbooth turns that same request into an HTTP 402 with a USDC price, while people keep browsing free.
This guide shows you how to set up agent402 tollbooth in front of a site or API, roll it out from observe mode to enforcement, and settle real USDC into a wallet or a Coinbase Business account. Stablecoin Insider installed version 0.10.5 and tested every mode locally, so the commands and results below come from the Tollbooth README on GitHub, the npm package itself, and the team's own run.
Key Takeaways
- Tollbooth is an MIT gate: humans pass free, AI crawlers get a 402.
- Start with observe mode, then bots, then strict only if you need it.
- Payments need a payTo plus a facilitator; payTo alone only advertises a price.
- Coinbase's CDP facilitator charges $0.001 per onchain settlement after 1,000 free a month.
- Mode all also charges Googlebot, so keep SEO pages on bots or strict.
What Agent402 Tollbooth is (and what it is not)
Tollbooth is the sell side of Agent402, published by Havok Holdings LLC under the MIT license. Version 0.10.5 went to npm on 13 October 2026 (UTC), according to the npm registry record, and it needs Node 20 or later with Express 5 as its only hard dependency.
The x402 packages (@x402/express, @x402/core, @x402/evm) and @coinbase/x402 are optional peer dependencies, as the published package.json shows. That keeps a proof-of-work-only install tiny, but it also means a real-money setup has extra installs you can't skip.
The gate speaks three rails on one 402 response. x402 carries a USDC quote, MPP (the Machine Payments Protocol) adds a WWW-Authenticate: Payment challenge settled through the same middleware, and a sha256 proof-of-work gives walletless agents a free path.
Adoption is still early. The npm downloads API counted 937 downloads in the 30 days from 13 September to 12 October 2026 (npm downloads API), across 30 releases since the first one on 14 June 2026.
What it is not: a hosted checkout, a refund system, or a bot-detection product. It is a per-request price tag that sits in front of content you already serve.
When Tollbooth beats Coinbase Business Checkouts
Coinbase's own agent path creates one checkout per payment and returns an x402_url that an agent pays once. Here's the problem for crawl pricing: a crawler reading thousands of pages doesn't want a checkout object for each one.
Tollbooth flips the unit of sale from an order to a request. The table below is Stablecoin Insider's comparison of the three seller paths SCI has covered, built from each vendor's current docs.
| Question | Agent402 Tollbooth | Coinbase Business Checkouts | Cloudflare Agents x402 (MCP) |
|---|---|---|---|
| Unit of sale | Every HTTP request to a page or API route | One checkout object per payment | One paid MCP tool call (paidTool) |
| Who gets charged | Mode based: AI crawler UAs, non-browsers, or everyone | Whoever pays the x402_url | Any MCP client calling a paid tool |
| Example price in docs | $0.001 default, $0.002 demo | 1.00 USDC create example | $0.01 per call |
| x402 scheme | exact (CLI settlement mode registers USDC exact only) | auth-capture, Base only | exact via a facilitator URL |
| Settlement truth | PAYMENT-RESPONSE on the 200, settled after your handler succeeds | Checkout status COMPLETED | Paid tool result after payment proof |
| Testnet path | base-sepolia via x402.org/facilitator | Sandbox omits x402_url | base-sepolia |
| Free path for agents | Proof-of-work | None | Free tools next to paid ones |
| Refunds | Not built in | Refund Checkout endpoint | Not built in |
| Best fit | Content sites and APIs priced per crawl | Invoices, orders, one-shot agent purchases | Paid tools inside an MCP server |
Sources: Tollbooth README, Coinbase Business x402 checkout docs, and Cloudflare's paidTool docs. For deeper walkthroughs, see SCI's Coinbase Business Checkouts how-to and Cloudflare Agents x402 MCP guide.
The rule of thumb is simple. If the buyer is a crawler reading many URLs, use a gate; if the buyer is completing an order, use a checkout.
Step 1: Install and run Tollbooth in observe mode
Let's start with measurement. Observe mode classifies and counts every request but never returns a 402, so you can see how much of your traffic is AI crawlers before you charge anyone.
As Express middleware:
npm install agent402-tollbooth
import express from "express";
import { createTollbooth } from "agent402-tollbooth";
const app = express();
const gate = createTollbooth({ observe: true });
app.use(gate);
app.get("/article", (_req, res) => res.send("your content"));
app.listen(3000);
// later: console.log(gate.stats().wouldCharge)
Or as a reverse proxy in front of any stack, with no code changes on the origin. The CLI listens on port 4021 by default and reads TOLLBOOTH_OBSERVE from the environment, per the README's environment table.
TOLLBOOTH_UPSTREAM=https://your-site.com \
TOLLBOOTH_OBSERVE=true \
TOLLBOOTH_ADMIN_TOKEN=change-me \
npx agent402-tollbooth
Crawlers that would pay get an X-Tollbooth-Observed: would-charge header, which makes log filtering easy. The proxy also serves a dashboard at /__tollbooth and JSON at /__tollbooth/stats.
Set TOLLBOOTH_ADMIN_TOKEN before you deploy. Without it the dashboard stays publicly reachable, showing aggregate counts only.
What each mode actually charges: SCI's test
The marketing pages describe the modes in a sentence each. Stablecoin Insider ran agent402-tollbooth 0.10.5 on Node 20 with four Express gates and sent the same four clients to each one on 14 October 2026.
| Client (headers sent) | observe | bots (default) | strict | all |
|---|---|---|---|---|
| Browser: Mozilla UA + Accept text/html | 200 | 200 | 200 | 402 |
| Googlebot UA + Accept text/html | 200 | 200 | 200 | 402 |
| GPTBot UA | 200 + would-charge | 402 | 402 | 402 |
| curl/8.5, Accept */* | 200 | 200 | 402 | 402 |
Method: Stablecoin Insider's local run of the agent402-tollbooth 0.10.5 package with payTo set and price $0.002, no facilitator, no live payment. The default crawler list lives in bots.js.
Three findings matter for operators. First, bots mode lets a plain curl or headless script through, because it only matches named crawler user agents such as GPTBot, ClaudeBot, CCBot, PerplexityBot and Bytespider.
Second, strict mode charged curl but passed Googlebot, since Googlebot sends a Mozilla-style UA and accepts HTML. That is good for SEO, and it also shows how any bot can fake its way through, as the README itself warns.
Third, mode all returned 402 to Googlebot.
Unless you exempt it with a free(req) predicate, all mode will cut your pages out of classic search indexing.
Step 2: Turn on bots mode and settle real USDC
Removing the observe flag turns on enforcement. The trap is that TOLLBOOTH_PAYTO on its own only advertises a quote: nothing can verify or settle it, so every paid request is refused and the CLI prints a warning at boot.
To take money you need both a payTo and a facilitator, plus the x402 peer packages. A dry run on Base Sepolia looks like this, per the README reverse-proxy section:
npm i agent402-tollbooth @x402/express @x402/core @x402/evm
TOLLBOOTH_UPSTREAM=https://your-site.com \
TOLLBOOTH_PAYTO=0xYourWallet \
TOLLBOOTH_NETWORK=base-sepolia \
TOLLBOOTH_FACILITATOR_URL=https://x402.org/facilitator \
TOLLBOOTH_PRICE='$0.002' \
TOLLBOOTH_SECRET=$(openssl rand -hex 32) \
npx agent402-tollbooth
With both values set, the proxy builds a standard @x402/express v2 stack in-process: verify, proxy the request, then settle only on a successful response, exactly once. The same 402 also carries MPP challenges for advertised chains in the default MPP list (Base and Celo), so a stock mppx client can pay too.
The CLI's settlement mode accepts base, base-sepolia, polygon, arbitrum, optimism, avalanche, celo, sei, monad, or a raw eip155 chain id for TOLLBOOTH_NETWORK. Your facilitator still has to settle that network, which is where most setups fail.
If more than one process serves traffic, keep TOLLBOOTH_SECRET stable and add TOLLBOOTH_REPLAY_SQLITE=/var/lib/tollbooth/replay.db. Otherwise one proof-of-work solve buys one free request per worker inside the token's 5-minute window.
Step 3: Get paid into Coinbase Business with the CDP facilitator
For a business that already reconciles in Coinbase Business, point TOLLBOOTH_PAYTO at the account's USDC receive address on Base and settle through Coinbase's facilitator with a CDP API key.
npm i agent402-tollbooth @x402/express @x402/core @x402/evm @coinbase/x402
# .env (keep it out of git)
TOLLBOOTH_CDP_API_KEY_ID=...
TOLLBOOTH_CDP_API_KEY_SECRET=...
set -a; . ./.env; set +a
TOLLBOOTH_PAYTO=0xYourCoinbaseBusinessBaseAddress \
TOLLBOOTH_PRICE='$0.005' \
TOLLBOOTH_UPSTREAM=http://localhost:8080 \
npx agent402-tollbooth
One detail the marketing pages skip: when both CDP keys are set, the CLI ignores TOLLBOOTH_FACILITATOR_URL and TOLLBOOTH_FACILITATOR_HEADERS and warns at boot, per the package's index.js. It also refuses to start if @coinbase/x402 isn't installed.
The CDP Facilitator's x402 v2 network table lists Base, Base Sepolia, Polygon, Arbitrum and World on EVM, plus Solana, according to Coinbase's CDP Facilitator docs. So on the CDP path, only base, base-sepolia, polygon and arbitrum overlap with Tollbooth's CLI list.
Pricing on that page: the first 1,000 onchain facilitator transactions each month are free, then each one costs $0.001, and verification is always free (CDP Facilitator pricing).
Run the per-crawl math before you pick a price
Tollbooth's CLI registers the exact scheme, so every paid crawl is its own onchain settlement. After the free tier, a $0.001 CDP fee eats 100% of the $0.001 default price, 50% of a $0.002 price, and 20% of a $0.005 price (fee source; prices from the README).
CDP's batch-settlement scheme can spread one onchain transaction across many payments, but Tollbooth's built-in CLI does not use it. If your crawl volume runs far past 1,000 paid requests a month, price at $0.005 or more, or compare facilitators first with SCI's x402 facilitator guide.
The keyless facilitator path
You don't need a CDP account to settle. Set TOLLBOOTH_FACILITATOR_URL to any facilitator that settles your network, and pass auth headers as JSON in TOLLBOOTH_FACILITATOR_HEADERS if it needs them.
The README says keyless free tiers exist for mainnet chains but doesn't name one, so check each provider's network list and screening policy. SCI's guides to the Circle x402 facilitator and the facilitator comparison cover the trade-offs.
Step 4: Test a paid crawl without tripping self_send_not_allowed
Coinbase's facilitator refuses a payment whose payer is also the payTo, returning self_send_not_allowed. Test from a second wallet, never from the receiving address.
Agent402 says it proved the CDP path with real USDC on 27 August 2026, with the settlement visible on Basescan. Any stock x402 client can pay; SCI's AgentKit x402 buyer guide shows the client side.
- Check the 402. A crawler UA should get accepts[] with scheme exact, your network, asset USDC and your payTo.
- Pay from a funded second wallet. Use base-sepolia first, then a tiny mainnet price.
- Read the receipt. A settled 200 carries a PAYMENT-RESPONSE header and X-Tollbooth-Paid: x402 (or mpp).
- Confirm the counters. gate.stats() or /__tollbooth/stats should show x402Paid or mppPaid rising.
The proof-of-work fallback: what it costs a crawler
Every 402 also offers a sha256 puzzle at 18 leading zero bits by default. The crawler resends with an X-Pow-Solution header, and the token is HMAC-signed, single-use and bound to that exact URL.
In SCI's run, a naive single-thread Node solver took between 279 and 1,594 ms across five 18-bit solves (median 818 ms) on a shared Xeon box, against the README's estimate of 0.1 to 0.5 seconds (README configuration table). Every first submission returned 200 with X-Tollbooth-Paid: pow, and every replay of the same solution returned 402 "already used".
That's the point of the rail. A walletless agent can still read a page, but a high-volume scraper pays in CPU, and TOLLBOOTH_ADAPTIVE=true raises difficulty as charged-request load climbs.
On the flip side, proof-of-work earns you nothing. If revenue is the goal, set pow: false in code or raise TOLLBOOTH_POW_BITS so paying USDC is the cheaper option for serious crawlers.
Edge deploys: Cloudflare Workers and Next.js
The same gate ships as agent402-tollbooth/edge on Web Crypto and Fetch, with ready templates for Cloudflare Workers, Next.js on Vercel, and Docker in the repo. On the edge, pass a stable secret, because proof-of-work tokens are HMAC-signed.
The Worker refuses to enforce without a Durable Object bound as TOLLBOOTH_REPLAY, unless you set TOLLBOOTH_ALLOW_NON_ATOMIC_REPLAY="true". The native Tempo rail and the x402 middleware mode are Node and Express features; the edge gate offers proof-of-work plus a verifyX402 callback, with MPP on that verifier since 0.10.0.
Stablecoin Insider's take: spend caps and what Tollbooth is not for
Spend caps belong on the buyer. An agent with a wallet should cap per-payment amounts in its own client, as Coinbase does with applySpendControls in its checkout payer sample.
On the seller side, your only controls are price, mode, and the free() predicate.
Don't use Tollbooth for:
- One-shot orders or invoices. Use a checkout with a refund endpoint, such as Coinbase Business Checkouts.
- Hard security boundaries. Strict mode is a heuristic; a bot that fakes browser headers gets the human pass.
- Search-facing pages in mode all. SCI's test shows Googlebot gets a 402.
- Solana payouts from the CLI. The CLI settlement mode is EVM USDC only; other assets and rails go through the library API.
- Pricing strategy. For how to set the number itself, read SCI's guide to pricing an API for AI agents and the agent vs card payment cost breakdown.
For the policy side of agent spending limits, see SCI's argument that stablecoin payments for AI agents need enforceable limits, and for protocol choice, x402 vs AP2 vs ACK-Pay. If you want MPP without x402, compare Stripe MPP payments in USDC.
What to do next
Install agent402 tollbooth in observe mode this week and let it count for seven days. If the would-charge number is meaningful, flip to bots mode on base-sepolia, test a paid crawl from a second wallet, then move to Base with a price that clears your facilitator fee.
The open question is demand: few crawlers pay x402 today. Run the meter now, and you'll have the data the day they start.
Selling one-shot agent purchases instead of per-crawl access? Stablecoin Insider's Coinbase Business Checkouts guide covers the hosted x402_url path end to end.
FAQ
What is Agent402 Tollbooth?
Agent402 Tollbooth is an MIT-licensed npm package that returns HTTP 402 to AI crawlers and lets them pay per request in USDC over x402 or MPP, or solve a proof-of-work. Humans and classic search bots pass free in the default bots mode.
How can you charge AI crawlers without blocking Google?
Use the default bots mode or strict mode. In Stablecoin Insider's test both passed Googlebot, while mode all returned 402 to it.
Why does Tollbooth refuse every paid request?
You probably set TOLLBOOTH_PAYTO without TOLLBOOTH_FACILITATOR_URL or CDP keys. A payTo alone only advertises a quote, and the CLI warns about it at boot.
Can Tollbooth pay out to a Coinbase Business account?
Yes. Set TOLLBOOTH_PAYTO to the account's USDC receive address on Base, add TOLLBOOTH_CDP_API_KEY_ID and TOLLBOOTH_CDP_API_KEY_SECRET, and install @coinbase/x402.
What does self_send_not_allowed mean?
Coinbase's facilitator rejected a payment where the payer and the payTo are the same address. Test from a second funded wallet.
Is Tollbooth better than Coinbase Business Checkouts?
It depends on the unit of sale. Tollbooth fits per-request crawl or API pricing; Checkouts fit one-shot orders and include refunds.
Does proof-of-work earn a site any money?
No. It gives walletless agents a free path that costs them CPU, so turn it off or raise the difficulty if revenue is the goal.
This content is provided for informational and educational purposes only and does not constitute financial, investment, legal, or tax advice; it is not financial advice, and no material herein should be interpreted as a recommendation, endorsement, or solicitation to buy or sell any asset or token. Software versions, prices, facilitator terms, and network lists change; check the live sites and docs before you deploy.
){kind=link}