# Tollbridge

> Paid intelligence for AI agents. One sentence per call, priced at $1.00 USDC on Base. Pay, then poll until the horizon.

## This origin is canonical

Every URL below is a path on THIS origin (https://api.tollbridge.app) — the live deployment
that served this file. The public identity is tollbridge.app (product),
api.tollbridge.app (this API), workspace.tollbridge.app (workspace) and
docs.tollbridge.dev (docs). Use this origin for the whole loop, the
MCP server, discovery and the docs pointer; do not synthesize another host.

## The loop (read this first)

1. PAY — POST https://api.tollbridge.app/v1/decisions  → 402.  Read the 402 body: it carries
   `payment` {scheme, network, asset, amount, payTo} and `next` {poll, blotter,
   feed, next}. Sign the EIP-3009 authorization and retry with the base64
   `PAYMENT-SIGNATURE` header (or send `x-tollbridge-payer: 0x<base-address>`
   to settle from prepaid credits instead).
2. RECEIVE — 200 with the DecisionRecord: decision_id, probability (or the
   choice distribution), confidence, and `horizon_end` — the instant the world
   answers. The body also carries `next.poll`.
3. POLL — GET https://api.tollbridge.app/v1/resolutions/<decision_id> until status is no longer
   "pending". Terminal outcomes: realized/obtains/not (probability) or
   realized with predicted/realized/match (choice), or unresolvable.
4. LURK (free) — GET https://api.tollbridge.app/v1/feed?limit=50 reads the newest TERMINAL chips:
   decision_id, question_id, asset, output, predicted, realized, match,
   observed, status, resolved_at, horizon_end. The schema depends on the
   question output: a CHOICE chip carries predicted + realized + match (the
   label that obtained, and whether it was the prediction); a PROBABILITY
   chip carries predicted (the frozen p, the number sold at emit) + observed
   (true = the event obtained) and its realized/match are null — a
   probabilistic claim has no binary match, so the fields are honestly
   absent rather than invented. No wallet, no model guts. Free forever.
5. RELAPSE — POST https://api.tollbridge.app/v1/decisions/next { previous_decision_id } to ask the
   NEXT dated sentence on the same question+asset. Same price. Refused while
   the previous clock is still open (clock_open) — wait for horizon_end.
6. HOOK (paid, same price) — POST https://api.tollbridge.app/v1/hooks { decision_id, url } and the
   worker POSTs the ResolutionRecord the instant the chip writes, signed
   `X-Tollbridge-Signature` (HMAC-SHA256), one retry. No polling needed.

## Beat the house (free)

POST https://api.tollbridge.app/v1/calls { decision_id, call } with `x-tollbridge-payer: 0x<address>`
locks YOUR call on an open clock — "obtains" or "not" on a probability
question, the question's own label (e.g. trending_up) on a choice question.
It is FREE: the only money in the system is the ask that opened the clock. A
call is a one-way door — immutable once locked (a second call is 409, a call
after horizon_end is 409 and the database itself refuses it), and it NEVER
moves the house number. When the clock resolves, the same evaluator that
graded the house grades your call; GET /v1/calls/scoreboard?payer= shows
your record against the house on identical events (your Brier, the house's,
per question). Personal only — a scoreboard read without a payer is a 404,
and no public leaderboard exists. Unresolvable outcomes grade nothing: a
call stays ungraded, never scored as a loss.

## Tools (MCP: POST https://api.tollbridge.app/mcp)

tollbridge_decision   ask (paid)   tollbridge_get_resolution   poll (free)
tollbridge_feed       lurk (free)  tollbridge_open_clocks      pending (free)
tollbridge_sheet      island (free) tollbridge_blotter          many-assets (free)
tollbridge_get_decision / tollbridge_lineage / tollbridge_calibration (free)
tollbridge_get_intelligence / tollbridge_list_releases (free — the measured record)

## The price ladder (evidence-gated)

Prices are rung-multiplied: the USD price of credits rises ×1.25 per rung, and a rung turns
only when its evidence milestone AND its intelligence gates are met (a published calibration
band, a proven-improvement release, …) with 24 hours’ public notice before it takes effect.
The live ladder — current rung, multiplier, both gate columns and the countdown — is published
free at GET https://api.tollbridge.app/v1/intelligence (and rides GET https://api.tollbridge.app/v1/pricing).

## Price and rail

$1.00 USDC per decision on Base (eip155:8453), scheme `exact`, payTo `0x934a5fC8b661c048da6112Ef800a7f4c73A258aa`.
Discovery: https://api.tollbridge.app/.well-known/x402 · MCP: https://api.tollbridge.app/.well-known/x402/mcp.json.
Prepaid credits: https://api.tollbridge.app/v1/billing/scout (one-time free; POST grants, GET reports status) then the `x-tollbridge-payer` header.

## Canonical hosts (Public Genesis)

tollbridge.app (product) · api.tollbridge.app (this API) ·
workspace.tollbridge.app (workspace) · docs.tollbridge.dev (docs).
Use THIS origin. Every link above is a path on the live deployment.

## Endpoints

- [GET /healthz: Liveness + provider health rollup](https://api.tollbridge.app/healthz) — free
- [GET /health: Alias of /healthz (operator convention)](https://api.tollbridge.app/health) — free
- [GET /readyz: Readiness: degraded when any provider is degraded, 503 when down](https://api.tollbridge.app/readyz) — free
- [GET /v1/pricing: Per-endpoint price list (PRICING-derived)](https://api.tollbridge.app/v1/pricing) — free
- [GET /v1/providers: Provider inventory + health](https://api.tollbridge.app/v1/providers) — free
- [GET /openapi.json: OpenAPI 3.1 specification](https://api.tollbridge.app/openapi.json) — free
- [GET /v1/openapi.json: OpenAPI 3.1 specification (alias of /openapi.json)](https://api.tollbridge.app/v1/openapi.json) — free
- [GET /.well-known/x402.json: x402 payment discovery](https://api.tollbridge.app/.well-known/x402.json) — free
- [GET /.well-known/x402: x402 payment discovery (alias of /.well-known/x402.json)](https://api.tollbridge.app/.well-known/x402) — free
- [GET /.well-known/mcp.json: MCP server + tool discovery](https://api.tollbridge.app/.well-known/mcp.json) — free
- [GET /.well-known/x402/mcp.json: MCP server + tool discovery (the x402-convention path; same document as /.well-known/mcp.json)](https://api.tollbridge.app/.well-known/x402/mcp.json) — free
- [GET /.well-known/ai.txt: Agent discovery pointer (llms.txt, llms-full.txt, x402, MCP, openapi)](https://api.tollbridge.app/.well-known/ai.txt) — free
- [GET /robots.txt: Crawler policy: Allow /, Disallow /v1/admin/](https://api.tollbridge.app/robots.txt) — free
- [GET /.well-known/agent.json: Agent identity card](https://api.tollbridge.app/.well-known/agent.json) — free
- [GET /llms.txt: llmstxt.org v2 specification (first 40 lines: the pay→poll→feed→next loop, tool names, the decision price on Base, canonical-host footnote)](https://api.tollbridge.app/llms.txt) — free
- [GET /llms-full.txt: The complete agent recipe + endpoint reference (same document as /llms.txt)](https://api.tollbridge.app/llms-full.txt) — free
- [GET /docs: Human documentation (302 to TOLLBRIDGE_DOCS_URL, default /openapi.json)](https://api.tollbridge.app/docs) — free
- [GET /v1/market/{asset}: Fresh quote + derived state (free market snapshot)](https://api.tollbridge.app/v1/market/{asset}) — free
- [GET /v1/market/{asset}/regime: S01 market-regime decision (jevChoice distribution)](https://api.tollbridge.app/v1/market/{asset}/regime) — $1.000 USDC via x402
- [GET /v1/market/{asset}/risk: S02 liquidation-risk decision (DEFERRED — typed refusal, refund-on-ask)](https://api.tollbridge.app/v1/market/{asset}/risk) — $1.000 USDC via x402 — DEFERRED (typed refusal, refund-on-ask; not a live evaluate)
- [GET /v1/liquidation/{asset}: Raw liquidation surfaces + honest unavailability](https://api.tollbridge.app/v1/liquidation/{asset}) — $0.002 USDC via x402
- [GET /v1/funding: Raw funding snapshot for every canonical asset](https://api.tollbridge.app/v1/funding) — $0.002 USDC via x402
- [GET /v1/funding/{asset}: S06 funding decision (live), basis, execution-risk context](https://api.tollbridge.app/v1/funding/{asset}) — $1.000 USDC via x402
- [GET /v1/funding/opportunities: S06 funding-anomaly scan with explicit assumptions (no profit claims)](https://api.tollbridge.app/v1/funding/opportunities) — $1.000 USDC via x402
- [GET /v1/wallet/{chain}/{address}: Wallet profile (state machine + sample adequacy) — surface wired, indexer unwired (typed 503); the S09/S10 decision is deferred](https://api.tollbridge.app/v1/wallet/{chain}/{address}) — $0.005 USDC via x402
- [GET /v1/wallet/{chain}/{address}/state: Wallet state machine position + evidence summary (S09/S10 decision surfaces — DEFERRED: no resolver)](https://api.tollbridge.app/v1/wallet/{chain}/{address}/state) — $0.005 USDC via x402 — DEFERRED (typed refusal, refund-on-ask; not a live evaluate)
- [GET /v1/wallet/{chain}/{address}/positions: Wallet balances surface](https://api.tollbridge.app/v1/wallet/{chain}/{address}/positions) — $0.005 USDC via x402
- [GET /v1/wallet/{chain}/{address}/events: Paginated wallet transfer events (wired rail, indexer unwired — typed 503, not a live tape)](https://api.tollbridge.app/v1/wallet/{chain}/{address}/events) — $0.005 USDC via x402
- [POST /v1/risk/transaction: S11 candidate-transaction risk (DEFERRED — typed refusal, refund-on-ask)](https://api.tollbridge.app/v1/risk/transaction) — $1.000 USDC via x402 — DEFERRED (typed refusal, refund-on-ask; not a live evaluate)
- [POST /v1/risk/token: S11 token-subject risk (DEFERRED — typed refusal, refund-on-ask)](https://api.tollbridge.app/v1/risk/token) — $1.000 USDC via x402 — DEFERRED (typed refusal, refund-on-ask; not a live evaluate)
- [POST /v1/risk/wallet: S11 wallet-subject risk (DEFERRED — typed refusal, refund-on-ask)](https://api.tollbridge.app/v1/risk/wallet) — $1.000 USDC via x402 — DEFERRED (typed refusal, refund-on-ask; not a live evaluate)
- [POST /v1/risk/protocol: S11 protocol-subject risk (shared S11 pipeline, subject labeling)](https://api.tollbridge.app/v1/risk/protocol) — $1.000 USDC via x402
- [POST /v1/decisions: Deep decision: run any catalog signal through the engine (PAID, Idempotency-Key aware). The 200 carries next.poll (the resolution path) + feed/blotter/next links.](https://api.tollbridge.app/v1/decisions) — $1.000 USDC via x402
- [POST /v1/decisions/next: THE RELAPSE PATH: ask the NEXT dated sentence on the same question+asset as a previous decision (PAID at the decision price). Refused with clock_open while the previous clock is pending.](https://api.tollbridge.app/v1/decisions/next) — $1.000 USDC via x402
- [POST /v1/hooks: Arm a resolution hook: the worker POSTs the ResolutionRecord to your url the instant the watched decision writes, signed X-Tollbridge-Signature (HMAC-SHA256, one retry). PAID at the decision price; the url is SSRF-checked (loopback/RFC1918/link-local/metadata refused); an already-terminal clock is a 409 telling you to read /v1/resolutions/:id.](https://api.tollbridge.app/v1/hooks) — $1.000 USDC via x402
- [GET /v1/decisions/latest: Latest decision for a question on an asset (free ledger lookup — the Deck reads the ledger, not session state)](https://api.tollbridge.app/v1/decisions/latest) — free
- [GET /v1/decisions: The SERIES: newest-first decisions for a question on an asset with resolutions joined (free, limit ≤ 20, refusals included)](https://api.tollbridge.app/v1/decisions) — free
- [GET /v1/decisions/{decision_id}: Fetch a recorded decision (free read)](https://api.tollbridge.app/v1/decisions/{decision_id}) — free
- [POST /v1/decisions/{decision_id}/replay: Deterministic policy-only replay of a recorded decision (free)](https://api.tollbridge.app/v1/decisions/{decision_id}/replay) — free
- [GET /v1/resolutions/{decision_id}: Resolution outcome of a settled decision (realized | obtains | not | unresolvable grammar — CHOICE claims resolve realized with the predicted/realized/match sentence; typed pending)](https://api.tollbridge.app/v1/resolutions/{decision_id}) — free
- [GET /v1/calibration: Reliability buckets per question (publication-gated; n too small shown honestly)](https://api.tollbridge.app/v1/calibration) — free
- [GET /v1/intelligence: The intelligence curve: the latest Decision-Intelligence Index snapshot (chain-verified; insufficient sample stated verbatim)](https://api.tollbridge.app/v1/intelligence) — free
- [GET /v1/intelligence/curve: The learning curve: the anchored evidence points and the published power-law fit (learning velocity with its CI)](https://api.tollbridge.app/v1/intelligence/curve) — free
- [GET /v1/intelligence/releases: The intelligence release feed: sealed releases and rejected candidates, with their measured deltas and gate verdicts](https://api.tollbridge.app/v1/intelligence/releases) — free
- [GET /v1/intelligence/releases/:version: One intelligence release as its full proof bundle: the sealed body, the evaluation, the gate verdicts, the dataset provenance](https://api.tollbridge.app/v1/intelligence/releases/:version) — free
- [GET /v1/clocks/open: Open clocks: the pending decisions across the live questions and canonical assets, soonest horizon first (free; [] when nothing is in flight — never an invented row)](https://api.tollbridge.app/v1/clocks/open) — free
- [GET /v1/feed: THE FEED: the newest TERMINAL chips (resolved decisions) newest-first — decision_id, question_id, asset, output, predicted, realized, match, observed, status, resolved_at, horizon_end. CHOICE chips carry predicted+realized+match (labels); PROBABILITY chips carry predicted (the frozen p) + observed (the event) with realized/match null — a probabilistic claim has no binary match. Free to lurk; no wallets, no model guts, no pending rows. limit defaults to 50 (max 200).](https://api.tollbridge.app/v1/feed) — free
- [POST /v1/calls: BEAT THE HOUSE: lock your OWN call on an OPEN clock before its horizon — obtains | not on a probability question, the question's own label on a choice question. FREE: credits are spent only on the ask that opened the clock; a call is never billed and never moves the house number. Send x-tollbridge-payer. Immutable after the horizon (409 CLOCK_CLOSED; the DB refuses a late insert), one call per payer per clock (409 CALL_LOCKED), unknown or refused decision 404. At resolve the SAME evaluator that graded the house grades your call; an unresolvable tape grades nothing.](https://api.tollbridge.app/v1/calls) — free
- [GET /v1/calls: Your calls + your scoreboard, strictly personal: rows are served only for the ?payer= you name, and no listing across payers exists. Calls, grades (score, house_outcome, realized_label), and the board — n, graded, open, player/house accuracy and Brier. Free; n=0 reports nulls, never zeros.](https://api.tollbridge.app/v1/calls) — free
- [GET /v1/calls/scoreboard: The personal scoreboard against the house on identical clocks: n, graded, open, player/house accuracy, both Briers, per question. Personal only — omitting ?payer= is a 404 (no public leaderboard ships; the opt-in flag records consent for a future one).](https://api.tollbridge.app/v1/calls/scoreboard) — free
- [POST /v1/calls/opt-in: Record your consent (default false) for a future public view of your scoreboard. No public board is served this wave even with opt-in — personal boards only.](https://api.tollbridge.app/v1/calls/opt-in) — free
- [POST /v1/standings: Register a scheduled run (every-window auto-ask) for one question × subject. FREE registration; the runs bill at the question tier via the worker. Requires spend_cap_credits >= 10 windows and acknowledge_spend_cap: true; one active run per identity triple (409 on a duplicate); an untiered question can never be scheduled (typed refusal).](https://api.tollbridge.app/v1/standings) — free
- [GET /v1/standings: Your scheduled runs (personal only, x-tollbridge-payer required). An empty list is data. DELETE /v1/standings/{id} stops one run (soft pause — the row and history survive; a foreign id is the same 404 as an unknown one).](https://api.tollbridge.app/v1/standings) — free
- [GET /v1/scoreboard: The PUBLIC opt-in leaderboard over graded player calls (?window=all|30d|7d). No pay-to-rank: billing never joins the ranking. >= 10 graded calls to rank, abbreviated handles. Zero qualified players is an honest empty board, not an error.](https://api.tollbridge.app/v1/scoreboard) — free
- [GET /v1/admin/economy-funnel: OPERATOR ONLY (x-admin-key): the real economy funnel projected from the journals the product already keeps — question opened, free question consumed, decision run, player call locked, decision resolved, call graded, XP, quest, badge, settled purchase and second paid run — plus the Phase 27 activation report (a payer activates on their FIRST GRADED call) and the snapshot trend. Unmeasurable steps are null with a named reason, never 0.](https://api.tollbridge.app/v1/admin/economy-funnel) — free
- [POST /v1/hook-endpoints: Register a PAYER-LEVEL outcome endpoint (paid from credits: billing.addon.hook, 30-day window). Every resolution that matches your payer fires to it, signed X-Tollbridge-Signature (HMAC-SHA256). The per-endpoint secret is returned once; cap 10 active endpoints; replay within the window is free.](https://api.tollbridge.app/v1/hook-endpoints) — free
- [GET /v1/hook-endpoints: Your outcome endpoints with delivery counts derived ONLY from the append-only hook_deliveries rows (registered / delivered / failing). Free; x-tollbridge-payer required. DELETE /v1/hook-endpoints/{endpoint_id} pauses one (soft stop; delivery history survives; a foreign id is the same 404 as an unknown one).](https://api.tollbridge.app/v1/hook-endpoints) — free
- [POST /v1/exports: Export YOUR decision history (CSV or JSONL, priced from credits: billing.export.asset_period, idempotent per payer/scope/subject/month, wallet redacted, 50k-row cap; a failure refunds). Returns the serialized file with an honest row-count header.](https://api.tollbridge.app/v1/exports) — free
- [GET /v1/push/config: Is Web Push configured on this deployment? Returns { configured, vapid_public_key } — configured:false with a null key is the honest dark state (subscribe nothing, promise nothing).](https://api.tollbridge.app/v1/push/config) — free
- [POST /v1/push/endpoints: Register one browser push subscription for a payer (x-tollbridge-payer required). The endpoint URL is SSRF-checked and must be https; re-registering the same endpoint refreshes its keys and re-enables it (idempotent).](https://api.tollbridge.app/v1/push/endpoints) — free
- [GET /v1/push/endpoints: Your push devices (host, timestamps, active flag — never a key). Free; x-tollbridge-payer required. DELETE /v1/push/endpoints/{endpoint_id} soft-stops one device (the row survives with disabled_at; a re-subscribe re-enables it — a device is never silently deleted).](https://api.tollbridge.app/v1/push/endpoints) — free
- [POST /v1/follows: Follow one (question × subject): on resolution the worker delivers the resolution sentence on every channel you enabled (channels bitmask 1=push 2=email 4=telegram; delivery requires the deployment to have that channel configured — an unconfigured channel fails visibly, never silently). Re-following is idempotent and updates the bitmask. Engagement state only: no probability, prompt or threshold rides these rows.](https://api.tollbridge.app/v1/follows) — free
- [GET /v1/follows: Your follows (question × subject × channel bitmask). Free; x-tollbridge-payer required. Unfollow is the identity-key DELETE (?question_id=&subject_kind=&subject=) — idempotent; removing nothing is data, not an error.](https://api.tollbridge.app/v1/follows) — free
- [GET /v1/alerts: Your active alert watches (kind, subject, your threshold). Free; x-tollbridge-payer required. DELETE /v1/alerts/{alert_id} stops one (soft unsubscribe — the row that documented the watch survives; a foreign id is the same 404 as an unknown one).](https://api.tollbridge.app/v1/alerts) — free
- [POST /v1/alerts: Watch a subject on the alert engine: kind (one of the seven engine kinds), asset or address, and for probability kinds your own threshold — delivery rides the SAME dedupe + cooldown law as operator alerts, out to your push devices. A threshold gates NOTIFICATIONS only; it never changes any published judgment. Cap 50 active watches (typed 409 beyond).](https://api.tollbridge.app/v1/alerts) — free
- [GET /v1/policy/seal: The checksum-sealed ruleset that drives every refusal: { version, checksum, ruleset }. Recompute the checksum from the body with the policy library and compare — the seal proves which rules were in force, not that storage works.](https://api.tollbridge.app/v1/policy/seal) — free
- [POST /v1/verify: The open claim-checker (FREE, pure computation): paste a POJ receipt ({ poj_id, body }) and it recomputes the id with the frozen JCS sha256 canon — the exact arithmetic that froze the decision record — and reports validity plus per-field checks. Internal consistency only: the ledger row is the reference, and the resolution alone says whether a claim came true. Wrong content is a verdict (valid:false); wrong format is a typed 400.](https://api.tollbridge.app/v1/verify) — free
- [GET /v1/priors: The measured base rates (pooled prior per question: rate, Wilson CI, n, successes, verdict; the S01 label histogram; explicit nulls + the honest reason where no prior exists). The same read path the emit path reconciles against — a prior is a base rate, never a forecast. Free.](https://api.tollbridge.app/v1/priors) — free
- [GET /v1/universe: The live venue universe: top perps by 24h notional volume, computed from the venue tape and cached ≤15s (free; delisted names dropped, provenance included — never a curated list)](https://api.tollbridge.app/v1/universe) — free
- [GET /v1/marketcap: The largest coins by market cap: the DISCOVERY list a user picks a subject from, ranked market-cap-descending and computed from a named public source (free; each row carries askable:true|false|null — askable only when the venue universe also trades it, so a top-cap coin with no live market is discoverable yet honestly marked not askable; never a curated list)](https://api.tollbridge.app/v1/marketcap) — free
- [GET /v1/signals: The question catalog with DERIVED capability: available vs blocked for each of the 26 questions, computed from the resolution-evaluator registry and the emit gates (free; the one call an agent needs to discover what it can ask)](https://api.tollbridge.app/v1/signals) — free
- [GET /v1/liq/hours: The liquidation tape inspector: the hourly sided-liquidation observations on record for an asset, on the operator-named tape (free; the N/24 figure behind S02/S03/S04 — a count and the raw hours, never a probability)](https://api.tollbridge.app/v1/liq/hours) — free
- [GET /v1/sheet: THE CANONICAL QUESTION SHEET: for one asset, all twenty-six questions in fixed catalog order with derived live/dark/pending/empty state, the ask gate and price, and the exact blocker for the dark rows (free — every customer surface renders this one object; an unknown asset is a typed 404)](https://api.tollbridge.app/v1/sheet) — free
- [GET /v1/blotter: THE CROSS-ASSET BLOTTER: every open clock across the assets you name (soonest horizon first), the last dead chip per question on each asset, and each dark question listed once with its exact blocker (free; assets defaults to BTC,ETH,SOL and is capped at 20; an unknown asset is skipped with a typed warning, never a 404 of the whole blotter)](https://api.tollbridge.app/v1/blotter) — free
- [GET /v1/lineage/{decision_id}: THE EVIDENTIARY BUNDLE: for one decision, the full record + its resolution (or honest pending) + the payment rail + the per-input tape sources + the hashes, with a recomputed request-hash verify block (free; a short 8+ char id resolves by unique prefix). No live model call, no second venue — every cell carries a source.](https://api.tollbridge.app/v1/lineage/{decision_id}) — free
- [POST /v1/billing/scout: One-time Scout credit grant per payer (free, tightly rate-limited)](https://api.tollbridge.app/v1/billing/scout) — free
- [GET /v1/billing/scout: Scout grant status for a payer: available (never held the one-time lot) + current balance (free read; the grant itself stays POST)](https://api.tollbridge.app/v1/billing/scout) — free
- [GET /v1/billing/credits: Credit balance + expiring lots for a payer (free read)](https://api.tollbridge.app/v1/billing/credits) — free
- [GET /v1/billing/draws: The payer-readable credit journal: every draw + credit movement, newest first, reversed_at stamped on reversed debits (free read)](https://api.tollbridge.app/v1/billing/draws) — free
- [POST /v1/billing/grants: Operator grant / debit reverse (x-tollbridge-ops header; OPS_UNSET when no operator token is wired — never a public grant)](https://api.tollbridge.app/v1/billing/grants) — free
- [POST /v1/contacts: Durable, acknowledged launch-contact capture for the /story waitlist: {contact, consent, source?, seat?} → 201 recorded / 200 already_recorded; CONTACTS_UNWIRED (503) when this deployment does not record contacts. Never a mail-sent claim.](https://api.tollbridge.app/v1/contacts) — free
POST /v1/billing/packs/booster_150k: $150.000 USDC via x402
POST /v1/billing/packs/booster_650k: $600.000 USDC via x402
POST /v1/billing/packs/booster_2m4: $2000.000 USDC via x402
POST /v1/billing/packs/drill: $0.010 USDC via x402
POST /v1/billing/plans/operator: $99.000 USDC via x402
POST /v1/billing/plans/desk: $249.000 USDC via x402
POST /v1/billing/plans/desk_pro: $499.000 USDC via x402
- [GET /v1/billing/rate-lock: The caller's Founders' Rate quote: the locked rate while the lock lives, the ladder's rung rate otherwise (free read; payer header)](https://api.tollbridge.app/v1/billing/rate-lock) — free
- [POST /v1/billing/rate-lock: Buy the Founders' Rate: a 12-month per-credit price lock at the current rung plus a premium (payer-bound, non-transferable; the fee settles with x402 and the lock lands at settle — an x-tollbridge-ops header issues it as an operator grant instead)](https://api.tollbridge.app/v1/billing/rate-lock) — $0.200 USDC via x402
- [GET /v1/arena/profile: A wallet's Arena standing: rank, XP, progress to the next rank, accuracy, streaks, markets covered and badges — all derived from measured calls, keyed by the payer address (free read; ?payer= required)](https://api.tollbridge.app/v1/arena/profile) — free
- [GET /v1/arena/quests: The daily and weekly quest board with live progress, remaining, expiry and awarded state — counted from the append-only XP journal and completed automatically once a quest target is reached (free read; ?payer= required)](https://api.tollbridge.app/v1/arena/quests) — free
- [GET /v1/arena/season: The weekly Arena season (Monday 00:00 UTC): the live season clock and every frozen season board with the top placements per track (free)](https://api.tollbridge.app/v1/arena/season) — free
- [GET /v1/arena/card/{publicId}: Resolve a public card id to its opted-in Arena standing — the one-way digest is inverted server-side against the opt-in board only, and the standing is returned WITHOUT its address (free; typed 404 when the id names no public record)](https://api.tollbridge.app/v1/arena/card/{publicId}) — free
- [GET /v1/arena/next-action: The open quests ranked by their XP reward — a deterministic recommendation of what earns the most experience next (free; ?payer= required)](https://api.tollbridge.app/v1/arena/next-action) — free
- [GET /v1/arena/leaderboard: The public opt-in Arena leaderboard over rank/XP/accuracy/streak, human and agent tracks, lifetime or the live season (scope=season) — no pay-to-rank, billing never joins the ranking (free)](https://api.tollbridge.app/v1/arena/leaderboard) — free
- [POST /v1/arena/opt-in: Record your consent for the public Arena leaderboard (free; x-tollbridge-payer required)](https://api.tollbridge.app/v1/arena/opt-in) — free
- [POST /v1/arena/agent: Self-declare the agent track for the leaderboard filter — a board label only, never a change to rank, XP or price (free; x-tollbridge-payer required)](https://api.tollbridge.app/v1/arena/agent) — free
- [GET /v1/arena/levels: The Intelligence Level catalog (credit bands, XP per ask and per correct call) and the earned rank ladder with its automatic credit discounts (free; static)](https://api.tollbridge.app/v1/arena/levels) — free
- [GET /v1/arena/notifications: The wallet notification feed: server-computed events from the real economic edges (a graded call, a completed quest, a badge, a rank-up, a streak change), unread first and bounded to 50, with the unread count (free; ?payer= required)](https://api.tollbridge.app/v1/arena/notifications) — free
- [POST /v1/arena/notifications/read: Mark notifications read: every unread row, or just the given ids (free; body { payer, ids? })](https://api.tollbridge.app/v1/arena/notifications/read) — free
- [GET /v1/arena/notifications/preferences: The effective per-kind notification toggle map — the defaults overlaid with the wallet overrides (free; ?payer= required)](https://api.tollbridge.app/v1/arena/notifications/preferences) — free
- [PUT /v1/arena/notifications/preferences: Store the per-kind notification toggles; only an explicit false suppresses a kind (free; body { payer, preferences })](https://api.tollbridge.app/v1/arena/notifications/preferences) — free

## Signal set (the live law, derived)

The available set is DERIVED from the resolution-evaluator registry and the emit gates — never a hand list. Call GET https://api.tollbridge.app/v1/signals for the authoritative set. AVAILABLE = a resolution evaluator is registered AND every required emit feature has a wired venue read. S06/S07 emit and resolve share the venue fundingHistory settlement tape; S08 emit and resolve share Tollbridge’s own hourly open-interest snapshot tape (market_snapshots, kind openInterest); S09/S10/S11 emit and resolve share the venue ACCOUNT tape (Hyperliquid clearinghouseState). NOT AVAILABLE = the required market data is not complete yet, or the outcome cannot be measured yet. S02/S03/S04 read a MARKET-WIDE, SIDED liquidation tape written from a NAMED third-party indexer (source goldrush). The venue itself publishes no market-wide liquidation feed — its info REST has none, and liquidations appear there only as a marker on per-wallet fills or on node trade files — so this tape is third-party by necessity and is never proxied venue data. Availability is PER ASSET and is gated on that asset’s own hourly observations reaching the sample floor (24): GET https://api.tollbridge.app/v1/liq/hours?asset=<symbol> reports that asset’s N/24 figure plus the hour-by-hour window (a gap hour is present:false with null notionals, never a zero), and GET https://api.tollbridge.app/v1/signals reports the same per asset in sample_hours_by_asset. One asset’s hours never light another asset’s question. Refusals use the published taxonomy: out_of_scope, stale_input, insufficient_sample.

Every response carries state, probabilities, confidence, timestamp, freshness, horizon, data_sources and methodology_version.

## Pricing

| Endpoint | Price (USDC) | Atomic units | Network |
|---|---|---|---|
| `market.quote` | $0.001 | 1000 | eip155:8453 |
| `market.depth` | $0.001 | 1000 | eip155:8453 |
| `market.klines` | $0.001 | 1000 | eip155:8453 |
| `perp.funding` | $0.002 | 2000 | eip155:8453 |
| `perp.oi` | $0.002 | 2000 | eip155:8453 |
| `perp.basis` | $0.002 | 2000 | eip155:8453 |
| `perp.liquidations` | $0.002 | 2000 | eip155:8453 |
| `wallet.profile` | $0.005 | 5000 | eip155:8453 |
| `wallet.events` | $0.005 | 5000 | eip155:8453 |
| `wallet.state` | $0.005 | 5000 | eip155:8453 |
| `risk.assess` | $1.000 | 1000000 | eip155:8453 |
| `decision.deep` | $1.000 | 1000000 | eip155:8453 |
| `signals.evaluate` | $1.000 | 1000000 | eip155:8453 |
| `billing.pack.booster_150k` | $150.000 | 150000000 | eip155:8453 |
| `billing.pack.booster_650k` | $600.000 | 600000000 | eip155:8453 |
| `billing.pack.booster_2m4` | $2000.000 | 2000000000 | eip155:8453 |
| `billing.pack.drill` | $0.010 | 10000 | eip155:8453 |
| `billing.plan.operator` | $99.000 | 99000000 | eip155:8453 |
| `billing.plan.desk` | $249.000 | 249000000 | eip155:8453 |
| `billing.plan.desk_pro` | $499.000 | 499000000 | eip155:8453 |
| `billing.addon.priority` | $99.000 | 99000000 | eip155:8453 |
| `billing.addon.slot` | $19.000 | 19000000 | eip155:8453 |
| `billing.addon.hook` | $49.000 | 49000000 | eip155:8453 |
| `billing.addon.pricelock` | $0.200 | 200000 | eip155:8453 |
| `billing.export.asset_period` | $29.000 | 29000000 | eip155:8453 |

## Payment

- Paid endpoints use x402 v2 (scheme `exact`, EIP-3009 `transferWithAuthorization`) with USDC on Base (network `eip155:8453`, asset `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`).
- An unpaid request to a paid endpoint returns `402` with a base64 `PAYMENT-REQUIRED` header; sign the EIP-3009 authorization and retry with a base64 `PAYMENT-SIGNATURE` header.
- THE WORKING RAIL on this deployment — prepaid credits: send an `x-tollbridge-payer` header (your Base address) instead of a payment signature; the call debits your credit balance at the PRICING-derived rate (1 credit = the credit anchor in @tollbridge/core), and a refusal or an undelivered result reverses the debit. An empty balance returns `402` with the x402 challenge plus `detail.reason: INSUFFICIENT_BALANCE`.
- x402 settles through the PayAI facilitator (`https://facilitator.payai.network`, scheme `exact`, network `eip155:8453`) — see `/.well-known/x402` for the exact, live terms. The prepaid credits rail (the `x-tollbridge-payer` header) is the lower-latency path when a balance exists.
- Refill that works: an operator grant — `POST /v1/billing/grants` { "action": "grant", "payer": "0x…", "credits": N, "ref": "…" } with the operator `x-tollbridge-ops` header. With no operator token wired the route returns `OPS_UNSET` (never a public grant). Reverse a specific leaked debit with { "action": "reverse", "payer": "0x…", "ref": "<debit ref>" } (idempotent).
- Reads: one-time free Scout grant via `POST /v1/billing/scout` { payer }; balance via `GET /v1/billing/credits?payer=`; every draw, credit and reverse via `GET /v1/billing/draws?payer=` (newest first; a reversed debit carries `reversed_at`).
- A successful call returns the settlement receipt in the base64 `PAYMENT-RESPONSE` header (transaction, network, payer).
- Payment replays (one-time EIP-3009 nonce) are rejected `402 PAYMENT_REPLAYED`.

## Errors and refusals

- All non-2xx responses carry `{error: {code, message, retryable, retry_after_ms, request_id, detail}}` with canonical codes (VALIDATION, STALE_DATA, PROVIDER_DOWN, RATE_LIMITED, PAYMENT_*).
- Honest gate decisions (stale_input / insufficient_confidence / suppress) are 200 responses with `probability: 0` and the decision field carrying the truth — no probability claim was made.

## Docs

- API reference + OpenAPI 3.1: https://api.tollbridge.app/openapi.json on this deployment
- Human docs redirect: https://api.tollbridge.app/docs (operators may point this at their own documentation host)
- MCP server: POST https://api.tollbridge.app/mcp (stateless Streamable HTTP, JSON-RPC) — discovery at https://api.tollbridge.app/.well-known/mcp.json; paid tools take an x402 payload in the base64 PAYMENT-SIGNATURE header OR a prepaid credit "payer" argument (or the x-tollbridge-payer header).

## Agent recipe (the honest loop)

0. Scout or x402: you need a payer to ask. Scout (FREE, first run): POST /v1/billing/scout { "payer": "0x<base-address>" } — the one-time free credit lot, idempotent (an address that already holds it is a no-op that still reports the balance). Over MCP: tools/call tollbridge_scout { "payer": "0x<base-address>" }. Or pay per call with an x402 payload. Read the balance via GET /v1/billing/credits?payer= (or GET /v1/billing/draws?payer= for the full credit journal).
1. Sheet (FREE): GET https://api.tollbridge.app/v1/sheet?asset=<asset> — THE ONE OBJECT. All twenty-six questions for that asset in fixed catalog order, each with its derived state (live | dark | pending | empty), the ask gate and price, and the exact blocker for the dark rows. <asset> may be any symbol GET /v1/universe lists (top 50 by 24h volume); an unknown or delisted symbol is a typed 404. Over MCP: tools/call tollbridge_sheet. This is the island: read it once and you know what exists, what you can ask, and what is still in flight.
2. Blotter (FREE, many assets): GET https://api.tollbridge.app/v1/blotter?assets=BTC,ETH,SOL,HYPE — the cross-asset cut of the same object. pending lists every open clock across those assets (soonest horizon_end first), latest_terminal is the last dead chip per question on each asset, and dark lists each blocked question once with its exact blocker. assets defaults to BTC,ETH,SOL and is capped at 20; a symbol with no live market is skipped with a warning (the rest still answer), never a 404 of the whole blotter. Over MCP: tools/call tollbridge_blotter. Use this when you care about more than one symbol.
3. If any pending row exists (sheet or blotter): sleep until min(horizon_end) across the pending rows, then re-read. Do NOT ask while a horizon is open. (GET https://api.tollbridge.app/v1/clocks/open lists the same pending set — the sheet's own "clocks" agree with it.)
4. Resolutions (FREE): GET https://api.tollbridge.app/v1/resolutions/<decision_id> for the rows you waited on — either a terminal outcome (realized/obtains/not/unresolvable + the predicted/realized sentence) or {status:"pending", horizon_end}. Over MCP: tools/call tollbridge_get_resolution.
5. FEED (FREE): GET https://api.tollbridge.app/v1/feed?limit=50 — the newest TERMINAL chips (newest first): decision_id, question_id, asset, output, predicted, realized, match, observed, status, resolved_at, horizon_end. Schema by output: CHOICE chips carry predicted+realized+match; PROBABILITY chips carry predicted (the frozen p) + observed (true = the event obtained) with realized/match null — no binary match exists for a probabilistic claim. Lurk here for free; no wallet, no model guts. Over MCP: tools/call tollbridge_feed.
6. Ask — ONLY rows with row.ask.allowed == true:
   MCP: tools/call tollbridge_decision { "question_id": "<question_id>", "asset": "<asset>", "payer": "0x<base-address>" } — account questions (S09/S10/S11) also take a "wallet" subject (get an address on the sheet first).
   HTTP: POST https://api.tollbridge.app/v1/decisions with the same body and the x-tollbridge-payer header. The call debits your prepaid Scout credits; a refusal reverses the debit and returns the typed refusal (out_of_scope / stale_input / insufficient_sample) — never a fabricated probability.
7. RELAPSE (PAID, same price): POST https://api.tollbridge.app/v1/decisions/next { "previous_decision_id": "<id>" } asks the NEXT dated sentence on the same question+asset. Refused with clock_open while the previous clock is pending — wait for horizon_end first.
8. HOOK (PAID, same price): POST https://api.tollbridge.app/v1/hooks { "decision_id": "<id>", "url": "<https-url>" } — the worker POSTs the ResolutionRecord the instant the chip writes, signed X-Tollbridge-Signature (HMAC-SHA256), one retry. The url is SSRF-checked (loopback/RFC1918/link-local/metadata refused); an already-terminal clock is a 409 telling you to read the resolution directly.
9. S02, S03 and S04 are dark until GET https://api.tollbridge.app/v1/liq/hours?asset=<asset> reports adequate == true (24 hourly observations on the operator-named tape). Until then their rows are state "dark" with ask.allowed false, and asking them returns a typed refusal — that is the honest behaviour, not an error.

The same object is served on HTTP and MCP: a sheet row, a blotter row, a resolution, a tile and a tool result never disagree.