| name | surf-chain |
| description | On-chain analytics via Surf — raw SQL against 80+ indexed chain tables, structured queries, schema introspection, wallet labels (CEX/Whale/Bridge/MEV…), wallet net worth, transfers, DeFi positions, gas prices, bridge volumes, yield pools. Use when the user wants on-chain forensics, wallet intelligence, holder analysis, transfer tracking, or custom chain queries. |
| triggers | ["on-chain","wallet analysis","wallet detail","wallet history","wallet net worth","token holders","token transfers","gas price","bridge volume","yield pool","label wallet","on-chain sql","chain query"] |
| argument-hint | <address, hash, or question> |
| cost-receipt | true |
You are running inside Franklin on {{wallet_chain}}. Use the BlockRun tool to call Surf's on-chain endpoints. The flagship capability here is on-chain SQL — write a query against 80+ indexed chain tables and get back a result set in sub-second.
Two different "chains" to keep straight:
- Payment chain — where Franklin's wallet signs the x402 USDC payment. Currently
{{wallet_chain}}. Surf only accepts settlement on Base (treasury 0x058a59…). If the user is on Solana, ask them to /chain base before retrying.
- Query chain — the chain the data is about. Passed as a parameter to endpoints like
onchain/gas-price, onchain/tx, token/holders, token/transfers. Valid values include ethereum, base, arbitrum, polygon, optimism, bsc. When the user doesn't specify and they're on base, default to chain: "base". If they ask about Solana on-chain data, note that these EVM-shaped endpoints don't cover Solana — use a Solana-specific tool instead.
How to use
BlockRun({ path: "/v1/surf/<endpoint>", method: "<GET|POST>", params|body: { ... } }). Method is GET unless the catalog says POST.
Endpoint catalog
Direct lookups (Tier 1, $0.001)
| Path | Method | Required | What it returns |
|---|
/v1/surf/onchain/gas-price | GET | chain | Current gas on the named chain |
/v1/surf/onchain/tx | GET | hash, chain | Tx details |
/v1/surf/onchain/bridge/ranking | GET | — | Bridge protocols ranked by volume |
/v1/surf/onchain/yield/ranking | GET | — | Yield pools (lending, LP, staking) |
Raw + structured chain query (Tier 3, $0.02 — premium)
| Path | Method | Required | What it returns |
|---|
/v1/surf/onchain/schema | GET | — | ClickHouse table schema introspection. Always call this FIRST before writing SQL so you know the tables, columns, and types. |
/v1/surf/onchain/query | POST | — (typed body) | Structured chain query with typed predicates. Safer than SQL when the question fits a fixed shape. |
/v1/surf/onchain/sql | POST | body: { query: string } | Raw SQL against 80+ indexed tables. Sub-second. Use for novel questions that the typed query can't express. |
Token analytics (Tier 2, $0.005)
| Path | Method | Required | What it returns |
|---|
/v1/surf/token/holders | GET | address, chain | Top token holders with balances |
/v1/surf/token/transfers | GET | address, chain | Token transfer history |
Wallet intelligence (Tier 2, $0.005)
| Path | Method | Required | What it returns |
|---|
/v1/surf/wallet/detail | GET | address | Aggregated wallet profile across chains |
/v1/surf/wallet/history | GET | address | Transaction history |
/v1/surf/wallet/net-worth | GET | address | Net-worth time series |
/v1/surf/wallet/transfers | GET | address | Transfer history |
/v1/surf/wallet/protocols | GET | address | DeFi positions (Aave, Lido, Uniswap, etc.) |
/v1/surf/wallet/labels/batch | GET | addresses (comma-sep) | Batch label lookup: CEX, Whale, Bridge, MEV, Contract, etc. |
How to choose
- "What's gas on Base?" →
onchain/gas-price with chain: "base" ($0.001). One call, done.
- "Look up this tx" →
onchain/tx with hash + chain.
- "Who owns this token?" →
token/holders ($0.005). Pair with wallet/labels/batch on the top 20 to see which holders are CEXes vs whales.
- "Profile this wallet" →
wallet/detail first ($0.005). If they want depth, follow up with wallet/history, wallet/net-worth, wallet/protocols.
- "Is this address a CEX / whale / MEV bot?" →
wallet/labels/batch — cheapest forensic call.
- "Bridge volume this week" →
onchain/bridge/ranking ($0.001).
- "Best yield on USDC right now" →
onchain/yield/ranking ($0.001), filter for USDC.
On-chain SQL workflow
For novel chain questions (e.g. "all addresses that received >100 ETH from Tornado in 2025"):
- Schema first —
BlockRun({ path: "/v1/surf/onchain/schema", method: "GET" }) ($0.02). Note the tables, columns, types.
- Try structured query —
BlockRun({ path: "/v1/surf/onchain/query", method: "POST", body: { /* typed predicates */ } }) ($0.02) when the shape fits.
- Raw SQL fallback —
BlockRun({ path: "/v1/surf/onchain/sql", method: "POST", body: { query: "SELECT …" } }) ($0.02) for anything else.
- Validate — if SQL fails parse or returns empty unexpectedly, fix the query and re-run. Each retry is $0.02 — be deliberate.
Cost discipline
- Wallet/token reads are $0.005 each. If you need 5 lookups, expect $0.025.
- Tier-3 chain queries are $0.02/call. Plan the schema → query → result loop before firing; don't fire speculative SQL.
- Always include the cost in your summary back to the user.
The user asked
$ARGUMENTS
