Installation
Packages, what each one does, and which are available today.
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; not yet run on Workers, 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 | Implemented; not verified against a live facilitator or chain |
@tollstile/mpp | MPP rails: Stripe charge, Tempo charge, Tempo session | Implemented; not verified against Stripe or Tempo. 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 |
@tollstile/sqlite | SQLite ledger: node:sqlite, better-sqlite3, bun:sqlite, D1 | Implemented; tested on node:sqlite |
Every package is tested against fakes, published test vectors, and reference libraries. None has been verified against live providers yet — real facilitators, chains, Stripe, Lightning nodes, or Skyfire. Each rail's page has a Verification status section with what was tested and how to check it live.
Not installable from npm yet
@tollstile/* 0.1.0 is on npm, but it depends on tollstile, which can be published again only after 2026-09-16 10:30 UTC (as [email protected]). Until then npm install fails with No versions available for tollstile. Build from the repository in the meantime. Install commands in these docs show the published names.
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. |
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.