Payment Rails¶

Routeweiler supports four payment rails. A rail is a complete payment protocol: challenge wire format, signing method, funding source, and settlement proof.

When a server returns 402 Payment Required, Routeweiler inspects the response headers to detect which rail it speaks, then routes to the best available option.

x402¶

EVM signed transfer on Base, Polygon, Arbitrum, World, or Solana.

x402 is an open standard for HTTP micropayments backed by ERC-3009 (transferWithAuthorization). The buyer signs a transfer authorization locally and sends it as a PAYMENT-SIGNATURE header. The server forwards it to a facilitator (e.g. x402.org) for on-chain settlement.

Property	Value
Wire header	`PAYMENT-REQUIRED` (base64-encoded JSON `accepts` array)
Signing	ERC-3009 `transferWithAuthorization` (EVM)
Settlement proof	On-chain transaction hash (`txid`)
Funding class	`EvmFundingSource`
Factory	`Funding.base_usdc(wallet=...)`, `Funding.base_sepolia_usdc(wallet=...)`

When to use: Any API that speaks x402. Currently the most common rail for agent-to-API payments, especially Base USDC.

Recipe: x402 — Base USDC

L402¶

BOLT-11 Lightning invoice, macaroon-gated.

L402 combines a BOLT-11 Lightning invoice with a macaroon credential. The buyer pays the invoice; once settled, the preimage unlocks the macaroon, which is sent as Authorization: L402 <macaroon>:<preimage> on the retry.

Property	Value
Wire header	`WWW-Authenticate: L402 macaroon="...", invoice="..."`
Signing	Lightning invoice payment (LND gRPC)
Settlement proof	Payment preimage
Funding class	`LightningFundingSource`
Factory	`Funding.lightning_lnd(client=..., network=..., node_pubkey=...)` or `await LightningFundingSource.create(client, network)`

When to use: APIs on the Lightning Network, or when you want sub-cent sats payments with instant settlement.

Recipe: L402 — Lightning

MPP-Tempo¶

Tempo 0x76 signed transaction (stablecoin on the Tempo L2).

MPP (Machine Payment Protocol) is an open standard for agent payments using WWW-Authenticate: Payment method=tempo. The buyer signs a 0x76 transaction type on the Tempo EVM L2 and sends it in an Authorization: Payment credential. The server submits it to the Tempo RPC and returns a receipt with the tx hash.

Property	Value
Wire header	`WWW-Authenticate: Payment method="tempo", intent="charge", ...`
Signing	Tempo 0x76 transaction (EIP-2718 type 0x76, EVM signing)
Settlement proof	On-chain transaction hash (`txid`)
Funding class	`TempoFundingSource`
Factory	`Funding.tempo_pathusd_moderato(wallet=...)` (testnet), `Funding.tempo_usdc(wallet=...)` (mainnet)

When to use: APIs on the Tempo L2 ecosystem; stablecoin payments without the gas overhead of Ethereum mainnet.

Recipe: MPP-Tempo

MPP-SPT¶

Stripe Shared Payment Token — fiat card payments via Stripe.

MPP-SPT uses WWW-Authenticate: Payment method=stripe. The buyer mints a Stripe Shared Payment Token (SPT) scoped to the seller's Stripe account; the server redeems it via a Stripe PaymentIntent. No crypto keys required on the buyer side — just a Stripe customer with a saved payment method.

Property	Value
Wire header	`WWW-Authenticate: Payment method="stripe", intent="charge", ...`
Signing	Stripe API call (SPT minting)
Settlement proof	SPT id (`spt_...`)
Funding class	`StripeFundingSource`
Factory	`Funding.stripe(api_key=..., customer=..., payment_method=...)`

When to use: APIs accepting Stripe payments; non-crypto buyers; teams that already run on Stripe and want to gate APIs without issuing crypto.

Recipe: MPP-SPT — Stripe

Rail selection¶

When a 402 response advertises multiple rails, Routeweiler picks the best one:

Sticky routing — if this (agent_id, session_id, host) tuple has a known-good rail from a previous call, reuse it.
Cost — FMV-converted amount in the reference currency; lower wins.
Policy prefer — rails named in a matching PolicyRule.prefer list rank higher.
Default rail — Policy.default_rail (default: "x402").
Registration order — adapter registration order is the final tiebreaker.

See Policy to control which rails are allowed and how they are ranked.