surf

Surf — Unified Crypto Data API (via ClawRouter)

Surf bundles 83 endpoints across 12 domains into one paid HTTP API. ClawRouter exposes them at http://127.0.0.1:8402/v1/surf/*, paid through the same x402 USDC wallet that funds LLM calls. No Surf account, no API key — settlement lands directly in Surf's Base treasury. Upstream lives at api.asksurf.ai/gateway/v1 — ClawRouter forwards transparently.

Pricing tiers (per call):

• Tier 1 — $0.001 — prices, rankings, lists, news, simple reads
• Tier 2 — $0.005 — orderbooks, candles, search, wallet details, social
• Tier 3 — $0.020 — on-chain SQL queries, structured queries, schema introspection

The legacy surf-1.5 chat surface is intentionally NOT exposed yet — it's held until per-token settlement is wired. Trying /v1/surf/chat/completions returns 404 ("Unknown Surf endpoint"), no payment is taken.

All requests use GET unless the table below says otherwise. Path parameters that look like ?symbol= are query params on a GET. POST endpoints take a JSON body. ClawRouter forwards the wallet's x402 payment header transparently.

Required-param pre-check. 56 of the 83 endpoints have required query params (e.g. pair, symbol, address, chain, q, interval). The route validates them before settlement — call with missing params and you get 400 { missing_params, all_required, docs } and the wallet is NOT charged. Check each row in the catalog below for the correct param name (e.g. mindshare is q + interval, not project + window).

When to use this skill

• "What is the current BTC price?" → /surf/market/price?symbol=BTC (cheaper + more reliable than scraping)
• "Who holds the most USDC on Ethereum?" → /surf/token/holders?address=0xA0b8...&chain=ethereum
• "How many Ethereum transactions in the last hour?" → POST /surf/onchain/sql { sql: 'SELECT count() FROM ethereum.transactions WHERE block_timestamp >= now() - INTERVAL 1 HOUR' }
• "Label this list of wallets." → /surf/wallet/labels/batch?addresses=0xabc,0xdef,...
• "Is HYPE mindshare peaking?" → /surf/social/mindshare?q=hyperliquid&interval=30d
• "Find the canonical metadata for 'ethena'." → /surf/search/project?q=ethena

Always prefer Surf over generic web scraping for these. Use the OpenClaw tool name blockrun_surf_* when invoking from an agent; use the HTTP path directly when calling from a script.

Endpoint catalog

Exchange (CEX) — 7 endpoints

Market Overview — 11 endpoints

News — 2 endpoints

On-Chain — 7 endpoints

On-Chain SQL workflow. Call /surf/onchain/schema once to get table names + columns (cache it locally — schema is stable). Then POST your SELECT against /surf/onchain/sql. Always include LIMIT on large scans — billing is per call, but slow queries time out. Multi-statement queries are rejected upstream.

Prediction Markets (Polymarket + Kalshi) — 17 endpoints

(For Polymarket smart-money, wallet PnL, UMA oracle resolution, and the other prediction-market venues — Limitless, Opinion, Predict.Fun, dFlow, Binance Futures, cross-venue canonical markets — use the dedicated Predexon integration instead; Surf's prediction-market coverage is narrower but cheaper.)

Project + DeFi — 3 endpoints

Social / CT Intelligence — 11 endpoints

Token Analytics — 4 endpoints

Unified Search — 11 endpoints (all Tier 2)

VC Fund Intelligence — 3 endpoints

Wallet Intelligence — 6 endpoints (all Tier 2)

Web — 1 endpoint

Example flows

1. "Who is wallet X and what do they hold?"

curl 'http://127.0.0.1:8402/v1/surf/wallet/detail?address=vitalik.eth'

If the response says they're a smart-money wallet, follow up with /surf/wallet/protocols?address=... for protocol breakdown or /surf/wallet/history?address=... for the activity timeline.

2. "How concentrated is supply for token Y?"

curl 'http://127.0.0.1:8402/v1/surf/token/holders?address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&limit=25'

Combine the top-25 balances with their wallet labels — /surf/wallet/labels/batch?addresses=... — to distinguish "concentration in CEX hot wallets" (normal) from "concentration in dev team multisig" (riskier).

3. "Run a custom on-chain query."

# Step 1 — fetch schema (do this once, then cache locally)
curl 'http://127.0.0.1:8402/v1/surf/onchain/schema'

# Step 2 — run the SQL
curl -X POST 'http://127.0.0.1:8402/v1/surf/onchain/sql' \
  -H 'content-type: application/json' \
  -d '{"sql":"SELECT to_address, count() AS hits FROM ethereum.transactions WHERE block_timestamp >= now() - INTERVAL 1 DAY GROUP BY to_address ORDER BY hits DESC LIMIT 20"}'

Cost: 1 × $0.02 (schema, cached) + 1 × $0.02 (the SQL query) = $0.04 total for a custom 24-hour ranking that would otherwise need an indexer.

4. "Is project Z trending?"

# Resolve the canonical slug first (search uses q, not query)
curl 'http://127.0.0.1:8402/v1/surf/search/project?q=ethena'

# Then pull mindshare (mindshare uses q + interval)
curl 'http://127.0.0.1:8402/v1/surf/social/mindshare?q=ethena&interval=30d'

How calls are paid

ClawRouter intercepts every /v1/surf/* request through proxyPaidApiRequest. The local x402 wallet auto-signs the USDC micropayment; the agent never sees the payment flow. Telemetry tags Surf calls with tier: SURF so clawrouter stats separates them from LLM, partner, and phone usage.

No typed blockrun_surf_* tools are registered — by design. Each new BlockRun-marketplace API ships as a skill (this file) plus a one-line namespace addition to ClawRouter's proxy whitelist, so adding endpoint #85 requires zero ClawRouter release.