@blockrun/mcp 0.22.3 → 0.23.0

package/skills/surf/SKILL.md

@@ -0,0 +1,295 @@
+---
+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 a Surf-1.5 chat answer with citations. 84 endpoints across exchange, on-chain, wallet, social, prediction, news, search, and chat — one API, pay-per-call in USDC via x402. Settles directly to Surf's Base treasury; no Surf account needed.
+triggers:
+  - "surf"
+  - "asksurf"
+  - "surf-1.5"
+  - "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 **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:
+
+```ts
+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
+
+| Tier | Price | Used by |
+|------|-------|---------|
+| 1 | $0.001 | prices, rankings, lists, news, profiles, simple reads (~50 endpoints) |
+| 2 | $0.005 | order books, candles, search, wallet detail, social aggregates (~30 endpoints) |
+| 3 | $0.020 | raw on-chain SQL, structured queries, surf-1.5 chat (3 endpoints) |
+
+Wrong / missing required params return HTTP 400 **without charging** — pre-validation runs before settlement.
+
+## Quick Decision Table — "User asks about X"
+
+| User wants… | Method | Path | Required | Tier |
+|---|---|---|---|---|
+| BTC/ETH price | GET | `market/price` | `symbol` | 1 |
+| ETF flow history | GET | `market/etf` | `symbol` | 1 |
+| Fear & Greed index | GET | `market/fear-greed` | – | 1 |
+| Top 100 tokens by market cap | GET | `market/ranking` | – | 1 |
+| Options skew / IV / volume | GET | `market/options` | `symbol` | 1 |
+| CEX ticker for a pair | GET | `exchange/price` | `pair` | 1 |
+| Perp snapshot (funding + OI) | GET | `exchange/perp` | `pair` | 1 |
+| Order book depth | GET | `exchange/depth` | `pair` | 2 |
+| OHLCV candles | GET | `exchange/klines` | `pair` | 2 |
+| Funding rate history | GET | `exchange/funding-history` | `pair` | 2 |
+| Long/short ratio | GET | `exchange/long-short-ratio` | `pair` | 2 |
+| Bridge protocols by volume | GET | `onchain/bridge/ranking` | – | 1 |
+| Yield pool ranking | GET | `onchain/yield/ranking` | – | 1 |
+| Current gas price (per chain) | GET | `onchain/gas-price` | `chain` | 1 |
+| Transaction details | GET | `onchain/tx` | `hash`, `chain` | 1 |
+| **Raw on-chain SQL** | POST | `onchain/sql` | body: `sql` | 3 |
+| **Structured on-chain query** | POST | `onchain/query` | body: typed predicates | 3 |
+| Inspect ClickHouse schema | GET | `onchain/schema` | – | 3 |
+| Polymarket markets ranking | GET | `prediction-market/polymarket/ranking` | – | 1 |
+| Polymarket price history | GET | `prediction-market/polymarket/prices` | `condition_id` | 1 |
+| Polymarket positions for wallet | GET | `prediction-market/polymarket/positions` | `address` | 2 |
+| Kalshi markets ranking | GET | `prediction-market/kalshi/ranking` | – | 1 |
+| Kalshi market detail | GET | `prediction-market/kalshi/markets` | `market_ticker` | 1 |
+| **Search Polymarket / Kalshi** | GET | `search/polymarket` / `search/kalshi` | – | 2 |
+| Wallet profile (cross-chain) | GET | `wallet/detail` | `address` | 2 |
+| Wallet net-worth time series | GET | `wallet/net-worth` | `address` | 2 |
+| Wallet DeFi positions | GET | `wallet/protocols` | `address` | 2 |
+| **Batch wallet labels (CEX/Whale/MEV…)** | GET | `wallet/labels/batch` | `addresses` | 2 |
+| Token tokenomics + unlocks | GET | `token/tokenomics` | – | 1 |
+| Token holders top N | GET | `token/holders` | `address`, `chain` | 2 |
+| Token transfers | GET | `token/transfers` | `address`, `chain` | 2 |
+| Token DEX trades | GET | `token/dex-trades` | `address` | 2 |
+| Social mindshare time series | GET | `social/mindshare` | `q`, `interval` | 2 |
+| Smart-follower history | GET | `social/smart-followers/history` | – | 2 |
+| Twitter user profile | GET | `social/user` | `handle` | 1 |
+| Twitter user posts | GET | `social/user/posts` | `handle` | 1 |
+| Tweet replies | GET | `social/tweet/replies` | `tweet_id` | 1 |
+| **Web search (crypto-scoped)** | GET | `search/web` | `q` | 2 |
+| News article search | GET | `search/news` | `q` | 2 |
+| KOL / CT people search | GET | `search/social/people` | `q` | 2 |
+| Tweet full-text search | GET | `search/social/posts` | `q` | 2 |
+| Project / token search | GET | `search/project` | `q` | 2 |
+| Wallet search (by ENS, label) | GET | `search/wallet` | `q` | 2 |
+| VC fund portfolio | GET | `fund/portfolio` | – | 1 |
+| VC fund ranking | GET | `fund/ranking` | `metric` | 1 |
+| DeFi protocol ranking | GET | `project/defi/ranking` | `metric` | 1 |
+| Project full profile | GET | `project/detail` | – | 1 |
+| Clean a webpage to markdown | GET | `web/fetch` | `url` | 2 |
+| **Surf-1.5 chat with citations** | POST | `chat/completions` | body: `model`, `messages` | 3 |
+| News feed | GET | `news/feed` | – | 1 |
+| Single news article | GET | `news/detail` | `id` | 1 |
+
+## Worked Examples
+
+### 1. "What's BTC trading at?"
+
+```ts
+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"
+
+```ts
+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?"
+
+```ts
+// 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?"
+
+```ts
+// 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"
+
+```ts
+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?"
+
+```ts
+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"
+
+```ts
+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)
+
+```python
+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