perp-cli 0.5.0 → 0.5.3

package/dist/index.js

@@ -322,16 +322,284 @@ const apiSpecCmd = program
     printJson(jsonOk(getCliSpec(program)));
 });
 apiSpecCmd._hidden = true;
-// Deprecated: perp status → use 'perp portfolio' or 'perp account'
-const statusCmd = program.command("status").description("Use 'perp portfolio'")
-    .option("--health", "Check connectivity").action(async (opts) => {
+// Unified dashboard: balances + positions + top arb opportunities
+program.command("status")
+    .description("Unified dashboard: balances, positions, and top arb opportunities")
+    .option("--health", "Check connectivity only")
+    .action(async (opts) => {
     if (opts.health) {
         const { runHealthCheck } = await import("./commands/risk.js");
         return runHealthCheck(isJson);
     }
-    console.log("Use 'perp portfolio' or 'perp account' instead.");
+    const json = isJson();
+    const { formatUsd, formatPnl, makeTable, printJson, jsonOk, withJsonErrors } = await import("./utils.js");
+    const { fetchAllFundingRates, TOP_SYMBOLS } = await import("./funding-rates.js");
+    const { saveFundingSnapshot, getHistoricalRates } = await import("./funding-history.js");
+    await withJsonErrors(json, async () => {
+        const EX_LIST = ["pacifica", "hyperliquid", "lighter"];
+        const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : "LT";
+        const snapshotPromises = EX_LIST.map(async (ex) => {
+            try {
+                const adapter = await getAdapterForExchange(ex);
+                const [balance, positions, orders] = await Promise.all([
+                    adapter.getBalance(), adapter.getPositions(), adapter.getOpenOrders(),
+                ]);
+                // Fetch spot balances for HL and LT (Pacifica is perp-only)
+                let spotHoldings = [];
+                let isUnified = false;
+                try {
+                    if (ex === "hyperliquid") {
+                        const { HyperliquidSpotAdapter } = await import("./exchanges/hyperliquid-spot.js");
+                        const hlSpot = new HyperliquidSpotAdapter(adapter);
+                        await hlSpot.init();
+                        const [raw, markets] = await Promise.all([hlSpot.getSpotBalances(), hlSpot.getSpotMarkets()]);
+                        const priceMap = new Map(markets.map(m => [m.baseToken.toUpperCase(), Number(m.markPrice)]));
+                        const strip = (t) => t.replace(/-SPOT$/i, "").toUpperCase();
+                        spotHoldings = raw.filter(b => Number(b.total) > 0).map(b => {
+                            const base = strip(b.token);
+                            return { ...b, valueUsd: base === "USDC" ? Number(b.total) : (priceMap.get(base) ?? 0) * Number(b.total) };
+                        });
+                        isUnified = !adapter.dex;
+                    }
+                    else if (ex === "lighter") {
+                        const { LighterAdapter } = await import("./exchanges/lighter.js");
+                        const { LighterSpotAdapter } = await import("./exchanges/lighter-spot.js");
+                        const ltSpot = new LighterSpotAdapter(adapter);
+                        await ltSpot.init();
+                        const [raw, markets] = await Promise.all([ltSpot.getSpotBalances(), ltSpot.getSpotMarkets()]);
+                        const priceMap = new Map(markets.map(m => [m.baseToken.toUpperCase(), Number(m.markPrice)]));
+                        spotHoldings = raw.filter(b => Number(b.total) > 0).map(b => ({
+                            ...b,
+                            valueUsd: b.token === "USDC" || b.token === "USDC_SPOT" ? Number(b.total) : (priceMap.get(b.token.toUpperCase()) ?? 0) * Number(b.total),
+                        }));
+                    }
+                }
+                catch { /* spot not available */ }
+                return { exchange: ex, connected: true, balance, positions, openOrders: orders.length, spotHoldings, isUnified, error: undefined };
+            }
+            catch (err) {
+                return { exchange: ex, connected: false, balance: null, positions: [], openOrders: 0, spotHoldings: [], isUnified: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        });
+        const arbPromise = fetchAllFundingRates({ symbols: TOP_SYMBOLS, minSpread: 0 }).catch(() => null);
+        const [snapshots, arbSnapshot] = await Promise.all([Promise.all(snapshotPromises), arbPromise]);
+        // Save funding snapshot for sparkline history
+        if (arbSnapshot) {
+            try {
+                const allRates = arbSnapshot.symbols.flatMap(s => s.rates);
+                if (allRates.length > 0)
+                    saveFundingSnapshot(allRates);
+            }
+            catch { /* */ }
+        }
+        // Build totals (include non-USDC spot value for unified accounts)
+        let totalEquity = 0;
+        let totalSpotValue = 0;
+        const allPositions = [];
+        const allSpotHoldings = [];
+        for (const s of snapshots) {
+            if (s.balance)
+                totalEquity += Number(s.balance.equity);
+            for (const p of s.positions)
+                allPositions.push({ ...p, exchange: s.exchange });
+            // For unified accounts (HL), USDC is already in perp equity — only add non-USDC spot
+            const displaySpot = s.isUnified
+                ? s.spotHoldings.filter(b => b.token.replace(/-SPOT$/i, "").toUpperCase() !== "USDC")
+                : s.spotHoldings;
+            const spotVal = displaySpot.reduce((sum, b) => sum + b.valueUsd, 0);
+            totalSpotValue += spotVal;
+            totalEquity += spotVal;
+            for (const b of displaySpot)
+                allSpotHoldings.push({ ...b, exchange: s.exchange });
+        }
+        // Top arb
+        const topArb = arbSnapshot
+            ? arbSnapshot.symbols.filter(s => s.maxSpreadAnnual >= 5).sort((a, b) => b.maxSpreadAnnual - a.maxSpreadAnnual).slice(0, 5)
+            : [];
+        // Risk
+        const marginUsed = snapshots.reduce((s, x) => s + (x.balance ? Number(x.balance.marginUsed) : 0), 0);
+        const marginPct = totalEquity > 0 ? (marginUsed / totalEquity) * 100 : 0;
+        const riskLevel = marginPct < 30 ? "LOW" : marginPct < 60 ? "MEDIUM" : "HIGH";
+        if (json) {
+            const now = new Date();
+            const h24 = new Date(now.getTime() - 24 * 3600_000);
+            return printJson(jsonOk({
+                version: _pkg.version,
+                totalEquity,
+                riskLevel,
+                exchanges: snapshots.map(s => ({
+                    name: s.exchange, connected: s.connected,
+                    equity: s.balance ? Number(s.balance.equity) : 0,
+                    available: s.balance ? Number(s.balance.available) : 0,
+                    spotHoldings: s.spotHoldings.filter(b => Number(b.total) > 0).map(b => ({
+                        token: b.token, total: b.total, available: b.available, valueUsd: b.valueUsd,
+                    })),
+                })),
+                totalSpotValue,
+                positions: allPositions,
+                topArbOpportunities: await (async () => {
+                    const { getHistoricalAverages: getAvgs } = await import("./funding-history.js");
+                    const syms = topArb.map(a => a.symbol);
+                    const avgs = syms.length > 0 ? getAvgs(syms, ["hyperliquid", "pacifica", "lighter"]) : new Map();
+                    return topArb.map(a => {
+                        const bestEx = a.rates.find(r => r.exchange === "hyperliquid")?.exchange ?? a.rates[0]?.exchange ?? "hyperliquid";
+                        const avg = avgs.get(`${a.symbol}:${bestEx}`);
+                        return {
+                            symbol: a.symbol, spreadAnnual: a.maxSpreadAnnual,
+                            direction: `${exAbbr(a.shortExchange)}>${exAbbr(a.longExchange)}`,
+                            avg24h: avg?.avg24h != null ? Math.abs(avg.avg24h) * 8760 * 100 : null,
+                            avg7d: avg?.avg7d != null ? Math.abs(avg.avg7d) * 8760 * 100 : null,
+                            rateHistory: getHistoricalRates(a.symbol, bestEx, h24, now).map(h => ({ ts: h.ts, hourlyRate: h.hourlyRate })),
+                        };
+                    });
+                })(),
+            }));
+        }
+        // ── Terminal UI ──
+        console.log(chalk.cyan.bold(`\n  perp-cli v${_pkg.version}`) + chalk.gray(` — ${snapshots.filter(s => s.connected).length} exchanges connected\n`));
+        // Balance bars + Top Arb side by side
+        const now = new Date();
+        const h24 = new Date(now.getTime() - 24 * 3600_000);
+        // Left column: Balances (perp + spot per exchange)
+        // Compute per-exchange totals: perp equity + non-USDC spot (unified) or all spot
+        const exTotals = snapshots.map(s => {
+            if (!s.connected || !s.balance)
+                return { total: 0, margin: 0, equity: 0 };
+            const equity = Number(s.balance.equity);
+            const margin = Number(s.balance.marginUsed);
+            const displaySpot = s.isUnified
+                ? s.spotHoldings.filter(b => b.token.replace(/-SPOT$/i, "").toUpperCase() !== "USDC")
+                : s.spotHoldings;
+            const spotVal = displaySpot.reduce((sum, b) => sum + b.valueUsd, 0);
+            return { total: equity + spotVal, margin, equity };
+        });
+        const balLines = [];
+        balLines.push(chalk.white.bold(" Balances"));
+        for (let i = 0; i < snapshots.length; i++) {
+            const s = snapshots[i];
+            if (!s.connected) {
+                balLines.push(` ${chalk.gray(exAbbr(s.exchange).padEnd(4))} ${chalk.red("disconnected")}`);
+                continue;
+            }
+            const { total, margin, equity } = exTotals[i];
+            const usagePct = equity > 0 ? (margin / equity) * 100 : 0;
+            const barFull = Math.min(20, Math.round(usagePct / 5));
+            const usageColor = usagePct < 30 ? chalk.green : usagePct < 60 ? chalk.yellow : chalk.red;
+            const bar = usageColor("\u2588".repeat(barFull)) + chalk.gray("\u2591".repeat(20 - barFull));
+            balLines.push(` ${chalk.white.bold(exAbbr(s.exchange).padEnd(4))} $${formatUsd(total).padEnd(9)} ${bar} ${usagePct.toFixed(0)}% used`);
+        }
+        // Spot holdings (non-USDC tokens with value)
+        const displaySpotHoldings = allSpotHoldings.filter(b => {
+            const tk = b.token.replace(/[-_]SPOT$/i, "").toUpperCase();
+            return tk !== "USDC";
+        });
+        if (displaySpotHoldings.length > 0) {
+            balLines.push("");
+            balLines.push(chalk.white.bold(" Spot Holdings"));
+            for (const b of displaySpotHoldings) {
+                const token = b.token.replace(/-SPOT$/i, "");
+                const ex = exAbbr(b.exchange);
+                balLines.push(` ${chalk.gray(ex.padEnd(4))} ${chalk.white.bold(token.padEnd(6))} ${b.total.padEnd(12)} ${chalk.gray(`$${formatUsd(b.valueUsd)}`)}`);
+            }
+        }
+        const riskColor = riskLevel === "LOW" ? chalk.green : riskLevel === "MEDIUM" ? chalk.yellow : chalk.red;
+        balLines.push(` ${"─".repeat(44)}`);
+        balLines.push(` ${chalk.cyan.bold("Total")} ${chalk.cyan.bold(`$${formatUsd(totalEquity)}`.padEnd(9))}    Risk: ${riskColor(riskLevel)}`);
+        // Right column: Top Arb Opportunities (with 24h/7d averages from local history — 0 API calls)
+        const { getHistoricalAverages } = await import("./funding-history.js");
+        const arbSymbols = topArb.map(a => a.symbol);
+        const arbExchanges = ["hyperliquid", "pacifica", "lighter"];
+        const histAvgs = arbSymbols.length > 0 ? getHistoricalAverages(arbSymbols, arbExchanges) : new Map();
+        const arbLines = [];
+        arbLines.push(chalk.white.bold(" Top Arb Opportunities"));
+        if (topArb.length > 0) {
+            //          SYMBOL   SPREAD   24h   TREND     7d     DIR
+            arbLines.push(chalk.gray(" " + "".padEnd(8) + "now".padEnd(9) + "24h".padEnd(7) + "".padEnd(9) + "7d".padEnd(7)));
+            for (const a of topArb) {
+                const spreadColor = a.maxSpreadAnnual >= 100 ? chalk.green.bold : a.maxSpreadAnnual >= 30 ? chalk.green : chalk.yellow;
+                const dir = `${exAbbr(a.shortExchange)}>${exAbbr(a.longExchange)}`;
+                const bestEx = a.rates.find(r => r.exchange === "hyperliquid")?.exchange ?? a.rates[0]?.exchange ?? "hyperliquid";
+                // 24h trend arrow
+                const history = getHistoricalRates(a.symbol, bestEx, h24, now);
+                let trend = "";
+                if (history.length >= 2) {
+                    const oldAnn = Math.abs(history[0].hourlyRate) * 8760 * 100;
+                    const newAnn = Math.abs(history[history.length - 1].hourlyRate) * 8760 * 100;
+                    const delta = newAnn - oldAnn;
+                    const abs = Math.abs(delta);
+                    trend = abs < 1 ? chalk.gray(`\u2500${abs.toFixed(0)}%`)
+                        : delta > 0 ? chalk.red(`\u25B2+${abs.toFixed(0)}%`)
+                            : chalk.green(`\u25BC-${abs.toFixed(0)}%`);
+                }
+                // 24h and 7d averages (annualized from hourly)
+                const avg = histAvgs.get(`${a.symbol}:${bestEx}`);
+                const avg24h = avg?.avg24h != null ? `${(Math.abs(avg.avg24h) * 8760 * 100).toFixed(0)}%` : "-";
+                const avg7d = avg?.avg7d != null ? `${(Math.abs(avg.avg7d) * 8760 * 100).toFixed(0)}%` : "-";
+                arbLines.push(` ${chalk.white.bold(a.symbol.padEnd(8))} ${spreadColor(`${a.maxSpreadAnnual.toFixed(1)}%`.padEnd(9))}${chalk.gray(avg24h.padEnd(7))}${trend.padEnd(9)}${chalk.gray(avg7d.padEnd(7))}${chalk.gray(dir)}`);
+            }
+        }
+        else {
+            arbLines.push(chalk.gray(" No opportunities above 5%"));
+        }
+        // Print layout — side-by-side if terminal is wide enough, else stacked
+        const stripAnsi = (s) => s.replace(/\u001b\[[0-9;]*m/g, "");
+        const termW = process.stdout.columns || 80;
+        const SIDE_BY_SIDE_MIN = 100; // 2 indent + 1 + 46 + 1 + 48 + 1
+        if (termW >= SIDE_BY_SIDE_MIN) {
+            const LEFT_W = 46;
+            const RIGHT_W = 48;
+            const maxLines = Math.max(balLines.length, arbLines.length);
+            console.log(`  ${"┌"}${"─".repeat(LEFT_W)}${"┬"}${"─".repeat(RIGHT_W)}${"┐"}`);
+            for (let i = 0; i < maxLines; i++) {
+                const left = balLines[i] ?? "";
+                const right = arbLines[i] ?? "";
+                const leftPad = LEFT_W - stripAnsi(left).length;
+                const rightPad = RIGHT_W - stripAnsi(right).length;
+                console.log(`  \u2502${left}${" ".repeat(Math.max(0, leftPad))}\u2502${right}${" ".repeat(Math.max(0, rightPad))}\u2502`);
+            }
+            console.log(`  ${"└"}${"─".repeat(LEFT_W)}${"┴"}${"─".repeat(RIGHT_W)}${"┘"}`);
+        }
+        else {
+            // Stacked layout for narrow terminals
+            const boxW = Math.min(termW - 4, 74); // 2 indent + 2 borders
+            const printBox = (lines) => {
+                console.log(`  ${"┌"}${"─".repeat(boxW)}${"┐"}`);
+                for (const line of lines) {
+                    const pad = boxW - stripAnsi(line).length;
+                    console.log(`  \u2502${line}${" ".repeat(Math.max(0, pad))}\u2502`);
+                }
+                console.log(`  ${"└"}${"─".repeat(boxW)}${"┘"}`);
+            };
+            printBox(balLines);
+            console.log();
+            printBox(arbLines);
+        }
+        // Positions
+        if (allPositions.length > 0) {
+            console.log(chalk.white.bold("\n  Positions"));
+            const posRows = allPositions.map(p => {
+                const sideColor = p.side === "long" ? chalk.green : chalk.red;
+                const notional = Math.abs(Number(p.size) * Number(p.markPrice));
+                const levStr = p.leverage > 0 ? `${p.leverage}x` : "-";
+                const warn = p.leverage >= 5 ? chalk.red(" \u26A0") : "";
+                return [
+                    chalk.white.bold(p.symbol.replace("-PERP", "")),
+                    chalk.gray(exAbbr(p.exchange)),
+                    sideColor(p.side.toUpperCase()),
+                    p.size,
+                    `$${formatUsd(p.entryPrice)}\u2192$${formatUsd(p.markPrice)}`,
+                    formatPnl(p.unrealizedPnl),
+                    `$${formatUsd(notional)}`,
+                    levStr + warn,
+                ];
+            });
+            console.log(makeTable(["Symbol", "Ex", "Side", "Size", "Entry\u2192Mark", "uPnL", "Notional", "Lev"], posRows));
+        }
+        else {
+            console.log(chalk.gray("\n  No open positions.\n"));
+        }
+    });
 });
-statusCmd._hidden = true;
 // Switch shared API URLs if --network testnet is used
 program.hook("preAction", () => {
     const network = program.opts().network;

package/dist/mcp-server.js

@@ -339,15 +339,15 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: `perp -e ${ex} --json account orders`, description: "List open orders to find order ID" }, { step: 2, command: `perp -e ${ex} --json trade edit <symbol> <orderId> <newPrice> <newSize>`, description: "Modify the order", dangerous: true });
         }
         else if (g.includes("arb") || g.includes("arbitrage")) {
-            steps.push({ step: 1, command: "perp --json arb scan --min 5", description: "Scan funding rate arbitrage opportunities" }, { step: 2, command: "perp --json arb scan", description: "Find high-spread opportunities" }, { step: 3, command: "perp --json gap show", description: "Check cross-exchange price gaps" }, { step: 4, command: "perp --json arb dex", description: "HIP-3 cross-dex arb opportunities (Hyperliquid)" });
+            steps.push({ step: 1, command: "perp --json arb scan --min 5", description: "Scan funding rate arbitrage opportunities" }, { step: 2, command: "perp --json arb scan --gaps", description: "Check cross-exchange price gaps" }, { step: 3, command: "perp --json arb scan --hip3", description: "HIP-3 cross-dex arb opportunities (Hyperliquid)" });
         }
         else if (g.includes("funding")) {
             const symbol = extractSymbol(g);
             if (symbol) {
-                steps.push({ step: 1, command: `perp --json arb rates`, description: `Funding rates across all exchanges` }, { step: 2, command: `perp -e ${ex} --json market funding ${symbol}`, description: `${symbol} funding history` });
+                steps.push({ step: 1, command: `perp --json arb scan --rates`, description: `Funding rates across all exchanges` }, { step: 2, command: `perp -e ${ex} --json market funding ${symbol}`, description: `${symbol} funding history` });
             }
             else {
-                steps.push({ step: 1, command: "perp --json arb rates", description: "Funding rates across all exchanges" }, { step: 2, command: "perp --json arb scan --min 5", description: "Funding rate arb opportunities" });
+                steps.push({ step: 1, command: "perp --json arb scan --rates", description: "Funding rates across all exchanges" }, { step: 2, command: "perp --json arb scan --min 5", description: "Funding rate arb opportunities" });
             }
         }
         else if (g.includes("bridge") || g.includes("transfer") || g.includes("cross-chain")) {
@@ -386,22 +386,22 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: `perp -e ${ex} --json risk status`, description: "Portfolio risk overview" }, { step: 2, command: `perp -e ${ex} --json risk limits`, description: "Current position limits" });
         }
         else if (g.includes("analytic") || g.includes("performance") || g.includes("pnl") || g.includes("p&l")) {
-            steps.push({ step: 1, command: `perp -e ${ex} --json analytics summary`, description: "Trading performance summary" }, { step: 2, command: `perp -e ${ex} --json analytics pnl`, description: "P&L breakdown" }, { step: 3, command: `perp -e ${ex} --json analytics funding`, description: "Funding payment history" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json history summary`, description: "Trading performance summary" }, { step: 2, command: `perp -e ${ex} --json history pnl`, description: "P&L breakdown" }, { step: 3, command: `perp -e ${ex} --json history funding`, description: "Funding payment history" });
         }
         else if (g.includes("history") || g.includes("log") || g.includes("audit")) {
             steps.push({ step: 1, command: `perp -e ${ex} --json history list`, description: "Execution audit trail" }, { step: 2, command: `perp -e ${ex} --json history stats`, description: "Execution statistics" });
         }
-        else if (g.includes("stream") || g.includes("live") || g.includes("watch") || g.includes("realtime")) {
+        else if (g.includes("live") || g.includes("watch") || g.includes("realtime")) {
             const symbol = extractSymbol(g);
             if (symbol) {
-                steps.push({ step: 1, command: `perp -e ${ex} stream book ${symbol}`, description: `Live ${symbol} orderbook` }, { step: 2, command: `perp -e ${ex} stream trades ${symbol}`, description: `Live ${symbol} trades` });
+                steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `${symbol} orderbook` }, { step: 2, command: `perp -e ${ex} --json market trades ${symbol}`, description: `${symbol} recent trades` }, { step: 3, command: `perp --json arb scan --gaps --live`, description: "Live cross-exchange price gap monitor" });
             }
             else {
-                steps.push({ step: 1, command: `perp -e ${ex} stream prices`, description: "Live price stream" }, { step: 2, command: `perp -e ${ex} stream events`, description: "Live account events (fills, liquidations)" });
+                steps.push({ step: 1, command: "perp --json arb scan --gaps --live", description: "Live cross-exchange price gap monitor" }, { step: 2, command: `perp -e ${ex} --json market prices`, description: "Current prices across exchanges" });
             }
         }
         else if (g.includes("gap")) {
-            steps.push({ step: 1, command: "perp --json gap show", description: "Cross-exchange price gaps" }, { step: 2, command: "perp --json gap watch", description: "Live gap monitor" });
+            steps.push({ step: 1, command: "perp --json arb scan --gaps", description: "Cross-exchange price gaps" }, { step: 2, command: "perp --json arb scan --gaps --live", description: "Live gap monitor" });
         }
         else if (g.includes("rebalance")) {
             steps.push({ step: 1, command: "perp --json rebalance check", description: "Check balance distribution" }, { step: 2, command: "perp --json rebalance plan", description: "Generate rebalance plan" }, { step: 3, command: "perp --json rebalance execute", description: "Execute rebalance", dangerous: true });
@@ -446,7 +446,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
                 steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `${symbol} orderbook` }, { step: 2, command: `perp -e ${ex} --json market funding ${symbol}`, description: `${symbol} funding history` }, { step: 3, command: `perp -e ${ex} --json market kline ${symbol} 1h`, description: `${symbol} hourly candles` });
             }
             else {
-                steps.push({ step: 1, command: "perp --json market prices", description: "All market prices" }, { step: 2, command: "perp --json gap show", description: "Cross-exchange price gaps" });
+                steps.push({ step: 1, command: "perp --json market prices", description: "All market prices" }, { step: 2, command: "perp --json arb scan --gaps", description: "Cross-exchange price gaps" });
             }
         }
         else if (g.includes("setting") || g.includes("config") || g.includes("referral")) {
@@ -708,6 +708,8 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                     history: "Shows order history (filled, cancelled, etc.)",
                     trades: "Shows trade execution history with prices and fees",
                     "funding-history": "Shows funding payments received/paid",
+                    funding: "Shows funding payments received/paid (alias for funding-history)",
+                    "twap-orders": "Shows active TWAP orders",
                     pnl: "Shows profit & loss summary",
                     margin: `Shows margin info for ${args[2] || "a symbol"}`,
                     settings: "Shows account settings (leverage, margin mode per symbol)",
@@ -715,26 +717,26 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: [],
                 category: "read",
-                relatedCommands: ["perp portfolio", "perp portfolio"],
+                relatedCommands: ["perp portfolio", "perp account balance"],
             };
         }
         else if (category === "arb") {
             explanation = {
                 command,
                 description: {
-                    rates: "Compares funding rates across all 3 exchanges",
-                    scan: "Scans for funding rate arbitrage opportunities with the largest spreads",
-                    funding: "Detailed funding rate analysis across exchanges",
-                    dex: "HIP-3 cross-dex arbitrage opportunities on Hyperliquid",
+                    scan: "Scans for funding rate arbitrage opportunities. Use --rates for funding rates, --gaps for price gaps, --hip3 for cross-dex arb, --positions for funding impact, --basis for basis trading",
                     auto: "Auto-execute funding rate arbitrage (runs as background job)",
+                    exec: "Execute an arb trade (enter paired positions on two exchanges)",
                     status: "Shows current arb positions and P&L",
                     close: "Closes an arb position on both exchanges",
                     history: "Shows arb execution history",
+                    config: "View/edit arb configuration",
+                    rebalance: "Rebalance funds across exchanges for arb positions",
                 }[sub] || `Arbitrage command: ${sub}`,
                 parameters: [],
-                risks: ["auto" === sub ? "Auto-executes trades on both exchanges" : ""].filter(Boolean),
-                category: sub === "auto" || sub === "close" ? "write" : "analysis",
-                relatedCommands: ["perp arb scan", "perp arb scan", "perp gap show"],
+                risks: [sub === "auto" || sub === "exec" ? "Executes trades on exchanges" : ""].filter(Boolean),
+                category: sub === "auto" || sub === "close" || sub === "exec" || sub === "rebalance" ? "write" : "analysis",
+                relatedCommands: ["perp arb scan", "perp arb status", "perp arb scan --gaps"],
             };
         }
         else if (category === "bridge") {
@@ -774,16 +776,6 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 relatedCommands: ["perp account positions", "perp portfolio"],
             };
         }
-        else if (category === "alert") {
-            explanation = {
-                command,
-                description: { add: "Add a price, funding rate, PnL, or liquidation alert", list: "List all active alerts", remove: "Remove an alert by ID", daemon: "Start the alert monitoring daemon", test: "Send a test alert notification", config: "Configure alert notification channels (Telegram, Discord)" }[sub] || `Alert command: ${sub}`,
-                parameters: [],
-                risks: [],
-                category: "read",
-                relatedCommands: ["perp risk status", "perp risk limits"],
-            };
-        }
         else if (category === "bot" || category === "run") {
             explanation = {
                 command,
@@ -797,9 +789,9 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
         else if (category === "history") {
             explanation = {
                 command,
-                description: { summary: "Trading performance summary", pnl: "P&L breakdown by symbol and time period", funding: "Funding payment history and totals", report: "Detailed performance report", perf: "Performance breakdown (daily/weekly/summary)" }[sub] || `History: ${sub}`,
+                description: { list: "Execution audit trail", stats: "Execution statistics", positions: "Position history", summary: "Trading performance summary", pnl: "P&L breakdown by symbol and time period", funding: "Funding payment history and totals", report: "Detailed performance report", snapshot: "Portfolio snapshot", track: "Track position over time", perf: "Performance breakdown (daily/weekly/summary)", prune: "Prune old execution records" }[sub] || `History: ${sub}`,
                 parameters: [],
-                risks: [],
+                risks: sub === "prune" ? ["Permanently removes old execution records"] : [],
                 category: "read",
                 relatedCommands: ["perp history summary", "perp history list"],
             };
@@ -807,21 +799,11 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
         else if (category === "wallet") {
             explanation = {
                 command,
-                description: { list: "List configured wallets", balance: "Check on-chain USDC/SOL/ETH balances", generate: "Generate a new wallet keypair", use: "Set active wallet" }[sub] || `Wallet: ${sub}`,
+                description: { show: "Show configured wallets with public addresses", list: "List configured wallets", balance: "Check on-chain USDC/SOL/ETH balances", generate: "Generate a new wallet keypair", import: "Import an existing private key", set: "Set private key for an exchange", use: "Set active wallet", remove: "Remove a wallet", rename: "Rename a wallet" }[sub] || `Wallet: ${sub}`,
                 parameters: [],
-                risks: sub === "generate" ? ["Store the private key securely — it cannot be recovered"] : [],
+                risks: sub === "generate" ? ["Store the private key securely — it cannot be recovered"] : sub === "remove" ? ["Wallet will be removed — ensure you have the private key backed up"] : [],
                 category: "read",
-                relatedCommands: ["perp wallet list", "perp wallet balance"],
-            };
-        }
-        else if (category === "gap") {
-            explanation = {
-                command,
-                description: { show: "Shows cross-exchange price gaps for all symbols", watch: "Live monitor for price gaps above threshold", track: "Track gap history", alert: "Alert when gaps exceed threshold" }[sub] || `Gap analysis: ${sub}`,
-                parameters: [],
-                risks: [],
-                category: "analysis",
-                relatedCommands: ["perp gap show", "perp arb scan"],
+                relatedCommands: ["perp wallet show", "perp wallet balance"],
             };
         }
         else if (category === "backtest") {
@@ -976,7 +958,8 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     orders: { usage: "perp account orders", description: "Open/pending orders" },
                     history: { usage: "perp account history", description: "Order history" },
                     trades: { usage: "perp account trades", description: "Trade fill history" },
-                    "funding-history": { usage: "perp account funding-history", description: "Funding payments" },
+                    "funding-history|funding": { usage: "perp account funding-history", description: "Funding payments" },
+                    "twap-orders": { usage: "perp account twap-orders", description: "Active TWAP orders" },
                     pnl: { usage: "perp account pnl", description: "Profit & loss" },
                     margin: { usage: "perp account margin <symbol>", description: "Position margin info" },
                     settings: { usage: "perp account settings", description: "Account settings (leverage per symbol)" },
@@ -1007,19 +990,23 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     fills: { usage: "perp trade fills [symbol]", description: "Recent fills" },
                     status: { usage: "perp trade status <orderId>", description: "Check order status" },
                     "pnl-track": { usage: "perp trade pnl-track", description: "Real-time PnL tracker" },
+                    split: { usage: "perp trade split <symbol> <side> <usd>", description: "Split large order into depth-based slices" },
+                    multi: { usage: "perp trade multi <legs...>", description: "Execute multi-leg orders (exchange:symbol:side:size)" },
+                    "cancel-stop": { usage: "perp trade cancel-stop <symbol> <stopOrderId>", description: "Cancel a stop order" },
+                    "cancel-twap": { usage: "perp trade cancel-twap <symbol> <twapOrderId>", description: "Cancel a TWAP order" },
                 },
             },
             arb: {
                 description: "Funding rate arbitrage & basis trading",
                 subcommands: {
-                    rates: { usage: "perp arb scan", description: "Compare funding rates" },
-                    scan: { usage: "perp arb scan --min <bps>", description: "Find arb opportunities" },
-                    funding: { usage: "perp arb funding", description: "Detailed funding analysis" },
-                    dex: { usage: "perp arb dex", description: "HIP-3 cross-dex arb" },
-                    auto: { usage: "perp arb auto --min-spread <bps>", description: "Auto-execute funding arb" },
+                    scan: { usage: "perp arb scan --min <pct>", description: "Find arb opportunities (use --rates, --gaps, --hip3, --positions, --basis, --compare, --history, --live)" },
+                    auto: { usage: "perp arb auto --min-spread <pct>", description: "Auto-execute funding arb" },
+                    exec: { usage: "perp arb exec <symbol> <longEx> <shortEx> <size>", description: "Execute arb trade on two exchanges" },
                     status: { usage: "perp arb status", description: "Current arb positions" },
                     close: { usage: "perp arb close <symbol>", description: "Close arb position" },
-                    history: { usage: "perp arb history", description: "Arb execution history" },
+                    "history|log": { usage: "perp arb history", description: "Arb execution history" },
+                    config: { usage: "perp arb config", description: "View/edit arb configuration" },
+                    rebalance: { usage: "perp arb rebalance", description: "Rebalance funds across exchanges for arb" },
                 },
             },
             risk: {
@@ -1043,32 +1030,48 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
             bot: {
                 description: "Automated trading bots",
                 subcommands: {
+                    start: { usage: "perp bot start <config>", description: "Start bot from config file" },
                     twap: { usage: "perp bot twap <symbol> <side> <size> <duration>", description: "TWAP execution" },
                     grid: { usage: "perp bot grid <symbol> --range <pct> --grids <n> --size <usd>", description: "Grid trading bot" },
                     dca: { usage: "perp bot dca <symbol> <side> <amount> <interval>", description: "DCA bot" },
+                    "funding-arb": { usage: "perp bot funding-arb", description: "Funding arb bot" },
                     "trailing-stop": { usage: "perp bot trailing-stop <symbol>", description: "Trailing stop bot" },
                     "quick-grid": { usage: "perp bot quick-grid <symbol>", description: "Quick grid bot" },
                     "quick-dca": { usage: "perp bot quick-dca <symbol> <side> <amount> <interval>", description: "Quick DCA bot" },
                     "quick-arb": { usage: "perp bot quick-arb", description: "Quick arb bot" },
+                    "preset-list": { usage: "perp bot preset-list", description: "List available bot presets" },
+                    preset: { usage: "perp bot preset <name> [symbol]", description: "Run a bot preset" },
+                    example: { usage: "perp bot example", description: "Show example bot config" },
                 },
             },
             wallet: {
                 description: "Wallet management",
                 subcommands: {
+                    show: { usage: "perp wallet show", description: "Show configured wallets with public addresses" },
                     list: { usage: "perp wallet list", description: "List wallets" },
-                    balance: { usage: "perp wallet balance", description: "On-chain balances" },
+                    balance: { usage: "perp wallet balance [name]", description: "On-chain balances" },
                     generate: { usage: "perp wallet generate solana|evm", description: "Generate new wallet" },
+                    import: { usage: "perp wallet import solana|evm <privateKey>", description: "Import existing private key" },
+                    set: { usage: "perp wallet set <exchange> <key>", description: "Set private key for exchange" },
+                    use: { usage: "perp wallet use <name> [exchange]", description: "Set active wallet" },
+                    remove: { usage: "perp wallet remove <name>", description: "Remove a wallet" },
+                    rename: { usage: "perp wallet rename <oldName> <newName>", description: "Rename a wallet" },
                 },
             },
             history: {
                 description: "Execution log, performance & audit trail",
                 subcommands: {
                     list: { usage: "perp history list", description: "Execution log" },
+                    stats: { usage: "perp history stats", description: "Execution statistics" },
+                    positions: { usage: "perp history positions", description: "Position history" },
                     summary: { usage: "perp history summary", description: "Performance summary" },
                     pnl: { usage: "perp history pnl", description: "P&L breakdown" },
                     funding: { usage: "perp history funding", description: "Funding payment history" },
                     report: { usage: "perp history report", description: "Full performance report" },
+                    snapshot: { usage: "perp history snapshot", description: "Portfolio snapshot" },
+                    track: { usage: "perp history track", description: "Track position over time" },
                     perf: { usage: "perp history perf --period daily|weekly|summary", description: "Performance breakdown" },
+                    prune: { usage: "perp history prune", description: "Prune old execution records" },
                 },
             },
             backtest: {

package/dist/utils.d.ts

@@ -3,6 +3,8 @@ export declare function formatUsd(value: string | number): string;
 export declare function formatPnl(value: string | number): string;
 export declare function formatPercent(value: string | number): string;
 export declare function makeTable(head: string[], rows: string[][]): string;
+/** Render a sparkline from numeric values. Returns unicode bar chart string. */
+export declare function sparkline(values: number[], width?: number): string;
 export declare function printJson(data: unknown): void;
 export declare function errorAndExit(msg: string): never;
 /** Standard JSON response envelope */

package/dist/utils.js

@@ -96,6 +96,38 @@ function sanitizeValue(val) {
     }
     return val;
 }
+// ── Sparkline ──
+// Density-based shading — renders consistently across all terminal fonts
+// (height-based ▁▂▃▄▅▆▇█ looks identical in many monospace fonts)
+const SPARK_CHARS = [" ", "░", "▒", "▓", "█"];
+/** Render a sparkline from numeric values. Returns unicode bar chart string. */
+export function sparkline(values, width) {
+    if (values.length === 0)
+        return "";
+    const data = width && values.length > width ? downsample(values, width) : values;
+    const min = Math.min(...data);
+    const max = Math.max(...data);
+    const range = max - min;
+    if (range === 0)
+        return SPARK_CHARS[2].repeat(data.length);
+    return data.map(v => {
+        const idx = Math.round(((v - min) / range) * (SPARK_CHARS.length - 1));
+        return SPARK_CHARS[idx];
+    }).join("");
+}
+function downsample(values, targetLen) {
+    const bucketSize = values.length / targetLen;
+    const result = [];
+    for (let i = 0; i < targetLen; i++) {
+        const start = Math.floor(i * bucketSize);
+        const end = Math.floor((i + 1) * bucketSize);
+        let sum = 0;
+        for (let j = start; j < end; j++)
+            sum += values[j];
+        result.push(sum / (end - start));
+    }
+    return result;
+}
 // ── JSON Output ──
 const _isNdjson = () => process.argv.includes("--ndjson");
 export function printJson(data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "dist/index.js",