surf git:20260518.e18d6d7B

Immutable. This exact content is served forever at /api/v1/blob/acd9daae6cec31b1.

---
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 | `ticker` |

(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?"**

```bash
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?"**

```bash
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."**

```bash
# Step 1 — fetch schema (do this once, then cache locally)
curl 'http://127.0.0.1:8402/v1/surf/onchain/schema'

# Step 2 — run the SQL
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?"**

```bash
# Resolve the canonical slug first (search uses q, not query)
curl 'http://127.0.0.1:8402/v1/surf/search/project?q=ethena'

# Then pull mindshare (mindshare uses q + interval)
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.