@blockrun/franklin 3.21.9 → 3.23.0

package/dist/tools/realface.js

@@ -0,0 +1,263 @@
+/**
+ * RealFace — enroll a real person's face as a reusable video avatar.
+ *
+ * Wraps BlockRun's /v1/realface/* flow so the agent never hand-rolls paths or
+ * x402. Enrollment is a three-step, human-in-the-loop flow because the upstream
+ * provider (Token360 / BytePlus) requires a live liveness check on a phone:
+ *
+ *   1. action="init" (FREE)   → creates a REAL_FACE group, returns an `h5_link`.
+ *                               Show it to the user as a QR / URL. They scan it
+ *                               on their phone and do a ~1-minute liveness check
+ *                               (nod + blink). The link expires in 120s; call
+ *                               init again with the same group_id to refresh.
+ *   2. action="status" (FREE) → poll the group until status === "active" (the
+ *                               person finished the phone liveness). Bounded
+ *                               poll (~24s) so a quick scan resolves in one call.
+ *   3. action="enroll" ($0.01)→ uploads a face photo (public https URL), waits
+ *                               for the biometric match, returns the `ta_xxx`
+ *                               asset id. Pre-flights group-active (425 if not);
+ *                               no charge if the upload/match fails.
+ *   action="list" (FREE)      → lists the wallet's enrolled RealFace assets.
+ *
+ * Use the returned `ta_xxx` as `real_face_asset_id` on a VideoGen call with a
+ * Seedance 2.0 model for cross-frame character consistency.
+ *
+ * x402 signing mirrors src/tools/videogen.ts / blockrun.ts (kept as copy-paste
+ * per the same rationale documented there — a shared module is out of scope).
+ */
+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 REQUEST_TIMEOUT_MS = 60_000;
+// status poll budget — a phone liveness check takes ~1 min, but the upstream
+// flip to `active` can lag the user saying "done" by a few seconds. Poll a
+// short window so a just-finished scan resolves in one call without hanging
+// the agent loop; if still pending, return and let the agent re-check.
+const STATUS_POLL_ATTEMPTS = 6;
+const STATUS_POLL_INTERVAL_MS = 4_000;
+const GROUP_ID_RE = /^legacy_rf_\d+$/;
+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 */ }
+    }
+    return header;
+}
+async function signPayment(response, chain, endpoint, resourceDescription) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            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 };
+        }
+        const wallet = getOrCreateWallet();
+        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] RealFace payment error: ${err.message}`);
+        return null;
+    }
+}
+function walletAddress(chain) {
+    if (chain === 'solana')
+        return getOrCreateSolanaWallet().then((w) => w.address);
+    return Promise.resolve(getOrCreateWallet().address);
+}
+async function timedFetch(url, init, ctx) {
+    const ctrl = new AbortController();
+    const onAbort = () => ctrl.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        return await fetch(url, { ...init, signal: ctrl.signal });
+    }
+    finally {
+        clearTimeout(timer);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+const fence = (raw) => `\n\n\`\`\`json\n${raw}\n\`\`\``;
+async function actionInit(base, input, ctx) {
+    const name = typeof input.name === 'string' ? input.name.trim() : '';
+    if (!name)
+        return { output: 'RealFace init needs a `name` (the real person\'s display name, 1–64 chars).', isError: true };
+    const groupId = typeof input.group_id === 'string' ? input.group_id.trim() : undefined;
+    if (groupId && !GROUP_ID_RE.test(groupId)) {
+        return { output: `RealFace init: group_id must look like "legacy_rf_<digits>". Got: ${groupId}`, isError: true };
+    }
+    const body = JSON.stringify(groupId ? { name, groupId } : { name });
+    const res = await timedFetch(`${base}/v1/realface/init`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': USER_AGENT },
+        body,
+    }, ctx);
+    const raw = await res.text().catch(() => '');
+    if (!res.ok)
+        return { output: `RealFace init failed (status ${res.status}).\n${raw.slice(0, 600)}`, isError: true };
+    return {
+        output: 'RealFace group created — FREE. Show the `h5_link` to the user as a QR code or tappable URL. ' +
+            'They scan it on their phone and complete a ~1-minute liveness check (nod + blink). The link ' +
+            'expires in ~120s — re-run action="init" with the same `group_id` to refresh. Then poll ' +
+            'action="status" with the `group_id` until status="active", and finish with action="enroll".' +
+            fence(raw),
+    };
+}
+async function actionStatus(base, input, ctx) {
+    const groupId = typeof input.group_id === 'string' ? input.group_id.trim() : '';
+    if (!GROUP_ID_RE.test(groupId)) {
+        return { output: 'RealFace status needs a valid `group_id` (format "legacy_rf_<digits>") from action="init".', isError: true };
+    }
+    let raw = '';
+    let lastStatus = '';
+    for (let attempt = 0; attempt < STATUS_POLL_ATTEMPTS; attempt++) {
+        if (ctx.abortSignal.aborted)
+            break;
+        const res = await timedFetch(`${base}/v1/realface/status?groupId=${encodeURIComponent(groupId)}`, {
+            method: 'GET',
+            headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
+        }, ctx);
+        raw = await res.text().catch(() => '');
+        if (!res.ok)
+            return { output: `RealFace status failed (status ${res.status}).\n${raw.slice(0, 600)}`, isError: true };
+        try {
+            lastStatus = String(JSON.parse(raw).status ?? '');
+        }
+        catch { /* keep raw */ }
+        if (lastStatus === 'active') {
+            return { output: `RealFace group is ACTIVE — the person finished the phone liveness check. Proceed with action="enroll".${fence(raw)}` };
+        }
+        if (attempt < STATUS_POLL_ATTEMPTS - 1)
+            await new Promise((r) => setTimeout(r, STATUS_POLL_INTERVAL_MS));
+    }
+    return {
+        output: `RealFace group not yet active (status="${lastStatus || 'unknown'}"). The person hasn't finished the phone ` +
+            `liveness check, or the upstream is still processing. Ask them to scan the QR (action="init" to refresh an ` +
+            `expired link), then call action="status" again.${fence(raw)}`,
+    };
+}
+async function actionEnroll(base, chain, input, ctx) {
+    const name = typeof input.name === 'string' ? input.name.trim() : '';
+    const imageUrl = typeof input.image_url === 'string' ? input.image_url.trim() : '';
+    const groupId = typeof input.group_id === 'string' ? input.group_id.trim() : '';
+    if (!name)
+        return { output: 'RealFace enroll needs `name`.', isError: true };
+    if (!GROUP_ID_RE.test(groupId))
+        return { output: 'RealFace enroll needs a valid `group_id` (from action="init").', isError: true };
+    if (!/^https?:\/\//.test(imageUrl)) {
+        return { output: 'RealFace enroll needs `image_url` as a public http(s) URL to the face photo (JPG/PNG/WEBP, ≤10 MB). The gateway fetches it server-side — local paths and data: URIs are not accepted.', isError: true };
+    }
+    const url = `${base}/v1/realface/enroll`;
+    const body = JSON.stringify({ name, image_url: imageUrl, group_id: groupId });
+    const headers = { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': USER_AGENT };
+    const start = Date.now();
+    let res = await timedFetch(url, { method: 'POST', headers, body }, ctx);
+    let paidUsd = 0;
+    if (res.status === 402) {
+        const signed = await signPayment(res, chain, url, `RealFace enrollment — "${name.slice(0, 32)}"`);
+        if (!signed)
+            return { output: 'RealFace enroll: payment signing failed. Check wallet balance with `franklin balance`.', isError: true };
+        paidUsd = signed.amountUsd;
+        res = await timedFetch(url, { method: 'POST', headers: { ...headers, ...signed.headers }, body }, ctx);
+    }
+    const raw = await res.text().catch(() => '');
+    if (!res.ok)
+        paidUsd = 0;
+    try {
+        recordUsage('RealFace:enroll', 0, 0, paidUsd, Date.now() - start);
+    }
+    catch { /* best-effort */ }
+    if (res.status === 425) {
+        return { output: `RealFace enroll: the group isn't active yet — the person must finish the phone liveness check first. No payment taken. Poll action="status" until active, then retry.\n${raw.slice(0, 600)}`, isError: true };
+    }
+    if (res.status === 422) {
+        return { output: `RealFace enroll: the uploaded photo didn't match the live face captured on the phone. No payment taken. Use a clearer front-facing photo of the same person and retry.\n${raw.slice(0, 600)}`, isError: true };
+    }
+    if (!res.ok) {
+        return { output: `RealFace enroll failed (status ${res.status}). No charge if 4xx pre-payment.\n${raw.slice(0, 600)}`, isError: true };
+    }
+    return {
+        output: `RealFace enrolled → $${paidUsd.toFixed(4)} · ${Date.now() - start}ms. ` +
+            `Use the returned \`asset_id\` (ta_xxx) as \`real_face_asset_id\` on a VideoGen call with ` +
+            `bytedance/seedance-2.0 or -fast for a real-person clip.${fence(raw)}`,
+    };
+}
+async function actionList(base, chain, ctx) {
+    const addr = await walletAddress(chain);
+    const res = await timedFetch(`${base}/v1/wallet/${addr}/realfaces`, {
+        method: 'GET',
+        headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
+    }, ctx);
+    const raw = await res.text().catch(() => '');
+    if (!res.ok)
+        return { output: `RealFace list failed (status ${res.status}).\n${raw.slice(0, 600)}`, isError: true };
+    return { output: `RealFace assets for ${addr}:${fence(raw)}` };
+}
+async function execute(input, ctx) {
+    const action = typeof input.action === 'string' ? input.action.trim() : '';
+    const chain = loadChain();
+    const base = API_URLS[chain]; // ends in /api
+    switch (action) {
+        case 'init': return actionInit(base, input, ctx);
+        case 'status': return actionStatus(base, input, ctx);
+        case 'enroll': return actionEnroll(base, chain, input, ctx);
+        case 'list': return actionList(base, chain, ctx);
+        default:
+            return { output: `RealFace: unknown action "${action}". Valid: init, status, enroll, list.`, isError: true };
+    }
+}
+export const realFaceCapability = {
+    spec: {
+        name: 'RealFace',
+        description: 'Enroll a real person\'s face as a reusable video avatar (ta_xxx asset), then use it in VideoGen ' +
+            'for cross-frame character consistency on Seedance 2.0. Human-in-the-loop, four actions:\n' +
+            '• action="init" (FREE) — create a group, get an `h5_link`; show it to the user as a QR. They scan it ' +
+            'on their phone and do a ~1-minute liveness check (nod + blink). Link expires in 120s — re-init with the ' +
+            'same `group_id` to refresh.\n' +
+            '• action="status" (FREE) — poll the `group_id` until status="active" (person finished the phone check).\n' +
+            '• action="enroll" ($0.01 USDC) — upload the face photo (`image_url`, public https) + `group_id`; returns ' +
+            'the `ta_xxx` asset id. No charge if the group isn\'t active (425) or the face doesn\'t match (422).\n' +
+            '• action="list" (FREE) — list this wallet\'s enrolled RealFace assets.\n' +
+            'Typical sequence: init → (user scans) → status → enroll → VideoGen with real_face_asset_id.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['init', 'status', 'enroll', 'list'],
+                    description: 'Which step of the RealFace flow to run.',
+                },
+                name: { type: 'string', description: 'Display name of the real person (1–64 chars). Required for init and enroll.' },
+                group_id: { type: 'string', description: 'The group id ("legacy_rf_<digits>") returned by action="init". Required for status and enroll; optional on init to refresh an expired h5_link.' },
+                image_url: { type: 'string', description: 'Public http(s) URL to the face photo (JPG/PNG/WEBP, ≤10 MB). Required for enroll. Fetched server-side — local paths / data: URIs are rejected.' },
+            },
+            required: ['action'],
+        },
+    },
+    concurrent: false,
+    execute,
+};

package/dist/tools/surf.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Surf — function-call tools for BlockRun's crypto data API.
+ *
+ * Three category tools (SurfMarket / SurfChain / SurfSocial) that mirror the
+ * /surf-market, /surf-chain, /surf-social skills. Unlike the generic BlockRun
+ * primitive (free-form `path` string), these expose the valid endpoints as an
+ * `endpoint` enum so the model picks instead of guessing, and they sign the
+ * x402 payment internally — the model never touches paths or payment, same UX
+ * as VideoGen / ImageGen.
+ *
+ * The endpoint tables below are derived from the gateway's SURF_ENDPOINTS
+ * registry (blockrun/src/lib/surf.ts). They are hand-maintained for now; a
+ * follow-up will generate them so the gateway stays the single source of truth.
+ *
+ * x402 signing mirrors src/tools/blockrun.ts (kept as copy-paste per the same
+ * rationale documented there — refactoring into a shared module is out of scope).
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const surfMarketCapability: CapabilityHandler;
+export declare const surfChainCapability: CapabilityHandler;
+export declare const surfSocialCapability: CapabilityHandler;
+export declare const surfCapabilities: CapabilityHandler[];

package/dist/tools/surf.js

@@ -0,0 +1,281 @@
+/**
+ * Surf — function-call tools for BlockRun's crypto data API.
+ *
+ * Three category tools (SurfMarket / SurfChain / SurfSocial) that mirror the
+ * /surf-market, /surf-chain, /surf-social skills. Unlike the generic BlockRun
+ * primitive (free-form `path` string), these expose the valid endpoints as an
+ * `endpoint` enum so the model picks instead of guessing, and they sign the
+ * x402 payment internally — the model never touches paths or payment, same UX
+ * as VideoGen / ImageGen.
+ *
+ * The endpoint tables below are derived from the gateway's SURF_ENDPOINTS
+ * registry (blockrun/src/lib/surf.ts). They are hand-maintained for now; a
+ * follow-up will generate them so the gateway stays the single source of truth.
+ *
+ * x402 signing mirrors src/tools/blockrun.ts (kept as copy-paste per the same
+ * rationale documented there — refactoring into a shared module is out of scope).
+ */
+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 TIMEOUT_MS = 30_000;
+// ── Endpoint tables (derived from gateway SURF_ENDPOINTS) ───────────────────
+const MARKET_ENDPOINTS = [
+    { path: 'market/ranking', method: 'GET', required: [], desc: 'Token rankings (market cap, volume, 24h change).' },
+    { path: 'market/fear-greed', method: 'GET', required: [], desc: 'Fear & Greed index history.' },
+    { path: 'market/futures', method: 'GET', required: [], desc: 'Futures market overview.' },
+    { path: 'market/price', method: 'GET', required: ['symbol'], desc: 'Token price history.' },
+    { path: 'market/etf', method: 'GET', required: ['symbol'], desc: 'Spot ETF flow history (BTC/ETH).' },
+    { path: 'market/options', method: 'GET', required: ['symbol'], desc: 'Options skew / IV / volume.' },
+    { path: 'market/liquidation/exchange-list', method: 'GET', required: [], desc: 'Liquidations by exchange.' },
+    { path: 'market/liquidation/order', method: 'GET', required: [], desc: 'Large (whale) liquidation orders.' },
+    { path: 'market/liquidation/chart', method: 'GET', required: ['symbol'], desc: 'Liquidation chart over time.' },
+    { path: 'market/onchain-indicator', method: 'GET', required: ['symbol', 'metric'], desc: 'On-chain indicators (NUPL/SOPR/MVRV/Puell/NVT).' },
+    { path: 'market/price-indicator', method: 'GET', required: ['indicator', 'symbol'], desc: 'Technical indicators (RSI/MACD/BBANDS/EMA).' },
+    { path: 'exchange/markets', method: 'GET', required: [], desc: 'CEX trading pairs catalog.' },
+    { path: 'exchange/price', method: 'GET', required: ['pair'], desc: 'CEX ticker price for a pair.' },
+    { path: 'exchange/perp', method: 'GET', required: ['pair'], desc: 'Perpetual contract snapshot.' },
+    { path: 'exchange/depth', method: 'GET', required: ['pair'], desc: 'Order book depth.' },
+    { path: 'exchange/klines', method: 'GET', required: ['pair'], desc: 'OHLCV candles.' },
+    { path: 'exchange/funding-history', method: 'GET', required: ['pair'], desc: 'Funding rate history.' },
+    { path: 'exchange/long-short-ratio', method: 'GET', required: ['pair'], desc: 'Long/short account ratio.' },
+    { path: 'fund/detail', method: 'GET', required: [], desc: 'VC fund profile detail.' },
+    { path: 'fund/portfolio', method: 'GET', required: [], desc: 'VC fund portfolio holdings.' },
+    { path: 'fund/ranking', method: 'GET', required: ['metric'], desc: 'Top VC funds ranking.' },
+    { path: 'news/feed', method: 'GET', required: [], desc: 'AI-curated crypto news feed.' },
+    { path: 'news/detail', method: 'GET', required: ['id'], desc: 'Full article detail by id.' },
+    { path: 'project/detail', method: 'GET', required: [], desc: 'Project profile.' },
+    { path: 'project/defi/metrics', method: 'GET', required: ['metric'], desc: 'DeFi protocol metrics.' },
+    { path: 'project/defi/ranking', method: 'GET', required: ['metric'], desc: 'DeFi protocol ranking.' },
+];
+const CHAIN_ENDPOINTS = [
+    { path: 'onchain/bridge/ranking', method: 'GET', required: [], desc: 'Bridge protocol ranking by volume.' },
+    { path: 'onchain/yield/ranking', method: 'GET', required: [], desc: 'Yield pool ranking (lending/LP/staking).' },
+    { path: 'onchain/gas-price', method: 'GET', required: ['chain'], desc: 'Current gas price for a chain.' },
+    { path: 'onchain/tx', method: 'GET', required: ['hash', 'chain'], desc: 'Transaction details by hash.' },
+    { path: 'onchain/schema', method: 'GET', required: [], desc: 'Schema introspection for the SQL tables.' },
+    { path: 'onchain/query', method: 'POST', required: [], desc: 'Structured chain query (POST body).' },
+    { path: 'onchain/sql', method: 'POST', required: [], desc: 'Raw SQL against 80+ indexed chain tables (POST body, Tier-3 $0.02).' },
+    { path: 'token/tokenomics', method: 'GET', required: [], desc: 'Token supply / unlock / distribution.' },
+    { path: 'token/dex-trades', method: 'GET', required: ['address'], desc: 'Recent DEX trades for a token.' },
+    { path: 'token/holders', method: 'GET', required: ['address', 'chain'], desc: 'Top holders / concentration.' },
+    { path: 'token/transfers', method: 'GET', required: ['address', 'chain'], desc: 'Token transfer history.' },
+    { path: 'wallet/detail', method: 'GET', required: ['address'], desc: 'Wallet overview.' },
+    { path: 'wallet/history', method: 'GET', required: ['address'], desc: 'Wallet activity history.' },
+    { path: 'wallet/net-worth', method: 'GET', required: ['address'], desc: 'Wallet net worth.' },
+    { path: 'wallet/transfers', method: 'GET', required: ['address'], desc: 'Wallet transfers.' },
+    { path: 'wallet/protocols', method: 'GET', required: ['address'], desc: 'Protocols the wallet interacts with.' },
+    { path: 'wallet/labels/batch', method: 'GET', required: ['addresses'], desc: 'Batch wallet labels (CEX/Whale/Bridge/MEV).' },
+];
+const SOCIAL_ENDPOINTS = [
+    { path: 'social/detail', method: 'GET', required: [], desc: 'Social signal detail.' },
+    { path: 'social/ranking', method: 'GET', required: [], desc: 'KOL / account influence ranking.' },
+    { path: 'social/smart-followers/history', method: 'GET', required: [], desc: 'Smart-follower growth history.' },
+    { path: 'social/mindshare', method: 'GET', required: ['q', 'interval'], desc: 'Topic/token mindshare over an interval.' },
+    { path: 'social/tweets', method: 'GET', required: ['ids'], desc: 'Tweets by ids.' },
+    { path: 'social/tweet/replies', method: 'GET', required: ['tweet_id'], desc: 'Replies to a tweet.' },
+    { path: 'social/user', method: 'GET', required: ['handle'], desc: 'User profile.' },
+    { path: 'social/user/followers', method: 'GET', required: ['handle'], desc: 'User followers.' },
+    { path: 'social/user/following', method: 'GET', required: ['handle'], desc: 'User followings.' },
+    { path: 'social/user/posts', method: 'GET', required: ['handle'], desc: 'User posts.' },
+    { path: 'social/user/replies', method: 'GET', required: ['handle'], desc: 'User replies.' },
+];
+// ── x402 signing (mirrors blockrun.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 */ }
+    }
+    return header;
+}
+async function signPayment(response, chain, endpoint, resourceDescription) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            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 };
+        }
+        const wallet = getOrCreateWallet();
+        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] Surf payment error: ${err.message}`);
+        return null;
+    }
+}
+// ── Shared call: resolve endpoint → sign x402 → return data ──────────────────
+async function callSurf(toolName, table, input, ctx) {
+    const endpoint = typeof input.endpoint === 'string' ? input.endpoint.trim().replace(/^\/+|\/+$/g, '') : '';
+    let entry = table.find((e) => e.path === endpoint);
+    if (!entry) {
+        // Tolerate a weak model dropping the category prefix ("fear-greed" instead
+        // of "market/fear-greed") — accept a suffix match when it's unambiguous.
+        const matches = table.filter((e) => e.path === endpoint || e.path.endsWith(`/${endpoint}`));
+        if (matches.length === 1) {
+            entry = matches[0];
+        }
+        else if (matches.length > 1) {
+            return { output: `Ambiguous ${toolName} endpoint "${endpoint}". Did you mean: ${matches.map((m) => m.path).join(', ')}?`, isError: true };
+        }
+        else {
+            return { output: `Unknown ${toolName} endpoint: "${endpoint}". Valid: ${table.map((e) => e.path).join(', ')}`, isError: true };
+        }
+    }
+    // Collect query params: the named fields the caller provided (everything
+    // except `endpoint`/`body`), plus an explicit `params` object if given.
+    const query = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (k === 'endpoint' || k === 'body' || k === 'params')
+            continue;
+        if (v !== undefined && v !== null && v !== '')
+            query[k] = v;
+    }
+    if (input.params && typeof input.params === 'object')
+        Object.assign(query, input.params);
+    const missing = entry.required.filter((p) => query[p] === undefined);
+    if (missing.length > 0) {
+        return {
+            output: `${toolName} ${endpoint} needs: ${entry.required.join(', ')}. Missing: ${missing.join(', ')}.`,
+            isError: true,
+        };
+    }
+    const chain = loadChain();
+    const base = API_URLS[chain]; // ends in /api
+    let url = `${base}/v1/surf/${entry.path}`;
+    const body = entry.method === 'POST'
+        ? (input.body && typeof input.body === 'object' ? input.body : query)
+        : undefined;
+    if (entry.method === 'GET' && Object.keys(query).length > 0) {
+        const usp = new URLSearchParams();
+        for (const [k, v] of Object.entries(query)) {
+            if (Array.isArray(v))
+                for (const x of v)
+                    usp.append(k, String(x));
+            else
+                usp.append(k, String(v));
+        }
+        url += `?${usp.toString()}`;
+    }
+    const start = Date.now();
+    const ctrl = new AbortController();
+    const onAbort = () => ctrl.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    const headers = { Accept: 'application/json', 'User-Agent': USER_AGENT };
+    if (entry.method === 'POST')
+        headers['Content-Type'] = 'application/json';
+    const payload = body !== undefined ? JSON.stringify(body) : undefined;
+    const resourceDescription = `Surf ${entry.method} /v1/surf/${entry.path}`;
+    try {
+        let response = await fetch(url, { method: entry.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 { output: `${toolName} ${endpoint}: payment signing failed`, isError: true };
+            paidUsd = signed.amountUsd;
+            response = await fetch(url, {
+                method: entry.method, signal: ctrl.signal,
+                headers: { ...headers, ...signed.headers }, body: payload,
+            });
+        }
+        if (!response.ok)
+            paidUsd = 0;
+        const raw = await response.text().catch(() => '');
+        try {
+            recordUsage(`${toolName}:${entry.path}`, 0, 0, paidUsd, Date.now() - start);
+        }
+        catch { /* best-effort */ }
+        if (!response.ok) {
+            return {
+                output: `${toolName} ${endpoint} failed (status ${response.status}). No charge if 4xx pre-payment.\n${raw.slice(0, 800)}`,
+                isError: true,
+            };
+        }
+        const head = `Surf /v1/surf/${entry.path} → $${paidUsd.toFixed(4)} · ${Date.now() - start}ms`;
+        return { output: `${head}\n\n\`\`\`json\n${raw}\n\`\`\`` };
+    }
+    catch (err) {
+        return { output: `${toolName} ${endpoint} error: ${err.message}`, isError: true };
+    }
+    finally {
+        clearTimeout(timer);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+// ── Tool specs ───────────────────────────────────────────────────────────────
+function makeSurfTool(name, blurb, table, extraParams) {
+    const endpointList = table.map((e) => `\`${e.path}\`${e.required.length ? ` (needs ${e.required.join('+')})` : ''} — ${e.desc}`).join('\n');
+    return {
+        spec: {
+            name,
+            description: `${blurb} Picks an endpoint from a fixed list and signs the x402 USDC payment from the wallet automatically — ` +
+                `you do not build paths or handle payment. Tier-1 $0.001, Tier-2 $0.005, Tier-3 $0.02.\n\nEndpoints:\n${endpointList}`,
+            input_schema: {
+                type: 'object',
+                properties: {
+                    endpoint: {
+                        type: 'string',
+                        enum: table.map((e) => e.path),
+                        description: 'Which Surf endpoint to call (see list in the tool description).',
+                    },
+                    ...extraParams,
+                    body: { type: 'object', description: 'Request body for POST endpoints (onchain/query, onchain/sql).' },
+                },
+                required: ['endpoint'],
+            },
+        },
+        concurrent: true,
+        execute: (input, ctx) => callSurf(name, table, input, ctx),
+    };
+}
+export const surfMarketCapability = makeSurfTool('SurfMarket', 'Crypto market data: token rankings, fear/greed, futures, ETF flows, options, liquidations, technical & on-chain indicators, CEX pairs, VC funds, news, DeFi projects.', MARKET_ENDPOINTS, {
+    symbol: { type: 'string', description: 'Token symbol, e.g. "BTC". Required by price/etf/options/liquidation-chart/indicators.' },
+    pair: { type: 'string', description: 'Exchange pair, e.g. "BTC-USDT". Required by exchange/* endpoints.' },
+    metric: { type: 'string', description: 'Metric name (e.g. "NUPL" for onchain-indicator, ranking metric for fund/project).' },
+    indicator: { type: 'string', description: 'Technical indicator, e.g. "RSI", "MACD", "BBANDS".' },
+    id: { type: 'string', description: 'Article id for news/detail.' },
+});
+export const surfChainCapability = makeSurfTool('SurfChain', 'On-chain data: bridge/yield rankings, gas, transactions, token analytics (holders, transfers, DEX trades), wallet intelligence, and raw SQL over 80+ indexed chain tables.', CHAIN_ENDPOINTS, {
+    chain: { type: 'string', description: 'Chain name, e.g. "ethereum", "base". Required by gas-price/tx/holders/transfers.' },
+    hash: { type: 'string', description: 'Transaction hash for onchain/tx.' },
+    address: { type: 'string', description: 'Token or wallet address.' },
+    addresses: { type: 'string', description: 'Comma-separated addresses for wallet/labels/batch.' },
+});
+export const surfSocialCapability = makeSurfTool('SurfSocial', 'Crypto-Twitter / KOL signal: influence rankings, mindshare, smart-follower history, tweets, and user profiles. The canonical source for CT sentiment.', SOCIAL_ENDPOINTS, {
+    q: { type: 'string', description: 'Query/topic for mindshare.' },
+    interval: { type: 'string', description: 'Time interval for mindshare, e.g. "24h", "7d".' },
+    handle: { type: 'string', description: 'Twitter/X handle for social/user* endpoints.' },
+    ids: { type: 'string', description: 'Comma-separated tweet ids for social/tweets.' },
+    tweet_id: { type: 'string', description: 'Tweet id for social/tweet/replies.' },
+});
+export const surfCapabilities = [
+    surfMarketCapability,
+    surfChainCapability,
+    surfSocialCapability,
+];

package/dist/tools/tool-categories.js

@@ -49,6 +49,13 @@ export const CORE_TOOL_NAMES = new Set([
     // category. Cross-platform pair lookup is unique to the gateway and
     // is the kind of data a non-wallet agent fundamentally cannot reach.
     'PredictionMarket',
+    // Crypto market data — fear/greed, token rankings, ETF flows, options,
+    // liquidations, technical & on-chain indicators. The "what's the crypto
+    // mood / which coins are pumping / BTC's RSI" category. Core so the agent
+    // reaches for it on natural crypto questions instead of falling back to
+    // TradingMarket prices + guessing the Fear & Greed index. SurfChain /
+    // SurfSocial stay activation-gated (lower-frequency, long-tail surface).
+    'SurfMarket',
     // Research — synthesized answers with real citations, semantic web
     // search, and clean URL fetching. Any factual current-events question
     // ("why did X drop?") should route here rather than the model's prior.