v1

Tip: the API, web and docs hosts all run the same commit. This page states what is live, what is not, and how to use what is live.

The five calls

Everything else is a variation on these. All five are free (no payment address, no credits):

The web pages, MCP tools and the CLI all read these five; none of them computes its own version. Reading is free — only asking (POST /v1/decisions) is paid, and the price is shown before the ask.

Every decision can be exhibited. GET /v1/lineage/<decision_id> (free, no model call) returns one bundle: the full recorded decision, its resolution (or a dated pending), the payment method and draw ids, the tape sources with their request hashes and fetch times, the recorded hashes, and a recomputed verify block — input_ok / state_ok are true, false, or unknown, and unknown is the honest absence on a pre-trace row, never a stand-in for true. The same object is read by tollbridge_lineage over MCP and tb lineage <id> in the CLI; the HTTP route, the tool, and the CLI all serve the one builder.

The loop is readable for free. GET /v1/feed?limit=50 returns the newest terminal chips — decision id, question, asset, the predicted and realized labels, whether they matched, and the horizon — with no wallet and no model internals. POST /v1/decisions answers 402 with the payment terms and the next moves in the body (next.poll, next.feed, next.blotter, next.next), so an agent that reads only the challenge knows where to stay until the horizon. POST /v1/decisions/next { previous_decision_id } asks the next dated sentence on the same question at the same price, refused while the previous clock is still open. The same reads are tollbridge_feed, tollbridge_decision and tollbridge_get_resolution over MCP.

The loop

event → horizon → refuse → pay → persist → resolve → series → model hash

• Event — each question is a measurable event with a stated window.
• Horizon — the window closes at horizon_end; until then the decision is an open clock.
• Refuse — stale input, an insufficient sample, or a surface the venue does not expose returns a typed refusal, never a made-up number. A refused ask is refunded.
• Pay — a paid ask uses prepaid credits (the working rail) or x402 per call where a facilitator is configured.
• Persist — every decision is written to the append-only ledger and can be read back by id.
• Resolve — at the horizon the outcome is measured and written; the grammar is realized | obtains | not | unresolvable.
• Series — the previous results for a question and asset are readable.
• Model hash — new emits carry the calculator version and the request hash.

What is live

Questions (8):

Assets: the Deck's rail pins BTC, ETH and SOL. Above it, the market list is the live Hyperliquid universe — the top perps by 24h notional volume (GET /v1/universe), computed from the venue tape and refreshed on a timer, never a curated list. Any symbol on that list is askable; an unknown or delisted symbol is refused.

Humans (web):

• Deck — the three-asset rail. S01 for BTC, ETH and SOL on first paint; S05 and S06 alongside. Above it, the live market list with a search, a sort, and a ⌘K jump; a row opens that one asset's question sheet — all eleven questions in one place, the available ones askable and the dark ones stating their real blocker.
• Open clocks — the strip of decisions still running, soonest deadline first. Pending only.
• Results — the last settled decision for every question and coin, taken from the same object the rest of the site reads (latest_terminal on the blotter) — one chip each, no separate history — with the calibration table beneath it. In-flight decisions are not repeated here; they belong to the In-progress strip.
• Ask 60m / Ask next 60m — the paid action. The price is shown before you ask, and a declined question is refunded.
• Payment — enter a Base address, get the one-time free credits, then ask.
• Logo returns to the dashboard.

Agents (MCP): the same objects as the web. Start with the sheet: tollbridge_sheet returns the one object — all eleven questions for one asset, each with its derived state, ask gate and exact blocker. Watching more than one symbol, use tollbridge_blotter: the same rows cut across a comma-separated asset list (default BTC,ETH,SOL) — every open clock soonest first, the last dead chip per question on each asset, and each dark question once with its blocker (an unknown symbol is skipped with a warning, never a failed read). The loop reads are free: the sheet, the blotter, the latest decision, its resolution, the open clocks, the price list. Asking is one paid tool call (tollbridge_decision) with a credit payer.

The question sheet is the object: GET /v1/sheet?asset= returns, for one asset, all eleven questions in fixed catalog order, each with a DERIVED state — live (askable), pending (a clock is open, with its decision id and horizon), empty (no decision on record yet — data, not an error) or dark (no live data source, carrying the exact blocker, never "coming soon"). Every surface — the web pages, MCP, the SDK — renders this one object; none of them computes rows itself. An unknown or delisted asset is a typed UNKNOWN_ASSET refusal.

The blotter is that object across assets: GET /v1/blotter?assets= returns the same rows for a comma-separated asset list in one call — pending (every open clock, soonest first), latest_terminal (the last dead chip per question on each asset) and dark (each blocked question once, with its blocker). It is derived from the sheet builder, so its pending set can never disagree with the sheet or the open-clocks read. A symbol with no live market is skipped with a typed warning — never a failed read of the whole blotter.

Open clocks as one call: GET /v1/clocks/open returns the same pending set the web strip computes — the AVAILABLE asset questions × BTC/ETH/SOL, derived from the resolver registry and the emit gates, never a hand list. Pending only, soonest horizon_end first. An empty list is data (nothing is in flight), not an error. A degraded read is a typed error, never an empty list or an invented row.

curl "https://api.tollbridge.app/v1/sheet?asset=BTC"
curl "https://api.tollbridge.app/v1/blotter?assets=BTC,ETH,SOL,HYPE"
curl https://api.tollbridge.app/v1/clocks/open

What is deferred

To light S02 / S03 / S04 (operator action)

1. Run a Hyperliquid node with --write-trades and mount its data dir at NODE_TRADES_DIR (the adapter reads node_trades/hourly/{YYYYMMDD}/{HH}).
2. Set LIQUIDATION_SOURCE=node_trades and start the worker with TOLLBRIDGE_WORKER_LIQUIDATION=1; it folds hourly sided notional into liquidation_hours.
3. Wait for N = 24 hourly rows on the asset (GET /v1/liq/hours?asset=BTC reports the count) — the emit gate refuses until then.
4. Nothing else is needed: the resolver and the emit path already read the same store, so the three questions turn available on their own.

A request for a deferred question returns a typed refusal (out_of_scope) and refunds the credits. Deferred questions are absent from the default pages.

How to ask

A person: open the dashboard, enter a Base address, get the free credits, then press Ask. The price appears before anything is charged.

An agent: read the sheet (GET /v1/sheet?asset=) — it tells you what exists, what is askable and what is in flight. Watching several symbols, read the blotter (GET /v1/blotter?assets=) for all of them at once. If any row is pending, sleep until the soonest horizon_end and re-read; never ask while a horizon is open. Then read the latest decision and its resolution, and ask ONLY a row whose ask.allowed is true, with a credit payer. The same object is served over HTTP and MCP.

How to refill

The working rail on this deployment is prepaid credits:

1. Free, once: POST /v1/billing/scout with your Base address grants 200 credits, one time per address.
2. Operator grant: POST /v1/billing/grants with the operator x-tollbridge-ops header. With no operator token wired the route returns OPS_UNSET — it is never a public grant. A specific leaked debit can be reversed with { "action": "reverse", … }, idempotently.
3. Credit journal: GET /v1/billing/draws?payer= lists every draw, credit and reversal, newest first; a reversed debit carries reversed_at.

What will not ship until a dependency exists

• x402 per-call settlement. PROVEN on Base mainnet. A paid ask settles end-to-end: POST /v1/decisions answers 402, the client signs the EIP-3009 authorization, the facilitator verifies and settles it, and the decision is served with a PAYMENT-RESPONSE receipt. The default facilitator (https://facilitator.payai.network) is mainnet-capable and needs no credentials — the x402 foundation's public testnet facilitator does not register eip155:8453 and will reject a mainnet settle. Override with TOLLBRIDGE_FACILITATOR_URL. Verified: a USDC transfer at the ask price landed on the recipient address on Base with the decision served in the same request.
• Wallet intelligence. No indexer exists. Wallet lookups return a typed failure and refund the credits; no profile is shown until a real indexer is wired.
• Subscription billing. The price book is live; recurring recharge, automatic refill and pack purchase are not.
• Notifications and webhooks. Live. Arm a hook with POST /v1/hooks { decision_id, url } (paid at the decision price) and we POST the resolution the instant the chip writes, signed X-Tollbridge-Signature (HMAC-SHA256), with one retry. The URL is checked against loopback, link-local and private addresses at registration and again before every delivery; an already-terminal clock returns 409 and points you at GET /v1/resolutions/<decision_id>.
• Calibration publications. Unpublished while the sample is below the floor of 30 per question. Unpublished is a stated state, not an error, and no placeholder chart is drawn.

Honesty

• No performance claims. A threshold's existence says what is asked, not how often it happens.
• Every probability carries its question, window, conditions, confidence and data age.
• A refusal is shown with its reason; a made-up number is never substituted.
• An empty result is data. A failed check says so and is never rendered as "nothing in flight".
• Merchant payments go to the configured address; the API serves the exact challenge it will accept.

The product is the open clock and the chip that follows. Everything else waits.