Running on QIE Mainnet. Unaudited, small amounts only.
Agents pay at the gate. Owners set the toll.
Turnspike lets any API charge per request in QUSDC. The payer's spending limits are enforced by the settlement contract itself, and each paid response is stored before it is sent, so a crash or outage never loses a payment.
Live from the gateway, unpaid request
GET turnspike-qie.fly.dev/v1/block-summary
- Request ID
- …
- Pays
- …
- Chain
- QIE 1990
- Resource
- …
- Settles through
- 0xa2f2…5d9c
An agent pays this on chain, within its owner's limits, then presents the proof.
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
The owner posts the rules. The contract enforces them.
Each rule is checked inside the pay transaction itself. If one fails, the transaction reverts with a named error and no QUSDC moves. The owner can always withdraw: there is no admin key, upgrade path or rescue function.
| Rule | What happens | Refused with |
|---|---|---|
| Per-call capOne payment above the cap is refused. | One payment above the cap is refused. | CapExceeded |
| Daily capSpend is counted per UTC day inside the same transaction that debits. Up to 2x can pass across midnight UTC; this is documented. | Spend is counted per UTC day inside the same transaction that debits. Up to 2x can pass across midnight UTC; this is documented. | DailyCapExceeded |
| Merchant allowlistPaying an address the owner has not allowed is refused. | Paying an address the owner has not allowed is refused. | MerchantNotAllowed |
| RevokeClears the agent. Its next payment is refused. | Clears the agent. Its next payment is refused. | NotOwnerAgent |
| PauseBlocks payments for this account. Withdrawals keep working. | Blocks payments for this account. Withdrawals keep working. | Paused |
| Single useEach (merchant, requestId) pair can be paid once, forever. | Each (merchant, requestId) pair can be paid once, forever. | RequestAlreadyUsed |
| BalanceAn agent cannot spend more than the owner deposited. | An agent cannot spend more than the owner deposited. | InsufficientBalance |
Three parties. The contract is the only one that decides.
Nobody has to trust the agent. The owner's rules live in the settlement contract, so a compromised agent can still only spend what the owner already allowed.
Owner
Deposits QUSDC into their own account on the contract and posts the rules for one agent key: a per-call cap, a daily cap, which merchants may be paid.
Holds the money and the rules
Agent
Meets a 402 at an API, checks the quote against its own payee list and price ceiling, then calls pay on the contract. It can only spend inside the owner's rules.
Holds a key that can pay, nothing more
Seller
Mounts the middleware, names a price per route, verifies the Paid event on QIE, stores the response, then sends it. A retry returns the stored copy.
Holds the resource and the merchant address
For API providers
Put a price on a route.
Mount the middleware and name a price per path. Unpaid requests get a 402 quote; paid ones are checked against the chain, stored, then served. Invalid input is refused before any price is quoted.
import express from "express";
import { turnspike } from "@turnspike-qie/middleware";
const app = express();
const paid = turnspike({
rpcUrls: ["https://rpc1mainnet.qie.digital", "https://rpc2mainnet.qie.digital"],
chainId: 1990,
contract: "0xa2f2e042861a593cc582c6d2d43a24457dcf5d9c", // deployed TurnpikeAllowance
token: "0x3F43DA82eC9A4f5285F10FaF1F26EcA7319E5DA5", // QUSDC, 6 decimals
merchant: process.env.MERCHANT_ADDRESS!, // where payments go
hmacSecrets: [process.env.HMAC_SECRET!], // at least 32 bytes
dbPath: "/data/turnspike.sqlite", // persistent volume
prices: {
"/forecast/:city": {
priceBase: 2500, // 0.0025 QUSDC
validate: (req) => /^[a-z-]+$/.test(req.path.split("/")[2] ?? "") ? null : "unknown_city", // 400 before any price
},
},
});
app.use("/v1", paid);
app.get("/v1/forecast/:city", (req, res) => res.json({ city: req.params.city, tomorrow: "sunny" }));
// recover payments made while you were down, then clean up challenges that can no longer be paid
setInterval(() => paid.reconcile().then(() => paid.purge()), 15 * 60_000);
app.listen(8080);For agent builders
Pay only who you trust.
The client SDK pays a 402 only when the origin and merchant are on your list, the price is under your ceiling, and the owner's on-chain limits allow it. It checks gas first, journals every step, and never pays twice after a crash.
import { TurnspikeClient, FileJournal, QIE_MAINNET, parseUnits } from "@turnspike-qie/client";
const client = new TurnspikeClient({
signer, // the AGENT key (keystore, KMS, remote signer). Never the owner key.
owner: "0xOwner…", // whose on-chain allowance pays
network: QIE_MAINNET,
policy: {
payees: [{ origin: "https://api.example.com", merchant: "0xMerchant…" }], // nobody else is ever paid
maxPriceBase: parseUnits("0.005"), // hard ceiling per request
},
approve: (q) => q.gasCostWei < 10n ** 15n, // your rule, before every payment
journal: new FileJournal(".turnspike/journal.json"), // restart-safe
});
const r = await client.fetch("https://api.example.com/v1/forecast/lagos", {}, { idempotencyKey: "lagos-today" });
if (r.ok && r.kind === "paid") console.log(await r.response.json(), r.payment.explorerUrl);
else if (!r.ok && r.paid) await client.resume("lagos-today"); // paid, not delivered yet: resume does not pay it againSettled on QIE Mainnet, in QUSDC.
One QUSDC is 1,000,000 base units, so a 0.001 QUSDC call is 1,000. Gas is paid in QIE: one payment measured 92,159 gas, about 0.0001 QIE.
- Network
- QIE Mainnet, chain 1990
What it does not promise.
No proof of delivery on chain.
The contract cannot see whether the API answered. A payment that lands before a failed delivery is not refunded; the SDK and the gateway recover it instead.
Not audited.
The contract has a 5 QUSDC deposit cap, the QUSDC issuer has mint and burn roles, and the gateway is run by the project.
Finality is measured, not proven.
Blocks arrive about every 3.6 s and the gateway waits for 2 confirmations. No reorg was seen in the blocks observed; that is not a guarantee.
Watch the barrier lift on mainnet.
Run the scripted agent against the live gateway, or fund an allowance of your own.