toll-booth

Nostr: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

Monetise any API with one line of code.

Live demo - pay 21 sats, get a joke. No account. No sign-up. (API)

Try it now

npx @forgesworn/toll-booth demo

Spins up a fully working L402-gated joke API on localhost. Mock Lightning backend, in-memory storage, zero configuration. Scan the QR code from your terminal when the free tier runs out.

---

Minimal example

import express from 'express'
import { Booth } from '@forgesworn/toll-booth'
import { phoenixdBackend } from '@forgesworn/toll-booth/backends/phoenixd'

const app = express()
const booth = new Booth({
  adapter: 'express',
  backend: phoenixdBackend({ url: 'http://localhost:9740', password: process.env.PHOENIXD_PASSWORD! }),
  pricing: { '/api': 10 },           // 10 sats per request
  upstream: 'http://localhost:8080',  // your existing API
})

app.get('/invoice-status/:paymentHash', booth.invoiceStatusHandler as express.RequestHandler)
app.post('/create-invoice', booth.createInvoiceHandler as express.RequestHandler)
app.use('/', booth.middleware as express.RequestHandler)

app.listen(3000)

---

The old way vs toll-booth

	The old way	With toll-booth
Step 1	Create a Stripe account	npm install @forgesworn/toll-booth
Step 2	Verify your identity (KYC)	Set your pricing: { '/api': 10 }
Step 3	Integrate billing SDK	app.use(booth.middleware)
Step 4	Build a sign-up page	Done. No sign-up page needed.
Step 5	Handle webhooks, refunds, chargebacks	Done. Payments are final.

---

Five zeroes

Zero accounts. Zero API keys. Zero chargebacks. Zero KYC. Zero vendor lock-in.

Your API earns money the moment it receives a request. Clients pay with Lightning, Cashu ecash, or NWC — no relationship with you required. Payments settle instantly and are cryptographically final — no disputes, no reversals, no Stripe risk reviews.

---

See it in production

satgate is a pay-per-token AI inference proxy built on toll-booth. It monetises any OpenAI-compatible endpoint — Ollama, vLLM, llama.cpp — with one command. Token counting, model pricing, streaming reconciliation, capacity management. Everything else — payments, credits, free tier, macaroon auth — is toll-booth.

~400 lines of product logic on top of the middleware. That's what "monetise any API with one line of code" looks like in practice.

---

Let AI agents pay for your API

toll-booth is the server side of a two-part stack for machine-to-machine payments. 402-mcp is the client side - an MCP server that gives AI agents the ability to discover, pay, and consume L402-gated APIs autonomously.

AI Agent -> 402-mcp -> toll-booth -> Your API

An agent using Claude, GPT, or any MCP-capable model can call your API, receive a 402 payment challenge, pay the Lightning invoice from its wallet, and retry - all without human intervention. No OAuth dance, no API key rotation, no billing portal.

---

Live demo

Visit jokes.trotters.dev in a browser to try it - get a free joke, hit the paywall, scan the QR code or pay with a browser wallet extension.

Or use the API directly:

# Get a free joke (1 free per day per IP)
curl https://jokes.trotters.dev/api/joke

# Free tier exhausted - request a Lightning invoice for 21 sats
curl -X POST https://jokes.trotters.dev/create-invoice

# Pay the invoice with any Lightning wallet, then authenticate
curl -H "Authorization: L402 <macaroon>:<preimage>" https://jokes.trotters.dev/api/joke

---

Features

• L402 protocol - industry-standard HTTP 402 payment flow with macaroon credentials
• Multiple Lightning backends - Phoenixd, LND, CLN, LNbits, NWC (any Nostr Wallet Connect wallet)
• Alternative payment methods - Cashu ecash tokens and xcashu (NUT-24) direct-header payments
• IETF Payment authentication - implements draft-ryan-httpauth-payment-01, the emerging standard for HTTP payment authentication. HMAC-bound stateless challenges with Lightning settlement.
• x402 stablecoin payments - accepts x402 on-chain stablecoin payments (USDC on Base, Polygon) alongside Lightning and Cashu simultaneously
• Cashu-only mode - no Lightning node required; ideal for serverless and edge deployments
• Credit system - pre-paid balance with volume discount tiers
• Free tier - configurable daily allowance (IP-hashed, no PII stored)
• Privacy by design - no personal data collected or stored; IP addresses are one-way hashed with a daily-rotating salt before any processing
• Self-service payment page - QR codes, tier selector, wallet adapter buttons
• SQLite persistence - WAL mode, automatic invoice expiry pruning
• Three framework adapters - Express, Web Standard (Deno/Bun/Workers), and Hono
• Framework-agnostic core - use the Booth facade or wire handlers directly

---

Quick start

npm install @forgesworn/toll-booth

Express

import express from 'express'
import { Booth } from '@forgesworn/toll-booth'
import { phoenixdBackend } from '@forgesworn/toll-booth/backends/phoenixd'

const app = express()
app.use(express.json())

const booth = new Booth({
  adapter: 'express',
  backend: phoenixdBackend({
    url: 'http://localhost:9740',
    password: process.env.PHOENIXD_PASSWORD!,
  }),
  pricing: { '/api': 10 },           // 10 sats per request
  upstream: 'http://localhost:8080',  // your API
  rootKey: process.env.ROOT_KEY,      // 64 hex chars, required for production
})

app.get('/invoice-status/:paymentHash', booth.invoiceStatusHandler as express.RequestHandler)
app.post('/create-invoice', booth.createInvoiceHandler as express.RequestHandler)
app.use('/', booth.middleware as express.RequestHandler)

app.listen(3000)

Web Standard (Deno / Bun / Workers)

import { Booth } from '@forgesworn/toll-booth'
import { lndBackend } from '@forgesworn/toll-booth/backends/lnd'

const booth = new Booth({
  adapter: 'web-standard',
  backend: lndBackend({
    url: 'https://localhost:8080',
    macaroon: process.env.LND_MACAROON!,
  }),
  pricing: { '/api': 5 },
  upstream: 'http://localhost:8080',
})

// Deno example
Deno.serve({ port: 3000 }, async (req: Request) => {
  const url = new URL(req.url)
  if (url.pathname.startsWith('/invoice-status/'))
    return booth.invoiceStatusHandler(req)
  if (url.pathname === '/create-invoice' && req.method === 'POST')
    return booth.createInvoiceHandler(req)
  return booth.middleware(req)
})

Hono

import { Hono } from 'hono'
import { createHonoTollBooth, type TollBoothEnv } from '@forgesworn/toll-booth/hono'
import { phoenixdBackend } from '@forgesworn/toll-booth/backends/phoenixd'
import { createTollBooth } from '@forgesworn/toll-booth'
import { sqliteStorage } from '@forgesworn/toll-booth/storage/sqlite'

const storage = sqliteStorage({ path: './toll-booth.db' })
const engine = createTollBooth({
  backend: phoenixdBackend({ url: 'http://localhost:9740', password: process.env.PHOENIXD_PASSWORD! }),
  storage,
  pricing: { '/api': 10 },
  upstream: 'http://localhost:8080',
  rootKey: process.env.ROOT_KEY!,
})

const tollBooth = createHonoTollBooth({ engine })
const app = new Hono<TollBoothEnv>()

// Mount payment routes
app.route('/', tollBooth.createPaymentApp({
  storage,
  rootKey: process.env.ROOT_KEY!,
  tiers: [],
  defaultAmount: 1000,
}))

// Gate your API
app.use('/api/*', tollBooth.authMiddleware)
app.get('/api/resource', (c) => {
  const balance = c.get('tollBoothCreditBalance')
  return c.json({ message: 'Paid content', balance })
})

export default app

Cashu-only (no Lightning node)

import { Booth } from '@forgesworn/toll-booth'

const booth = new Booth({
  adapter: 'web-standard',
  redeemCashu: async (token, paymentHash) => {
    // Verify and redeem the ecash token with your Cashu mint
    // Return the amount redeemed in satoshis
    return amountRedeemed
  },
  pricing: { '/api': 5 },
  upstream: 'http://localhost:8080',
})

No Lightning node, no channels, no liquidity management. Ideal for serverless and edge deployments.

xcashu (Cashu ecash via NUT-24)

import { Booth } from '@forgesworn/toll-booth'

const booth = new Booth({
  adapter: 'web-standard',
  xcashu: {
    mints: ['https://mint.minibits.cash'],
    unit: 'sat',
  },
  pricing: { '/api': 10 },
  upstream: 'http://localhost:3000',
})

Clients pay by sending X-Cashu: cashuB... tokens in the request header. Proofs are verified and swapped at the configured mint(s) using cashu-ts.

Unlike the redeemCashu callback (which integrates Cashu into the L402 payment-and-redeem flow), xcashu is a self-contained payment rail: the client attaches a token directly to the API request and gets access in one step — no separate redeem endpoint required. Both rails can run simultaneously; the 402 challenge will include both WWW-Authenticate (L402) and X-Cashu headers.

IETF Payment (draft-ryan-httpauth-payment-01)

const booth = new Booth({
  adapter: 'express',
  backend: phoenixdBackend({ url: '...', password: '...' }),
  ietfPayment: {
    realm: 'api.example.com',
    // hmacSecret auto-derived from rootKey if omitted
  },
  pricing: { '/api': 10 },
  upstream: 'http://localhost:8080',
})

Implements the IETF Payment authentication scheme - the emerging standard for HTTP payment authentication. Challenges are stateless (HMAC-SHA256 bound, no database lookup on verify), with JCS-encoded charge requests and timing-safe validation. The 402 response includes a WWW-Authenticate: Payment header alongside the L402 challenge, so clients can use whichever scheme they support.

---

Guides

• Monetise any Express API in 60 seconds
• Monetise your Ollama endpoint
• Let AI agents pay for your API

---

Case studies

• satgate: Pay-per-token AI inference
• jokes.trotters.dev: From zero to production L402 API

---

Lightning backends

import { phoenixdBackend } from '@forgesworn/toll-booth/backends/phoenixd'
import { lndBackend } from '@forgesworn/toll-booth/backends/lnd'
import { clnBackend } from '@forgesworn/toll-booth/backends/cln'
import { lnbitsBackend } from '@forgesworn/toll-booth/backends/lnbits'
import { nwcBackend } from '@forgesworn/toll-booth/backends/nwc'

Each backend implements the LightningBackend interface (createInvoice + checkInvoice).

Backend	Status	Notes
Phoenixd	Stable	Simplest self-hosted option
LND	Stable	Industry standard
CLN	Stable	Core Lightning REST API
LNbits	Stable	Any LNbits instance - self-hosted or hosted
NWC	Stable	Any Nostr Wallet Connect wallet (Alby Hub, Mutiny, Umbrel, Phoenix, etc.) — E2E encrypted via NIP-44

---

Why not Aperture?

Aperture is Lightning Labs' production L402 reverse proxy. It's battle-tested and feature-rich. Use it if you can.

	Aperture	toll-booth
Language	Go binary	TypeScript middleware
Deployment	Standalone reverse proxy	Embeds in your app, or runs as a gateway in front of any HTTP service
Lightning node	Requires LND	Phoenixd, LND, CLN, LNbits, NWC, or none (Cashu-only)
Payment rails	Lightning only	Lightning, Cashu ecash, xcashu (NUT-24), x402 stablecoins, IETF Payment - simultaneously
IETF Payment	No	Yes - draft-ryan-httpauth-payment-01 with stateless HMAC challenges
x402 stablecoins	No	Yes - USDC on Base, Polygon via pluggable facilitator
Cashu ecash	No	Yes - redeemCashu callback + xcashu (NUT-24) direct-header rail
Credit system	No	Pre-paid balance with volume discount tiers
Framework adapters	N/A (standalone proxy)	Express, Web Standard (Deno/Bun/Workers), Hono
Serverless	No - long-running process	Yes - Web Standard adapter runs on Cloudflare Workers, Deno, Bun
Configuration	YAML file	Programmatic (code)

For a detailed comparison with all alternatives, see docs/comparison.md.

---

x402 stablecoin payments

x402 is Coinbase's HTTP 402 payment protocol for on-chain stablecoins. toll-booth speaks it natively. A single deployment accepts Lightning and x402 stablecoins and Cashu — simultaneously. The seller doesn't care how they get paid. They just want paid.

const booth = new Booth({
  adapter: 'express',
  backend: phoenixdBackend({ url: '...', password: '...' }),
  x402: {
    receiverAddress: '0x1234...abcd',
    network: 'base',
    facilitator: myFacilitator, // verifies on-chain settlement
  },
  pricing: { '/api': { sats: 10, usd: 5 } }, // price in both currencies
  upstream: 'http://localhost:8080',
})

The 402 challenge includes both WWW-Authenticate (L402) and Payment-Required (x402) headers. Clients choose their preferred rail. x402 payments settle into the same credit system as Lightning — volume discount tiers apply regardless of payment method.

The unique value of toll-booth isn't any single payment rail. It's the middleware layer: gating, credit accounting, free tiers, volume discounts, upstream proxying, and macaroon credentials — all framework-agnostic, all runtime-agnostic, all payment-rail agnostic. Payment protocols are pluggable rails. toll-booth is the booth.

---

Using toll-booth with any API

toll-booth works as a reverse proxy gateway, so the upstream API can be written in any language - C#, Go, Python, Ruby, Java, or anything else that speaks HTTP. The upstream service doesn't need to know about L402 or Lightning; it just receives normal requests.

Client ---> toll-booth (Node.js) ---> Your API (any language)
                |                          |
          L402 payment gating        Plain HTTP requests
          Macaroon verification      X-Credit-Balance header added

Point upstream at your existing service:

const booth = new Booth({
  adapter: 'express',
  backend: phoenixdBackend({ url: '...', password: '...' }),
  pricing: { '/api/search': 5, '/api/generate': 20 },
  upstream: 'http://my-dotnet-api:5000',  // ASP.NET, FastAPI, Gin, Rails...
})

Deploy toll-booth as a sidecar (Docker Compose, Kubernetes) or as a standalone gateway in front of multiple services. See examples/valhalla-proxy/ for a complete Docker Compose reference - the Valhalla routing engine it gates is a C++ service.

---

Production checklist

• Set a persistent rootKey (64 hex chars / 32 bytes). Without it, a random key is generated per restart and all existing macaroons become invalid. Generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
• Use a persistent dbPath (default: ./toll-booth.db).
• Enable strictPricing: true to prevent unpriced routes from bypassing billing.
• Ensure your pricing keys match the paths the middleware actually sees (after mounting).
• Set trustProxy: true when behind a reverse proxy, or provide a getClientIp callback for per-client free-tier isolation.
• If you implement redeemCashu, make it idempotent for the same paymentHash - crash recovery depends on it.
• Rate-limit /create-invoice at your reverse proxy - each call creates a real Lightning invoice.

---

Example deployments

sats-for-laughs - build your own paid API

examples/sats-for-laughs/ is the fastest path from "I have an API" to "my API earns sats". It's the same code that runs the live demo. Includes a web frontend with QR codes and wallet adapter buttons, plus a JSON API for programmatic access. Clone it, change three env vars, deploy.

cd examples/sats-for-laughs
cp .env.example .env          # add your Phoenixd credentials
docker compose up -d          # or: MOCK=true npm start

Includes mock mode for local development (auto-settles invoices, no Lightning node needed), Docker Compose with Phoenixd, and a pre-generated pool of 100+ jokes across six topics.

valhalla-proxy - production reference

examples/valhalla-proxy/ gates the Valhalla routing engine (a C++ service) behind Lightning payments. Full Docker Compose setup demonstrating toll-booth as a sidecar proxy in front of non-JavaScript infrastructure.

---

Payment flow

sequenceDiagram
    participant C as Client
    participant T as toll-booth
    participant U as Upstream API

    C->>T: GET /api/resource
    T->>T: Check free tier
    alt Free tier available
        T->>U: Proxy request
        U-->>T: Response
        T-->>C: 200 + X-Free-Remaining header
    else Free tier exhausted
        T-->>C: 402 + Invoice + Macaroon
        C->>C: Pay via Lightning / Cashu / NWC
        C->>T: GET /api/resource<br/>Authorization: L402 macaroon:preimage
        T->>T: Verify macaroon + preimage
        T->>T: Settle credit + debit cost
        T->>U: Proxy request
        U-->>T: Response
        T-->>C: 200 + X-Credit-Balance header
    end

Loading

1. Client requests a priced endpoint without credentials
2. Free tier checked - if allowance remains, request passes through
3. If exhausted - 402 response with BOLT-11 invoice + macaroon
4. Client pays via Lightning, NWC, or Cashu
5. Client sends Authorization: L402 <macaroon>:<preimage>
6. Macaroon verified, credit deducted, request proxied upstream

---

Configuration

The five most common options:

Option	Type	Description
adapter	'express' | 'web-standard' | 'hono'	Framework integration to use
backend	LightningBackend	Lightning node (optional if using Cashu-only)
pricing	Record<string, number>	Route pattern to cost in sats
upstream	string	URL to proxy authorised requests to
freeTier	{ requestsPerDay: number } or { creditsPerDay: number }	Daily free allowance per IP (request-count or sats-budget)

See docs/configuration.md for the full reference including rootKey, creditTiers, trustProxy, nwcPayInvoice, redeemCashu, and all other options.

---

Documentation

Document	Description
Why L402?	The case for permissionless, machine-to-machine payments
Architecture	How toll-booth, satgate, and 402-mcp fit together
Configuration	Full reference for all Booth options
Deployment	Docker, nginx, Cloudflare Workers, Deno, Bun, Hono
Security	Threat model, macaroon security, hardening measures
Migration	Upgrading from v1 to v2, and v2 to v3
Contributing	Development setup, conventions, adding backends

---

Ecosystem

Project	Role
toll-booth	Payment-rail agnostic HTTP 402 middleware
satgate	Production showcase — pay-per-token AI inference proxy (~400 lines on toll-booth)
402-mcp	Client side — AI agents discover, pay, and consume L402 APIs

---

Support

If you find toll-booth useful, consider sending a tip:

• Lightning: thedonkey@strike.me
• Nostr zaps: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

Licence

MIT