> ## Content Index > Fetch the complete content index at: https://stablecoininsider.org/llms.txt > Use this file to discover other available public pages before exploring further. # How to Charge AI Crawlers with Agent402 Tollbooth (2026) - URL: https://stablecoininsider.org/how-to-charge-ai-crawlers-agent402-tollbooth/ - Published: 2026-10-14T12:01:00.000Z - Updated: 2026-10-14T12:26:16.000Z - Description: Set up Agent402 Tollbooth to charge AI crawlers per request in USDC: observe to bots to strict rollout with real env vars, CDP vs keyless facilitators, proof-of-work fallback, and SCI's mode test results. - Author: Alexandra - Tags: AI, Stablecoins 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](https://github.com/MikeyPetrillo/Agent402/tree/main/tollbooth), 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 this guide is: an operator how-to for agent402-tollbooth 0.10.5 (npm latest on 14 October 2026), checked against the package README, its source files, Coinbase's CDP Facilitator docs, and a local Stablecoin Insider test of every mode and the proof-of-work rail. The team did not send a live USDC payment, and nothing here recommends a token or a vendor. [How to Accept Agentic USDC Payments with Coinbase Business Checkouts (2026)Stablecoin Insider's guide to Coinbase's hosted x402\_url checkout: auth-capture on Base, COMPLETED as settlement truth, and the sandbox gap.![](https://stablecoininsider.org/favicon.ico)Stablecoin Insider](https://stablecoininsider.org/how-to-accept-agentic-usdc-with-coinbase-business-checkouts/) ## 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](https://registry.npmjs.org/agent402-tollbooth/0.10.5), 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](https://unpkg.com/agent402-tollbooth@0.10.5/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](https://x402.org) carries a USDC quote, [MPP](https://mpp.dev) (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](https://api.npmjs.org/downloads/point/last-month/agent402-tollbooth)), 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](https://github.com/MikeyPetrillo/Agent402/tree/main/tollbooth) | 1.00 USDC create example | [$0.01 per call](https://developers.cloudflare.com/agents/agentic-payments/x402/charge-for-mcp-tools/) | | x402 scheme | exact (CLI settlement mode registers USDC exact only) | [auth-capture, Base only](https://docs.cdp.coinbase.com/coinbase-business/checkout-apis/accept-x402-payments) | 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](https://github.com/MikeyPetrillo/Agent402/tree/main/tollbooth), [Coinbase Business x402 checkout docs](https://docs.cdp.coinbase.com/coinbase-business/checkout-apis/accept-x402-payments), and [Cloudflare's paidTool docs](https://developers.cloudflare.com/agents/agentic-payments/x402/charge-for-mcp-tools/). For deeper walkthroughs, see SCI's [Coinbase Business Checkouts how-to](https://stablecoininsider.org/how-to-accept-agentic-usdc-with-coinbase-business-checkouts/) and [Cloudflare Agents x402 MCP guide](https://stablecoininsider.org/how-to-charge-for-mcp-tools-with-cloudflare-agents-x402/). 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: ```bash npm install agent402-tollbooth ``` ```javascript 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](https://github.com/MikeyPetrillo/Agent402/tree/main/tollbooth). ```bash 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](https://registry.npmjs.org/agent402-tollbooth/0.10.5) with payTo set and price $0.002, no facilitator, no live payment. The default crawler list lives in [bots.js](https://github.com/MikeyPetrillo/Agent402/blob/main/tollbooth/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. ⚠️ SEO rule: keep public, search-facing pages on bots or strict. Use mode all only for API routes or premium content you never wanted indexed, and add a free() predicate for your own clients. ## 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](https://github.com/MikeyPetrillo/Agent402/tree/main/tollbooth): ```bash 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. ```bash 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](https://docs.cdp.coinbase.com/x402/core-concepts/facilitator). 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](https://docs.cdp.coinbase.com/x402/core-concepts/facilitator)). ### 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](https://docs.cdp.coinbase.com/x402/core-concepts/facilitator); prices from the [README](https://github.com/MikeyPetrillo/Agent402/tree/main/tollbooth)). 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](https://stablecoininsider.org/how-to-choose-an-x402-facilitator-for-usdc/). 💸 Budget rule: at $0.002 per crawl on the CDP facilitator, half of every paid request above 1,000 a month goes to settlement fees. Either raise the price, keep volume under the free tier, or use a facilitator whose terms fit sub-cent payments. ### 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](https://stablecoininsider.org/how-to-enable-circle-x402-facilitator-for-usdc/) and the [facilitator comparison](https://stablecoininsider.org/how-to-choose-an-x402-facilitator-for-usdc/) 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](https://basescan.org/tx/0x8175178ac4e2229dfd9385a3c78c491ffe554b08fdf52cf92f99425c983ec5d1). Any stock x402 client can pay; SCI's [AgentKit x402 buyer guide](https://stablecoininsider.org/how-to-pay-for-an-x402-api-with-coinbase-agentkit/) 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](https://github.com/MikeyPetrillo/Agent402/tree/main/tollbooth)). 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 🧠 Stablecoin Insider's take: Tollbooth is the cleanest open-source way the team has seen to put a USDC price on a crawl, and observe mode alone is worth installing. But it is a seller tool with no buyer-side spend cap, no refunds, and settlement fees that can swallow sub-cent prices. Treat it as a meter, not a business model, until real crawlers start paying. 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](https://docs.cdp.coinbase.com/coinbase-business/checkout-apis/accept-x402-payments). 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](https://stablecoininsider.org/how-to-accept-agentic-usdc-with-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](https://stablecoininsider.org/price-an-api-for-ai-agents/) and the [agent vs card payment cost breakdown](https://stablecoininsider.org/agent-payments-vs-card-payments-cost/). For the policy side of agent spending limits, see SCI's argument that [stablecoin payments for AI agents need enforceable limits](https://stablecoininsider.org/stablecoin-payments-for-ai-agents/), and for protocol choice, [x402 vs AP2 vs ACK-Pay](https://stablecoininsider.org/x402-vs-ap2-vs-ack-pay/). If you want MPP without x402, compare [Stripe MPP payments in USDC](https://stablecoininsider.org/how-to-accept-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. --- [Read the Tollbooth README](https://github.com/MikeyPetrillo/Agent402/tree/main/tollbooth) 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. [Read the Checkouts how-to ](https://stablecoininsider.org/how-to-accept-agentic-usdc-with-coinbase-business-checkouts/) [How to Choose an x402 Facilitator for USDC (2026)Stablecoin Insider's facilitator comparison: CDP free tier and per-transaction pricing, gas sponsorship, KYT, and network reach.![](https://stablecoininsider.org/favicon.ico)Stablecoin Insider](https://stablecoininsider.org/how-to-choose-an-x402-facilitator-for-usdc/) ## 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.