/surf

name: surf
description: Use when the user wants crypto data — token prices, on-chain SQL, prediction-market positions, CEX order books, wallet labels/net-worth, social mindshare, news, or unified search. 83 endpoints across exchange, on-chain, wallet, social, prediction, news and search — one API, flat $0.0085/call in USDC via x402. Settles directly to Surf's Base treasury; no Surf account needed.
triggers:
  - "surf"
  - "asksurf"
  - "crypto data"
  - "on-chain sql"
  - "clickhouse crypto"
  - "wallet labels"
  - "wallet net worth"
  - "smart followers"
  - "ct mindshare"
  - "social mindshare"
  - "kol search"
  - "fear and greed"
  - "etf flows"
  - "funding rate"
  - "long short ratio"
  - "liquidation chart"
  - "tokenomics unlock"
  - "vc fund portfolio"
  - "defi protocol metrics"
  - "bridge ranking"
  - "yield ranking"
  - "airdrop search"
  - "options skew"
  - "perp snapshot"
  - "gas price"
  - "polymarket data"
  - "kalshi data"

Surf — Crypto Data via BlockRun

Surf (asksurf.ai) aggregates **83 crypto data endpoints** across CEX market data, on-chain SQL (13 chains, 80+ ClickHouse tables), 100M+ labeled wallets, prediction markets (Polymarket + Kalshi side-by-side), social/CT intelligence, news and unified search.

BlockRun is Surf's x402 payment rail — every call settles **directly to Surf's Base treasury**. You hold the wallet, BlockRun holds the Surf key, Surf holds the data. No Surf account, no API key, no monthly minimum.

How to Call from MCP

One tool, three params. The MCP tool auto-routes method (POST when `body` is set, GET otherwise) and auto-validates required params before settling:

blockrun_surf({ path: "market/price", params: { symbol: "BTC" } })

blockrun_surf({ path: "onchain/sql", body: {
  sql: "SELECT token_address, count() FROM ethereum.dex_trades WHERE block_time > now() - INTERVAL 1 DAY GROUP BY 1 ORDER BY 2 DESC LIMIT 10"
}})

blockrun_surf({ path: "wallet/labels/batch", params: { addresses: "0xabc,0xdef" } })

Pricing — one flat rate

**$0.0085 per call. Every endpoint, no tiers, including raw on-chain SQL.**

Verified against the gateway's own `payment-required` header, which is free to request — send any call with no payment header and it quotes the exact charge. All of `market/price`, `wallet/labels/batch`, `social/mindshare`, `news/feed`, `exchange/klines`, `search/web` **and `onchain/sql`** return the same $0.0085 (`SURF_TIER_1/2/3_PRICE` are all identical upstream).

Ignore any "premium tier" pricing you may have seen — SQL used to cost more and no longer does.

Wrong / missing required params return HTTP 400 **without charging** — pre-validation runs before settlement.

Do NOT use Surf for prediction markets

Surf carries 17 `prediction-market/*` endpoints (Polymarket + Kalshi). **Use `blockrun_markets` (Predexon) instead — same data, same price, and far deeper.**

Predexon used to be 7.5× cheaper; since 2026-07-15 both bill the same flat rate, so the choice is now purely about coverage — and Predexon still wins on coverage by a wide margin.

| | Predexon (`blockrun_markets`) | Surf | |---|---|---| | Polymarket / Kalshi markets | $0.0085 | $0.0085 (same) | | Wallet clustering, smart money, leaderboards | ✅ | ❌ none | | Limitless, Opinion, Predict.Fun, sports, UMA | ✅ | ❌ Polymarket + Kalshi only |

The only Surf prediction-market endpoint with no Predexon equivalent is `prediction-market/category-metrics`. Everything else is a strictly worse buy. See [`skills/prediction-markets/SKILL.md`](../prediction-markets/SKILL.md).

**Reach for Surf when Predexon cannot answer it:** on-chain SQL, 100M+ wallet labels across 13 chains, 16 CEXs, social/CT intelligence, news, tokenomics/unlocks, liquidations, ETF flows, VC portfolios. Predexon has none of those.

Quick Decision Table — "User asks about X"

| User wants… | Method | Path | Required | |---|---|---|---| | BTC/ETH price | GET | `market/price` | `symbol` | | ETF flow history | GET | `market/etf` | `symbol` | | Fear & Greed index | GET | `market/fear-greed` | – | | Top 100 tokens by market cap | GET | `market/ranking` | – | | Options skew / IV / volume | GET | `market/options` | `symbol` | | CEX ticker for a pair | GET | `exchange/price` | `pair` | | Perp snapshot (funding + OI) | GET | `exchange/perp` | `pair` | | Order book depth | GET | `exchange/depth` | `pair` | | OHLCV candles | GET | `exchange/klines` | `pair` | | Funding rate history | GET | `exchange/funding-history` | `pair` | | Long/short ratio | GET | `exchange/long-short-ratio` | `pair` | | Bridge protocols by volume | GET | `onchain/bridge/ranking` | – | | Yield pool ranking | GET | `onchain/yield/ranking` | – | | Current gas price (per chain) | GET | `onchain/gas-price` | `chain` | | Transaction details | GET | `onchain/tx` | `hash`, `chain` | | **Raw on-chain SQL** | POST | `onchain/sql` | body: `sql` | | **Structured on-chain query** | POST | `onchain/query` | body: typed predicates | | Inspect ClickHouse schema | GET | `onchain/schema` | – | | Polymarket markets ranking | GET | `prediction-market/polymarket/ranking` | – | | Polymarket price history | GET | `prediction-market/polymarket/prices` | `condition_id` | | Polymarket positions for wallet | GET | `prediction-market/polymarket/positions` | `address` | | Kalshi markets ranking | GET | `prediction-market/kalshi/ranking` | – | | Kalshi market detail | GET | `prediction-market/kalshi/markets` | `market_ticker` | | **Search Polymarket / Kalshi** | GET | `search/polymarket` / `search/kalshi` | – | | Wallet profile (cross-chain) | GET | `wallet/detail` | `address` | | Wallet net-worth time series | GET | `wallet/net-worth` | `address` | | Wallet DeFi positions | GET | `wallet/protocols` | `address` | | **Batch wallet labels (CEX/Whale/MEV…)** | GET | `wallet/labels/batch` | `addresses` | | Token tokenomics + unlocks | GET | `token/tokenomics` | – | | Token holders top N | GET | `token/holders` | `address`, `chain` | | Token transfers | GET | `toke