Quickstart

From zero to a paid deep decision in five minutes — free snapshot first, then x402 with USDC on Base.

Five minutes, two steps, zero accounts: a free market snapshot (no key, no wallet), then a paid deep decision settled with USDC on Base through the standard x402 flow.

GIVE YOUR AGENT CRYPTO INTELLIGENCE. Pay per decision with USDC. No account. No API key.

0. Requirements

A shell with curl — nothing else for step 1.
For the paid step: an Ethereum-style private key holding USDC on Base (the x402 exact scheme signs an EIP-3009 transferWithAuthorization; you never create an account anywhere).
Node.js 22+ if you use the TypeScript SDK.

1. Free market snapshot (no key)

The market snapshot is the open-data carve-out — it is free, always, with no key:

curl https://api.tollbridge.dev/v1/market/BTC

Response (shape):

{
  "data": {
    "asset": "BTC",
    "venue": "hyperliquid",
    "quote": { "price", "bid", "ask", "mark", "index", "volume_24h" },
    "derived": { "mid", "spread_bps" },
    "provenance": { "source", "provider", "timestamp", "received_at", "age_ms", "quality" }
  },
  "meta": {
    "request_id", "timestamp", "state", "probabilities", "confidence", "freshness",
    "horizon", "data_sources", "methodology_version", "pricing": null
  }
}

The same snapshot is also the free MCP tool tollbridge_market_state.

1. Read a recorded decision (free)

Decision records are append-only and publicly readable — no payment for the ledger read:

curl https://api.tollbridge.dev/v1/decisions/<decision_id>

Unknown ids return 404 DECISION_NOT_FOUND — an honest miss, never a synthesized record.

Payments are EIP-3009 transferWithAuthorization of USDC on Base (eip155:8453), signed by your own key. There is no account, no API key, no deposit flow — the agent holds its own funds and pays per call. Any viem signer works:

import { privateKeyToAccount } from 'viem/accounts';

// Any EVM account holding USDC on Base (eip155:8453).
export const account = privateKeyToAccount('0x<your private key>');

Fund it with USDC on Base — running a decision starts at $1 (1,000 credits; long-window questions $2, account questions $5 — see Pricing). Your first 3 entry-tier questions are free per payer address (S01 Market regime, S05 Volatility expansion, S06 Funding anomaly), and a refusal never spends one of them. Reading stays free.

3. Paid deep decision via x402

The TypeScript SDK performs the full x402 flow (challenge → sign → retry → receipt) for you:

import { Tollbridge } from '@tollbridge/sdk-typescript';
import { privateKeyToAccount } from 'viem/accounts';
import { account } from './wallet';

const paying = new Tollbridge({
  baseUrl: 'https://api.tollbridge.dev',
  x402: {
    signer: account,            // viem Account — signs EIP-3009 over USDC on Base
    maxAmountAtomic: '1000000', // defensive cap = the $1 entry tier (1000000 atomic);
                                // raise it to 2000000 / 5000000 for $2 / $5 questions
  },
});

// Deep decision: run any catalog signal through the engine (PAID).
const decision = await paying.decision({ asset: 'BTC', question_id: 'S06_funding_anomaly' });

decision.data.probability;   // the recorded probability
decision.data.confidence;    // jev-derived confidence
decision.data.decision;      // publish | monitor | escalate | suppress | …
decision.payment;            // the typed PAYMENT-RESPONSE settlement receipt

Without an x402 signer the identical call throws PaymentRequiredError carrying the decoded challenge — the agent decides whether to pay. Nothing is ever signed implicitly. For that entry-tier S06 question the challenge quotes "amount": "1000000" — that is $1, USDC on eip155:8453 — and the amount you receive is always authoritative (never a price you hardcode).

4. Or hand the whole thing to MCP

Point an MCP client at the server and call the tool catalog directly (see MCP):

{
  "mcpServers": {
    "tollbridge": {
      "type": "http",
      "url": "https://api.tollbridge.dev/mcp"
    }
  }
}

Where to next

The full endpoint catalog: API.
How payment works on the wire: x402.
What a decision record contains: Decisions.
What things cost and why: Pricing.