PARTNER
Surf
All crypto data, one API, x402-paid in USDC.
Surf (asksurf.ai) aggregates 84+ crypto data endpoints across CEX market data, on-chain SQL, wallet intelligence (100M+ labels), prediction markets, social mindshare, news, and unified search. BlockRun is Surf's x402 payment layer — every call settles directly to Surf's Base treasury, no Surf account or API key required from the caller.
84 endpoints live
From $0.001/call
Direct USDC settlement to Surf
No Surf account needed
Why Agents Reach For It
Crypto data is fragmented across 60+ providers (CoinGecko, Dune, Etherscan, Nansen, …). Surf collapses the most-used reads into one OpenAPI surface so agents skip 60+ integrations.
CEX + DEX Market Data
Live prices, candles, order books, funding rates, perps from 16 CEX. Plus on-chain DEX trades and DEX-aggregated metrics.
On-Chain SQL Access
Direct SQL against 80+ ClickHouse tables (DEX trades, transfers, lending, staking, bridges). Sub-second queries on Ethereum, Base, Arbitrum, BSC, TRON, HyperEVM, Tempo.
100M+ Labeled Wallets
Cross-chain wallet labels (CEX, Whale, Bridge, MEV, Bot, Fund) across 13 networks. Net-worth, DeFi positions, transfer history, batch lookups.
Social + Prediction Markets
Twitter mindshare time series, smart-follower history, CT KOL search. Plus Polymarket + Kalshi events, prices, trades, positions side by side.
Pricing — Three Flat Tiers
Pay only for the endpoint you call. No monthly minimum, no credit packs.
TIER 1
$0.001
per call
Prices, rankings, lists, news, profiles, simple reads.
TIER 2
$0.005
per call
Order books, candles, search, social aggregates, wallet detail.
TIER 3
$0.02
per call
On-chain SQL queries, schema introspection, structured queries.
All Endpoints
84 endpoints across 13 domains. URL pattern: /api/v1/surf/<path>.
Exchange (CEX) (7)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/exchange/markets | $0.001 | Exchange trading pairs catalog. |
| GET | /api/v1/surf/exchange/price | $0.001 | CEX ticker price for a trading pair. |
| GET | /api/v1/surf/exchange/perp | $0.001 | Perpetual contract snapshot. |
| GET | /api/v1/surf/exchange/depth | $0.005 | Exchange order book depth. |
| GET | /api/v1/surf/exchange/klines | $0.005 | OHLCV candlesticks for a CEX pair. |
| GET | /api/v1/surf/exchange/funding-history | $0.005 | Funding rate history for a perp contract. |
| GET | /api/v1/surf/exchange/long-short-ratio | $0.005 | Long/short ratio history. |
VC Fund Intelligence (3)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/fund/detail | $0.001 | VC fund profile detail. |
| GET | /api/v1/surf/fund/portfolio | $0.001 | VC fund portfolio holdings. |
| GET | /api/v1/surf/fund/ranking | $0.001 | Top VC funds ranking. |
Market Overview (11)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/market/ranking | $0.001 | Token rankings (market cap, volume, change). |
| GET | /api/v1/surf/market/fear-greed | $0.001 | Fear & Greed index history. |
| GET | /api/v1/surf/market/futures | $0.001 | Futures market overview. |
| GET | /api/v1/surf/market/price | $0.001 | Token price history. |
| GET | /api/v1/surf/market/etf | $0.001 | ETF flow history (BTC/ETH spot ETFs). |
| GET | /api/v1/surf/market/options | $0.001 | Options market data (skew, IV, volume). |
| GET | /api/v1/surf/market/liquidation/exchange-list | $0.005 | Liquidations broken out by exchange. |
| GET | /api/v1/surf/market/liquidation/order | $0.005 | Large liquidation orders (whale liquidations). |
| GET | /api/v1/surf/market/liquidation/chart | $0.005 | Liquidation chart over time. |
| GET | /api/v1/surf/market/onchain-indicator | $0.005 | On-chain indicators (NUPL, SOPR, MVRV, Puell, NVT). |
| GET | /api/v1/surf/market/price-indicator | $0.005 | Technical indicators (RSI, MACD, Bollinger, EMA). |
News (2)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/news/feed | $0.001 | AI-curated crypto news feed. |
| GET | /api/v1/surf/news/detail | $0.001 | Full article detail by ID. |
On-Chain (SQL + Reads) (7)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/onchain/bridge/ranking | $0.001 | Bridge protocol ranking by volume. |
| GET | /api/v1/surf/onchain/yield/ranking | $0.001 | Yield pool ranking (lending, LP, staking). |
| GET | /api/v1/surf/onchain/gas-price | $0.001 | Current gas price across supported chains. |
| GET | /api/v1/surf/onchain/tx | $0.001 | Transaction details by hash. |
| GET | /api/v1/surf/onchain/schema | $0.020 | On-chain ClickHouse table schema introspection. |
| POST | /api/v1/surf/onchain/query | $0.020 | Structured on-chain blockchain query (typed predicates). |
| POST | /api/v1/surf/onchain/sql | $0.020 | Raw SQL query against 80+ ClickHouse tables (sub-second). |
Prediction Markets (Polymarket + Kalshi) (17)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/prediction-market/category-metrics | $0.001 | Prediction-market category metrics. |
| GET | /api/v1/surf/prediction-market/polymarket/ranking | $0.001 | Polymarket market ranking. |
| GET | /api/v1/surf/prediction-market/polymarket/trades | $0.001 | Polymarket trades history. |
| GET | /api/v1/surf/prediction-market/polymarket/markets | $0.001 | Polymarket market detail (requires market_slug). |
| GET | /api/v1/surf/prediction-market/polymarket/events | $0.001 | Polymarket event detail (requires event_slug). |
| GET | /api/v1/surf/prediction-market/polymarket/prices | $0.001 | Polymarket price history for one market. |
| GET | /api/v1/surf/prediction-market/polymarket/volumes | $0.001 | Polymarket volume history for one market. |
| GET | /api/v1/surf/prediction-market/polymarket/open-interest | $0.001 | Polymarket open-interest history for one market. |
| GET | /api/v1/surf/prediction-market/polymarket/positions | $0.005 | Polymarket positions for a wallet. |
| GET | /api/v1/surf/prediction-market/polymarket/activity | $0.005 | Polymarket wallet activity (merges/splits/redeems). |
| GET | /api/v1/surf/prediction-market/kalshi/ranking | $0.001 | Kalshi market ranking. |
| GET | /api/v1/surf/prediction-market/kalshi/markets | $0.001 | Kalshi market detail. |
| GET | /api/v1/surf/prediction-market/kalshi/events | $0.001 | Kalshi event detail. |
| GET | /api/v1/surf/prediction-market/kalshi/prices | $0.001 | Kalshi price history for one market. |
| GET | /api/v1/surf/prediction-market/kalshi/trades | $0.001 | Kalshi trades history for one market. |
| GET | /api/v1/surf/prediction-market/kalshi/volumes | $0.001 | Kalshi volume history for one market. |
| GET | /api/v1/surf/prediction-market/kalshi/open-interest | $0.001 | Kalshi open-interest history for one market. |
Project + DeFi Protocols (3)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/project/detail | $0.001 | Aggregated project profile (token + DeFi + social). |
| GET | /api/v1/surf/project/defi/metrics | $0.001 | Per-protocol DeFi metrics (TVL, fees, revenue). |
| GET | /api/v1/surf/project/defi/ranking | $0.001 | DeFi protocol ranking. |
Unified Search (11)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/search/airdrop | $0.005 | Airdrop opportunity search. |
| GET | /api/v1/surf/search/events | $0.005 | Project event search. |
| GET | /api/v1/surf/search/kalshi | $0.005 | Kalshi event search. |
| GET | /api/v1/surf/search/polymarket | $0.005 | Polymarket event search. |
| GET | /api/v1/surf/search/web | $0.005 | Web search across crypto sources. |
| GET | /api/v1/surf/search/project | $0.005 | Project search by name, ticker, or description. |
| GET | /api/v1/surf/search/news | $0.005 | News article search. |
| GET | /api/v1/surf/search/wallet | $0.005 | Wallet search by address, ENS, or label. |
| GET | /api/v1/surf/search/fund | $0.005 | VC fund search. |
| GET | /api/v1/surf/search/social/people | $0.005 | Social user (CT KOL) search. |
| GET | /api/v1/surf/search/social/posts | $0.005 | Social post (tweet) full-text search. |
Social / CT Intelligence (11)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/social/detail | $0.005 | Aggregated social analytics for a project. |
| GET | /api/v1/surf/social/ranking | $0.005 | Social mindshare ranking. |
| GET | /api/v1/surf/social/smart-followers/history | $0.005 | Smart-follower count history (high-signal accounts). |
| GET | /api/v1/surf/social/mindshare | $0.005 | Project mindshare time series. |
| GET | /api/v1/surf/social/tweets | $0.001 | Fetch social posts by IDs. |
| GET | /api/v1/surf/social/tweet/replies | $0.001 | Replies to a specific tweet. |
| GET | /api/v1/surf/social/user | $0.001 | Social user (Twitter) profile. |
| GET | /api/v1/surf/social/user/followers | $0.001 | User followers list. |
| GET | /api/v1/surf/social/user/following | $0.001 | User following list. |
| GET | /api/v1/surf/social/user/posts | $0.001 | User social posts. |
| GET | /api/v1/surf/social/user/replies | $0.001 | User replies. |
Token Analytics (4)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/token/tokenomics | $0.001 | Token unlock schedule + vesting. |
| GET | /api/v1/surf/token/dex-trades | $0.005 | Token DEX trade history. |
| GET | /api/v1/surf/token/holders | $0.005 | Top token holders with balances. |
| GET | /api/v1/surf/token/transfers | $0.005 | Token transfer history. |
Wallet Intelligence (6)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/wallet/detail | $0.005 | Aggregated wallet profile across chains. |
| GET | /api/v1/surf/wallet/history | $0.005 | Wallet transaction history. |
| GET | /api/v1/surf/wallet/net-worth | $0.005 | Wallet net-worth time series. |
| GET | /api/v1/surf/wallet/transfers | $0.005 | Wallet transfer history. |
| GET | /api/v1/surf/wallet/protocols | $0.005 | Wallet DeFi protocol positions (Aave, Lido, Uni…). |
| GET | /api/v1/surf/wallet/labels/batch | $0.005 | Batch wallet label lookup (CEX, Whale, Bridge, MEV…). |
Web (1)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| GET | /api/v1/surf/web/fetch | $0.005 | Fetch + clean a web page into markdown. |
chat (1)
| Method | Endpoint | Price | Purpose |
|---|---|---|---|
| POST | /api/v1/surf/chat/completions | $0.020 | OpenAI-compatible chat with surf-1.5. Supports `citation: ['source','chart']` for grounded answers. Flat $0.02/call in v1; per-token billing coming. |
Quick Start
Below: a $0.001 BTC price read. Same pattern works for any of the 84 endpoints — change the path and parameters.
# 1. Trigger 402 to learn pricing
curl "https://blockrun.ai/api/v1/surf/market/price?symbol=BTC"
# → HTTP 402 payment-required: eyJ4NDAy...
# 2. Sign EIP-3009 USDC transfer, then replay with X-Payment header
curl "https://blockrun.ai/api/v1/surf/market/price?symbol=BTC" \
-H "X-Payment: <signed-x402>"
# Response: token price history payload from Surf.
# Settlement: 0.001 USDC → Surf treasury on Base.USE FROM CLAUDE / CURSOR
Install the BlockRun MCP server once and the blockrun_surf tool exposes all 84 endpoints as typed actions to Claude Code, Cursor, ChatGPT Desktop. Run claude mcp add blockrun --transport http https://mcp.blockrun.ai/mcp.
Behind the Scenes
Surf (asksurf.ai)
Surf runs the data pipelines and ClickHouse warehouse. BlockRun is the x402 payment layer — we hold the Surf API key, route requests upstream, and x402 settles each call directly to Surf's Base treasury wallet. Your wallet, our key, their data, their revenue.
asksurf.aiGet Started
Fund a wallet with USDC on Base or Solana. Hit any Surf endpoint, attach payment, done.