@blockrun/franklin 3.18.0 → 3.19.0

package/dist/agent/context.js

@@ -296,6 +296,22 @@ On-chain affiliate (20 bps in sell-token, force-set server-side) flows to BlockR
 - \`/v1/modal/{...path}\` — Modal GPU sandbox passthrough (create/exec/etc.).
 - \`/v1/pm/{...path}\` — prediction-market data passthrough.
 
+**Surf — crypto data + chat (x402-paid)** via the generic \`BlockRun\` capability. ~55 curated endpoints. Tier-1 $0.001, Tier-2 $0.005, Tier-3 / chat $0.02.
+- \`/v1/surf/exchange/*\` — CEX trading pairs, prices, perps, depth, klines, funding history, long/short ratio.
+- \`/v1/surf/market/*\` — token rankings, fear/greed, futures, ETF flows, options skew, liquidations, on-chain indicators (NUPL/SOPR/MVRV), price indicators (RSI/MACD/BBANDS).
+- \`/v1/surf/news/{feed,detail}\` — AI-curated crypto news.
+- \`/v1/surf/onchain/{bridge,yield,gas-price,tx,schema,query,sql}\` — bridge/yield rankings, gas, tx detail, **raw SQL against 80+ indexed chain tables (Tier-3, $0.02)**, structured chain query, schema introspection.
+- \`/v1/surf/token/{tokenomics,dex-trades,holders,transfers}\` — token analytics.
+- \`/v1/surf/wallet/{detail,history,net-worth,transfers,protocols,labels/batch}\` — wallet intelligence + batch labels (CEX/Whale/Bridge/MEV).
+- \`/v1/surf/social/*\` — KOL/CT mindshare, smart-follower history, tweets, user profiles. The canonical source for crypto-Twitter signal.
+- \`/v1/surf/fund/{detail,portfolio,ranking}\` — VC fund profiles, portfolios, ranking.
+- \`/v1/surf/project/{detail,defi/metrics,defi/ranking}\` — project profiles + DeFi protocol metrics.
+- \`/v1/surf/chat/completions\` — surf-1.5 chat model with first-class citations (\`citation: ["source","chart"]\`). \$0.02/call flat.
+
+For Surf workflows, prefer the bundled skills (\`/surf-market\`, \`/surf-chain\`, \`/surf-social\`, \`/surf-chat\`) — they document which endpoint to pick for which question and the cost trade-off. Skipped (use the dedicated tools instead): \`/v1/surf/prediction-market/*\` (use \`PredictionMarket\`), \`/v1/surf/search/*\` (use \`ExaSearch\`), \`/v1/surf/web/*\` (use \`BrowserX\`).
+
+**Generic gateway primitive**: \`BlockRun({ path, method, params, body })\` is a single capability that signs x402 and forwards to ANY path under \`/api\`. Use it for Surf endpoints (above) and any future BlockRun partner that doesn't have a dedicated capability yet. Always specify the exact path; the primitive will not guess.
+
 **Endpoints that DO NOT exist** (common hallucinations — do NOT call):
 - \`/v1/image/generate\` (singular — use \`/v1/images/generations\`)
 - \`/v1/spending\` (no such route — derive from on-chain history if needed)

package/dist/skills-bundled/surf-chain/SKILL.md

@@ -0,0 +1,92 @@
+---
+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

package/dist/skills-bundled/surf-chat/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: surf-chat
+description: Crypto-native chat with citations via the surf-1.5 model. Different from a generic LLM call — surf-1.5 is grounded in live crypto data and returns first-class citations (source links + charts). Use when the user wants research-shaped answers about projects, tokens, market events, or DeFi protocols, with sources attached.
+triggers:
+  - "surf chat"
+  - "crypto research"
+  - "ask surf"
+  - "with citations"
+  - "grounded answer"
+argument-hint: <research question>
+cost-receipt: true
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. The `surf-1.5` model is crypto-native: it knows current market data, projects, on-chain flow, social signal, and returns structured citations. Reach for it when the user wants a sourced answer rather than a vibes-based one.
+
+**Chain note:** Surf currently settles x402 payments on **Base** only. If the user's active chain is `solana`, ask them to `/chain base` before calling — surf-1.5 is $0.02/call, so a failed payment retry isn't free.
+
+## How to use
+
+Call:
+
+```
+BlockRun({
+  path: "/v1/surf/chat/completions",
+  method: "POST",
+  body: {
+    model: "surf-1.5",
+    messages: [
+      { role: "user", content: "<the question>" }
+    ],
+    citation: ["source", "chart"]
+  }
+})
+```
+
+Cost: **flat $0.02 per call** (per-token billing is Phase 2 upstream).
+
+### Response shape
+
+OpenAI-compatible, with two extras:
+- `choices[0].message.content` — the text answer
+- `choices[0].message.citations[]` — array of `{ type: "source" | "chart", url, title }`
+
+When you report back to the user, **always include the citations** as a footer:
+
+```
+[Answer text]
+
+Sources:
+1. <title> — <url>
+2. <title> — <url>
+```
+
+If `citations` is empty, mention that the answer is ungrounded.
+
+### Multi-turn
+
+Pass previous `messages` back in for follow-up turns. Each turn is $0.02.
+
+## When to use surf-chat vs the main agent loop
+
+- **Use surf-chat** when: the question is about market state, project research, narrative tracking, or "what happened to X in the last week" — anywhere fresh crypto context matters and you want citations to share with the user.
+- **Use the main agent loop** (no surf-chat) when: the question is general reasoning, coding, planning, summarization of content already in scope, or anything where adding citations doesn't add value.
+
+The wallet is funding the surf-chat call directly — be deliberate about reaching for it.
+
+## When to use surf-chat vs the data endpoints
+
+- **surf-chat** is good when you don't know which endpoints to compose, or when the answer is qualitative ("what's the bull case for $X?").
+- The **`/surf-market` / `/surf-chain` / `/surf-social` skills** are better when the question is structured ("price of BTC", "RSI on ETH", "wallet net worth") — they're $0.001–$0.005 each and you keep full control of the data.
+
+If you can answer with one $0.001 call to a data endpoint, do that. Only escalate to surf-chat when the question needs synthesis across many endpoints or the user explicitly asks for cited research.
+
+## The user asked
+
+$ARGUMENTS

package/dist/skills-bundled/surf-market/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: surf-market
+description: Crypto market data via Surf — prices, futures, ETFs, options, fear/greed, technical and on-chain indicators, token DEX flows, news, project profiles, VC fund holdings. Use when the user asks about market conditions, ranking tokens, futures positioning, technical signals, options skew, news context, or VC/fund intelligence.
+triggers:
+  - "market overview"
+  - "fear greed"
+  - "futures"
+  - "etf flow"
+  - "options skew"
+  - "tokenomics"
+  - "rsi"
+  - "macd"
+  - "liquidations"
+  - "vc fund"
+  - "token ranking"
+argument-hint: <symbol or question>
+cost-receipt: true
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. Crypto market data lives behind the `BlockRun` tool, which signs USDC x402 payments from the user's wallet on every call. Pick the cheapest endpoint that answers the question.
+
+**Chain note:** Surf currently settles x402 payments on **Base** only (treasury is `0x058a59…` on Base). If the user's active chain is `solana` and you hit a payment error, tell them to switch with `/chain base` before retrying — the request itself works, the wallet just needs to be on Base to sign the payment.
+
+## How to use
+
+Call `BlockRun({ path: "/v1/surf/<endpoint>", method: "GET", params: { ... } })`. All endpoints below are GET unless noted. Required params must be supplied or you'll get a 400 (no charge).
+
+## Endpoint catalog
+
+### Exchange (CEX intelligence)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/exchange/markets` | $0.001 | — | Trading pairs catalog across major CEXes |
+| `/v1/surf/exchange/price` | $0.001 | `pair` | Ticker price for a pair |
+| `/v1/surf/exchange/perp` | $0.001 | `pair` | Perpetual contract snapshot |
+| `/v1/surf/exchange/depth` | $0.005 | `pair` | Order book depth |
+| `/v1/surf/exchange/klines` | $0.005 | `pair` | OHLCV candlesticks |
+| `/v1/surf/exchange/funding-history` | $0.005 | `pair` | Perp funding rate history |
+| `/v1/surf/exchange/long-short-ratio` | $0.005 | `pair` | Long/short positioning |
+
+### Market (broad-market intelligence)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/market/ranking` | $0.001 | — | Token ranking (market cap, volume, change) |
+| `/v1/surf/market/fear-greed` | $0.001 | — | Fear & Greed index history |
+| `/v1/surf/market/futures` | $0.001 | — | Futures market overview |
+| `/v1/surf/market/price` | $0.001 | `symbol` | Token price history |
+| `/v1/surf/market/etf` | $0.001 | `symbol` | Spot ETF flow history (BTC, ETH) |
+| `/v1/surf/market/options` | $0.001 | `symbol` | Options skew / IV / volume |
+| `/v1/surf/market/liquidation/exchange-list` | $0.005 | — | Liquidations by exchange |
+| `/v1/surf/market/liquidation/order` | $0.005 | — | Large liquidation orders |
+| `/v1/surf/market/liquidation/chart` | $0.005 | `symbol` | Liquidation chart over time |
+| `/v1/surf/market/onchain-indicator` | $0.005 | `symbol`, `metric` | NUPL, SOPR, MVRV, Puell, NVT |
+| `/v1/surf/market/price-indicator` | $0.005 | `indicator`, `symbol` | RSI, MACD, Bollinger, EMA |
+
+### News
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/news/feed` | $0.001 | — | AI-curated crypto news feed |
+| `/v1/surf/news/detail` | $0.001 | `id` | Full article by ID |
+
+### Project (DeFi protocols + project profiles)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/project/detail` | $0.001 | — | Aggregated project profile (token + DeFi + social) |
+| `/v1/surf/project/defi/metrics` | $0.001 | `metric` | Per-protocol DeFi metrics (TVL, fees, revenue) |
+| `/v1/surf/project/defi/ranking` | $0.001 | `metric` | DeFi protocol ranking |
+
+### Token (on-chain analytics)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/token/tokenomics` | $0.001 | — | Unlock schedule + vesting |
+| `/v1/surf/token/dex-trades` | $0.005 | `address` | DEX trade history |
+
+### Fund (VC + treasury intelligence)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/fund/detail` | $0.001 | — | VC fund profile |
+| `/v1/surf/fund/portfolio` | $0.001 | — | VC fund portfolio holdings |
+| `/v1/surf/fund/ranking` | $0.001 | `metric` | Top VC funds ranking |
+
+## How to choose
+
+- **"How's the market?"** → `market/fear-greed` + `market/ranking` (both $0.001). Cheap snapshot.
+- **"What's BTC doing?"** → `market/price` for history, `exchange/price` for spot tick, `market/etf` for institutional flow.
+- **"Show me liquidations."** → `market/liquidation/chart` for time series, `market/liquidation/order` for whale events.
+- **"Technical signal on ETH"** → `market/price-indicator` with `indicator: "RSI"` (or MACD, BBANDS, EMA).
+- **"On-chain health"** → `market/onchain-indicator` with `metric: "NUPL"` etc.
+- **"Who holds this token / where is it traded?"** → `token/tokenomics` for supply schedule, `token/dex-trades` for flow.
+- **"What VCs back this project?"** → `fund/portfolio` (filter by project).
+
+## Cost discipline
+
+- Most read endpoints are Tier 1 ($0.001). Burn freely.
+- Tier 2 ($0.005) endpoints carry depth, history, or fraud-signal data — use when the cheaper endpoint can't answer.
+- Avoid speculative multi-endpoint scans. Pick the right endpoint for the question; if unsure, ask the user one clarifying question first.
+- Report the cost on every call in your summary: "Pulled fear/greed history ($0.001). Index sits at 62 (greed)."
+
+## The user asked
+
+$ARGUMENTS

package/dist/skills-bundled/surf-social/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: surf-social
+description: Crypto-Twitter / KOL intelligence via Surf — project mindshare time series, smart-follower history (high-signal accounts), social ranking, tweet + replies fetch, user profile / followers / posts / replies. Use when the user asks about KOL sentiment, project attention, smart money commentary, narrative momentum, or specific Twitter handles.
+triggers:
+  - "kol sentiment"
+  - "mindshare"
+  - "smart followers"
+  - "crypto twitter"
+  - "ct sentiment"
+  - "twitter analysis"
+  - "social ranking"
+  - "tweet"
+  - "twitter handle"
+argument-hint: <project, handle, or question>
+cost-receipt: true
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. Use the `BlockRun` tool to call Surf's social endpoints. This is the canonical source for crypto-Twitter signal — mindshare scoring, KOL identification, and reply-graph analysis.
+
+**Chain note:** Surf currently settles x402 payments on **Base** only. If the user's active chain is `solana` and you hit a payment error, ask them to `/chain base` before retrying. The social data itself is chain-agnostic.
+
+## How to use
+
+`BlockRun({ path: "/v1/surf/<endpoint>", method: "GET", params: { ... } })`. All endpoints below are GET.
+
+## Endpoint catalog
+
+### Project-level signal (Tier 2, $0.005)
+| Path | Required params | What it returns |
+|---|---|---|
+| `/v1/surf/social/detail` | — | Aggregated social analytics for a project |
+| `/v1/surf/social/ranking` | — | Mindshare ranking across projects |
+| `/v1/surf/social/smart-followers/history` | — | Smart-follower count history (high-signal accounts only) |
+| `/v1/surf/social/mindshare` | `q`, `interval` | Mindshare time series for a project (`q` = ticker or name, `interval` = `1d` / `7d` / `30d`) |
+
+### Tweet-level (Tier 1, $0.001)
+| Path | Required params | What it returns |
+|---|---|---|
+| `/v1/surf/social/tweets` | `ids` (comma-sep) | Fetch tweets by ID |
+| `/v1/surf/social/tweet/replies` | `tweet_id` | Replies to a specific tweet |
+
+### User-level (Tier 1, $0.001)
+| Path | Required params | What it returns |
+|---|---|---|
+| `/v1/surf/social/user` | `handle` | Twitter user profile |
+| `/v1/surf/social/user/followers` | `handle` | Followers list |
+| `/v1/surf/social/user/following` | `handle` | Following list |
+| `/v1/surf/social/user/posts` | `handle` | User posts |
+| `/v1/surf/social/user/replies` | `handle` | User replies |
+
+## How to choose
+
+- **"What's the market saying about $X?"** → `social/mindshare` with `q: "X", interval: "7d"` ($0.005). Read the trend, not the absolute number.
+- **"Who's the smart money following $X?"** → `social/smart-followers/history` ($0.005). Compare growth rate to baseline.
+- **"Top projects by attention right now"** → `social/ranking` ($0.005).
+- **"Is @handle a real player?"** → `social/user` then `social/user/followers` (look at follower-to-following ratio + which smart accounts follow them).
+- **"What did @handle say recently?"** → `social/user/posts` ($0.001 each).
+- **"Show me the reply storm under tweet X"** → `social/tweet/replies` ($0.001).
+
+## When NOT to use this skill
+
+- Generic Twitter scraping or non-crypto sentiment → use `BrowserX` or a web search tool. Surf is curated for crypto-relevant accounts.
+- Real-time tweet streaming → not supported; this is historical / batch reads.
+
+## Cost discipline
+
+- User-level reads are cheap ($0.001). Free to fan out across 5–10 handles when profiling.
+- Project-level signal is $0.005/call. One mindshare + one smart-followers call is usually enough to answer "is this thing real?".
+- Always include the cost in your summary.
+
+## The user asked
+
+$ARGUMENTS

package/dist/tools/blockrun.d.ts

@@ -0,0 +1,21 @@
+/**
+ * BlockRun primitive — the generic x402-paid gateway capability.
+ *
+ * One tool, every BlockRun endpoint. Replaces the per-API hardcoded pattern
+ * (ImageGen, VideoGen, Phone tools, etc) for new integrations. Skills in
+ * src/skills-bundled/<name>/SKILL.md describe which paths to call for which
+ * user intents; this tool just signs the x402 payment and forwards.
+ *
+ * Why the indirection: BlockRun keeps shipping new partner APIs (Surf,
+ * Phone & Voice, future ML/data partners). Hardcoding each as a fresh
+ * CapabilityHandler means a Franklin npm release per partner and a bigger
+ * tool list for the LLM to reason about. This primitive plus markdown
+ * skill files decouples API expansion from agent releases — new partners
+ * ship as a new SKILL.md, no code change.
+ *
+ * Signing pattern mirrors src/tools/modal.ts and src/phone/client.ts; we
+ * deliberately keep the copy-paste rather than refactor those into a
+ * shared module (out of scope; would touch unrelated tools).
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const blockrunCapability: CapabilityHandler;

package/dist/tools/blockrun.js

@@ -0,0 +1,257 @@
+/**
+ * BlockRun primitive — the generic x402-paid gateway capability.
+ *
+ * One tool, every BlockRun endpoint. Replaces the per-API hardcoded pattern
+ * (ImageGen, VideoGen, Phone tools, etc) for new integrations. Skills in
+ * src/skills-bundled/<name>/SKILL.md describe which paths to call for which
+ * user intents; this tool just signs the x402 payment and forwards.
+ *
+ * Why the indirection: BlockRun keeps shipping new partner APIs (Surf,
+ * Phone & Voice, future ML/data partners). Hardcoding each as a fresh
+ * CapabilityHandler means a Franklin npm release per partner and a bigger
+ * tool list for the LLM to reason about. This primitive plus markdown
+ * skill files decouples API expansion from agent releases — new partners
+ * ship as a new SKILL.md, no code change.
+ *
+ * Signing pattern mirrors src/tools/modal.ts and src/phone/client.ts; we
+ * deliberately keep the copy-paste rather than refactor those into a
+ * shared module (out of scope; would touch unrelated tools).
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, USER_AGENT } from '../config.js';
+import { recordUsage } from '../stats/tracker.js';
+import { logger } from '../logger.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 120_000;
+// ─── x402 payment signing (same shape as modal.ts / phone/client.ts) ──────
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.clone().json());
+            if (body.x402 || body.accepts)
+                header = btoa(JSON.stringify(body));
+        }
+        catch { /* not JSON, no header */ }
+    }
+    return header;
+}
+async function signPayment(response, chain, endpoint, resourceDescription) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+            const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+            const feePayer = details.extra?.feePayer || details.recipient;
+            const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || resourceDescription,
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return {
+                headers: { 'PAYMENT-SIGNATURE': payload },
+                amountUsd: Number(details.amount) / 1_000_000,
+            };
+        }
+        else {
+            const wallet = getOrCreateWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired);
+            const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || resourceDescription,
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+                extra: details.extra,
+            });
+            return {
+                headers: { 'PAYMENT-SIGNATURE': payload },
+                amountUsd: Number(details.amount) / 1_000_000,
+            };
+        }
+    }
+    catch (err) {
+        logger.warn(`[franklin] BlockRun payment error: ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Pull the settlement tx hash from the gateway's X-Payment-Receipt
+ * header. The X-Payment-Response header doesn't carry the amount (only
+ * { success, transaction, network, payer }), so we don't parse it here
+ * — the amount comes from what signPayment authorized in the 402 retry.
+ */
+function extractTxHash(response) {
+    return response.headers.get('x-payment-receipt');
+}
+async function callGateway(url, method, body, resourceDescription, abortSignal, timeoutMs) {
+    const start = Date.now();
+    const chain = loadChain();
+    const headers = {
+        'Accept': 'application/json',
+        'User-Agent': USER_AGENT,
+    };
+    if (method === 'POST')
+        headers['Content-Type'] = 'application/json';
+    const ctrl = new AbortController();
+    const onParentAbort = () => ctrl.abort();
+    abortSignal.addEventListener('abort', onParentAbort, { once: true });
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const payload = method === 'POST' && body !== undefined ? JSON.stringify(body) : undefined;
+        let response = await fetch(url, { method, signal: ctrl.signal, headers, body: payload });
+        let paidUsd = 0;
+        if (response.status === 402) {
+            const signed = await signPayment(response, chain, url, resourceDescription);
+            if (!signed) {
+                return {
+                    ok: false, status: 402,
+                    body: { error: 'payment signing failed' }, raw: '',
+                    paidUsd: 0, txHash: null, latencyMs: Date.now() - start,
+                };
+            }
+            paidUsd = signed.amountUsd;
+            response = await fetch(url, {
+                method, signal: ctrl.signal,
+                headers: { ...headers, ...signed.headers },
+                body: payload,
+            });
+        }
+        const txHash = extractTxHash(response);
+        // If the gateway returned 4xx after we signed, settlement was skipped
+        // server-side (per the route's "Payment was NOT charged" pattern). Don't
+        // claim a paid amount the wallet didn't actually spend.
+        if (!response.ok)
+            paidUsd = 0;
+        const raw = await response.text().catch(() => '');
+        let parsed = {};
+        try {
+            parsed = raw ? JSON.parse(raw) : {};
+        }
+        catch { /* leave as {} */ }
+        return {
+            ok: response.ok, status: response.status, body: parsed, raw,
+            paidUsd, txHash, latencyMs: Date.now() - start,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        abortSignal.removeEventListener('abort', onParentAbort);
+    }
+}
+function buildUrl(path, params) {
+    const chain = loadChain();
+    const base = API_URLS[chain]; // ends in /api
+    const clean = path.startsWith('/') ? path : `/${path}`;
+    const url = `${base}${clean}`;
+    if (!params || Object.keys(params).length === 0)
+        return url;
+    const usp = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                usp.append(key, String(v));
+        }
+        else {
+            usp.append(key, String(value));
+        }
+    }
+    const qs = usp.toString();
+    return qs ? `${url}?${qs}` : url;
+}
+function fmtUsd(n) {
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    return `$${n.toFixed(2)}`;
+}
+export const blockrunCapability = {
+    spec: {
+        name: 'BlockRun',
+        description: 'Call any BlockRun gateway endpoint. Signs an x402 USDC payment from the user wallet, retries on HTTP 402, and returns the response. ' +
+            'Use this for crypto data (Surf — markets, on-chain, social, chat), AI inference (chat / image / video / music), phone numbers and voice calls, ' +
+            'prediction markets, DeFi data, and any other API exposed under https://blockrun.ai/marketplace. ' +
+            'The path must start with "/v1/" or "/.well-known/". ' +
+            'Bundled skills like /surf-market, /surf-chain, /surf-social, /surf-chat document which endpoints to call for common workflows — read those when you are unsure which path serves the user\'s question. ' +
+            'Cost is wallet-charged automatically; the response includes the actual USD paid.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'API path under /api, starting with "/v1/" or "/.well-known/". E.g. "/v1/surf/market/fear-greed", "/v1/phone/numbers/list", "/v1/chat/completions".',
+                },
+                method: {
+                    type: 'string',
+                    enum: ['GET', 'POST'],
+                    description: 'HTTP method. Default: POST if `body` is provided, otherwise GET.',
+                },
+                params: {
+                    type: 'object',
+                    description: 'Query-string parameters. Use for GETs. E.g. { symbol: "BTC" }.',
+                },
+                body: {
+                    type: 'object',
+                    description: 'JSON body. Use for POSTs. E.g. { model: "surf-1.5", messages: [...] }.',
+                },
+                timeoutMs: {
+                    type: 'number',
+                    description: `Optional client-side timeout in ms. Default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS}.`,
+                },
+            },
+            required: ['path'],
+        },
+    },
+    concurrent: true,
+    async execute(input, ctx) {
+        const raw = input;
+        const path = typeof raw.path === 'string' ? raw.path.trim() : '';
+        if (!path) {
+            return { output: 'Error: `path` is required (e.g. "/v1/surf/market/fear-greed").', isError: true };
+        }
+        if (!/^\/(v1|\.well-known)\//.test(path)) {
+            return {
+                output: `Error: path must start with "/v1/" or "/.well-known/". Got: ${path}`,
+                isError: true,
+            };
+        }
+        const params = (raw.params && typeof raw.params === 'object') ? raw.params : undefined;
+        const body = (raw.body && typeof raw.body === 'object') ? raw.body : undefined;
+        // Method resolution: explicit > inferred from body > default GET
+        const explicitMethod = typeof raw.method === 'string' ? raw.method.toUpperCase() : '';
+        const method = explicitMethod === 'POST' || explicitMethod === 'GET'
+            ? explicitMethod
+            : (body ? 'POST' : 'GET');
+        const timeoutMs = Math.min(Math.max(1_000, typeof raw.timeoutMs === 'number' ? raw.timeoutMs : DEFAULT_TIMEOUT_MS), MAX_TIMEOUT_MS);
+        const url = buildUrl(path, method === 'GET' ? params : undefined);
+        const resourceDescription = `BlockRun ${method} ${path}`;
+        const result = await callGateway(url, method, method === 'POST' ? body : undefined, resourceDescription, ctx.abortSignal, timeoutMs);
+        // Telemetry — show in the panel Audit tab regardless of success
+        try {
+            recordUsage(`BlockRun:${path}`, 0, 0, result.paidUsd, result.latencyMs);
+        }
+        catch { /* best-effort */ }
+        if (!result.ok) {
+            const detail = typeof result.body?.error === 'string'
+                ? result.body.error
+                : `HTTP ${result.status}`;
+            const fullOutput = result.raw || JSON.stringify(result.body, null, 2);
+            return {
+                output: `BlockRun ${method} ${path} failed: ${detail} (status ${result.status}). No charge if status is 4xx pre-payment.`,
+                fullOutput,
+                isError: true,
+            };
+        }
+        const head = `BlockRun ${method} ${path} → ${fmtUsd(result.paidUsd)}${result.txHash ? ` · tx ${result.txHash.slice(0, 10)}…` : ''} · ${result.latencyMs}ms`;
+        const payload = typeof result.body === 'object' ? JSON.stringify(result.body, null, 2) : String(result.body);
+        return {
+            output: `${head}\n${payload}`,
+            fullOutput: `${head}\n${payload}`,
+        };
+    },
+};

package/dist/tools/index.js

@@ -32,6 +32,7 @@ import { base0xGaslessSwapCapability } from './zerox-gasless.js';
 import { defiLlamaProtocolsCapability, defiLlamaProtocolCapability, defiLlamaChainsCapability, defiLlamaYieldsCapability, defiLlamaPriceCapability, } from './defillama.js';
 import { predictionMarketCapability } from './prediction.js';
 import { modalCapabilities } from './modal.js';
+import { blockrunCapability } from './blockrun.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -163,6 +164,7 @@ export const allCapabilities = [
     defiLlamaYieldsCapability,
     defiLlamaPriceCapability,
     predictionMarketCapability, // Polymarket / Kalshi / matching / smart money via Predexon
+    blockrunCapability, // Generic x402-paid gateway primitive — Surf, Phone, future partners (see /surf-* skills)
     // Modal GPU sandbox tools — registered but hidden by default (not in
     // CORE_TOOL_NAMES). Agent must `ActivateTool({names:["ModalCreate",...]})`
     // before they appear in its tool inventory. High-cost ($0.40/H100 create)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {