Philosophy
Why Tollstile exists, what it believes, and what it refuses to become.
The problem
Software is starting to buy software. Protocols such as x402 and MPP define how a payment is requested and proven. What nobody standardizes is everything a merchant builds around it: deciding who has to pay, verifying against your own price, settling at the right moment, refunding when the work didn't happen, surviving retries and crashes, and recording every outcome.
Every team rebuilds this. Payment code rebuilt in a hurry is payment code that leaks money.
Core beliefs
The lifecycle is the product, not the protocol
Protocols will converge, fork, and absorb each other. What every merchant needs regardless is the same: price, grant access, verify, settle, fulfill, refund, record.
Who pays is separate from how they pay
Rails answer how a payment is made. Access policies answer whether the caller must pay. They are configured separately and composed per route.
Rails share a lifecycle, not a lowest common denominator
Every rail implements the same lifecycle contract and declares its capabilities: flows, single or reusable authorizations, variable amounts, quotes, refunds, and lookup. Mismatches fail at startup.
You own the ledger
Payment records belong in your database as your operational record; the provider stays the final authority on whether money moved, and reconciliation keeps the two in agreement. No Tollstile account, no required dashboard, no telemetry.
Tollstile never takes custody of funds
A library that holds money is a financial institution with a README. Tollstile verifies, asks the provider to settle or refund, and records.
No duplicate economic effects
Exactly-once execution is not achievable across a network, a database, a provider, and your handler. Charges are state machines on a payment axis and a fulfillment axis; retries, replays, and recovery never settle or refund twice. Ambiguous outcomes are unknown until reconciled.
Fail closed, and make trade-offs explicit
A failure while verifying always denies. Flows and fulfillment are explicit choices, never hidden defaults. The price charged is the price quoted.
The first paid request takes five minutes
The test rail and memory ledger run the full lifecycle with no wallet, network, or account.
How we decide
- Money correctness — no unpaid access, no duplicate economic effects, no hidden outcomes.
- Security — verify everything, trust nothing from the wire.
- Neutrality — no rail, provider, or platform gets special treatment.
- Developer experience — small, typed, obvious.
- Simplicity — less code, fewer concepts.
- Performance — only with a benchmark.
What we say no to
- Claiming exactly-once execution.
- Guessing the outcome of an ambiguous settlement.
- Token swaps, currency conversion, or issuing a token.
- A default or recommended rail.
- Required cloud services, accounts, or telemetry.
- Issuing identities. Tollstile verifies evidence; it does not issue it.
- Deciding prices for you.
Open source promise
Tollstile is MIT-licensed and complete. Everything needed to charge for APIs and tools in production is in the library, free. If a hosted product ever exists, it will offer things that genuinely require hosting — never features removed from the library.