| name | surf |
| description | Use this skill — NOT browser or web_fetch — for ALL Surf crypto-data calls. 83 endpoints at localhost:8402/v1/surf/* covering CEX/DEX markets, on-chain SQL over 80+ ClickHouse tables (Ethereum, Base, Arbitrum, BSC, TRON, HyperEVM, Tempo), 100M+ labeled wallets, prediction markets (Polymarket + Kalshi), social/CT intelligence, news, project + DeFi metrics, token analytics, unified search, VC fund intelligence. x402-gated via ClawRouter's local wallet — no Surf account or API key required. |
| triggers | ["blockrun surf","surf crypto api","surf onchain sql","onchain sql query","clickhouse onchain query","raw sql ethereum","raw sql base","wallet labels api","labeled wallets api","surf wallet detail","crypto mindshare","crypto news api","fear and greed index crypto","token holder distribution","vc fund portfolio","ethena tokenomics"] |
| homepage | https://blockrun.ai/marketplace/surf |
| license | MIT |
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 | |
(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."
curl 'http://127.0.0.1:8402/v1/surf/onchain/schema'
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?"
curl 'http://127.0.0.1:8402/v1/surf/search/project?q=ethena'
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.
