Skip to content
Turnspike

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

Parties in the Turnspike system
PartyLives inRole
OwnerWalletFunds the account, sets the agent, caps, merchants. Can pause, revoke and withdraw at any time.
AgentKeyHolds a key that can only call pay. No authority over policy or funds.
Allowance contractOn-chainHolds owner balances, enforces limits, consumes request IDs, emits Paid. No admin, no upgrade.
MerchantAddressThe address that receives QUSDC for the API. The owner allowlists it.
GatewayOff-chainIssues signed challenges, verifies receipts, delivers once. Never holds funds, never signs transactions.
Gateway databaseOff-chainSQLite 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.

Agentkey only calls payAllowance contractlimits, single useMerchantreceives QUSDCQIE RPCreceipts and logsGatewayverify, deliver onceHTTP 200 with the resource (after verification)pay

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.

  1. Request

    The agent asks for a protected resource.

    GET /v1/block-summary

  2. Quote

    The seller answers with a signed, expiring challenge bound to one resource and price.

    402 Payment Required

  3. Pay

    The agent calls pay on the contract. The owner's rules are checked on chain.

    Paid(owner, agent, merchant, requestId, amount)

  4. Verify

    The seller reads the receipt from QIE and waits for confirmations.

    202 pending

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