Rails
How an agent pays, and what each payment protocol can do.
A rail is how a payment is made and proven. It turns a price into an offer in its own asset, issues the protocol's challenge, verifies proofs, and settles, refunds, releases, and looks up charges through its provider.
Rails are not policies
A subscription is not a payment protocol, and x402 is not a pricing model. Rails decide how a payment is made; access policies decide whether a caller pays. See Access policies.
Capabilities
Rails genuinely differ. Each declares what it can do instead of pretending to be identical.
| Capability | Meaning |
|---|---|
flows | Which flows it supports |
authorization | single or reusable proofs |
variableAmount | Can settle less than the authorized maximum |
quotes | Carries a signed quote through its protocol |
refund · partialRefund | Can return settled money |
lookup | Can ask its provider what happened to a charge — required |
A rail without lookup is refused: without it, an unknown outcome could only be guessed.
When a provider is down
- While issuing a challenge (a Lightning node cannot create an invoice), that rail is left out of the
402. If no rail can offer, the answer is503 payment_unavailable. - While verifying, the request gets
503and the handler does not run. - While settling or refunding, the charge becomes
unknownand reconciliation asks the provider later.
Payer evidence
Some proofs must be kept to settle after a crash, such as a signed x402 payload. A rail keeps them in the authorization's data only until the charge is final, then redact drops them. Evidence never appears in logs, errors, events, or receipts.
Price and asset
A route is priced in a currency; a rail settles in an asset. The rail's offer states the asset, network, integer amount, and the basis of conversion — par for a USD stablecoin configured as USD, or rate for a merchant-supplied rate. Tollstile never converts currencies on its own.