perp-cli 0.4.8 → 0.4.9

package/README.md

@@ -13,9 +13,10 @@ npx -y perp-cli --json portfolio
 ## Features
 
 - **3 Exchanges** — trade, bridge, arbitrage across Pacifica, Hyperliquid, Lighter
-- **Funding Rate Arb** — scan spreads + one-command dual-leg execution (`arb exec`)
+- **Funding Rate Arb** — perp-perp + spot-perp scan & one-command dual-leg execution
 - **Portfolio** — single call returns balances, positions, risk level across all exchanges
-- **CCTP V2 Bridge** — $0 fee USDC bridging (Solana, Arbitrum, Base)
+- **Funds** — deposit, withdraw, CCTP bridge, internal transfer in one group
+- **Bots** — TWAP, grid, DCA, trailing-stop with background job management
 - **Agent-First Design** — `--json`, `--fields`, `--ndjson`, `--dry-run`, runtime schema introspection
 - **Safety** — pre-trade validation, response sanitization, client-id deduplication
 
@@ -35,6 +36,30 @@ Same EVM key works for both Hyperliquid and Lighter.
 
 > **Lighter API Key Index:** Indexes 0–3 are reserved by Lighter's frontend (web/mobile). perp-cli defaults to index `4`. Override with `LIGHTER_API_KEY_INDEX` env var or `--key-index` flag on `manage setup-api-key`. Valid range: 4–254.
 
+## Command Groups
+
+| Group | Description |
+|-------|-------------|
+| `market` | Prices, orderbook, funding, klines, HIP-3 dexes |
+| `account` | Balance, positions, orders, margin |
+| `trade` | Market/limit/stop orders, close, scale, split execution |
+| `arb` | Funding rate arb — scan, exec, close, monitor (perp-perp & spot-perp) |
+| `bot` | TWAP, grid, DCA, trailing-stop bots |
+| `funds` | Deposit, withdraw, transfer, CCTP bridge |
+| `bridge` | Cross-chain USDC bridge (deBridge DLN) |
+| `risk` | Risk limits, liquidation distance, guardrails |
+| `wallet` | Multi-wallet management & on-chain balances |
+| `history` | Execution log, PnL, performance breakdown |
+| `manage` | Margin mode, subaccount, API keys, builder |
+| `portfolio` | Cross-exchange unified overview |
+| `dashboard` | Live web dashboard |
+| `settings` | CLI settings (referrals, defaults) |
+| `backtest` | Strategy backtesting |
+| `plan` | Multi-step composite execution plans |
+| `rebalance` | Cross-exchange balance management |
+| `jobs` | Background job management (tmux) |
+| `agent` | Schema introspection, capabilities, health check |
+
 ## Core Commands
 
 ```bash
@@ -48,18 +73,32 @@ perp --json -e <EX> market funding <SYM>
 
 # Trading
 perp --json -e <EX> trade market <SYM> buy <SIZE>
+perp --json -e <EX> trade market <SYM> buy <SIZE> --smart      # IOC limit at best bid/ask (less slippage)
+perp --json -e <EX> trade split <SYM> buy 5000                 # orderbook-aware split (large orders)
 perp --json -e <EX> trade close <SYM>
 perp --json -e <EX> trade leverage <SYM> <N>
 
 # Funding rate arbitrage
-perp --json arb scan --min 5                                              # find opportunities
+perp --json arb scan --min 5                                              # perp-perp opportunities
+perp --json arb scan --mode spot-perp                                     # spot+perp opportunities
 perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage 2 --isolated # execute both legs
+perp --json arb spot-exec <SYM> <spotEx> <perpEx> <$>                     # spot+perp entry
+
+# Funds (deposit, withdraw, transfer)
+perp --json funds deposit hyperliquid 100
+perp --json funds withdraw pacifica 50
+perp --json funds transfer 100 <ADDRESS>          # HL internal transfer
+perp --json funds info                            # all routes & limits
 
 # Risk
 perp --json risk limits --max-leverage 5
 perp --json risk liquidation-distance
 
-# Bridge
+# Bots
+perp --json bot twap <SYM> buy <SIZE> 30m
+perp --json bot grid <SYM> --range 5 --grids 10 --size 100
+
+# Bridge (cross-chain USDC)
 perp --json bridge quote --from solana --to arbitrum --amount 100
 perp --json bridge send --from solana --to arbitrum --amount 100
 ```
@@ -92,7 +131,7 @@ perp --json portfolio
 # Runtime schema introspection (don't guess commands — query this)
 perp --json agent schema
 
-# Filter output to save tokens
+# Filter output to specific fields (saves tokens)
 perp --json --fields totalEquity,risk portfolio
 
 # Stream large lists as NDJSON (one JSON per line)

package/dist/arb/reconcile.d.ts

@@ -0,0 +1,28 @@
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export interface ReconciliationIssue {
+    type: "orphan" | "phantom" | "size_mismatch";
+    symbol: string;
+    exchange: string;
+    side: "long" | "short";
+    localSize: number | null;
+    exchangeSize: number | null;
+    severity: "warning" | "critical";
+    suggestion: string;
+}
+export interface ReconciliationResult {
+    issues: ReconciliationIssue[];
+    healthy: number;
+    fixesApplied?: string[];
+}
+/**
+ * Reconcile local arb state with actual exchange positions.
+ *
+ * Detects three types of issues:
+ * - **Orphan**: Position exists on exchange but not in local arb state (manual entry?)
+ * - **Phantom**: Position exists in local state but not on exchange (liquidated? manually closed?)
+ * - **Size mismatch**: Both exist but sizes differ beyond tolerance
+ */
+export declare function reconcileArbPositions(adapters: Map<string, ExchangeAdapter>, opts?: {
+    fix?: boolean;
+    tolerancePct?: number;
+}): Promise<ReconciliationResult>;

package/dist/arb/reconcile.js

@@ -0,0 +1,162 @@
+import { getPositions, removePosition, updatePosition } from "./state.js";
+/** Normalize symbol for comparison (strip -PERP suffix, uppercase) */
+function normalizeSymbol(symbol) {
+    return symbol.toUpperCase().replace(/-PERP$/, "");
+}
+/** Find a matching exchange position by symbol */
+function findExchangePosition(positions, symbol, side) {
+    const norm = normalizeSymbol(symbol);
+    return positions.find(p => normalizeSymbol(p.symbol) === norm && p.side === side);
+}
+/**
+ * Reconcile local arb state with actual exchange positions.
+ *
+ * Detects three types of issues:
+ * - **Orphan**: Position exists on exchange but not in local arb state (manual entry?)
+ * - **Phantom**: Position exists in local state but not on exchange (liquidated? manually closed?)
+ * - **Size mismatch**: Both exist but sizes differ beyond tolerance
+ */
+export async function reconcileArbPositions(adapters, opts) {
+    const tolerancePct = opts?.tolerancePct ?? 1;
+    const shouldFix = opts?.fix ?? false;
+    const issues = [];
+    const fixesApplied = [];
+    let healthy = 0;
+    const localPositions = getPositions();
+    // Fetch all exchange positions
+    const exchangePositions = new Map();
+    for (const [name, adapter] of adapters) {
+        try {
+            const pos = await adapter.getPositions();
+            exchangePositions.set(name, pos);
+        }
+        catch {
+            exchangePositions.set(name, []);
+        }
+    }
+    // Track which exchange positions are accounted for
+    const accountedFor = new Set(); // "exchange:symbol:side"
+    // Check each local arb position against exchange
+    for (const arb of localPositions) {
+        // Check long leg
+        const longPositions = exchangePositions.get(arb.longExchange) ?? [];
+        const longMatch = findExchangePosition(longPositions, arb.symbol, "long");
+        if (!longMatch) {
+            issues.push({
+                type: "phantom",
+                symbol: arb.symbol,
+                exchange: arb.longExchange,
+                side: "long",
+                localSize: arb.longSize,
+                exchangeSize: null,
+                severity: "critical",
+                suggestion: `Local state has long ${arb.symbol} on ${arb.longExchange} but exchange has no position. May have been liquidated or manually closed.`,
+            });
+            if (shouldFix) {
+                removePosition(arb.symbol);
+                fixesApplied.push(`Removed phantom position ${arb.symbol} (long leg missing on ${arb.longExchange})`);
+                continue; // Skip short leg check since we removed the position
+            }
+        }
+        else {
+            accountedFor.add(`${arb.longExchange}:${normalizeSymbol(arb.symbol)}:long`);
+            const exchangeSize = Math.abs(Number(longMatch.size));
+            const localSize = Math.abs(arb.longSize);
+            const diffPct = localSize > 0 ? (Math.abs(exchangeSize - localSize) / localSize) * 100 : 0;
+            if (diffPct > tolerancePct) {
+                issues.push({
+                    type: "size_mismatch",
+                    symbol: arb.symbol,
+                    exchange: arb.longExchange,
+                    side: "long",
+                    localSize,
+                    exchangeSize,
+                    severity: "warning",
+                    suggestion: `Long size mismatch: local ${localSize} vs exchange ${exchangeSize} (${diffPct.toFixed(1)}% diff). Partial fill or manual adjustment?`,
+                });
+                if (shouldFix) {
+                    updatePosition(arb.symbol, { longSize: exchangeSize });
+                    fixesApplied.push(`Updated ${arb.symbol} long size: ${localSize} → ${exchangeSize}`);
+                }
+            }
+            else {
+                healthy++;
+            }
+        }
+        // Check short leg
+        const shortPositions = exchangePositions.get(arb.shortExchange) ?? [];
+        const shortMatch = findExchangePosition(shortPositions, arb.symbol, "short");
+        if (!shortMatch) {
+            // Don't double-report if we already removed via fix
+            if (shouldFix && !getPositions().find(p => p.symbol === arb.symbol))
+                continue;
+            issues.push({
+                type: "phantom",
+                symbol: arb.symbol,
+                exchange: arb.shortExchange,
+                side: "short",
+                localSize: arb.shortSize,
+                exchangeSize: null,
+                severity: "critical",
+                suggestion: `Local state has short ${arb.symbol} on ${arb.shortExchange} but exchange has no position. May have been liquidated or manually closed.`,
+            });
+            if (shouldFix) {
+                removePosition(arb.symbol);
+                fixesApplied.push(`Removed phantom position ${arb.symbol} (short leg missing on ${arb.shortExchange})`);
+            }
+        }
+        else {
+            accountedFor.add(`${arb.shortExchange}:${normalizeSymbol(arb.symbol)}:short`);
+            const exchangeSize = Math.abs(Number(shortMatch.size));
+            const localSize = Math.abs(arb.shortSize);
+            const diffPct = localSize > 0 ? (Math.abs(exchangeSize - localSize) / localSize) * 100 : 0;
+            if (diffPct > tolerancePct) {
+                issues.push({
+                    type: "size_mismatch",
+                    symbol: arb.symbol,
+                    exchange: arb.shortExchange,
+                    side: "short",
+                    localSize,
+                    exchangeSize,
+                    severity: "warning",
+                    suggestion: `Short size mismatch: local ${localSize} vs exchange ${exchangeSize} (${diffPct.toFixed(1)}% diff). Partial fill or manual adjustment?`,
+                });
+                if (shouldFix) {
+                    updatePosition(arb.symbol, { shortSize: exchangeSize });
+                    fixesApplied.push(`Updated ${arb.symbol} short size: ${localSize} → ${exchangeSize}`);
+                }
+            }
+            else {
+                healthy++;
+            }
+        }
+    }
+    // Check for orphan positions (on exchange but not in local state)
+    for (const [exchangeName, positions] of exchangePositions) {
+        for (const pos of positions) {
+            const key = `${exchangeName}:${normalizeSymbol(pos.symbol)}:${pos.side}`;
+            if (!accountedFor.has(key)) {
+                // Check if this exchange is used in any arb position
+                const isArbExchange = localPositions.some(p => p.longExchange === exchangeName || p.shortExchange === exchangeName);
+                // Only report orphans on exchanges that are part of arb state
+                if (isArbExchange || localPositions.length > 0) {
+                    issues.push({
+                        type: "orphan",
+                        symbol: pos.symbol,
+                        exchange: exchangeName,
+                        side: pos.side,
+                        localSize: null,
+                        exchangeSize: Math.abs(Number(pos.size)),
+                        severity: "warning",
+                        suggestion: `Position on ${exchangeName} not tracked in arb state. Manual entry or untracked strategy?`,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        issues,
+        healthy,
+        ...(fixesApplied.length > 0 ? { fixesApplied } : {}),
+    };
+}

package/dist/commands/account.d.ts

@@ -1,3 +1,3 @@
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/interface.js";
-export declare function registerAccountCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean): void;
+export declare function registerAccountCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean, getAdapterForExchange?: (exchange: string) => Promise<ExchangeAdapter>): void;

package/dist/commands/account.js

@@ -1,42 +1,210 @@
 import { PacificaAdapter } from "../exchanges/pacifica.js";
-import { HyperliquidAdapter } from "../exchanges/hyperliquid.js";
-import { makeTable, formatUsd, formatPnl, printJson, jsonOk, jsonError, symbolMatch } from "../utils.js";
+import { makeTable, formatUsd, formatPnl, printJson, jsonOk, jsonError, symbolMatch, withJsonErrors } from "../utils.js";
 import chalk from "chalk";
+import { assessRisk } from "../risk.js";
+const EXCHANGES = ["pacifica", "hyperliquid", "lighter"];
+async function fetchExchangeSnapshot(name, getAdapter) {
+    try {
+        const adapter = await getAdapter(name);
+        const [balance, positions, orders] = await Promise.all([
+            adapter.getBalance(),
+            adapter.getPositions(),
+            adapter.getOpenOrders(),
+        ]);
+        return {
+            exchange: name,
+            connected: true,
+            balance,
+            positions,
+            openOrders: orders.length,
+        };
+    }
+    catch (err) {
+        return {
+            exchange: name,
+            connected: false,
+            balance: null,
+            positions: [],
+            openOrders: 0,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function buildSummary(snapshots) {
+    let totalEquity = 0;
+    let totalAvailable = 0;
+    let totalMarginUsed = 0;
+    let totalUnrealizedPnl = 0;
+    let totalPositions = 0;
+    let totalOpenOrders = 0;
+    const allPositions = [];
+    for (const snap of snapshots) {
+        if (snap.balance) {
+            totalEquity += Number(snap.balance.equity);
+            totalAvailable += Number(snap.balance.available);
+            totalMarginUsed += Number(snap.balance.marginUsed);
+            totalUnrealizedPnl += Number(snap.balance.unrealizedPnl);
+        }
+        totalPositions += snap.positions.length;
+        totalOpenOrders += snap.openOrders;
+        for (const pos of snap.positions) {
+            allPositions.push({ ...pos, exchange: snap.exchange });
+        }
+    }
+    // Risk metrics
+    const marginUtilization = totalEquity > 0 ? (totalMarginUsed / totalEquity) * 100 : 0;
+    let largestPosition = null;
+    for (const pos of allPositions) {
+        const notional = Math.abs(Number(pos.size) * Number(pos.markPrice));
+        if (!largestPosition || notional > largestPosition.notional) {
+            largestPosition = { symbol: pos.symbol, exchange: pos.exchange, notional };
+        }
+    }
+    const exchangeConcentration = snapshots
+        .filter(s => s.balance && Number(s.balance.equity) > 0)
+        .map(s => ({
+        exchange: s.exchange,
+        pct: totalEquity > 0 ? (Number(s.balance.equity) / totalEquity) * 100 : 0,
+    }))
+        .sort((a, b) => b.pct - a.pct);
+    // Full risk assessment (reuses same data, no extra API calls)
+    const riskBalances = snapshots
+        .filter(s => s.balance)
+        .map(s => ({ exchange: s.exchange, balance: s.balance }));
+    const riskPositions = allPositions.map(p => ({ exchange: p.exchange, position: p }));
+    const assessment = assessRisk(riskBalances, riskPositions);
+    return {
+        totalEquity,
+        totalAvailable,
+        totalMarginUsed,
+        totalUnrealizedPnl,
+        totalPositions,
+        totalOpenOrders,
+        exchanges: snapshots,
+        positions: allPositions,
+        riskMetrics: {
+            marginUtilization,
+            largestPosition,
+            exchangeConcentration,
+        },
+        risk: {
+            level: assessment.level,
+            canTrade: assessment.canTrade,
+            violations: assessment.violations,
+        },
+    };
+}
 function pac(adapter) {
     if (!(adapter instanceof PacificaAdapter))
         throw new Error("This command requires --exchange pacifica");
     return adapter;
 }
-export function registerAccountCommands(program, getAdapter, isJson) {
+export function registerAccountCommands(program, getAdapter, isJson, getAdapterForExchange) {
     const account = program.command("account").description("Account commands");
-    account
-        .command("info")
-        .description("Show account balance and info")
-        .action(async () => {
-        const adapter = await getAdapter();
-        const bal = await adapter.getBalance();
-        if (isJson())
-            return printJson(jsonOk(bal));
-        console.log(chalk.cyan.bold(`\n  ${adapter.name.toUpperCase()} Account Info\n`));
-        console.log(`  Equity:       $${formatUsd(bal.equity)}`);
-        console.log(`  Available:    $${formatUsd(bal.available)}`);
-        console.log(`  Margin Used:  $${formatUsd(bal.marginUsed)}`);
-        console.log(`  Unreal. PnL:  ${formatPnl(bal.unrealizedPnl)}`);
-        console.log();
-    });
     account
         .command("balance")
-        .description("Alias for 'account info' — show account balance")
+        .alias("info")
+        .description("Account overview: perp balance, spot holdings, and 24h funding")
         .action(async () => {
         const adapter = await getAdapter();
-        const bal = await adapter.getBalance();
-        if (isJson())
-            return printJson(jsonOk(bal));
-        console.log(chalk.cyan.bold(`\n  ${adapter.name.toUpperCase()} Account Balance\n`));
-        console.log(`  Equity:       $${formatUsd(bal.equity)}`);
-        console.log(`  Available:    $${formatUsd(bal.available)}`);
-        console.log(`  Margin Used:  $${formatUsd(bal.marginUsed)}`);
-        console.log(`  Unreal. PnL:  ${formatPnl(bal.unrealizedPnl)}`);
+        const exName = adapter.name.toLowerCase();
+        // Fetch perp balance + funding in parallel
+        const [bal, fundingPayments] = await Promise.all([
+            adapter.getBalance(),
+            adapter.getFundingPayments(200).catch(() => []),
+        ]);
+        // Spot balances (HL and LT only)
+        let spotBalances = [];
+        try {
+            if (exName === "hyperliquid") {
+                const { HyperliquidSpotAdapter } = await import("../exchanges/hyperliquid-spot.js");
+                const hlSpot = new HyperliquidSpotAdapter(adapter);
+                await hlSpot.init();
+                const raw = await hlSpot.getSpotBalances();
+                // Get spot prices for USD valuation
+                const markets = await hlSpot.getSpotMarkets();
+                const priceMap = new Map(markets.map(m => [m.baseToken.toUpperCase(), Number(m.markPrice)]));
+                // HL spot API returns token names with -SPOT suffix (e.g., "HYPE-SPOT", "USDC-SPOT")
+                const stripSuffix = (t) => t.replace(/-SPOT$/i, "").toUpperCase();
+                spotBalances = raw
+                    .filter(b => Number(b.total) > 0)
+                    .map(b => {
+                    const base = stripSuffix(b.token);
+                    return {
+                        ...b,
+                        valueUsd: base === "USDC" ? Number(b.total) : (priceMap.get(base) ?? 0) * Number(b.total),
+                    };
+                });
+            }
+            else if (exName === "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 = await ltSpot.getSpotBalances();
+                const markets = await ltSpot.getSpotMarkets();
+                const priceMap = new Map(markets.map(m => [m.baseToken.toUpperCase(), Number(m.markPrice)]));
+                spotBalances = 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 */ }
+        // 24h funding summary
+        const cutoff24h = Date.now() - 24 * 60 * 60 * 1000;
+        const recent = fundingPayments.filter(f => f.time >= cutoff24h);
+        const funding24h = recent.reduce((sum, f) => sum + Number(f.payment), 0);
+        // Total spot value
+        const totalSpotUsd = spotBalances.reduce((s, b) => s + (b.valueUsd ?? 0), 0);
+        if (isJson()) {
+            return printJson(jsonOk({
+                perp: bal,
+                spot: spotBalances,
+                funding24h,
+                fundingPayments24h: recent.length,
+                totalSpotValueUsd: totalSpotUsd,
+                totalAccountValueUsd: Number(bal.equity) + totalSpotUsd,
+            }));
+        }
+        // ── Perp Balance ──
+        console.log(chalk.cyan.bold(`\n  ${exName.toUpperCase()} Account Balance\n`));
+        console.log(chalk.white.bold("  Perp Account"));
+        console.log(`    Equity:       $${formatUsd(bal.equity)}`);
+        console.log(`    Available:    $${formatUsd(bal.available)}`);
+        console.log(`    Margin Used:  $${formatUsd(bal.marginUsed)}`);
+        console.log(`    Unreal. PnL:  ${formatPnl(bal.unrealizedPnl)}`);
+        // ── Spot Holdings ──
+        if (spotBalances.length > 0) {
+            console.log(chalk.white.bold("\n  Spot Holdings"));
+            const rows = spotBalances.map(b => [
+                chalk.white.bold(b.token),
+                b.total,
+                b.available,
+                b.held !== "0" ? b.held : chalk.gray("-"),
+                b.valueUsd ? `$${formatUsd(b.valueUsd)}` : chalk.gray("-"),
+            ]);
+            console.log(makeTable(["Token", "Total", "Available", "Held", "Value"], rows));
+        }
+        else if (exName === "hyperliquid" || exName === "lighter") {
+            console.log(chalk.gray("\n  No spot holdings.\n"));
+        }
+        // ── Funding 24h ──
+        console.log(chalk.white.bold("  Funding (24h)"));
+        console.log(`    Payments:     ${recent.length}`);
+        console.log(`    Total:        ${formatPnl(funding24h)}`);
+        // ── Total ──
+        const totalValue = Number(bal.equity) + totalSpotUsd;
+        if (totalSpotUsd > 0) {
+            console.log(chalk.white.bold("\n  Total"));
+            console.log(`    Perp Equity:  $${formatUsd(bal.equity)}`);
+            console.log(`    Spot Value:   $${formatUsd(totalSpotUsd)}`);
+            console.log(`    Total Value:  $${formatUsd(totalValue)}`);
+        }
         console.log();
     });
     account
@@ -172,42 +340,9 @@ export function registerAccountCommands(program, getAdapter, isJson) {
         ]);
         console.log(makeTable(["Time", "Symbol", "Payment"], rows));
     });
-    account
-        .command("portfolio")
-        .description("Portfolio overview")
-        .action(async () => {
-        const adapter = await getAdapter();
-        if (adapter instanceof PacificaAdapter) {
-            const portfolio = await adapter.sdk.getPortfolio(adapter.publicKey);
-            printJson(jsonOk(portfolio));
-        }
-        else if (adapter instanceof HyperliquidAdapter) {
-            const state = await adapter.client.info.perpetuals.getClearinghouseState(adapter.address);
-            printJson(jsonOk(state));
-        }
-    });
-    account
-        .command("balance-history")
-        .description("Balance change history")
-        .action(async () => {
-        const adapter = await getAdapter();
-        const p = pac(adapter);
-        const raw = await p.sdk.getBalanceHistory(p.publicKey);
-        if (isJson())
-            return printJson(jsonOk(raw));
-        const history = (raw.data ?? raw);
-        if (!Array.isArray(history) || history.length === 0) {
-            console.log(chalk.gray("\n  No balance history.\n"));
-            return;
-        }
-        const rows = history.slice(0, 30).map((h) => [
-            new Date(Number(h.created_at ?? h.timestamp ?? 0)).toLocaleString(),
-            String(h.type ?? h.event_type ?? ""),
-            formatPnl(String(h.amount ?? h.change ?? "0")),
-            `$${formatUsd(String(h.balance ?? "0"))}`,
-        ]);
-        console.log(makeTable(["Time", "Type", "Change", "Balance"], rows));
-    });
+    // "account portfolio" removed — use top-level "portfolio" for cross-exchange view
+    // or "account balance" for single-exchange balance
+    // "account balance-history" removed — Pacifica-only, rarely used
     account
         .command("margin <symbol>")
         .description("Margin details for a specific symbol position")
@@ -422,4 +557,106 @@ export function registerAccountCommands(program, getAdapter, isJson) {
         ]);
         console.log(makeTable(["ID", "Symbol", "Side", "Size", "Filled", "Duration"], rows));
     });
+    // ── Portfolio (top-level command) ──
+    if (getAdapterForExchange) {
+        program
+            .command("portfolio")
+            .description("Cross-exchange portfolio overview (all exchanges at once)")
+            .option("--exchange <exchanges>", "Comma-separated exchanges to include (default: all)")
+            .action(async (opts) => {
+            await withJsonErrors(isJson(), async () => {
+                const exchanges = opts.exchange
+                    ? opts.exchange.split(",").map(e => e.trim())
+                    : [...EXCHANGES];
+                const snapshots = await Promise.all(exchanges.map(ex => fetchExchangeSnapshot(ex, getAdapterForExchange)));
+                const summary = buildSummary(snapshots);
+                if (isJson()) {
+                    return printJson(jsonOk(summary));
+                }
+                // ── Header ──
+                console.log(chalk.cyan.bold("\n  Cross-Exchange Portfolio\n"));
+                // ── Balance Summary ──
+                console.log(chalk.white.bold("  Balances"));
+                const balRows = snapshots.map(s => {
+                    if (!s.connected) {
+                        return [chalk.white(s.exchange), chalk.red("disconnected"), "-", "-", "-", chalk.gray(s.error ?? "")];
+                    }
+                    const b = s.balance;
+                    return [
+                        chalk.white.bold(s.exchange),
+                        `$${formatUsd(b.equity)}`,
+                        `$${formatUsd(b.available)}`,
+                        `$${formatUsd(b.marginUsed)}`,
+                        formatPnl(b.unrealizedPnl),
+                        chalk.green("connected"),
+                    ];
+                });
+                // Totals row
+                balRows.push([
+                    chalk.cyan.bold("TOTAL"),
+                    chalk.cyan.bold(`$${formatUsd(summary.totalEquity)}`),
+                    chalk.cyan.bold(`$${formatUsd(summary.totalAvailable)}`),
+                    chalk.cyan.bold(`$${formatUsd(summary.totalMarginUsed)}`),
+                    formatPnl(summary.totalUnrealizedPnl),
+                    "",
+                ]);
+                console.log(makeTable(["Exchange", "Equity", "Available", "Margin Used", "uPnL", "Status"], balRows));
+                // ── Positions ──
+                if (summary.positions.length > 0) {
+                    console.log(chalk.white.bold("\n  Open Positions"));
+                    const posRows = summary.positions.map(p => {
+                        const sideColor = p.side === "long" ? chalk.green : chalk.red;
+                        const notional = Math.abs(Number(p.size) * Number(p.markPrice));
+                        return [
+                            chalk.white.bold(p.symbol),
+                            chalk.gray(p.exchange),
+                            sideColor(p.side.toUpperCase()),
+                            p.size,
+                            `$${formatUsd(p.entryPrice)}`,
+                            `$${formatUsd(p.markPrice)}`,
+                            formatPnl(p.unrealizedPnl),
+                            `$${formatUsd(notional)}`,
+                            `${p.leverage}x`,
+                        ];
+                    });
+                    console.log(makeTable(["Symbol", "Exchange", "Side", "Size", "Entry", "Mark", "uPnL", "Notional", "Lev"], posRows));
+                }
+                else {
+                    console.log(chalk.gray("\n  No open positions.\n"));
+                }
+                // ── Risk Metrics ──
+                console.log(chalk.white.bold("\n  Risk Metrics"));
+                const levelColor = {
+                    low: chalk.green,
+                    medium: chalk.yellow,
+                    high: chalk.red,
+                    critical: chalk.bgRed.white,
+                }[summary.risk.level];
+                console.log(`  Risk Level:         ${levelColor(summary.risk.level.toUpperCase())}`);
+                console.log(`  Can Trade:          ${summary.risk.canTrade ? chalk.green("YES") : chalk.red("NO")}`);
+                const mu = summary.riskMetrics.marginUtilization;
+                const muColor = mu < 30 ? chalk.green : mu < 60 ? chalk.yellow : chalk.red;
+                console.log(`  Margin Utilization: ${muColor(`${mu.toFixed(1)}%`)}`);
+                if (summary.riskMetrics.largestPosition) {
+                    const lp = summary.riskMetrics.largestPosition;
+                    console.log(`  Largest Position:   ${lp.symbol} on ${lp.exchange} ($${formatUsd(lp.notional)})`);
+                }
+                if (summary.riskMetrics.exchangeConcentration.length > 0) {
+                    console.log(`  Exchange Allocation:`);
+                    for (const ec of summary.riskMetrics.exchangeConcentration) {
+                        const bar = "\u2588".repeat(Math.round(ec.pct / 5)) + "\u2591".repeat(20 - Math.round(ec.pct / 5));
+                        console.log(`    ${ec.exchange.padEnd(12)} ${bar} ${ec.pct.toFixed(1)}%`);
+                    }
+                }
+                if (summary.risk.violations.length > 0) {
+                    console.log(chalk.red.bold("\n  Risk Violations"));
+                    for (const v of summary.risk.violations) {
+                        const sevColor = { low: chalk.green, medium: chalk.yellow, high: chalk.red, critical: chalk.bgRed.white }[v.severity];
+                        console.log(`    ${sevColor(v.severity.toUpperCase().padEnd(8))} ${v.message}`);
+                    }
+                }
+                console.log();
+            });
+        });
+    }
 }