surf-chain

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