@blockrun/franklin 3.12.1 → 3.12.3

package/dist/agent/context.js

@@ -205,9 +205,8 @@ You run on the BlockRun AI Gateway. When the user asks you to "test the BlockRun
 - \`GET /v1/models\` — full model catalog (id, owner, context window, pricing).
 - \`GET /v1/health/overview\` · \`/v1/health/regions\` · \`/v1/health/chain\` · \`/v1/health/models\` — gateway status.
 
-**Trading & DeFi (mixed methods, x402-paid; new in v3.12.0)**
-- \`GET  /v1/defillama/protocols\` · \`/v1/defillama/protocol/{slug}\` · \`/v1/defillama/chains\` · \`/v1/defillama/yields\` — TVL / yield-pool data, Apache-2.0 source. \$0.005/call.
-- \`GET  /v1/defillama/prices/{coins}\` — token price lookup (coingecko:bitcoin, ethereum:0x..., solana:mint, comma-separated). \$0.001/call.
+**Trading & DeFi (mixed methods, x402-paid)**
+- For DefiLlama data, **use the built-in tools** \`DeFiLlamaProtocols\`, \`DeFiLlamaProtocol\`, \`DeFiLlamaChains\`, \`DeFiLlamaYields\`, \`DeFiLlamaPrice\`. They handle x402 payment automatically and filter responses (DefiLlama raw payloads are 5–10 MB; the tools return ranked summaries). Do NOT call \`/v1/defillama/*\` via Bash + curl — the wallet won't sign payments through that path.
 - \`POST /v1/solana/rpc\` — JSON-RPC passthrough to public mainnet-beta (getAccountInfo, getTokenSupply, sendTransaction, etc.). \$0.0005 per call (per element of a batch). Use this instead of running your own RPC infra.
 
 **Solana DEX swap (Jupiter Ultra)**
@@ -233,6 +232,53 @@ A bare \`402\` on a POST means the endpoint is healthy and the payment flow is w
 
 **Verifying gateway health**: GET \`/v1/health/overview\` (free) is the right probe. Listing endpoints? Fetch \`/openapi.json\` and read the \`paths\` object — that is the source of truth, not your training memory.`;
 }
+function getTradingPlaybookSection() {
+    return `# Trading playbook (built-in tools)
+
+Franklin has built-in tools for live Solana DEX swaps (\`JupiterSwap\`, \`JupiterQuote\`) and DeFi-data lookups (\`DeFiLlamaProtocols\`, \`DeFiLlamaProtocol\`, \`DeFiLlamaChains\`, \`DeFiLlamaYields\`, \`DeFiLlamaPrice\`). When the user asks for live trades or DeFi data, route through these tools — NOT WebSearch, NOT Bash + curl, NOT WebFetch (those won't sign x402 payments and will hit 402 walls).
+
+## Before any live swap
+
+1. **Quote first if the user hasn't already seen the numbers.** Run \`JupiterQuote\` to surface input amount, output amount, rate, price impact, and route. Users make informed decisions when they see numbers, not vibes.
+2. **Reject \`priceImpactPct\` > 5 %** unless the user has explicitly asked to proceed despite impact. Memecoins on illiquid days routinely have 10–30 % impact — that is a money-losing trade. Tell them, ask them, then maybe proceed.
+3. **Large-swap warning above ~\$20 USD equivalent.** Estimate via stablecoin reference if available (USDC, USDT inputs are 1:1). If you can't reliably estimate, say so in the AskUser prompt: "I cannot easily price-check this output token in USD before the swap; please confirm only if you know what you are buying."
+
+## During a swap
+
+- **Default \`auto_approve: false\`.** Only set true if the user has just authorized this specific call ("yes, swap 0.01 SOL for USDC"). NEVER set auto-approve session-wide. NEVER set it to "just do all three swaps I asked about" — each swap gets its own AskUser confirmation.
+- **Be transparent about the 20 bps BlockRun referral fee.** It is shown by \`JupiterQuote\` automatically; if the user asks why, explain: it's BlockRun's integrator cut via Jupiter's official Referral Program — same mechanism Phantom and other Solana wallets use. The user is paying for the convenience layer.
+- **Surface the Solscan link prominently after execution.** Trust is built on receipts. "Done" without a signature link is a red flag for the user.
+
+## Failure handling
+
+- \`No Solana wallet found\` → run \`franklin setup solana\`. The harness usually auto-creates on first run; this error means the file is corrupt or unreadable.
+- \`/execute\` returns \`InsufficientFundsForRent\` / \`insufficient lamports\` / \`TokenAccountNotFound\` → user's Solana wallet is empty for the input mint. Show them the wallet pubkey (it was in the AskUser prompt) and tell them to send the input token to that address.
+- \`/order\` returns no transaction or 30 %+ price impact → no liquidity for the pair. Suggest a smaller amount or a different output token.
+- Live-swap session cap reached → user has done many live swaps in this session. Hard-stop is intentional; suggest \`/retry\` or set \`FRANKLIN_LIVE_SWAP_CAP\` to raise.
+
+## Never
+
+- Chain multiple live swaps without showing the running USD spent so far this turn.
+- Tell the user "I executed your trade" without the Solscan link or signature.
+- Compute USD value or P&L by guessing prices. Use \`TradingMarket\`, \`DeFiLlamaPrice\`, or \`JupiterQuote\` (with stablecoin reference) for ground truth.
+- Mix paper and live state in your reply. Paper trading lives in \`TradingPortfolio\` (\`~/.blockrun/portfolio.json\`); live swaps are recorded in \`~/.blockrun/trades.jsonl\` with \`kind: 'live'\`. Be explicit about which one you're acting in.
+
+## DeFi data (DeFiLlama tools)
+
+- Match the tool to the question.
+  - "What's pumping on Solana?" → \`DeFiLlamaProtocols(chain='Solana', top_n=10)\`
+  - "Top yield for USDC" → \`DeFiLlamaYields(symbol='USDC', stablecoin_only=true)\`
+  - "Aave's TVL" → \`DeFiLlamaProtocol(slug='aave-v3')\`
+  - "BTC price" → \`DeFiLlamaPrice(coins=['coingecko:bitcoin'])\` or \`TradingMarket\`
+- **Filter aggressively.** Default \`top_n=10\` unless the user asked for more. Raw DefiLlama payloads are 5–10 MB and will blow your context window.
+- **Never call the same DeFiLlama endpoint twice in one turn.** Each call is paid. If you find yourself doing it, your plan is wrong.
+
+## Paper vs. live
+
+- Paper trading (TradingPortfolio etc.) is for plan-grade simulation: positions, risk caps, P&L tracking, no on-chain. Use it when the user wants to "test" or "simulate" a strategy.
+- Live trading is JupiterSwap. It costs real USDC, signs an on-chain tx, and shows up on Solscan. NEVER conflate — if the user says "swap" they usually mean live; if they say "simulate" or "paper" they mean paper.
+`;
+}
 function getToolPatternsSection() {
     return `# Tool Selection Patterns
 - **Finding files**: Glob first (by name/pattern), then Grep (by content), then Read (specific file). Don't start with Read unless you know the exact path.
@@ -301,6 +347,7 @@ export function assembleInstructions(workingDir, model) {
         getMissingAccessSection(),
         getWalletKnowledgeSection(),
         getBlockRunApiSection(),
+        getTradingPlaybookSection(),
         getToolPatternsSection(),
         getTokenEfficiencySection(),
         getVerificationSection(),

package/dist/tools/defillama.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DefiLlama capabilities — TVL, yield pools, protocol metadata, and token
+ * prices via the BlockRun `/v1/defillama/*` endpoints. Each tool handles
+ * x402 payment automatically against the user's USDC wallet.
+ *
+ * Five tools, each filtered + formatted on the way back so we don't dump
+ * 5–10 MB of raw DefiLlama JSON into agent context:
+ *  - DeFiLlamaProtocols   $0.005/call — top-N protocols by TVL
+ *  - DeFiLlamaProtocol    $0.005/call — single protocol detail
+ *  - DeFiLlamaChains      $0.005/call — TVL ranked by chain
+ *  - DeFiLlamaYields      $0.005/call — yield pools, filtered + ranked
+ *  - DeFiLlamaPrice       $0.001/call — token price lookup
+ *
+ * DefiLlama is Apache 2.0 / "free for public and commercial use" — the
+ * BlockRun gateway adds metering + (future) caching/reliability layers,
+ * which is what the per-call charge funds.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const defiLlamaProtocolsCapability: CapabilityHandler;
+export declare const defiLlamaProtocolCapability: CapabilityHandler;
+export declare const defiLlamaChainsCapability: CapabilityHandler;
+export declare const defiLlamaYieldsCapability: CapabilityHandler;
+export declare const defiLlamaPriceCapability: CapabilityHandler;

package/dist/tools/defillama.js

@@ -0,0 +1,408 @@
+/**
+ * DefiLlama capabilities — TVL, yield pools, protocol metadata, and token
+ * prices via the BlockRun `/v1/defillama/*` endpoints. Each tool handles
+ * x402 payment automatically against the user's USDC wallet.
+ *
+ * Five tools, each filtered + formatted on the way back so we don't dump
+ * 5–10 MB of raw DefiLlama JSON into agent context:
+ *  - DeFiLlamaProtocols   $0.005/call — top-N protocols by TVL
+ *  - DeFiLlamaProtocol    $0.005/call — single protocol detail
+ *  - DeFiLlamaChains      $0.005/call — TVL ranked by chain
+ *  - DeFiLlamaYields      $0.005/call — yield pools, filtered + ranked
+ *  - DeFiLlamaPrice       $0.001/call — token price lookup
+ *
+ * DefiLlama is Apache 2.0 / "free for public and commercial use" — the
+ * BlockRun gateway adds metering + (future) caching/reliability layers,
+ * which is what the per-call charge funds.
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION } from '../config.js';
+const TIMEOUT_MS = 30_000;
+// ─── Shared GET-with-x402 flow ────────────────────────────────────────────
+async function getWithPayment(path, ctx) {
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const endpoint = `${apiUrl}${path}`;
+    const headers = {
+        Accept: 'application/json',
+        'User-Agent': `franklin/${VERSION}`,
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    try {
+        let response = await fetch(endpoint, {
+            method: 'GET',
+            signal: controller.signal,
+            headers,
+        });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint);
+            if (!paymentHeaders) {
+                throw new Error('Payment signing failed — check wallet balance');
+            }
+            response = await fetch(endpoint, {
+                method: 'GET',
+                signal: controller.signal,
+                headers: { ...headers, ...paymentHeaders },
+            });
+        }
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            throw new Error(`DefiLlama ${path} failed (${response.status}): ${errText.slice(0, 200)}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeout);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+async function signPayment(response, chain, endpoint) {
+    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 || 'Franklin DefiLlama call',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        const wallet = await 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 || 'Franklin DefiLlama call',
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        console.error(`[franklin] DefiLlama payment error: ${err.message}`);
+        return null;
+    }
+}
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.json());
+            if (body.x402 || body.accepts)
+                header = btoa(JSON.stringify(body));
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return header;
+}
+// ─── Formatting helpers ──────────────────────────────────────────────────
+function formatUsd(value) {
+    if (value == null || !Number.isFinite(value))
+        return 'n/a';
+    if (value >= 1e9)
+        return `$${(value / 1e9).toFixed(2)}B`;
+    if (value >= 1e6)
+        return `$${(value / 1e6).toFixed(2)}M`;
+    if (value >= 1e3)
+        return `$${(value / 1e3).toFixed(2)}K`;
+    return `$${value.toFixed(2)}`;
+}
+function formatPct(value, digits = 2) {
+    if (value == null || !Number.isFinite(value))
+        return 'n/a';
+    const sign = value >= 0 ? '+' : '';
+    return `${sign}${value.toFixed(digits)}%`;
+}
+export const defiLlamaProtocolsCapability = {
+    spec: {
+        name: 'DeFiLlamaProtocols',
+        description: 'Rank DeFi protocols by total value locked (TVL) across all chains, optionally filtered by category, chain, or minimum TVL. ' +
+            'Returns the top-N protocols (default 20), each with TVL, 24h/7d change, chain breakdown, and slug. ' +
+            'Uses BlockRun gateway → DefiLlama. $0.005 per call. ' +
+            'Categories include: Lending, Liquid Staking, Bridge, Dexes, CDP, Yield, Yield Aggregator, Derivatives, Stablecoins, Insurance, etc.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                top_n: { type: 'number', description: 'Max results (default 20, hard cap 100).' },
+                category: { type: 'string', description: 'Category filter, exact match (case-insensitive).' },
+                chain: { type: 'string', description: 'Chain name filter (e.g. "Ethereum", "Solana", "Base").' },
+                min_tvl_usd: { type: 'number', description: 'Drop protocols with TVL below this floor.' },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        const topN = Math.min(Math.max(1, params.top_n ?? 20), 100);
+        try {
+            const res = await getWithPayment('/v1/defillama/protocols', ctx);
+            let list = res ?? [];
+            if (params.category) {
+                const want = params.category.toLowerCase();
+                list = list.filter((p) => (p.category ?? '').toLowerCase() === want);
+            }
+            if (params.chain) {
+                const want = params.chain.toLowerCase();
+                list = list.filter((p) => (p.chains ?? []).some((c) => c.toLowerCase() === want));
+            }
+            if (params.min_tvl_usd != null) {
+                list = list.filter((p) => Number(p.tvl) >= params.min_tvl_usd);
+            }
+            list.sort((a, b) => Number(b.tvl) - Number(a.tvl));
+            list = list.slice(0, topN);
+            if (list.length === 0)
+                return { output: 'No DefiLlama protocols matched the filters.' };
+            const lines = [
+                `## DefiLlama protocols — top ${list.length}` +
+                    (params.category ? ` · category=${params.category}` : '') +
+                    (params.chain ? ` · chain=${params.chain}` : ''),
+            ];
+            list.forEach((p, i) => {
+                const chains = (p.chains ?? []).slice(0, 4).join(', ');
+                const more = (p.chains ?? []).length > 4 ? ` +${(p.chains ?? []).length - 4}` : '';
+                const cat = p.category ? ` · ${p.category}` : '';
+                const change = p.change_1d != null ? ` · 24h ${formatPct(p.change_1d)}` : '';
+                lines.push(`${i + 1}. **${p.name}** (${p.slug}) — ${formatUsd(Number(p.tvl))}${cat}${change}\n   chains: ${chains}${more}`);
+            });
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const defiLlamaProtocolCapability = {
+    spec: {
+        name: 'DeFiLlamaProtocol',
+        description: 'Detailed TVL + chain breakdown for a single DeFi protocol identified by DefiLlama slug ' +
+            '(e.g. "aave", "uniswap", "lido", "jito", "marinade-finance"). ' +
+            'Returns TVL across each chain it operates on, recent change, audits, social. ' +
+            '$0.005 per call. To find a slug, run DeFiLlamaProtocols first.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'DefiLlama protocol slug, lowercase, dash-separated.' },
+            },
+            required: ['slug'],
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        if (!params.slug)
+            return { output: 'Error: slug is required', isError: true };
+        try {
+            const safeSlug = encodeURIComponent(params.slug.trim().toLowerCase());
+            const p = await getWithPayment(`/v1/defillama/protocol/${safeSlug}`, ctx);
+            const chainBreakdown = p.currentChainTvls
+                ? Object.entries(p.currentChainTvls)
+                    .filter(([k]) => !k.endsWith('-staking') && !k.endsWith('-borrowed') && !k.endsWith('-pool2'))
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, 8)
+                    .map(([chain, tvl]) => `${chain} ${formatUsd(tvl)}`)
+                    .join(', ')
+                : 'n/a';
+            const totalTvl = p.currentChainTvls
+                ? Object.values(p.currentChainTvls).reduce((a, b) => a + b, 0)
+                : Array.isArray(p.tvl)
+                    ? p.tvl[p.tvl.length - 1]?.totalLiquidityUSD ?? 0
+                    : p.tvl ?? 0;
+            const lines = [
+                `## ${p.name}${p.category ? ` (${p.category})` : ''}`,
+                '',
+                `TVL: ${formatUsd(totalTvl)}`,
+            ];
+            if (p.change_1d != null)
+                lines.push(`24h change: ${formatPct(p.change_1d)}`);
+            if (p.change_7d != null)
+                lines.push(`7d change: ${formatPct(p.change_7d)}`);
+            lines.push(`Chains: ${chainBreakdown}`);
+            if (p.url)
+                lines.push(`URL: ${p.url}`);
+            if (p.twitter)
+                lines.push(`Twitter: @${p.twitter}`);
+            if (p.audits)
+                lines.push(`Audits: ${p.audits}`);
+            if (p.description)
+                lines.push('', p.description);
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const defiLlamaChainsCapability = {
+    spec: {
+        name: 'DeFiLlamaChains',
+        description: 'TVL ranking across every chain DefiLlama tracks. Default returns top 20 by TVL. $0.005 per call.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                top_n: { type: 'number', description: 'Max results (default 20, hard cap 200).' },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        const topN = Math.min(Math.max(1, params.top_n ?? 20), 200);
+        try {
+            const list = await getWithPayment('/v1/defillama/chains', ctx);
+            const sorted = (list ?? []).slice().sort((a, b) => Number(b.tvl) - Number(a.tvl)).slice(0, topN);
+            if (sorted.length === 0)
+                return { output: 'DefiLlama returned no chains.' };
+            const lines = [`## TVL by chain — top ${sorted.length}`];
+            sorted.forEach((c, i) => {
+                const sym = c.tokenSymbol ? ` (${c.tokenSymbol})` : '';
+                lines.push(`${i + 1}. **${c.name}**${sym} — ${formatUsd(Number(c.tvl))}`);
+            });
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const defiLlamaYieldsCapability = {
+    spec: {
+        name: 'DeFiLlamaYields',
+        description: 'Search DeFi yield pools (lending, LPs, vaults, staking) by symbol/chain/project, ranked by APY. ' +
+            'Returns top-N pools (default 10). $0.005 per call. ' +
+            'Default filters: TVL > $1M (avoid microcaps), APY > 0. Override via params. ' +
+            'Use stablecoin_only=true for "where can my USDC earn?" queries.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                symbol: { type: 'string', description: 'Token symbol filter (e.g. "USDC", "ETH"). Matches tokens in the pool.' },
+                chain: { type: 'string', description: 'Chain filter (e.g. "Ethereum", "Solana", "Base").' },
+                project: { type: 'string', description: 'DefiLlama project slug filter (e.g. "aave-v3", "lido", "kamino").' },
+                min_tvl_usd: { type: 'number', description: 'Minimum pool TVL in USD (default 1_000_000).' },
+                min_apy_pct: { type: 'number', description: 'Minimum APY in percent (default 0).' },
+                stablecoin_only: { type: 'boolean', description: 'If true, only stablecoin pools.' },
+                top_n: { type: 'number', description: 'Max results (default 10, hard cap 50).' },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        const topN = Math.min(Math.max(1, params.top_n ?? 10), 50);
+        const minTvl = params.min_tvl_usd ?? 1_000_000;
+        const minApy = params.min_apy_pct ?? 0;
+        try {
+            const res = await getWithPayment('/v1/defillama/yields', ctx);
+            const pools = res.data ?? [];
+            let filtered = pools.filter((p) => (p.apy ?? -1) >= minApy && (p.tvlUsd ?? 0) >= minTvl);
+            if (params.symbol) {
+                const want = params.symbol.toUpperCase();
+                filtered = filtered.filter((p) => p.symbol?.toUpperCase().includes(want));
+            }
+            if (params.chain) {
+                const want = params.chain.toLowerCase();
+                filtered = filtered.filter((p) => p.chain?.toLowerCase() === want);
+            }
+            if (params.project) {
+                const want = params.project.toLowerCase();
+                filtered = filtered.filter((p) => p.project?.toLowerCase() === want);
+            }
+            if (params.stablecoin_only) {
+                filtered = filtered.filter((p) => p.stablecoin === true);
+            }
+            filtered.sort((a, b) => (b.apy ?? 0) - (a.apy ?? 0));
+            const top = filtered.slice(0, topN);
+            if (top.length === 0)
+                return { output: 'No yield pools matched the filters.' };
+            const filterDesc = [
+                params.symbol && `symbol=${params.symbol}`,
+                params.chain && `chain=${params.chain}`,
+                params.project && `project=${params.project}`,
+                params.stablecoin_only && 'stablecoin_only',
+                `min_tvl=${formatUsd(minTvl)}`,
+                `min_apy=${minApy}%`,
+            ]
+                .filter(Boolean)
+                .join(' · ');
+            const lines = [`## Yield pools — top ${top.length} by APY · ${filterDesc}`];
+            top.forEach((p, i) => {
+                const breakdown = p.apyBase != null && p.apyReward != null
+                    ? ` (base ${p.apyBase.toFixed(2)}% + reward ${p.apyReward.toFixed(2)}%)`
+                    : '';
+                const il = p.ilRisk ? ` · IL: ${p.ilRisk}` : '';
+                lines.push(`${i + 1}. **${p.project}** / ${p.chain} / ${p.symbol} — ${(p.apy ?? 0).toFixed(2)}% APY${breakdown}\n   TVL: ${formatUsd(p.tvlUsd)}${il} · pool: ${p.pool}`);
+            });
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};
+export const defiLlamaPriceCapability = {
+    spec: {
+        name: 'DeFiLlamaPrice',
+        description: 'Token price lookup via DefiLlama (covers thousands of tokens — anything DEX-listed). $0.001 per call. ' +
+            'Coin identifier syntax: "{platform}:{address}" or "coingecko:{slug}". ' +
+            'Examples: "coingecko:bitcoin" (BTC USD), "ethereum:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" (WETH), ' +
+            '"solana:So11111111111111111111111111111111111111112" (SOL/wSOL), ' +
+            '"solana:DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" (BONK). ' +
+            'Pass multiple identifiers for batch lookup. ' +
+            'Use the existing /v1/crypto/price/{symbol} endpoint via TradingMarket for the major-asset shorthand instead — ' +
+            'this tool is for arbitrary on-chain mints / addresses.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                coins: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Coin identifiers in DefiLlama syntax. Up to 50 per call.',
+                },
+            },
+            required: ['coins'],
+        },
+    },
+    execute: async (input, ctx) => {
+        const params = input;
+        if (!params.coins || params.coins.length === 0) {
+            return { output: 'Error: coins array is required', isError: true };
+        }
+        if (params.coins.length > 50) {
+            return { output: `Error: max 50 coins per call (got ${params.coins.length})`, isError: true };
+        }
+        try {
+            const safeList = params.coins.map((c) => encodeURIComponent(c.trim())).join(',');
+            const res = await getWithPayment(`/v1/defillama/prices/${safeList}`, ctx);
+            const coins = res.coins ?? {};
+            const lines = [`## Token prices — ${Object.keys(coins).length} match(es)`];
+            for (const id of params.coins) {
+                const entry = coins[id];
+                if (!entry || entry.price == null) {
+                    lines.push(`- ${id}: no price returned`);
+                    continue;
+                }
+                const sym = entry.symbol ? ` (${entry.symbol})` : '';
+                const conf = entry.confidence != null ? ` · conf ${(entry.confidence * 100).toFixed(0)}%` : '';
+                const ts = entry.timestamp ? ` · ${new Date(entry.timestamp * 1000).toISOString().slice(0, 19)}Z` : '';
+                lines.push(`- **${id}**${sym}: $${entry.price.toFixed(entry.price < 0.01 ? 8 : 4)}${conf}${ts}`);
+            }
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: `Error: ${err.message}`, isError: true };
+        }
+    },
+    concurrent: true,
+};

package/dist/tools/index.js

@@ -26,6 +26,7 @@ import { moaCapability } from './moa.js';
 import { webhookPostCapability } from './webhook.js';
 import { walletCapability } from './wallet.js';
 import { jupiterQuoteCapability, jupiterSwapCapability } from './jupiter.js';
+import { defiLlamaProtocolsCapability, defiLlamaProtocolCapability, defiLlamaChainsCapability, defiLlamaYieldsCapability, defiLlamaPriceCapability, } from './defillama.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -147,6 +148,11 @@ export const allCapabilities = [
     walletCapability,
     jupiterQuoteCapability,
     jupiterSwapCapability,
+    defiLlamaProtocolsCapability,
+    defiLlamaProtocolCapability,
+    defiLlamaChainsCapability,
+    defiLlamaYieldsCapability,
+    defiLlamaPriceCapability,
 ];
 export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, detachCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/jupiter.js

@@ -27,6 +27,47 @@ const BLOCKRUN_REFERRAL_FEE_BPS = 20; // 0.2% — Jupiter docs default; well bel
 const ULTRA_BASE = 'https://lite-api.jup.ag/ultra/v1';
 const ORDER_TIMEOUT_MS = 15_000;
 const EXECUTE_TIMEOUT_MS = 30_000;
+// ─── Session safety: cumulative live-swap counter ─────────────────────────
+// We removed the per-turn $-cap in v3.11.0 because it kept firing on legit
+// LLM workloads — but a live on-chain swap is irreversible, so a cap here is
+// different in kind. Default 10 swaps per Franklin process; user can override
+// via FRANKLIN_LIVE_SWAP_CAP env (set to 0 to disable). Resets on restart.
+const DEFAULT_LIVE_SWAP_CAP = 10;
+const liveSwapCap = (() => {
+    const raw = process.env.FRANKLIN_LIVE_SWAP_CAP;
+    if (!raw)
+        return DEFAULT_LIVE_SWAP_CAP;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return DEFAULT_LIVE_SWAP_CAP;
+    if (n <= 0)
+        return Infinity;
+    return Math.floor(n);
+})();
+let liveSwapCount = 0;
+// ─── Large-swap warning threshold ────────────────────────────────────────
+// USD value above which we surface a "Large swap" line in the AskUser
+// confirm — only computable when input is a known stablecoin. Override via
+// FRANKLIN_LIVE_SWAP_WARN_USD env (default $20).
+const DEFAULT_LARGE_SWAP_USD = 20;
+const largeSwapThresholdUsd = (() => {
+    const raw = process.env.FRANKLIN_LIVE_SWAP_WARN_USD;
+    if (!raw)
+        return DEFAULT_LARGE_SWAP_USD;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_LARGE_SWAP_USD;
+    return n;
+})();
+const STABLECOIN_MINTS = new Set([
+    'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+    'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB', // USDT
+]);
+function estimateUsdValue(inputMint, humanAmount) {
+    if (STABLECOIN_MINTS.has(inputMint))
+        return humanAmount;
+    return null; // unknown — caller will surface a "couldn't price" warning instead
+}
 // ─── Symbol → mint shortcuts ──────────────────────────────────────────────
 // Agents prefer "USDC" / "SOL" over 44-char base58 mint addresses. Anything
 // not in this map is passed through verbatim — power users can drop in any
@@ -180,22 +221,37 @@ async function executeJupiterQuote(input) {
     }
 }
 async function executeJupiterSwap(input, ctx) {
+    // Session-cap pre-check (cheapest, fail fast).
+    if (liveSwapCount >= liveSwapCap) {
+        return {
+            output: `Live-swap session cap reached (${liveSwapCount}/${liveSwapCap}). ` +
+                `Stopping to protect your wallet — this is a deliberate guardrail, not an error in your prompt.\n\n` +
+                `To raise: \`FRANKLIN_LIVE_SWAP_CAP=20 franklin\` (or 0 to disable).\n` +
+                `To continue with a fresh count: restart Franklin (\`exit\` then re-launch).`,
+            isError: true,
+        };
+    }
     const inputMint = resolveMint(input.input_mint);
     const outputMint = resolveMint(input.output_mint);
     const inDec = decimalsFor(inputMint);
     const amountAtomic = toAtomicUnits(input.amount, inDec);
-    // Load wallet first — fail fast if Solana isn't set up.
+    // Load wallet — `getOrCreateSolanaWallet` auto-creates on first run, so this
+    // path firing means the file is corrupt or the .blockrun dir is unreadable.
     let keypair;
     try {
         keypair = await loadSolanaKeypair();
     }
     catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
         return {
-            output: `No Solana wallet found. Run \`franklin setup solana\` to generate one, or check ~/.blockrun/solana-wallet.json.\n` +
-                `(${err instanceof Error ? err.message : 'unknown error'})`,
+            output: `Couldn't load your Solana wallet. ` +
+                `Run \`franklin setup solana\` to (re)generate one. ` +
+                `If that's already worked before, check ~/.blockrun/solana-wallet.json is readable.\n\n` +
+                `Underlying error: ${msg}`,
             isError: true,
         };
     }
+    const walletAddress = keypair.publicKey.toBase58();
     // Step 1 — fetch order with our referral identity attached.
     let order;
     try {
@@ -203,7 +259,7 @@ async function executeJupiterSwap(input, ctx) {
             inputMint,
             outputMint,
             amount: amountAtomic,
-            taker: keypair.publicKey.toBase58(),
+            taker: walletAddress,
         });
     }
     catch (err) {
@@ -221,8 +277,16 @@ async function executeJupiterSwap(input, ctx) {
     // Step 2 — confirm with user (unless explicit auto_approve override).
     if (!input.auto_approve && ctx.onAskUser) {
         const quoteText = formatQuote(order);
-        const question = `Execute this Jupiter swap?\n\n${quoteText}\n\nWallet: ${keypair.publicKey.toBase58()}`;
-        const answer = await ctx.onAskUser(question, ['Confirm', 'Cancel']);
+        const usdEst = estimateUsdValue(inputMint, input.amount);
+        const sections = ['Execute this Jupiter swap?', '', quoteText];
+        if (usdEst != null && usdEst >= largeSwapThresholdUsd) {
+            sections.push('', `⚠ Large swap warning — input is ~$${usdEst.toFixed(2)} (above $${largeSwapThresholdUsd} threshold). Confirm only if this matches your intent.`);
+        }
+        else if (usdEst == null) {
+            sections.push('', `Note: input is not a stablecoin, so I cannot price-check this in USD before signing. Verify the output amount matches your intent.`);
+        }
+        sections.push('', `Wallet: ${walletAddress}`, `Live-swap session count: ${liveSwapCount}/${liveSwapCap === Infinity ? '∞' : liveSwapCap}`);
+        const answer = await ctx.onAskUser(sections.join('\n'), ['Confirm', 'Cancel']);
         if (answer.toLowerCase() !== 'confirm') {
             return { output: 'Swap cancelled by user.' };
         }
@@ -248,6 +312,19 @@ async function executeJupiterSwap(input, ctx) {
             requestId: order.requestId,
         });
         if (exec.status !== 'Success') {
+            const errStr = (exec.error ?? '').toLowerCase();
+            const looksInsufficient = errStr.includes('insufficient') ||
+                errStr.includes('lamports') ||
+                errStr.includes('tokenaccountnotfound') ||
+                errStr.includes('not enough');
+            if (looksInsufficient) {
+                return {
+                    output: `Swap failed: insufficient balance. Your Solana wallet (${walletAddress}) does not hold enough of the input token.\n\n` +
+                        `Send ${symbolFor(inputMint)} to that address (or fund it via the Franklin UI), then retry.\n\n` +
+                        `Underlying error: ${exec.error ?? exec.code ?? 'unknown'}`,
+                    isError: true,
+                };
+            }
             return {
                 output: `Jupiter Ultra /execute reported ${exec.status}` +
                     (exec.error ? `: ${exec.error}` : '') +
@@ -255,6 +332,7 @@ async function executeJupiterSwap(input, ctx) {
                 isError: true,
             };
         }
+        liveSwapCount += 1;
         const sig = exec.signature ?? '<unknown>';
         const explorer = `https://solscan.io/tx/${sig}`;
         return {
@@ -263,6 +341,7 @@ async function executeJupiterSwap(input, ctx) {
                 formatQuote(order),
                 `Signature: ${sig}`,
                 explorer,
+                `(Session live-swap count: ${liveSwapCount}/${liveSwapCap === Infinity ? '∞' : liveSwapCap})`,
             ].join('\n'),
         };
     }

package/package.json

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