SDKs

The TypeScript facade with automatic x402 payment — and the honest status of the Python SDK.

TypeScript — `@tollbridge/sdk-typescript`

Typed client for the Tollbridge API with automatic x402 payment support. One typed method per API route; responses pass the {data, meta} envelope through unmodified, plus the typed settlement receipt on paid calls.

pnpm add @tollbridge/sdk-typescript

Quickstart

import { Tollbridge } from '@tollbridge/sdk-typescript';

// baseUrl is REQUIRED — there are no defaults (the deployment is explicit).
const toll = new Tollbridge({ baseUrl: 'https://api.tollbridge.app' });

// FREE (no wallet)
const market = await toll.market('BTC');
market.data.derived.mid;

// PAID (x402) — sign with your own key, per call, no account anywhere
const paying = new Tollbridge({
  baseUrl: 'https://api.tollbridge.app',
  x402: { signer: account }, // a viem Account (privateKeyToAccount) or WalletClient
});

const decision = await paying.decision({ asset: 'BTC', question_id: 'S06_funding_anomaly' });
decision.meta.confidence;  // { value, basis: 'jev' } | null
decision.meta.freshness;   // freshness entries
decision.meta.horizon;     // decision horizon
decision.payment;          // typed PAYMENT-RESPONSE settlement receipt

Every method resolves to the same result shape:

interface TollResult<T> {
  data: T;                                    // the §I data payload, passed through verbatim
  meta: ResponseMeta;                         // honesty block: confidence/freshness/horizon/…
  status: number;                             // HTTP status
  response: TollbridgeResponse;               // the underlying Response
  payment: X402SettlementReceipt | undefined; // PAYMENT-RESPONSE receipt, surfaced typed
}

Method surface (one per route)

Facade method	Route
`market(asset)`	`GET /v1/market/{asset}` (free)
`pricing()` / `providers()`	`GET /v1/pricing`, `GET /v1/providers` (free)
`decisions(id)` / `replay(id, opts?)`	ledger read + deterministic replay (free)
`getIntelligence()` / `getIntelligenceCurve(opts?)`	the measured record + learning curve (free)
`listIntelligenceReleases(opts?)` / `getIntelligenceRelease(version)`	the sealed release feed + one proof bundle (free)
`marketRegime(asset)` / `marketRisk(asset)`	S01 / S02 (paid)
`liquidation(asset)`	raw surfaces (paid)
`fundingSnapshot()` / `funding(asset)` / `fundingOpportunities()`	funding (paid)
`wallet(ref)` / `walletState(ref)` / `walletPositions(ref)`	wallet (paid)
`transactionRisk` / `tokenRisk` / `walletRisk` / `protocolRisk`	S11 (paid)
`decision(input)`	deep decision (paid)

Typed errors

Every non-2xx carries the universal envelope { error: { code, message, retryable, retry_after_ms, request_id, detail } }; the SDK maps it onto typed classes (all extend TollError, which preserves code, status, requestId, retryable, retryAfterMs, detail):

Class	Raised for
`TollValidationError`	`VALIDATION` (400)
`TollRateLimitError`	`RATE_LIMITED` (429) — `retryAfterMs` set
`TollUnavailableError`	`STALE_DATA` / `PROVIDER_DOWN` / `JEV_REFUSED` / `INSUFFICIENT_SAMPLE` (503)
`PaymentRequiredError`	402 without x402 config — carries the decoded challenge
`PaymentRejectedError`	signed payment rejected on retry (never charged)
`PaymentChallengeError`	client-side defensive refusal of a hostile challenge
`TollPaymentError`	other 402-family failures
`TollError`	anything else (envelope fields preserved)

import { PaymentRequiredError, TollRateLimitError, TollUnavailableError } from '@tollbridge/sdk-typescript';

try {
  await toll.decision({ asset: 'BTC', question_id: 'S06_funding_anomaly' });
} catch (err) {
  if (err instanceof PaymentRequiredError) {
    err.requirements.amount;   // atomic USDC string, PRICING-derived
    err.requirements.payTo;    // settlement address
  } else if (err instanceof TollRateLimitError) {
    await sleep(err.retryAfterMs ?? 1000);
  } else if (err instanceof TollUnavailableError) {
    // honest unavailability — err.retryable hints whether to retry
  }
}

x402 guarantees

Single-flight nonce guard — concurrent identical paid requests share one signed payment and one settlement; distinct payloads always sign independently with fresh nonces.
Hostile challenges are refused client-side (PaymentChallengeError) before anything is signed: foreign network, unexpected asset/scheme, malformed or above-cap amounts.
The client never talks to a facilitator — verify/settle are the resource server's business.

Python (reference snippets — official Python SDK in progress)

The official Python SDK package is future work. Until it ships, the Python snippets throughout this portal are reference snippets over plain httpx: they show the exact wire behavior (the 402 challenge header, the signed retry, the receipt header) but are not an official client. See any API page for the pattern:

import httpx

r = httpx.get("https://api.tollbridge.app/v1/market/BTC")  # free surface
assert r.status_code == 200

CLI

The tollbridge CLI (workspace apps/cli) drives the same surfaces from a terminal with --json/--x402/--verbose/--api-url flags and honest REAL/DERIVED badges.

TypeScript — @tollbridge/sdk-typescript