Product
One contract holds the rules. One gateway handles delivery.
Turnspike separates what must be trusted to the chain (limits, settlement, single use) from what a seller needs off-chain (challenges, verification, durable delivery).
The system
Who does what
| Party | Lives in | Role |
|---|---|---|
| Owner | Wallet | Funds the account, sets the agent, caps, merchants. Can pause, revoke and withdraw at any time. |
| Agent | Key | Holds a key that can only call pay. No authority over policy or funds. |
| Allowance contract | On-chain | Holds owner balances, enforces limits, consumes request IDs, emits Paid. No admin, no upgrade. |
| Merchant | Address | The address that receives QUSDC for the API. The owner allowlists it. |
| Gateway | Off-chain | Issues signed challenges, verifies receipts, delivers once. Never holds funds, never signs transactions. |
| Gateway database | Off-chain | SQLite on a persistent volume. Every payment state transition is recorded and survives restarts. |
Settlement path
Where the money and the proof travel
Funds move once, on-chain, from the owner's allowance to the merchant. The gateway only reads the result.
One lane, five stops, from request to resource.
Every stop is a real HTTP status or a real contract event. Refusals happen at the pay stop and cost the agent nothing but gas.
Request
The agent asks for a protected resource.
GET /v1/block-summary
Quote
The seller answers with a signed, expiring challenge bound to one resource and price.
402 Payment Required
Pay
The agent calls pay on the contract. The owner's rules are checked on chain.
Paid(owner, agent, merchant, requestId, amount)
Verify
The seller reads the receipt from QIE and waits for confirmations.
202 pending
Pass
The response is stored, then sent. The same proof returns the stored copy.
200 OK
Delivery guarantees
Paid once, delivered once.
- Idempotent replay
- Presenting the same proof again returns the stored response for the same resource. A different resource is refused with 403.
- Crash recovery
- If the gateway dies after verifying payment but before responding, the row stays PAID_CONFIRMED. The same proof delivers after restart, with no second charge.
- Pending, not promised
- If the receipt is missing or under-confirmed, the gateway answers 202 pending. Turnspike makes no latency promise.
- Known limit
- There is no refund if payment lands and delivery never succeeds. Such payments are listed as paid but undelivered.
Watch the barrier lift on mainnet.
Run the scripted agent against the live gateway, or fund an allowance of your own.