---
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:**
1. **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.
2. **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"):

1. **Schema first** — `BlockRun({ path: "/v1/surf/onchain/schema", method: "GET" })` ($0.02). Note the tables, columns, types.
2. **Try structured query** — `BlockRun({ path: "/v1/surf/onchain/query", method: "POST", body: { /* typed predicates */ } })` ($0.02) when the shape fits.
3. **Raw SQL fallback** — `BlockRun({ path: "/v1/surf/onchain/sql", method: "POST", body: { query: "SELECT …" } })` ($0.02) for anything else.
4. **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