Skip to content
Turnspike

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

402
Asking the gate for a quote…
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.

  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

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.

Spending rules enforced by the settlement contract, and the error each one returns
RuleRefused with
Per-call capOne 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.DailyCapExceeded
Merchant allowlistPaying an address the owner has not allowed is refused.MerchantNotAllowed
RevokeClears the agent. Its next payment is refused.NotOwnerAgent
PauseBlocks payments for this account. Withdrawals keep working.Paused
Single useEach (merchant, requestId) pair can be paid once, forever.RequestAlreadyUsed
BalanceAn 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.

server.ts
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);
Provider guide

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.

agent.ts
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 again
Agent builder guide

Settled 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
Settlement contract
0xa2f2e042861a593cc582c6d2d43a24457dcf5d9c
QUSDC token
0x3F43DA82eC9A4f5285F10FaF1F26EcA7319E5DA5

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.

Read the security notes

Watch the barrier lift on mainnet.

Run the scripted agent against the live gateway, or fund an allowance of your own.