Pay-per-Crawl for Node · v0.1.2 · free, open sourceCharge AI crawlers in Express, Fastify, Hono or Koa
One adapter package for the four common Node servers. Mount it before your routes and every page is gated the same way.
Works with: Express, Fastify, Hono (Node, Bun, Deno, Workers), Koa
Install
npm install @forgemeshlabs/pay-per-crawl-node
Add the gate
import { payPerCrawl } from "@forgemeshlabs/pay-per-crawl-node/express";
app.use(payPerCrawl({ payTo: "0xYourWallet", mode: "monitor" })); // before your routesimport { payPerCrawl } from "@forgemeshlabs/pay-per-crawl-node/fastify";
await app.register(payPerCrawl, { payTo: "0xYourWallet", mode: "gate" });import { payPerCrawl } from "@forgemeshlabs/pay-per-crawl-node/hono";
app.use("*", payPerCrawl({ payTo: "0xYourWallet" }));import { payPerCrawl } from "@forgemeshlabs/pay-per-crawl-node/koa";
app.use(payPerCrawl({ payTo: "0xYourWallet" }));Turn it on
- 1Install the package and mount the adapter for your framework before your routes.
- 2Pass payTo and priceUsd as options, or set PAY_TO and PRICE_USD in the environment.
- 3Run in monitor mode first and read the per-request events, then set mode: "gate".
Settings
| PAY_TO | Your 0x wallet on Base. Required to charge. |
|---|---|
| PRICE_USD | Price per page fetch in USDC. Default 0.01, minimum 0.005. |
| MODE | monitor (default) logs what bots would have paid; gate answers 402. |
| FACILITATOR_URL | Any x402 facilitator that settles on Base. Default PayAI, no API key. |
| CLASS_POLICY | JSON per class: search, social, monitor, seo, ai, automation, bot → free, paid or block. |
| BOT_OVERRIDES | JSON per crawler name, wins over the class: {"GPTBot":"paid","Bytespider":"block"}. |
| ALLOW_PATHS | Comma list of path prefixes that are never gated. |
| TRUST_HEADER | Header carrying the real client IP behind your proxy. Right-most entry is used. |
| MPP_SECRET | Long random string signing MPP challenges. Set it so challenges survive restarts. |
| PRO_KEY | Optional Pay-per-Crawl Pro license for the hosted dashboard. |
Things to know
- Express, Fastify and Koa verify search engines with Node DNS. Hono uses DNS-over-HTTPS so it also runs on edge runtimes.
- Set trustHeader only to a header your own proxy overwrites or appends, such as x-forwarded-for behind nginx. Without it the socket address is used.
- Replay lock is in memory per process. Pass a store to share it across instances.
- Behind Cloudflare, set AI Crawl Control and any "Block AI bots" rule to Allow for the crawlers you want to charge. A crawler blocked at the edge never reaches the gate and never sees the 402.
- Humans never see a 402. Search engines are verified by reverse DNS; a request that only claims to be Googlebot is charged.
- Start in monitor mode. It logs every bot with what it would have paid and never blocks. Switch to gate when the numbers make sense.
Proof it settles
Real settlements on Base mainnet through the PayAI facilitator, $0.01 each, October 2026:
- Same core as the Next.js edition; mainnet hashes on that guide