Surf — Crypto Data via BlockRun

Surf (asksurf.ai) aggregates 84 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, unified search, and Surf-1.5 chat with citations.

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: "chat/completions", body: {
  model: "surf/surf-1.5",
  messages: [{ role: "user", content: "What's the Polymarket consensus for the 2028 US election?" }],
}})

Three Pricing Tiers

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

Quick Decision Table — "User asks about X"

Worked Examples

1. "What's BTC trading at?"

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

Cost: $0.001. 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.02. Raw ClickHouse — same query language Surf's own UI uses.

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.005 = $0.02. 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. "Surf-1.5 chat with grounded citations"

blockrun_surf({
  path: "chat/completions",
  body: {
    model: "surf/surf-1.5",
    messages: [
      { role: "user", content: "Summarize ETH's on-chain activity this week. Cite sources." }
    ],
    citation: ["source", "chart"]
  }
})

Cost: $0.02 flat (per-token billing in Phase 2). Returns OpenAI-compatible response + citations.

6. "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" })

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

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

Cost: 2 × $0.001 + 2 × $0.005 = $0.012.

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: "..." }
• chat/completions — OpenAI-compatible chat completion

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 (84 endpoints, 13 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

Chat — 1

chat/completions (POST) — Surf-1.5 with citation: ["source","chart"] support

Gotchas

• Required params: 56 of 84 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.
• `chat/completions` is flat $0.02 in v1 — per-token billing rolls out in Phase 2. For high-volume chat, run cost estimates assuming the flat rate.
• The chat endpoint uses a different upstream base (api.asksurf.ai/v1 instead of /gateway/v1). The BlockRun proxy handles this transparently — you just call chat/completions.
• `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