# Tollstile

> Open-source payment middleware for APIs, MCP tools, and AI agents. Accept x402 and MPP payments with subscriptions, credits, spend limits, refunds, and a merchant-owned ledger.

Tollstile adds HTTP 402 pay-per-call pricing to API routes and MCP tools in TypeScript. Install `tollstile` and an adapter — `@tollstile/hono`, `@tollstile/express`, `@tollstile/next`, `@tollstile/fetch`, `@tollstile/mcp` for MCP tools, or `@tollstile/proxy` as a paid gateway in front of a service in any language (Python FastAPI, MCP Python SDK, Go) — create one instance with `createTollstile({ rails, ledger })`, and wrap a route: `app.get("/weather", tollstile(toll.price("$0.05")), handler)`. Prices are strings like "$0.05" or `upTo("$0.50")`, never numbers. Use `testRail()` and `memoryLedger()` for local development. Denials are JSON `{ error: { code, retryable, action, message, detail } }`: branch on `error.code` and follow `error.action` (pay, retry_later, fix_request, stop). Retry paid requests with an `Idempotency-Key` header (MCP: `_meta["tollstile/idempotency-key"]`) so a retry never pays twice. Status: public beta, early access. The API and payment behavior may change before v1.0, and some rails are experimental and may be unstable in production. Every package is implemented and tested against fakes, published test vectors, and reference libraries; each rail page states its verification status. AP2 userMandate and the MPP Tempo session rail are experimental.

## Getting started

- [Using Tollstile with coding agents](https://tollstile.com/llms.mdx/docs/coding-agents/content.md): Give Claude Code, Codex, Cursor, and other coding agents what they need to add payments with Tollstile.
- [Introduction](https://tollstile.com/llms.mdx/docs/content.md): Tollstile is open-source payment middleware for APIs, MCP tools, and AI agents.
- [Installation](https://tollstile.com/llms.mdx/docs/installation/content.md): Packages, what each one does, and which are available today.
- [Quickstart](https://tollstile.com/llms.mdx/docs/quickstart/content.md): Add pay-per-call pricing to an API in five minutes with the test rail. No wallet or account.

## Tutorials

- [Charge for MCP tool calls](https://tollstile.com/llms.mdx/docs/guides/charge-for-mcp-tools/content.md): Put a price on MCP tools with @tollstile/mcp. Build it on the test rail, call it from an MCP client, then accept x402 stablecoin payments.
- [Monetize an API with x402](https://tollstile.com/llms.mdx/docs/guides/monetize-an-api-with-x402/content.md): Charge per request in USDC with x402 on a Hono API. Build on the test rail, switch to x402 exact on Base Sepolia, and use upto for variable prices.
- [Accept x402 payments in Express](https://tollstile.com/llms.mdx/docs/guides/x402-with-express/content.md): Charge per request in USDC on an Express 5 API with @tollstile/express and the x402 rail, starting from the test rail.
- [Add a paid route to Next.js](https://tollstile.com/llms.mdx/docs/guides/nextjs-paid-route/content.md): Charge per call for a Next.js App Router route handler with @tollstile/next, from the test rail to x402 with a Postgres ledger.
- [Charge per call on Cloudflare Workers](https://tollstile.com/llms.mdx/docs/guides/cloudflare-workers/content.md): Price a Cloudflare Worker with @tollstile/fetch, keep the ledger in D1 with @tollstile/sqlite, and reconcile from a cron trigger.
- [Accept MPP payments](https://tollstile.com/llms.mdx/docs/guides/accept-mpp-payments/content.md): Accept Machine Payments Protocol payments with Stripe (cards through Shared Payment Tokens) and Tempo stablecoins, over HTTP and MCP.
- [Admit only verified agents](https://tollstile.com/llms.mdx/docs/guides/verified-agents-only/content.md): Require Web Bot Auth HTTP message signatures from trusted agents with verifiedAgent() from @tollstile/web-bot-auth, alongside payment.

## Common tasks

- [Add prepaid credits](https://tollstile.com/llms.mdx/docs/guides/add-credits/content.md): Let callers pay from a prepaid balance. Credits are reserved before the handler runs, then committed or released.
- [Add pay-per-call pricing to an API](https://tollstile.com/llms.mdx/docs/guides/add-pay-per-call-pricing/content.md): Charge AI agents and API clients a fixed price per request with HTTP 402, using Tollstile.
- [Add spend limits for agents](https://tollstile.com/llms.mdx/docs/guides/add-spend-limits/content.md): Cap how many paid calls and how much spend a single payer can make.
- [Let subscribers through without paying](https://tollstile.com/llms.mdx/docs/guides/add-subscriptions/content.md): Give active subscribers free access to paid routes while everyone else pays per call.
- [Charge for usage](https://tollstile.com/llms.mdx/docs/guides/charge-for-usage/content.md): Authorize a maximum per call and settle only what the handler actually used — for LLM, image, and video generation.
- [Dynamic pricing with quotes](https://tollstile.com/llms.mdx/docs/guides/dynamic-pricing/content.md): Compute a price per request and still charge exactly what the payer was quoted.
- [Early Access operations](https://tollstile.com/llms.mdx/docs/guides/early-access-operations/content.md): A provider-neutral checklist for running Tollstile safely in an early access environment.
- [Run reconciliation](https://tollstile.com/llms.mdx/docs/guides/reconciliation/content.md): Resolve charges left mid-lifecycle by crashes or unknown provider outcomes.
- [Test payment failures](https://tollstile.com/llms.mdx/docs/guides/test-payment-failures/content.md): Simulate provider outages, timeouts, and rejections with the test rail before real money is involved.

## Concepts

- [Access policies](https://tollstile.com/llms.mdx/docs/concepts/access-policies/content.md): Decide whether a caller has to pay, and from what.
- [Authorizations and charges](https://tollstile.com/llms.mdx/docs/concepts/authorizations-and-charges/content.md): What the payer authorized, each economic effect against it, and the two axes every charge moves on.
- [Errors](https://tollstile.com/llms.mdx/docs/concepts/errors/content.md): Machine-readable denials — a stable code, whether retrying helps, and what to do next.
- [Flows](https://tollstile.com/llms.mdx/docs/concepts/flows/content.md): The order in which a charge settles and the service runs.
- [Guarantees](https://tollstile.com/llms.mdx/docs/concepts/guarantees/content.md): What Tollstile promises, and what it does not.
- [Idempotency](https://tollstile.com/llms.mdx/docs/concepts/idempotency/content.md): Retry a paid request safely. Payer-scoped keys, recorded outcomes, and retries after released or refunded attempts.
- [Ledger](https://tollstile.com/llms.mdx/docs/concepts/ledger/content.md): Your operational record of authorizations, charges, and claims — in your own database.
- [Quotes](https://tollstile.com/llms.mdx/docs/concepts/quotes/content.md): What the server offered — signed, immutable, and never stored.
- [Rails](https://tollstile.com/llms.mdx/docs/concepts/rails/content.md): How an agent pays, and what each payment protocol can do.
- [Requirements](https://tollstile.com/llms.mdx/docs/concepts/requirements/content.md): Conditions every admitted request must meet, checked after the payer is known and before anything is reserved.

## Rails

- [Build a rail](https://tollstile.com/llms.mdx/docs/rails/build-a-rail/content.md): Add any payment protocol or provider to Tollstile with createRail(), a fake provider, and the conformance kit — no core changes.
- [Community rails](https://tollstile.com/llms.mdx/docs/rails/community/content.md): Rails published by others, how to get yours listed, and how a rail becomes an official @tollstile/* package.
- [KYAPay](https://tollstile.com/llms.mdx/docs/rails/kyapay/content.md): The KYAPay rail. Accept Skyfire pay and kya-pay tokens — funded holds charged per request until they are used up or expire.
- [L402](https://tollstile.com/llms.mdx/docs/rails/l402/content.md): The L402 (Lightning) rail. The payer pays an invoice once, then presents the macaroon and preimage on every call until the credential's value or lifetime runs out.
- [MPP](https://tollstile.com/llms.mdx/docs/rails/mpp/content.md): Machine Payments Protocol rails — Stripe charge (Shared Payment Tokens), Tempo charge, and the experimental Tempo session — over HTTP and MCP.
- [Test rail](https://tollstile.com/llms.mdx/docs/rails/test/content.md): Run the full payment lifecycle locally with no wallet, network, or account.
- [x402](https://tollstile.com/llms.mdx/docs/rails/x402/content.md): The x402 V2 rail. Agents pay per request in USDC or another EVM token; Tollstile verifies through a facilitator before the handler and settles after it succeeded.

## Ledgers

- [Postgres](https://tollstile.com/llms.mdx/docs/ledgers/postgres/content.md): Keep authorizations, charges, their transition history, and replay claims in your own PostgreSQL database with @tollstile/postgres.
- [SQLite and D1](https://tollstile.com/llms.mdx/docs/ledgers/sqlite/content.md): Keep the Tollstile ledger in SQLite — node:sqlite, better-sqlite3, bun:sqlite, or Cloudflare D1 — with @tollstile/sqlite.

## Integrations

- [Express](https://tollstile.com/llms.mdx/docs/adapters/express/content.md): Charge per call for Express 5 routes with paid() from @tollstile/express.
- [Fetch (Workers, Deno, Bun)](https://tollstile.com/llms.mdx/docs/adapters/fetch/content.md): Charge per call for Web-standard Request/Response handlers on Cloudflare Workers, Deno, Bun, and Node with paid() from @tollstile/fetch.
- [Hono](https://tollstile.com/llms.mdx/docs/adapters/hono/content.md): Charge per call for Hono routes on Node, Bun, Deno, and Cloudflare Workers.
- [MCP](https://tollstile.com/llms.mdx/docs/adapters/mcp/content.md): Charge per call for MCP tools on servers built with @modelcontextprotocol/sdk, with paidTool().
- [Next.js](https://tollstile.com/llms.mdx/docs/adapters/nextjs/content.md): Charge per call for Next.js App Router route handlers with paid() from @tollstile/next.
- [Proxy (any language)](https://tollstile.com/llms.mdx/docs/adapters/proxy/content.md): Charge for a FastAPI, Python MCP, Go, or Rails service without changing its code — put a Tollstile gateway in front of it.

## Comparisons

- [How Tollstile compares](https://tollstile.com/llms.mdx/docs/compare/overview/content.md): Tollstile compared with raw x402 middleware, MPP SDKs, edge gateways, and Stripe.
- [Tollstile vs MPP SDKs](https://tollstile.com/llms.mdx/docs/compare/tollstile-vs-mpp-sdk/content.md): What the Machine Payments Protocol SDK covers, and what Tollstile adds for merchants.
- [Tollstile vs Stripe](https://tollstile.com/llms.mdx/docs/compare/tollstile-vs-stripe/content.md): Why not just use Stripe to charge AI agents? How Tollstile and Stripe fit together.
- [Tollstile vs raw x402 middleware](https://tollstile.com/llms.mdx/docs/compare/tollstile-vs-x402/content.md): When the official x402 middleware is enough, and what Tollstile adds on top of x402 for APIs and MCP tools.

## Project

- [Core design](https://tollstile.com/llms.mdx/docs/design/content.md): The implemented request pipeline, execution plans, payment lifecycle, component contracts, and recovery model.
- [Philosophy](https://tollstile.com/llms.mdx/docs/philosophy/content.md): Why Tollstile exists, what it believes, and what it refuses to become.
- [Roadmap](https://tollstile.com/llms.mdx/docs/roadmap/content.md): What ships in v0.1, and what is out of scope.

## Optional

- [Full documentation](https://tollstile.com/llms-full.txt): every page as one Markdown file