Builders

Public API

Free, no key, CORS open, rate-limited per IP. Every response carries provenance and a degraded list so you can tell unknown from zero.

Envelope

{
  "data": { ... },
  "generatedAt": "2026-09-11T02:04:41.227Z",
  "sources": [{ "name": "Robinhood quote", "url": "...", "fetchedAt": "..." }, { "name": "Robinhood Chain RPC", "block": "59888753" }],
  "degraded": ["chainlink:feed"],
  "cache": { "maxAgeSeconds": 10 }
}

Errors: { "error": { "code": "not_found", "message": "..." }, "generatedAt": "..." } with a matching HTTP status (400 bad input, 404 unknown token, 429 rate limited, 503 upstream unavailable). Rate limit: 120 requests/minute per IP with a burst of 40; cache on your side.

Endpoints

Endpoint	Returns
`GET /tokens`	All canonical tokens with address, on-chain multiplier, paused flag, Chainlink coverage.
`GET /token/{symbol\|address}?size=1000`	The full Fair-Value Card: session, multiplier, references with freshness, pools with executable prices and list, corporate actions, verdict. `size` ∈ 100, 1000, 10000 USDG.
`GET /verify/{address}`	`verdict`: canonical · lookalike · unknown, with reason, on-chain symbol/name and the canonical entry when relevant.
`GET /quote?token=AAPL&side=sell&amount=1&bandBps=50`	A swap plan: reference, per-pool candidates with list, and either a ready decision (expected and minimum output, deadline, calldata for the Universal Router, approvals needed) or a refusal with code, message and action.
`GET /portfolio/{address}`	Holdings of every canonical token: raw balance, UI-adjusted shares, reference price, value, next corporate action.
`GET /session`	US market session state in New York time.
`GET /health`	Chain and registry reachability.

Examples

curl https://surgetech.live/api/v1/verify/0xaF3D76f1834A1d425780943C99Ea8A608f8a93f9
curl "https://surgetech.live/api/v1/token/NVDA?size=1000"
curl "https://surgetech.live/api/v1/quote?token=AAPL&side=buy&amount=250&bandBps=50"

The quote endpoint returns calldata but never signs anything; execution is always from the caller's own wallet. Amounts in data are strings in base units unless the field name ends in Decimal or the value is a price.

Semantics

degraded names the upstream that failed (robinhood:quote, chainlink:feed, chain:pools, …). Fields that depend on it are null, never 0.
references.selected.freshness is fresh, stale or unknown; only fresh references guard swaps.
listBps is signed: negative is below the reference.
All addresses are EIP-55 checksummed. Pool ids are the Uniswap v4 keccak256(abi.encode(PoolKey)).

Fixture mode (SURGE_FIXTURE_MODE=1) serves recorded registry data for tests; production never runs in fixture mode and the health endpoint reports which mode is active.