Tollbooth (pay-per-crawl)

agent402-tollbooth · npm · MIT

The sell side: middleware or a reverse proxy that puts a per-request price on a site or API for AI crawlers and agents while human visitors browse free. One 402 carries an x402 offer and an MPP challenge, plus a proof-of-work path for a walletless agent. Non-custodial: payments go to your own wallet.

Install

npm install agent402-tollbooth express @x402/express @x402/core @x402/evm

Example

import express from "express";
import { createTollbooth } from "agent402-tollbooth";
import { paymentMiddleware } from "@x402/express";
import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const payTo = "0xYourWallet";
const price = "$0.002";
// verifies and settles USDC on Base through the x402 facilitator you choose
const x402 = paymentMiddleware(
  { "/*": { accepts: [{ scheme: "exact", network: "eip155:8453", price, payTo }] } },
  new x402ResourceServer(new HTTPFacilitatorClient({ url: process.env.X402_FACILITATOR_URL }))
    .register("eip155:8453", new ExactEvmScheme()),
);

const app = express();
// People pass through; known AI crawlers get a 402 and pay (x402 or MPP) or solve a proof-of-work.
app.use(createTollbooth({ payTo, price, x402 }));

app.get("/article", (_req, res) => res.send("...your content..."));
app.listen(3000);

What it exposes

createTollbooth(config): Express-compatible middleware with charge modes, adaptive proof-of-work and a stats sink.
npx agent402-tollbooth: a reverse proxy that needs no code change on the origin.
An edge build on the Web Crypto and Fetch APIs, with deploy templates for Cloudflare Workers, Next.js and Docker.
gate.stats() in the middleware for what was served and paid; the reverse proxy and the Worker also serve a /__tollbooth dashboard.

How payment works

x402: USDC through a facilitator you choose, verified before the request is served and settled only on a successful response.
MPP: WWW-Authenticate: Payment challenges on the same 402, including native MPP on Tempo with split payments.
Proof-of-work: a sha256 puzzle, single-use and bound to the exact URL, so a crawler with no wallet can still get through.

# reverse proxy in front of any site, settling over x402 and MPP from env alone;
# install the gate with its x402 peers in one folder and run it from there
npm i agent402-tollbooth @x402/express @x402/core @x402/evm
TOLLBOOTH_UPSTREAM=https://your-site.com \
TOLLBOOTH_PAYTO=0xYourWallet \
TOLLBOOTH_FACILITATOR_URL=https://x402.org/facilitator \
TOLLBOOTH_NETWORK=base-sepolia \
npx agent402-tollbooth   # testnet dry run; for mainnet, drop TOLLBOOTH_NETWORK and use a mainnet facilitator

Your x402 middleware settles a payment only after your handler answers below 400, so a crawler is not charged for a failed request. Background: HTTP 402 Payment Required · Pay-per-call APIs.