agent402-tollbooth 0.9.2 → 0.9.3

package/README.md

@@ -10,17 +10,12 @@ The first self-hostable pay-per-crawl gate that speaks both wires on one 402 -
 the sell side of [Agentic Finance](https://agent402.tools/agentic-finance),
 where agents pay and sites get paid, per request, with no account in between.
 
-The big platforms are converging on the same model: Cloudflare's
-[pay-per-crawl](https://stackoverflow.blog/2026/02/26/how-pay-per-crawl-is-reshaping-data-monetization/)
-and now its [Monetization Gateway](https://blog.cloudflare.com/monetization-gateway/)
-(launched July 2026 - x402 charging in USDC on Base for anything behind Cloudflare:
-pages, APIs, datasets, MCP tools) confirm that pay-per-request is the business model
-of the agentic web. Tollbooth is the **open-source monetization gateway**: the same
-idea, but MIT-licensed and live today, running in
-front of *any* origin (even a Cloudflare Worker), non-custodial (you hold the wallet,
-no signup or Merchant-of-Record), and - the wedge the platform gateways don't offer -
-with a **proof-of-work free tier** so a walletless agent still has a path through.
-Built on the same hardened 402 + proof-of-work machinery as
+Tollbooth is an **open-source monetization gateway**: MIT-licensed, running in
+front of *any* origin (Express, a reverse proxy, Next.js, a Cloudflare Worker),
+non-custodial (you hold the wallet, no signup or Merchant-of-Record), settling
+over x402 and MPP on one 402 - including native MPP on Tempo with split
+payments - and with a **proof-of-work free tier** so a walletless agent still
+has a path through. Built on the same hardened 402 + proof-of-work machinery as
 [Agent402](https://github.com/MikeyPetrillo/Agent402).
 
 ## See it work (one command)
@@ -123,8 +118,7 @@ must pay, or `null` to let it through.
 **Ready-to-deploy templates** (copy a folder, don't assemble from docs):
 
 - **Cloudflare Workers** → [`deploy/cloudflare/`](deploy/cloudflare/) - a ready
-  `wrangler.toml` + a 3-step deploy guide (the open pay-per-crawl, on the
-  incumbent's own platform).
+  `wrangler.toml` + a 3-step deploy guide.
 - **Next.js / Vercel** → [`deploy/nextjs/`](deploy/nextjs/) - a drop-in
   `middleware.js` + a 3-step deploy guide.
 - **Docker** → [`deploy/docker/`](deploy/docker/) - a `Dockerfile` +
@@ -162,8 +156,8 @@ export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)
 > On the edge, pass a stable `secret` (PoW tokens are HMAC-signed). For
 > single-use replay protection across stateless invocations, supply a `store`
 > (e.g. a Cloudflare KV wrapper - the Worker entry wires this for you).
-> The `x402:` middleware mode and MPP are Node/Express features today; the
-> edge gate offers proof-of-work plus the `verifyX402` callback.
+> The `x402:` middleware mode, MPP and the native Tempo rail are Node/Express
+> features today; the edge gate offers proof-of-work plus the `verifyX402` callback.
 
 ## Accepting USDC: x402 and MPP on the same 402
 
@@ -240,9 +234,21 @@ app.use(createTollbooth({
 }));
 ```
 
+The `tempo` object takes `apiKey` (required), `recipient` (required, your
+Tempo payTo), `currency` or `currencies` (TIP-20 token addresses; default USDC.e
+`0x20C000000000000000000000b9537d11c60E8b50`, one challenge minted per currency,
+first = preferred), `splits` (up to 10, total below the price, same transaction),
+`chainId` (default 4217, Tempo mainnet), `apiBaseUrl` (relay, default
+`https://api.tempo.xyz`), `decimals` (6), `timeoutSeconds` (300), plus the
+confirm knobs below. A bad config throws at construction - the gate never boots
+minting unpayable challenges.
+
 Or from env on the CLI: `TOLLBOOTH_TEMPO_API_KEY`, `TOLLBOOTH_TEMPO_RECIPIENT`
-(defaults to `TOLLBOOTH_PAYTO`), optional `TOLLBOOTH_TEMPO_CURRENCY`,
-`TOLLBOOTH_TEMPO_SPLITS="0xabc:0.0002,0xdef:0.0001"`.
+(defaults to `TOLLBOOTH_PAYTO`), optional `TOLLBOOTH_TEMPO_CURRENCY` (CSV of
+token addresses), `TOLLBOOTH_TEMPO_SPLITS="0xabc:0.0002,0xdef:0.0001"`,
+`TOLLBOOTH_TEMPO_API_BASE` (relay override), `TOLLBOOTH_TEMPO_RPC_URL` (confirm
+RPC override). Tempo works with NO x402 middleware at all (a Tempo-only
+tollbooth) and next to one.
 
 Every 402 then carries a `WWW-Authenticate: Payment` tempo/charge challenge
 (next to any evm challenges from the x402 rail, if you run both); a stock
@@ -293,6 +299,9 @@ live incident transaction in the tests).
 | `mpp` | `true` when `x402` set | Accept MPP (`WWW-Authenticate: Payment` / `Authorization: Payment`) through the `x402` middleware |
 | `mppSecret` | `powSecret` / `TOLLBOOTH_SECRET` | HMAC secret binding MPP challenge ids (stable across workers) |
 | `mppNetworks` | `[8453, 42220]` | EVM chain ids to offer as MPP challenges (`"all"` = every EVM chain the middleware advertises) |
+| `tempo` | env (`TOLLBOOTH_TEMPO_*`) or off | Native MPP on Tempo (0.9.0): `{ apiKey, recipient, currency \| currencies, splits, chainId, apiBaseUrl, decimals, timeoutSeconds, confirm, confirmRpcUrl }` - mints `tempo/charge` challenges, validates with Tempo's relay before the handler, broadcasts after a <400 response. Works with or without `x402` |
+| `tempo.confirm` | `true` | Chain-truth confirm (0.9.2): on a relay broadcast failure, check the chain for the credential's own txid before answering 402; `false` disables |
+| `tempo.confirmRpcUrl` | `https://rpc.tempo.xyz` (`TOLLBOOTH_TEMPO_RPC_URL`) | Tempo JSON-RPC used by the confirm step |
 | `verifyX402(req, opts)` | – | Legacy verify-only USDC check (deprecated for settle-after-handler middlewares; see above) |
 | `resourceBaseUrl` | `""` | Absolute base used for the `resource` field / PoW binding |
 | `observe` | `false` | Observe-only: classify and count, but never 402. For pre-launch traffic measurement. |
@@ -309,11 +318,18 @@ Read by the bundled proxy / Express entry point (`index.js`):
 | `TOLLBOOTH_PAYTO` | – | Wallet address; advertises a USDC x402 quote (and, with `TOLLBOOTH_FACILITATOR_URL`, settles it) |
 | `TOLLBOOTH_FACILITATOR_URL` | – | x402 facilitator that settles your network. With `TOLLBOOTH_PAYTO` the CLI builds a real `@x402/express` middleware and takes payment over x402 **and** MPP (0.8.0). Needs `@x402/express @x402/core @x402/evm` installed; refuses to start without them |
 | `TOLLBOOTH_FACILITATOR_HEADERS` | – | Optional JSON object of auth headers sent on the facilitator's `/verify`, `/settle`, `/supported` (e.g. `{"X-API-Key":"…"}`) |
+| `TOLLBOOTH_CDP_API_KEY_ID` + `TOLLBOOTH_CDP_API_KEY_SECRET` | – | Settle through Coinbase's facilitator (CDP) instead of a URL: fee-free on Base, and the endpoint is indexed in Coinbase's x402 Bazaar. Needs `npm i @coinbase/x402`. This is how a Coinbase Business account gets paid by agents: `TOLLBOOTH_PAYTO` = the account's USDC (Base) receive address. |
 | `TOLLBOOTH_PRICE` | `"$0.001"` | Advertised price per request |
 | `TOLLBOOTH_NETWORK` | `"base"` | x402 network. CLI settlement mode accepts `base`, `base-sepolia`, `polygon`, `arbitrum`, `optimism`, `avalanche`, `celo`, `sei`, `monad`, or a raw `eip155:<id>` |
 | `TOLLBOOTH_MPP` | on when `x402` set | `false` to switch MPP off |
 | `TOLLBOOTH_MPP_SECRET` | `TOLLBOOTH_SECRET` | HMAC secret for MPP challenge ids |
 | `TOLLBOOTH_MPP_NETWORKS` | `8453,42220` | CSV of EVM chain ids to offer as MPP challenges, or `all` |
+| `TOLLBOOTH_TEMPO_API_KEY` | – | Tempo API key (`mpp:write` scope). Presence switches on the native Tempo rail (0.9.0) |
+| `TOLLBOOTH_TEMPO_RECIPIENT` | `TOLLBOOTH_PAYTO` | Tempo payTo (0x address) |
+| `TOLLBOOTH_TEMPO_CURRENCY` | USDC.e on Tempo | CSV of TIP-20 token addresses to offer (one challenge each, first = preferred) |
+| `TOLLBOOTH_TEMPO_SPLITS` | – | `0xabc:0.0002,0xdef:0.0001` - split recipients + USD amounts paid in the same transaction (≤10, total below the price) |
+| `TOLLBOOTH_TEMPO_API_BASE` | `https://api.tempo.xyz` | Tempo relay base URL override |
+| `TOLLBOOTH_TEMPO_RPC_URL` | `https://rpc.tempo.xyz` | Tempo JSON-RPC for the chain-truth confirm step (0.9.2) |
 | `TOLLBOOTH_ASSET` | `"USDC"` | Asset symbol in the quote (`USDG` charges in USDG on Robinhood Chain) |
 | `TOLLBOOTH_POW_BITS` | `18` | Proof-of-work difficulty in leading zero bits |
 | `TOLLBOOTH_MODE` | `"bots"` | Who pays: `bots` · `all` · `strict` |
@@ -381,7 +397,7 @@ changes. Bots see a `X-Tollbooth-Observed: would-charge` header in observe mode
 ## Analytics
 
 The middleware keeps aggregate counters (no per-request data):
-- `gate.stats()` → sync, in-process mirror: `{ requests, freeAllowed, wouldCharge, charged, powSolved, x402Paid, mppPaid, difficultyNow, observe }`.
+- `gate.stats()` → sync, in-process mirror: `{ requests, freeAllowed, wouldCharge, charged, powSolved, x402Paid, mppPaid, tempoPaid, difficultyNow, observe }`.
 - `gate.snapshot()` → async, reads from the configured durable sink (defaults to memory).
 - `gate.flush()` → flush any buffered deltas to the durable sink (call inside `ctx.waitUntil` on edge runtimes).
 
@@ -585,3 +601,23 @@ Celo by default - what a stock mppx client can sign); add `4663` there or pass
 ## Legal
 
 Use of the hosted instance at agent402.tools is subject to its [Terms of Service](https://agent402.tools/terms) (acceptable-use policy included) and [Privacy Policy](https://agent402.tools/privacy). This package is MIT-licensed; the hosted server is AGPL-3.0. Both are provided as-is without warranty, and self-hosted deployments are their operator's responsibility.
+
+## Get paid into a Coinbase Business account
+
+Coinbase Business accounts receive x402 payments from AI agents directly. The
+tollbooth is the "integrate x402 into your API" step: 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
+TOLLBOOTH_PAYTO=0xYourCoinbaseBusinessBaseAddress \
+TOLLBOOTH_CDP_API_KEY_ID=... TOLLBOOTH_CDP_API_KEY_SECRET=... \
+TOLLBOOTH_PRICE='$0.005' TOLLBOOTH_UPSTREAM=http://localhost:8080 \
+npx agent402-tollbooth
+```
+
+Every paid request settles as USDC into the Coinbase Business account; humans
+browse your site normally. Full walkthrough with an Express example:
+https://agent402.tools/guides/coinbase-business-get-paid-by-agents
+

package/index.js

@@ -686,9 +686,16 @@ export const CLI_NETWORKS = {
 export async function buildCliX402Middleware(env = process.env) {
   const payTo = env.TOLLBOOTH_PAYTO || "";
   const facilitatorUrl = env.TOLLBOOTH_FACILITATOR_URL || "";
+  // Coinbase's facilitator (CDP) authenticates every verify/settle call with
+  // a short-lived JWT signed by a CDP API key, so a static header cannot
+  // reach it; @coinbase/x402's createFacilitatorConfig mints them. With the
+  // two keys set the CLI settles through CDP (fee-free on Base, and the
+  // endpoint is indexed in Coinbase's x402 Bazaar), no URL needed. This is
+  // the path a Coinbase Business account uses to get paid by agents.
+  const cdpKeys = env.TOLLBOOTH_CDP_API_KEY_ID && env.TOLLBOOTH_CDP_API_KEY_SECRET;
   if (!payTo) return null;
-  if (!facilitatorUrl) {
-    console.warn("⚠ TOLLBOOTH_PAYTO is set without TOLLBOOTH_FACILITATOR_URL: the 402 advertises a USDC quote but nothing here can verify or settle a payment, so every paid request is refused. Set TOLLBOOTH_FACILITATOR_URL (a public x402 facilitator that settles your network - keyless free tiers exist; https://x402.org/facilitator for base-sepolia) to actually charge, over x402 and MPP.");
+  if (!facilitatorUrl && !cdpKeys) {
+    console.warn("⚠ TOLLBOOTH_PAYTO is set without TOLLBOOTH_FACILITATOR_URL (or TOLLBOOTH_CDP_API_KEY_ID/SECRET): the 402 advertises a USDC quote but nothing here can verify or settle a payment, so every paid request is refused. Set TOLLBOOTH_FACILITATOR_URL (a public x402 facilitator that settles your network - keyless free tiers exist; https://x402.org/facilitator for base-sepolia) to actually charge, over x402 and MPP.");
     return null;
   }
   const asset = (env.TOLLBOOTH_ASSET || "USDC").toUpperCase();
@@ -717,7 +724,17 @@ export async function buildCliX402Middleware(env = process.env) {
   if (env.TOLLBOOTH_FACILITATOR_HEADERS) {
     try { authHeaders = JSON.parse(env.TOLLBOOTH_FACILITATOR_HEADERS); } catch { console.error("✖ TOLLBOOTH_FACILITATOR_HEADERS must be a JSON object of header name -> value. Refusing to start."); process.exit(1); }
   }
-  const client = new HTTPFacilitatorClient({
+  let cdpConfig = null;
+  if (cdpKeys) {
+    try {
+      const { createFacilitatorConfig } = await import("@coinbase/x402");
+      cdpConfig = createFacilitatorConfig(env.TOLLBOOTH_CDP_API_KEY_ID, env.TOLLBOOTH_CDP_API_KEY_SECRET);
+    } catch (e) {
+      console.error(`✖ TOLLBOOTH_CDP_API_KEY_ID/SECRET are set, so this gate must settle through Coinbase's facilitator, but @coinbase/x402 is not installed (${String(e?.message || e).slice(0, 120)}). Install it: npm install @coinbase/x402`);
+      process.exit(1);
+    }
+  }
+  const client = new HTTPFacilitatorClient(cdpConfig || {
     url: facilitatorUrl,
     ...(authHeaders ? { createAuthHeaders: async () => ({ verify: authHeaders, settle: authHeaders, supported: authHeaders }) } : {}),
   });
@@ -857,7 +874,7 @@ async function startCli() {
     app.use((_req, res) => res.json({ ok: true, note: "Bare tollbooth gate (no TOLLBOOTH_UPSTREAM set). Clients that reach here paid or solved a proof-of-work." }));
   }
   app.listen(port, () => {
-    const paidLabel = x402mw ? `x402 + MPP (${process.env.TOLLBOOTH_ASSET || "USDC"}, settling via ${process.env.TOLLBOOTH_FACILITATOR_URL})` : (process.env.TOLLBOOTH_PAYTO ? `x402 quote only (${process.env.TOLLBOOTH_ASSET || "USDC"}, NOT settling - set TOLLBOOTH_FACILITATOR_URL)` : "");
+    const paidLabel = x402mw ? `x402 + MPP (${process.env.TOLLBOOTH_ASSET || "USDC"}, settling via ${process.env.TOLLBOOTH_CDP_API_KEY_ID && process.env.TOLLBOOTH_CDP_API_KEY_SECRET ? "Coinbase CDP" : process.env.TOLLBOOTH_FACILITATOR_URL})` : (process.env.TOLLBOOTH_PAYTO ? `x402 quote only (${process.env.TOLLBOOTH_ASSET || "USDC"}, NOT settling - set TOLLBOOTH_FACILITATOR_URL)` : "");
     const rails = [gate.pow ? "proof-of-work" : "", paidLabel].filter(Boolean).join(" + ");
     console.log(`agent402-tollbooth listening on :${port} — charging AI bots via ${rails || "proof-of-work"}`);
     if (upstream) console.log(`  proxying → ${upstream}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Agent402 tollbooth: open-source, self-hostable pay-per-crawl for x402 AND MPP (the sell side of Agentic Finance): charge AI bots per request (USDC via x402, or MPP - the Machine Payments Protocol - through the same settlement, or USDG on Robinhood Chain, or free proof-of-work) while humans browse free. Drop-in Express middleware or reverse proxy that settles both wires from env alone - no Cloudflare, no Stripe, no signup.",
   "type": "module",
   "main": "index.js",
@@ -47,11 +47,15 @@
     "express": "^5.0.0"
   },
   "peerDependencies": {
+    "@coinbase/x402": ">=2.0.0",
     "@x402/core": ">=2.0.0",
     "@x402/evm": ">=2.0.0",
     "@x402/express": ">=2.0.0"
   },
   "peerDependenciesMeta": {
+    "@coinbase/x402": {
+      "optional": true
+    },
     "@x402/core": {
       "optional": true
     },