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.

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	token/transfers	address, chain
Token DEX trades	GET	token/dex-trades	address
Social mindshare time series	GET	social/mindshare	q, interval
Smart-follower history	GET	social/smart-followers/history	–
Twitter user profile	GET	social/user	handle
Twitter user posts	GET	social/user/posts	handle
Tweet replies	GET	social/tweet/replies	tweet_id
Web search (crypto-scoped)	GET	search/web	q
News article search	GET	search/news	q
KOL / CT people search	GET	search/social/people	q
Tweet full-text search	GET	search/social/posts	q
Project / token search	GET	search/project	q
Wallet search (by ENS, label)	GET	search/wallet	q
VC fund portfolio	GET	fund/portfolio	–
VC fund ranking	GET	fund/ranking	metric
DeFi protocol ranking	GET	project/defi/ranking	metric
Project full profile	GET	project/detail	–
Clean a webpage to markdown	GET	web/fetch	url
News feed	GET	news/feed	–
Single news article	GET	news/detail	id

Worked Examples

1. "What's BTC trading at?"

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

Cost: $0.0085. Returns price history; latest point = current price.

2. "Top 10 tokens by DEX volume on Ethereum in the last 24h"

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

Cost: $0.0085. Raw ClickHouse — same query language Surf's own UI uses, at the same flat rate as any other Surf read.

3. "Is this whale wallet labeled? What does it hold?"

// Step 1 — labels (CEX / Whale / Bridge / MEV / Bot / Fund)
blockrun_surf({ path: "wallet/labels/batch", params: { addresses: "0xabc...,0xdef..." } })

// Step 2 — cross-chain holdings + DeFi positions
blockrun_surf({ path: "wallet/detail", params: { address: "0xabc..." } })
blockrun_surf({ path: "wallet/protocols", params: { address: "0xabc..." } })

// Step 3 — net-worth time series
blockrun_surf({ path: "wallet/net-worth", params: { address: "0xabc..." } })

Cost: 4 × $0.0085 = $0.034. Replaces a Nansen subscription for one-off lookups.

4. "What's the market saying about the 2028 election?"

// Compare Polymarket + Kalshi side by side
blockrun_surf({ path: "search/polymarket", params: { q: "2028 US president" } })
blockrun_surf({ path: "search/kalshi",     params: { q: "2028 US president" } })

// Then pull the order book on the leading market
blockrun_surf({ path: "prediction-market/polymarket/prices",
                params: { condition_id: "0x..." } })

5. "Where's mindshare moving for L1s?"

blockrun_surf({ path: "social/mindshare", params: { q: "solana", interval: "1d" } })
blockrun_surf({ path: "social/mindshare", params: { q: "monad",  interval: "1d" } })
blockrun_surf({ path: "social/ranking" })

6. "ETF flows + funding rate + long/short — give me the macro picture"

blockrun_surf({ path: "market/etf",                params: { symbol: "BTC" } })
blockrun_surf({ path: "market/fear-greed" })
blockrun_surf({ path: "exchange/funding-history",  params: { pair: "BTC-USDT" } })
blockrun_surf({ path: "exchange/long-short-ratio", params: { pair: "BTC-USDT" } })

Cost: 4 × $0.0085 = $0.034.

Method Routing — When to Use body

Pass body (POST) only for these three endpoints:

• onchain/query — structured, typed predicates against ClickHouse
• onchain/sql — raw SQL string in { sql: "..." }

Everything else is GET with params.

Python SDK (for non-MCP use)

from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()

# GET — same as blockrun_surf({ path, params })
price = client._get_with_payment_raw("/v1/surf/market/price", {"symbol": "BTC"})

# POST — same as blockrun_surf({ path, body })
result = client._request_with_payment_raw("/v1/surf/onchain/sql", {
    "sql": "SELECT count() FROM ethereum.transactions WHERE block_time > now() - INTERVAL 1 HOUR"
})

Full Endpoint Catalog (83 endpoints, 12 categories)

Exchange (CEX) — 7

exchange/markets · exchange/price · exchange/perp · exchange/depth · exchange/klines · exchange/funding-history · exchange/long-short-ratio

Fund (VC intelligence) — 3

fund/detail · fund/portfolio · fund/ranking

Market — 11

market/ranking · market/fear-greed · market/futures · market/price · market/etf · market/options · market/liquidation/exchange-list · market/liquidation/order · market/liquidation/chart · market/onchain-indicator · market/price-indicator

News — 2

news/feed · news/detail

On-chain — 7

onchain/bridge/ranking · onchain/yield/ranking · onchain/gas-price · onchain/tx · onchain/schema · onchain/query (POST) · onchain/sql (POST)

Prediction Markets — 17

Polymarket: prediction-market/polymarket/ranking · .../trades · .../markets · .../events · .../prices · .../volumes · .../open-interest · .../positions · .../activity · prediction-market/category-metrics Kalshi: prediction-market/kalshi/ranking · .../markets · .../events · .../prices · .../trades · .../volumes · .../open-interest

Project + DeFi — 3

project/detail · project/defi/metrics · project/defi/ranking

Search — 11

search/airdrop · search/events · search/kalshi · search/polymarket · search/web · search/project · search/news · search/wallet · search/fund · search/social/people · search/social/posts

Social — 11

social/detail · social/ranking · social/smart-followers/history · social/mindshare · social/tweets · social/tweet/replies · social/user · social/user/followers · social/user/following · social/user/posts · social/user/replies

Token — 4

token/tokenomics · token/dex-trades · token/holders · token/transfers

Wallet — 6

wallet/detail · wallet/history · wallet/net-worth · wallet/transfers · wallet/protocols · wallet/labels/batch

Web — 1

web/fetch

Gotchas

• Required params: 56 of 83 endpoints require at least one param. The 402 response and the in-tool route surface which fields are missing. Missing params → 400 + no charge.
• Solana wallet works too: blockrun_surf routes through whichever chain the BlockRun wallet is on (Base or Solana). Surf settlement always lands in Surf's Base treasury.
• onchain/sql is powerful but unrestricted: there's no row limit on the server side. Add LIMIT to your query or you'll pay for a megabyte of JSON.
• X-Payment-Receipt header lands on the response with the settlement tx hash — keep it for accounting.

Reference

• Surf marketplace page: https://blockrun.ai/marketplace/surf
• Surf upstream docs: https://docs.asksurf.ai
• Surf publisher: https://asksurf.ai
• BlockRun proxy source: src/lib/surf.ts in the BlockRun web repo