
agent-tollbooth-402
io.github.Red-Center-Studio/agent-tollbooth-402
HTTP 402 & x402 V2 billing, pricing quotes, signed receipts, and Stripe top-ups for APIs & MCP.
Documentation
Agent Tollbooth 402
Monetize APIs, Cloudflare Workers, Hono apps, Next.js routes, and MCP servers in under 60 seconds with dual-rail HTTP 402 payments.
Built by Red Center Studio for Google Antigravity and Claude Code.
3-Line Quickstart (30-Second Zero-Config Sandbox)
npm install
npm run validate
npm run test:sandbox
Zero API keys, zero crypto wallets, and zero Stripe setup required to run your first 402 -> sign -> 200 OK loop locally.
5-Line withTollbooth Setup
Copy-paste into any Cloudflare Worker, Web Fetch handler, or Next.js route:
import { withTollbooth } from "@redcenterstudio/agent-tollbooth-edge";
export default withTollbooth({ priceUsd: 0.01, mode: "hybrid" }, async (request) => {
return Response.json({ ok: true, path: new URL(request.url).pathname });
});
- Local test without wallets or keys: change
mode: "hybrid"tomode: "sandbox"and callcreateSandboxReceipt()orcreateSandboxX402Header(). - Hono middleware:
app.use("/api/*", honoTollbooth({ priceUsd: 0.01, mode: "hybrid" })). - Cloudflare D1 replay protection: pass
nonceStore: new D1NonceStore(env.DB)insidewithTollbooth((env) => ({ ... }), handler).
Live Clearinghouse & Screenshots
Live clearinghouse portal & MCP endpoint: https://tollbooth.redcenterstudio.com (/pay · /demo/402)
- Setup Walkthrough Video (MP4) — copying the install command, running the live
402check, and inspecting the browser checkout card.

| HTTP 402 Browser Checkout Card | Mobile Responsive Layout (390px) |
|---|---|
![]() | ![]() |
Dual-Rail Architecture & Browser 402 Checkout Card
agent-tollbooth-402 supports both x402 V2 on-chain USDC authorizations and Red Center Fiat Agent Wallets verified in <1ms via Web Crypto (HMAC-SHA256 / Ed25519).
- Programmatic AI Agents (
Accept: application/json): Receive402 Payment Requiredwith Base64PAYMENT-REQUIRED,WWW-Authenticate, CORSAccess-Control-Expose-Headers,priceUsd,acceptedRails,code, and a plain-Englishfix_hint. - Human Browser Requests (
Accept: text/html): Receive a responsive Red Center Studio402Checkout Card (#24181aIronstone,#d9622bRed Ochre,#e3a23cSpinifex Gold,#f5efe6Sand) displaying endpoint details, price, payment curl snippets, and a Fund Agent Wallet action link.
flowchart LR
Agent["AI Agent / Browser"] -->|1. Request API or /mcp| Edge["@redcenterstudio/agent-tollbooth-edge"]
Edge -->|2. Unpaid -> 402 JSON or HTML Card| Agent
Agent -->|3A. Rail A: PAYMENT-SIGNATURE x402 V2| Edge
Agent -->|3B. Rail B: Bearer rcs_receipt_... <1ms Web Crypto| Edge
Edge -->|4A. /verify & /settle| Facilitator["Clearinghouse Worker / Facilitator"]
Edge -->|4B. HMAC-SHA256 / Ed25519 + D1 used_nonces| NonceDB[("Cloudflare D1")]
Facilitator -->|Atomic Debit & Ledger| NonceDB
Edge -->|5. 200 OK + PAYMENT-RESPONSE| Agent
Pricing & Revenue Split
| Tier | Price | Clearinghouse Fee (Developer Net) | What You Get |
|---|---|---|---|
| Free / BYO x402 Mode | $0 | 0% (100% net) | Unlimited /agent-tollbooth-402:scan-routes, zero-dependency middleware injection, /agent-tollbooth-402:test-agent simulator, exact x402 V2 scheme with any facilitator. |
| Hybrid Fiat + x402 Clearinghouse | $0/mo | 7% (93% net) | Enables Stripe-funded Fiat Agent Wallets (rcs_receipt_... <1ms edge verification) + automated Stripe Connect payouts via tollbooth.redcenterstudio.com. |
| Tollbooth Pro Pass | $39 one-time ($79 Agency) | 3% (97% net) | Drops clearinghouse fee from 7% to 3%, unlocks upto dynamic per-token/per-KB metering, custom HTML 402 pages, and per-agent spend caps. |
| Done-For-You Integration | From $399 | Custom | End-to-end custom MCP + HTTP 402 Tollbooth wrapping, D1 ledger setup, and verification by Red Center Studio. |
Plugin Installation (Antigravity + Claude Code)
Install in Claude Code:
/plugin install agent-tollbooth-402 --marketplace Red-Center-Studio/agent-tollbooth-402
Install in Antigravity (~/.gemini/config/plugins/):
git clone https://github.com/Red-Center-Studio/agent-tollbooth-402.git ~/.gemini/config/plugins/agent-tollbooth-402
Install the zero-dependency Edge Middleware in a Worker, Hono, or Next.js project:
npm install github:Red-Center-Studio/agent-tollbooth-402
- Remote MCP Server (
mcp_config.json&.mcp.json): Connects tohttps://tollbooth.redcenterstudio.com/mcpvia Streamable HTTP (tollbooth_pricing_quote,tollbooth_wallet_balance,tollbooth_issue_receipt,tollbooth_verify_x402). See our Privacy Policy. - Skills (
skills/):scan-routes: Audits Cloudflare Workers, Hono, Next.js App Router, Express, and MCP endpoints.install-tollbooth: Auto-detects framework, previews diff, and injects 1-stepwithTollbooth(...).test-agent: Runs the 30-second zero-config sandbox402 -> sign -> 200 OKsmoke test.
- Scoped Guardrails (
rules/http-402-guardrails.md): Enforces bypass exemptions, constant-time Web Crypto checks, replay protection, downstream5xxidempotency, integer microdollar math, and spend caps.
Troubleshooting FAQ
| Error Code | Meaning | Fix (fix_hint) |
|---|---|---|
MISSING_PAYMENT | Request had neither PAYMENT-SIGNATURE nor Bearer rcs_receipt_.... | Attach an x402 V2 PAYMENT-SIGNATURE header, a Rail B receipt, or use createSandboxReceipt() in mode: "sandbox". |
INSUFFICIENT_FUNDS | Payment authorization or wallet balance is below priceMicros. | Authorize at least priceMicros atomic units or top up the agent wallet balance. |
RECEIPT_EXPIRED | exp / iat / validBefore fell outside the +/-30s clock-skew window. | Re-sign a fresh receipt or x402 authorization using synchronized UTC seconds. |
NONCE_REPLAYED | The receipt jti or x402 nonce was already consumed in used_nonces. | Generate a new unique crypto.randomUUID() nonce/receipt for every new paid request. |
INVALID_SIGNATURE | Web Crypto HMAC/Ed25519 verification failed, or aud / payTo / network mismatched. | Confirm RECEIPT_SIGNING_SECRET, ed25519PublicKey, payTo, and target URL match. |
| Browser CORS blocked reading headers | Browser client cannot read PAYMENT-REQUIRED or PAYMENT-RESPONSE. | Middleware automatically sets Access-Control-Expose-Headers: PAYMENT-REQUIRED, PAYMENT-RESPONSE, X-Agent-Receipt, WWW-Authenticate, X-Tollbooth-Rail. |
Reference Clearinghouse Note (
packages/clearinghouse-worker): Includes placeholder D1 IDs (wrangler.jsonc) and.dev.vars.exampleplaceholders. Supply your own D1 database and Wrangler secrets before deploying to your own Cloudflare account.
License
MIT — Red Center Studio (https://redcenterstudio.com)
No installation packages available.
Remote
Related Servers
io.github.Red-Center-Studio/nocode-migrator
Move a Bubble® app's UI, backend, D1 data, and R2 files to your Cloudflare account. Free preview.
io.github.Red-Center-Studio/rcs-tools
Free website checks: AI search readiness, AI crawler access, domain health, DNS risks. No key.
io.github.Red-Center-Studio/sitewatch
Website monitoring in Claude: domain, certificate, DNS and email checks with plain alerts and fixes.

