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

Path	Tier	Required
/surf/exchange/markets	T1	—
/surf/exchange/price	T1	pair
/surf/exchange/perp	T1	pair
/surf/exchange/depth	T2	pair
/surf/exchange/klines	T2	pair
/surf/exchange/funding-history	T2	pair
/surf/exchange/long-short-ratio	T2	pair

Market Overview — 11 endpoints

Path	Tier	Required
/surf/market/ranking	T1	—
/surf/market/fear-greed	T1	—
/surf/market/futures	T1	—
/surf/market/price	T1	symbol
/surf/market/etf	T1	symbol
/surf/market/options	T1	symbol
/surf/market/liquidation/exchange-list	T2	—
/surf/market/liquidation/order	T2	—
/surf/market/liquidation/chart	T2	symbol
/surf/market/onchain-indicator	T2	symbol, metric (NUPL, SOPR, MVRV, Puell, NVT)
/surf/market/price-indicator	T2	indicator (RSI, MACD, Bollinger, EMA), symbol

News — 2 endpoints

Path	Tier	Required
/surf/news/feed	T1	— (limit optional)
/surf/news/detail	T1	id

On-Chain — 7 endpoints

Path	Method	Tier	Required
/surf/onchain/bridge/ranking	GET	T1	—
/surf/onchain/yield/ranking	GET	T1	—
/surf/onchain/gas-price	GET	T1	chain
/surf/onchain/tx	GET	T1	hash, chain
/surf/onchain/schema	GET	T3	—
/surf/onchain/query	POST	T3	typed predicates in body
/surf/onchain/sql	POST	T3	{ sql: "SELECT ..." }

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

Path	Tier	Required
/surf/prediction-market/category-metrics	T1	—
/surf/prediction-market/polymarket/ranking	T1	—
/surf/prediction-market/polymarket/trades	T1	—
/surf/prediction-market/polymarket/markets	T1	market_slug
/surf/prediction-market/polymarket/events	T1	event_slug
/surf/prediction-market/polymarket/prices	T1	condition_id
/surf/prediction-market/polymarket/volumes	T1	condition_id
/surf/prediction-market/polymarket/open-interest	T1	condition_id
/surf/prediction-market/polymarket/positions	T2	address
/surf/prediction-market/polymarket/activity	T2	address
/surf/prediction-market/kalshi/ranking	T1	—
/surf/prediction-market/kalshi/markets	T1	market_ticker
/surf/prediction-market/kalshi/events	T1	event_ticker
/surf/prediction-market/kalshi/prices	T1	ticker
/surf/prediction-market/kalshi/trades	T1	ticker
/surf/prediction-market/kalshi/volumes	T1	ticker
/surf/prediction-market/kalshi/open-interest	T1	ticker

(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

Path	Tier	Required
/surf/project/detail	T1	—
/surf/project/defi/metrics	T1	metric
/surf/project/defi/ranking	T1	metric

Social / CT Intelligence — 11 endpoints

Path	Tier	Required
/surf/social/detail	T2	—
/surf/social/ranking	T2	—
/surf/social/smart-followers/history	T2	—
/surf/social/mindshare	T2	q, interval
/surf/social/tweets	T1	ids
/surf/social/tweet/replies	T1	tweet_id
/surf/social/user	T1	handle
/surf/social/user/followers	T1	handle
/surf/social/user/following	T1	handle
/surf/social/user/posts	T1	handle
/surf/social/user/replies	T1	handle

Token Analytics — 4 endpoints

Path	Tier	Required
/surf/token/tokenomics	T1	—
/surf/token/dex-trades	T2	address
/surf/token/holders	T2	address, chain
/surf/token/transfers	T2	address, chain

Unified Search — 11 endpoints (all Tier 2)

Path	Required
/surf/search/airdrop	—
/surf/search/events	—
/surf/search/kalshi	—
/surf/search/polymarket	—
/surf/search/web	q
/surf/search/project	q
/surf/search/news	q
/surf/search/wallet	q
/surf/search/fund	q
/surf/search/social/people	q
/surf/search/social/posts	q

VC Fund Intelligence — 3 endpoints

Path	Tier	Required
/surf/fund/detail	T1	—
/surf/fund/portfolio	T1	—
/surf/fund/ranking	T1	metric

Wallet Intelligence — 6 endpoints (all Tier 2)

Path	Required
/surf/wallet/detail	address
/surf/wallet/history	address
/surf/wallet/net-worth	address
/surf/wallet/transfers	address
/surf/wallet/protocols	address
/surf/wallet/labels/batch	addresses (comma-separated, ≤200)

Web — 1 endpoint

Path	Tier	Required
/surf/web/fetch	T2	url

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.