Installation
Packages, what each one does, and which are available today.
Public Beta · early access
npm install tollstile| Package | Purpose | Status |
|---|---|---|
tollstile | Core: quotes, execution plans, idempotency, structured denials, authorizations, charges, flows, reconciliation, access policies (subscriber, credits, payPerCall), requirements (limit, payers, when), test rail, memory ledger | Implemented |
@tollstile/hono | Hono middleware (Node, Bun, Deno, Workers) | Implemented |
@tollstile/mcp | MCP tools on @modelcontextprotocol/sdk | Implemented; tested with the real SDK |
@tollstile/express | Express 5 routes | Implemented; tested with a real Express app |
@tollstile/next | Next.js App Router route handlers | Implemented; not yet run inside a Next.js app |
@tollstile/fetch | Web-standard handlers: Workers, Deno, Bun | Implemented; running on Cloudflare Workers in the live demo. Not yet run on Deno or Bun |
create-tollstile | Project template with a paid route and a paying test agent | Implemented |
@tollstile/x402 | x402 rail (exact, upto) over HTTP and MCP | exact verified on Base Sepolia with x402.org, including a real USDC transfer; upto and production facilitators not verified |
@tollstile/mpp | MPP rails: Stripe charge, Tempo charge, Tempo session | Stripe charge verified in Stripe test mode, including retries, refunds, and reconciliation. Tempo not run against a node; Tempo session is experimental |
@tollstile/l402 | L402 (Lightning) rail | Implemented; not verified against a Lightning node |
@tollstile/kyapay | KYAPay rail | Implemented; not verified against Skyfire |
@tollstile/web-bot-auth | verifiedAgent() via HTTP message signatures | Implemented; not verified against a live agent |
@tollstile/ap2 | userMandate() via AP2 mandates | Experimental |
@tollstile/postgres | Postgres ledger: pg, postgres.js, Neon, PGlite | Implemented; tested on PGlite, and on a real PostgreSQL 16 server in CI under 100-way concurrency and crash recovery |
@tollstile/sqlite | SQLite ledger: node:sqlite, better-sqlite3, bun:sqlite, D1 | Implemented; tested on node:sqlite, and running on D1 in the live demo |
Every package is tested against fakes, published test vectors, and reference libraries. Two have been run against real providers in test environments: x402 on Base Sepolia, and MPP's Stripe rail in Stripe test mode. The rest — Tempo, Lightning nodes, Skyfire — have never been contacted. Each rail's page has a Verification status section with what was tested and how to check it live.
Create an instance
import { createTollstile, memoryLedger, testRail } from "tollstile";
export const toll = createTollstile({
rails: [testRail()],
ledger: memoryLedger(),
// Required with live rails: signs quotes. Use at least 32 random characters.
// secret: process.env.TOLLSTILE_SECRET,
});| Option | Default | Purpose |
|---|---|---|
rails | — | Rails you accept. Test rails cannot be mixed with live rails. |
ledger | — | Where authorizations, charges, and claims are recorded. |
secret | random (test rails only) | Signs quotes. A list rotates: the first signs, all verify. |
quoteTtlMs | 5 minutes | How long a quote is honored. |
maxRequestBytes | 1 MiB | The largest body this instance will price. A request declaring more is refused before anything else happens; one that declares nothing is refused the moment its stream passes the limit, on any route that reads the body. Routes that never read it are not buffered. See SECURITY.md. |
providerTimeoutMs | 10 seconds | Upper bound for any provider call. |
clock | system clock | Inject for tests. |
onEvent | — | Typed lifecycle events for logs and metrics. |
The conformance kit is exported from tollstile/testing, a subpath of tollstile; there is no separate testing package to install.