# 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 a framework adapter such as `@tollstile/hono`, 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. Status: pre-release; the core, test rail, memory ledger, and Hono adapter are implemented; live rails, SQL ledgers, and other adapters are in development.

## 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.

## 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.
- [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.
- [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.
- [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

- [MPP](https://tollstile.com/llms.mdx/docs/rails/mpp/content.md): The Machine Payments Protocol — HTTP 402 with payment-method-agnostic credentials.
- [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): Stablecoin payments over HTTP 402, stewarded by the x402 Foundation.

## Integrations

- [Express](https://tollstile.com/llms.mdx/docs/adapters/express/content.md): Price Express routes.
- [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.
- [Next.js](https://tollstile.com/llms.mdx/docs/adapters/nextjs/content.md): Price Next.js route handlers.

## 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): Quotes, authorizations, charges on two axes, flows, reservations, and reconciliation — the model behind Tollstile.
- [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