API

Tollbridge is a paid probabilistic intelligence API for AI agents: market, funding, wallet, and risk signals (S01..S11) computed over an append-only decision ledger, with honest refusals instead of fabricated numbers.

• Base URL (hosted): https://api.tollbridge.dev
• Payment rail: x402 v2 — exact scheme, EIP-3009 USDC on Base (eip155:8453)
• Success envelope: every response is {data, meta} where meta carries request_id, timestamp, state, probabilities, confidence, freshness, horizon, data_sources, methodology_version (and pricing on paid endpoints).

Every page in this section documents its endpoints with four example styles: curl, TypeScript (the real @tollbridge/sdk-typescript facade), Python (reference httpx snippets — the official Python SDK is in progress; these snippets are a faithful wire-level reference, not an official package), and MCP (a tool-call example from the tool catalog where a tool proxies the surface — stated honestly where none does in v1).

Free vs paid

The free/paid split is declared once in the route registry and enforced identically everywhere:

• Free: platform surfaces (/healthz, /readyz, /v1/pricing, /v1/providers, /openapi.json, /.well-known/*, /llms.txt), the market snapshot (GET /v1/market/{asset}), the decision ledger read + replay (GET /v1/decisions/{id}, POST /v1/decisions/{id}/replay) and the decision-intelligence reads (GET /v1/intelligence, GET /v1/intelligence/curve, GET /v1/intelligence/releases and its per-release detail).
• Paid: every engine decision and every raw perp/wallet surface, priced per its PRICING key (see Pricing).

{asset} ∈ BTC | ETH | SOL (else VALIDATION); {chain} ∈ base (v1); {address} is a 20-byte hex address.

Endpoint inventory

Payment (x402) in one paragraph

1. Call a paid endpoint without PAYMENT-SIGNATURE → 402 with a base64 PAYMENT-REQUIRED header describing the EIP-3009 requirements (amount derived from the price table).
2. Sign the transferWithAuthorization authorization and retry with a base64 PAYMENT-SIGNATURE header.
3. On success the response carries the settlement receipt in the base64 PAYMENT-RESPONSE header.
4. Replayed payments (one-time nonce) are rejected with 402 PAYMENT_REPLAYED.

Any x402 SDK — or the TypeScript SDK — performs steps 1–3 automatically. Full details: x402.

# 1) get the challenge
curl -i https://api.tollbridge.dev/v1/decisions \
  -H 'content-type: application/json' \
  -d '{"asset":"BTC","question_id":"S06_funding_anomaly"}'
# → 402, PAYMENT-REQUIRED: <base64>

Refusals (honest gate decisions)

Stale/degraded inputs, inadequate baselines, and unavailable surfaces are 200 responses with the refusal recorded as the decision — probability and confidence are 0 ("no claim"; the decision field carries the truth):

Error envelope (all non-2xx)

{"error": {"code": "STALE_DATA", "message": "funding older than staleness budget", "retryable": true, "retry_after_ms": null, "request_id": "req_", "detail": {"reason": "..."}}}

Stable machine reasons in detail.reason: DECISION_NOT_FOUND (404), REPLAY_INPUT_LOST (409), DECISION_REPLAYED (409), REQUEST_VALIDATION_FAILED, CIRCUIT_OPEN, JEV_CALL_FAILED.

Sections

• Platform — healthz, readyz, pricing, providers.
• Discovery — openapi.json, .well-known/*, llms.txt.
• Market — the free snapshot.
• Market signals — S01 regime, S02 liquidation risk.
• Liquidations — raw liquidation surfaces.
• Funding — funding snapshot, S06/S07 decisions, opportunities.
• Wallet — profile, state, positions.
• Risk — S11 across transaction/token/wallet/protocol subjects.
• Decisions — deep decision, ledger read, replay.