@blockrun/franklin 3.12.2 → 3.13.0

package/dist/agent/context.js

@@ -213,6 +213,12 @@ You run on the BlockRun AI Gateway. When the user asks you to "test the BlockRun
 - Use the **\`JupiterQuote\` and \`JupiterSwap\` built-in tools** — they call Jupiter's Ultra API directly from this process. The user is the first-party caller of Jupiter; we are not a gateway proxy here. A 20 bps platform fee is collected on-chain as part of the swap (Jupiter Referral Program — official integrator mechanism, not a hidden cost).
 - Do NOT try to call \`/v1/jupiter/...\` on the BlockRun gateway — there is no such endpoint (Jupiter ToU forbids the gateway-proxy model).
 
+**Base DEX swap (0x V2 Permit2)**
+- Use the **\`Base0xQuote\` and \`Base0xSwap\` built-in tools** for swaps on Base (chain id 8453). Mirrors Jupiter's local-call posture: 0x's API is hit directly, the user signs the Permit2 EIP-712 with their Base keypair, the tx settles on Base RPC. 0x's official affiliate program embeds 20 bps in the sell-token automatically (BlockRun affiliate, on-chain).
+- Symbol shortcuts pre-mapped: ETH (native), WETH, USDC, USDT, CBBTC, CBETH, AERO, DAI. Raw \`0x...\` addresses pass through.
+- **Each Franklin user supplies their OWN \`ZERO_EX_API_KEY\`** (free, no credit card, 10 req/s — sign up at https://dashboard.0x.org). The affiliate cut routes to BlockRun via the swap query params regardless of whose API key is making the call. If the swap tool errors with the env-var message, repeat the URL to the user — do not try to set the env yourself or invent a key.
+- For native ETH → token: no Permit2 approval needed (native value path). For ERC-20 → token: first-time-per-token Permit2 approval auto-runs before the swap (one-time gas cost; future swaps of the same sell-token reuse it).
+
 **Sandbox (POST, x402-paid)**
 - \`/v1/modal/{...path}\` — Modal GPU sandbox passthrough (create/exec/etc.).
 - \`/v1/pm/{...path}\` — prediction-market data passthrough.
@@ -232,6 +238,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.
@@ -300,6 +353,7 @@ export function assembleInstructions(workingDir, model) {
         getMissingAccessSection(),
         getWalletKnowledgeSection(),
         getBlockRunApiSection(),
+        getTradingPlaybookSection(),
         getToolPatternsSection(),
         getTokenEfficiencySection(),
         getVerificationSection(),

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 { base0xQuoteCapability, base0xSwapCapability } from './zerox-base.js';
 import { defiLlamaProtocolsCapability, defiLlamaProtocolCapability, defiLlamaChainsCapability, defiLlamaYieldsCapability, defiLlamaPriceCapability, } from './defillama.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
@@ -148,6 +149,8 @@ export const allCapabilities = [
     walletCapability,
     jupiterQuoteCapability,
     jupiterSwapCapability,
+    base0xQuoteCapability,
+    base0xSwapCapability,
     defiLlamaProtocolsCapability,
     defiLlamaProtocolCapability,
     defiLlamaChainsCapability,

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/dist/tools/zerox-base.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 0x Swap API V2 (Permit2) — Franklin built-in tools for Base trading.
+ *
+ * Same posture as the JupiterSwap tools, different chain + aggregator:
+ *   - Calls 0x's API directly from this Franklin process (the user is the
+ *     first-party caller; we are not a gateway proxy → no ToS violation).
+ *   - Embeds BlockRun's affiliate identity in every quote (`swapFeeRecipient`
+ *     + `swapFeeBps` + `swapFeeToken`). Fee flows on-chain to BlockRun at
+ *     swap settlement — 0x's officially-supported integrator monetization.
+ *   - User signs locally with their existing Base/EVM keypair (via @blockrun/
+ *     llm's `getOrCreateWallet`); we never custody.
+ *
+ * Two tools exposed:
+ *   - Base0xQuote — indicative price, free, no signing
+ *   - Base0xSwap  — full quote → sign Permit2 → submit raw tx → BaseScan link
+ *
+ * Reference (official 0x example):
+ *   https://github.com/0xProject/0x-examples/tree/main/swap-v2-permit2-headless-example
+ *
+ * Required env:
+ *   ZERO_EX_API_KEY  — get one free at https://dashboard.0x.org
+ *   BASE_RPC_URL     — optional override; defaults to public Base RPC
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const base0xQuoteCapability: CapabilityHandler;
+export declare const base0xSwapCapability: CapabilityHandler;

package/dist/tools/zerox-base.js

@@ -0,0 +1,472 @@
+/**
+ * 0x Swap API V2 (Permit2) — Franklin built-in tools for Base trading.
+ *
+ * Same posture as the JupiterSwap tools, different chain + aggregator:
+ *   - Calls 0x's API directly from this Franklin process (the user is the
+ *     first-party caller; we are not a gateway proxy → no ToS violation).
+ *   - Embeds BlockRun's affiliate identity in every quote (`swapFeeRecipient`
+ *     + `swapFeeBps` + `swapFeeToken`). Fee flows on-chain to BlockRun at
+ *     swap settlement — 0x's officially-supported integrator monetization.
+ *   - User signs locally with their existing Base/EVM keypair (via @blockrun/
+ *     llm's `getOrCreateWallet`); we never custody.
+ *
+ * Two tools exposed:
+ *   - Base0xQuote — indicative price, free, no signing
+ *   - Base0xSwap  — full quote → sign Permit2 → submit raw tx → BaseScan link
+ *
+ * Reference (official 0x example):
+ *   https://github.com/0xProject/0x-examples/tree/main/swap-v2-permit2-headless-example
+ *
+ * Required env:
+ *   ZERO_EX_API_KEY  — get one free at https://dashboard.0x.org
+ *   BASE_RPC_URL     — optional override; defaults to public Base RPC
+ */
+import { createWalletClient, http, publicActions, concat, numberToHex, size, parseUnits, formatUnits, maxUint256, erc20Abi, getContract, } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import { getOrCreateWallet } from '@blockrun/llm';
+// ─── BlockRun affiliate identity on Base ─────────────────────────────────
+// Reuses the existing BlockRun ops wallet that already receives x402
+// settlements on Base. Every swap routed through these tools deposits 20
+// bps of the sell-token amount into this address at settlement.
+const BLOCKRUN_BASE_AFFILIATE = '0xe9030014F5DAe217d0A152f02A043567b16c1aBf';
+const BLOCKRUN_AFFILIATE_FEE_BPS = 20; // 0.2% — matches Jupiter Ultra path.
+// ─── 0x API endpoints ─────────────────────────────────────────────────────
+const ZEROX_BASE = 'https://api.0x.org/swap/permit2';
+const ZEROX_VERSION = 'v2';
+const ZEROX_TIMEOUT_MS = 20_000;
+// ─── Default Base RPC ────────────────────────────────────────────────────
+// Public Base mainnet endpoint. Override via BASE_RPC_URL env (Alchemy,
+// QuickNode public, etc.). The user-facing call is the swap submission;
+// quote fetches are off-chain.
+const DEFAULT_BASE_RPC = 'https://mainnet.base.org';
+// ─── Session safety: cumulative live-swap counter ─────────────────────────
+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;
+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;
+})();
+// ─── Base token map ──────────────────────────────────────────────────────
+// EVM addresses are case-sensitive in some libraries — store as checksum.
+const NATIVE_ETH = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
+const SYMBOL_TO_ADDRESS = {
+    ETH: NATIVE_ETH,
+    WETH: '0x4200000000000000000000000000000000000006',
+    USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    USDT: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
+    CBBTC: '0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf',
+    CBETH: '0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22',
+    AERO: '0x940181a94A35A4569E4529A3CDfB74e38FD98631',
+    DAI: '0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb',
+};
+const TOKEN_DECIMALS = {
+    [NATIVE_ETH.toLowerCase()]: 18,
+    '0x4200000000000000000000000000000000000006': 18, // WETH
+    '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': 6, // USDC
+    '0xfde4c96c8593536e31f229ea8f37b2ada2699bb2': 6, // USDT
+    '0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf': 8, // CBBTC
+    '0x2ae3f1ec7f1f5012cfeab0185bfc7aa3cf0dec22': 18, // CBETH
+    '0x940181a94a35a4569e4529a3cdfb74e38fd98631': 18, // AERO
+    '0x50c5725949a6f0c72e6c4a641f24049a917db0cb': 18, // DAI
+};
+const STABLECOIN_ADDRESSES = new Set([
+    '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC
+    '0xfde4c96c8593536e31f229ea8f37b2ada2699bb2', // USDT
+    '0x50c5725949a6f0c72e6c4a641f24049a917db0cb', // DAI
+]);
+function resolveTokenAddress(input) {
+    const upper = input.trim().toUpperCase();
+    if (SYMBOL_TO_ADDRESS[upper])
+        return SYMBOL_TO_ADDRESS[upper];
+    return input.trim();
+}
+function decimalsFor(address) {
+    const lower = address.toLowerCase();
+    return TOKEN_DECIMALS[lower] ?? 18;
+}
+function symbolFor(address) {
+    const lower = address.toLowerCase();
+    for (const [sym, addr] of Object.entries(SYMBOL_TO_ADDRESS)) {
+        if (addr.toLowerCase() === lower)
+            return sym;
+    }
+    return `${address.slice(0, 6)}…${address.slice(-4)}`;
+}
+function isStablecoin(address) {
+    return STABLECOIN_ADDRESSES.has(address.toLowerCase());
+}
+function estimateUsdValue(sellTokenAddr, humanAmount) {
+    if (isStablecoin(sellTokenAddr))
+        return humanAmount;
+    return null; // unknown — caller surfaces a "couldn't price" notice
+}
+function isNativeEth(addr) {
+    return addr.toLowerCase() === NATIVE_ETH.toLowerCase();
+}
+// ─── Wallet + client setup ───────────────────────────────────────────────
+async function loadEvmWallet() {
+    const raw = await getOrCreateWallet();
+    // @blockrun/llm returns { privateKey: '0x...', address: '0x...' } — use it
+    // verbatim for viem.
+    const account = privateKeyToAccount(raw.privateKey);
+    return { account, address: raw.address };
+}
+function makeClient(account) {
+    const rpcUrl = process.env.BASE_RPC_URL || DEFAULT_BASE_RPC;
+    return createWalletClient({
+        account,
+        chain: base,
+        transport: http(rpcUrl),
+    }).extend(publicActions);
+}
+function zeroxHeaders() {
+    const apiKey = process.env.ZERO_EX_API_KEY;
+    if (!apiKey) {
+        throw new Error("Base swaps need a 0x API key. Each Franklin user sets their own (free, no credit card): " +
+            "1) Sign up at https://dashboard.0x.org · " +
+            "2) Copy the API key from the Demo App or your own app · " +
+            "3) Run `ZERO_EX_API_KEY=zx_... franklin` (or add it to ~/.zshrc / ~/.bashrc). " +
+            "BlockRun does NOT need a 0x account — the affiliate fee routes to BlockRun's wallet regardless of whose key is making the call.");
+    }
+    return {
+        'Content-Type': 'application/json',
+        '0x-api-key': apiKey,
+        '0x-version': ZEROX_VERSION,
+    };
+}
+// ─── 0x API calls ────────────────────────────────────────────────────────
+async function zeroxFetch(path, params) {
+    const url = `${ZEROX_BASE}/${path}?${params.toString()}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ZEROX_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { headers: zeroxHeaders(), signal: controller.signal });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`0x ${path} returned ${res.status}: ${text.slice(0, 300)}`);
+        }
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function buildSwapParams(args) {
+    const p = new URLSearchParams({
+        chainId: String(base.id),
+        sellToken: args.sellTokenAddr,
+        buyToken: args.buyTokenAddr,
+        sellAmount: args.sellAmountAtomic,
+        taker: args.taker,
+    });
+    if (args.feeRecipient && args.feeBps && args.feeBps > 0 && args.feeToken) {
+        p.set('swapFeeRecipient', args.feeRecipient);
+        p.set('swapFeeBps', String(args.feeBps));
+        p.set('swapFeeToken', args.feeToken);
+    }
+    return p;
+}
+// ─── Formatting ──────────────────────────────────────────────────────────
+function formatQuoteText(q) {
+    const sellDec = decimalsFor(q.sellToken);
+    const buyDec = decimalsFor(q.buyToken);
+    const sellHuman = Number(formatUnits(BigInt(q.sellAmount), sellDec));
+    const buyHuman = Number(formatUnits(BigInt(q.buyAmount), buyDec));
+    const sellSym = symbolFor(q.sellToken);
+    const buySym = symbolFor(q.buyToken);
+    const rate = sellHuman > 0 ? buyHuman / sellHuman : 0;
+    const route = q.route?.fills?.map((f) => f.source).filter(Boolean).slice(0, 4).join(' → ') ||
+        '0x V2 router';
+    const minOut = q.minBuyAmount
+        ? Number(formatUnits(BigInt(q.minBuyAmount), buyDec))
+        : null;
+    const lines = [
+        `${sellHuman.toFixed(Math.min(8, sellDec))} ${sellSym} → ${buyHuman.toFixed(Math.min(8, buyDec))} ${buySym}`,
+        `Rate: 1 ${sellSym} ≈ ${rate.toPrecision(6)} ${buySym}`,
+    ];
+    if (minOut != null) {
+        lines.push(`Min received: ${minOut.toFixed(Math.min(8, buyDec))} ${buySym}`);
+    }
+    lines.push(`Route: ${route}`);
+    lines.push(`Affiliate fee: ${BLOCKRUN_AFFILIATE_FEE_BPS} bps (BlockRun affiliate, taken in ${sellSym})`);
+    return lines.join('\n');
+}
+// ─── Quote (read-only) ───────────────────────────────────────────────────
+async function executeBase0xQuote(input) {
+    let walletAddress;
+    try {
+        const wallet = await loadEvmWallet();
+        walletAddress = wallet.address;
+    }
+    catch (err) {
+        return {
+            output: `Couldn't load Base wallet: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+        };
+    }
+    const sellTokenAddr = resolveTokenAddress(input.sell_token);
+    const buyTokenAddr = resolveTokenAddress(input.buy_token);
+    const sellDec = decimalsFor(sellTokenAddr);
+    const sellAmount = parseUnits(input.sell_amount.toString(), sellDec).toString();
+    const params = buildSwapParams({
+        sellTokenAddr,
+        buyTokenAddr,
+        sellAmountAtomic: sellAmount,
+        taker: walletAddress,
+        feeRecipient: BLOCKRUN_BASE_AFFILIATE,
+        feeBps: BLOCKRUN_AFFILIATE_FEE_BPS,
+        // Take the fee in the sell token so it's deterministic and doesn't
+        // depend on the output token having an existing recipient ATA / balance.
+        feeToken: sellTokenAddr,
+    });
+    try {
+        const price = await zeroxFetch('price', params);
+        if (!price.liquidityAvailable && price.liquidityAvailable !== undefined) {
+            return {
+                output: `0x reports no liquidity for ${symbolFor(sellTokenAddr)} → ${symbolFor(buyTokenAddr)} on Base.`,
+                isError: true,
+            };
+        }
+        return { output: formatQuoteText(price) };
+    }
+    catch (err) {
+        return { output: `0x /price failed: ${err instanceof Error ? err.message : String(err)}`, isError: true };
+    }
+}
+// ─── Swap (full execute) ─────────────────────────────────────────────────
+async function executeBase0xSwap(input, ctx) {
+    if (liveSwapCount >= liveSwapCap) {
+        return {
+            output: `Live-swap session cap reached (${liveSwapCount}/${liveSwapCap}). Stopping to protect your wallet.\n` +
+                `Override with FRANKLIN_LIVE_SWAP_CAP=20 (or 0 to disable), or restart Franklin to reset.`,
+            isError: true,
+        };
+    }
+    let wallet;
+    try {
+        wallet = await loadEvmWallet();
+    }
+    catch (err) {
+        return {
+            output: `Couldn't load Base wallet. Run \`franklin setup\` to (re)generate a Base wallet, ` +
+                `or check ~/.blockrun/.session.\n\nUnderlying error: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+        };
+    }
+    const client = makeClient(wallet.account);
+    const sellTokenAddr = resolveTokenAddress(input.sell_token);
+    const buyTokenAddr = resolveTokenAddress(input.buy_token);
+    const sellDec = decimalsFor(sellTokenAddr);
+    const sellAmount = parseUnits(input.sell_amount.toString(), sellDec).toString();
+    const params = buildSwapParams({
+        sellTokenAddr,
+        buyTokenAddr,
+        sellAmountAtomic: sellAmount,
+        taker: wallet.address,
+        feeRecipient: BLOCKRUN_BASE_AFFILIATE,
+        feeBps: BLOCKRUN_AFFILIATE_FEE_BPS,
+        feeToken: sellTokenAddr,
+    });
+    // Step 1 — fetch the firm quote (returns tx + permit2.eip712 to sign).
+    let quote;
+    try {
+        quote = await zeroxFetch('quote', params);
+    }
+    catch (err) {
+        return {
+            output: `0x /quote failed: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+        };
+    }
+    if (!quote.transaction) {
+        return {
+            output: `0x returned no transaction — likely no liquidity for this pair.`,
+            isError: true,
+        };
+    }
+    // Step 2 — confirm with user (unless explicit auto_approve override).
+    if (!input.auto_approve && ctx.onAskUser) {
+        const quoteText = formatQuoteText(quote);
+        const usdEst = estimateUsdValue(sellTokenAddr, input.sell_amount);
+        const sections = ['Execute this 0x swap on Base?', '', quoteText];
+        if (usdEst != null && usdEst >= largeSwapThresholdUsd) {
+            sections.push('', `⚠ Large swap warning — input is ~$${usdEst.toFixed(2)} (above $${largeSwapThresholdUsd} threshold).`);
+        }
+        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: ${wallet.address}`, `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.' };
+        }
+    }
+    // Step 3 — for ERC-20 sell tokens, ensure Permit2 has an allowance.
+    // Native ETH skips this entirely.
+    if (!isNativeEth(sellTokenAddr)) {
+        const allowanceIssue = quote.issues?.allowance ?? null;
+        if (allowanceIssue) {
+            try {
+                const erc20 = getContract({ address: sellTokenAddr, abi: erc20Abi, client });
+                const { request } = await erc20.simulate.approve([allowanceIssue.spender, maxUint256]);
+                const approveHash = await erc20.write.approve(request.args);
+                await client.waitForTransactionReceipt({ hash: approveHash });
+            }
+            catch (err) {
+                return {
+                    output: `Permit2 approval failed for ${symbolFor(sellTokenAddr)}: ${err instanceof Error ? err.message : String(err)}\n` +
+                        `This is a one-time setup step per token; retry the swap and it should succeed.`,
+                    isError: true,
+                };
+            }
+        }
+        // Step 4 — sign the Permit2 EIP-712 typed-data and append signature to
+        // transaction.data per the canonical 0x recipe.
+        if (!quote.permit2?.eip712) {
+            return {
+                output: '0x quote did not include permit2.eip712 — non-Permit2 path required, not yet supported.',
+                isError: true,
+            };
+        }
+        let signature;
+        try {
+            signature = await client.signTypedData(quote.permit2.eip712);
+        }
+        catch (err) {
+            return {
+                output: `Permit2 signing failed: ${err instanceof Error ? err.message : String(err)}`,
+                isError: true,
+            };
+        }
+        const sigLengthHex = numberToHex(size(signature), { signed: false, size: 32 });
+        quote.transaction.data = concat([quote.transaction.data, sigLengthHex, signature]);
+    }
+    // Step 5 — submit. Native ETH path uses sendTransaction (with value);
+    // ERC-20 path uses signTransaction + sendRawTransaction (matches the
+    // official 0x example to avoid double-signing pitfalls).
+    let txHash;
+    try {
+        if (isNativeEth(sellTokenAddr)) {
+            txHash = await client.sendTransaction({
+                account: wallet.account,
+                chain: base,
+                to: quote.transaction.to,
+                data: quote.transaction.data,
+                value: BigInt(quote.transaction.value),
+                gas: quote.transaction.gas ? BigInt(quote.transaction.gas) : undefined,
+                gasPrice: quote.transaction.gasPrice ? BigInt(quote.transaction.gasPrice) : undefined,
+            });
+        }
+        else {
+            const nonce = await client.getTransactionCount({ address: wallet.address });
+            const signedTx = await client.signTransaction({
+                account: wallet.account,
+                chain: base,
+                to: quote.transaction.to,
+                data: quote.transaction.data,
+                gas: quote.transaction.gas ? BigInt(quote.transaction.gas) : undefined,
+                gasPrice: quote.transaction.gasPrice ? BigInt(quote.transaction.gasPrice) : undefined,
+                nonce,
+            });
+            txHash = await client.sendRawTransaction({ serializedTransaction: signedTx });
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const lower = msg.toLowerCase();
+        if (lower.includes('insufficient') ||
+            lower.includes('exceeds balance') ||
+            lower.includes('not enough')) {
+            return {
+                output: `Swap failed: insufficient balance. Your Base wallet (${wallet.address}) does not hold enough ${symbolFor(sellTokenAddr)}.\n\n` +
+                    `Send ${symbolFor(sellTokenAddr)} to that address (or fund it via Coinbase / a bridge), then retry.\n\n` +
+                    `Underlying error: ${msg}`,
+                isError: true,
+            };
+        }
+        return {
+            output: `Submit failed: ${msg}`,
+            isError: true,
+        };
+    }
+    liveSwapCount += 1;
+    const explorer = `https://basescan.org/tx/${txHash}`;
+    return {
+        output: [
+            '✓ Swap executed on Base.',
+            formatQuoteText(quote),
+            `Tx hash: ${txHash}`,
+            explorer,
+            `(Session live-swap count: ${liveSwapCount}/${liveSwapCap === Infinity ? '∞' : liveSwapCap})`,
+        ].join('\n'),
+    };
+}
+// ─── Capability handlers ─────────────────────────────────────────────────
+const COMMON_INPUT_PROPERTIES = {
+    sell_token: {
+        type: 'string',
+        description: "Sell-token address (Base EVM 0x... 42 chars), OR a symbol shortcut: ETH, WETH, USDC, USDT, CBBTC, CBETH, AERO, DAI.",
+    },
+    buy_token: {
+        type: 'string',
+        description: 'Buy-token address or symbol shortcut (same list as sell_token).',
+    },
+    sell_amount: {
+        type: 'number',
+        description: 'Amount of sell_token to swap, in human units (e.g. 0.01 ETH, 1.5 USDC). Decimals are looked up automatically for known tokens; defaults to 18 for unknown ERC-20s.',
+    },
+};
+export const base0xQuoteCapability = {
+    spec: {
+        name: 'Base0xQuote',
+        description: "Read-only price quote for a Base DEX swap via 0x V2. Returns sell/buy amounts, rate, minimum-received, route, and the BlockRun affiliate fee that would apply. Free — no on-chain transaction. Use before Base0xSwap to inspect the trade.",
+        input_schema: {
+            type: 'object',
+            required: ['sell_token', 'buy_token', 'sell_amount'],
+            properties: COMMON_INPUT_PROPERTIES,
+        },
+    },
+    execute: async (input) => {
+        return executeBase0xQuote(input);
+    },
+    concurrent: true,
+};
+export const base0xSwapCapability = {
+    spec: {
+        name: 'Base0xSwap',
+        description: "Execute a Base DEX swap via 0x V2 (Permit2). Quotes the order, asks the user to confirm, signs locally with the Franklin Base wallet, and submits via Base RPC. A 20 bps affiliate fee in the sell-token is collected on-chain by 0x as part of the swap (BlockRun affiliate program — official 0x integrator mechanism). Returns the BaseScan transaction link. Requires ZERO_EX_API_KEY env var (free at dashboard.0x.org).",
+        input_schema: {
+            type: 'object',
+            required: ['sell_token', 'buy_token', 'sell_amount'],
+            properties: {
+                ...COMMON_INPUT_PROPERTIES,
+                auto_approve: {
+                    type: 'boolean',
+                    description: 'If true, skip the AskUser confirm. Default false — agent should leave this false unless the user explicitly authorized this specific call.',
+                },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        return executeBase0xSwap(input, ctx);
+    },
+    concurrent: false,
+};

package/package.json

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