perp-cli 0.3.3

package/dist/commands/dex.js

@@ -0,0 +1,114 @@
+import chalk from "chalk";
+import { HyperliquidAdapter } from "../exchanges/hyperliquid.js";
+import { printJson, jsonOk, makeTable, formatUsd, withJsonErrors } from "../utils.js";
+export function registerDexCommands(program, getAdapter, isJson) {
+    const dex = program.command("dex").description("HIP-3 deployed perp dex commands (Hyperliquid)");
+    // ── dex list ──
+    dex
+        .command("list")
+        .description("List all available HIP-3 deployed perp dexes")
+        .action(async () => {
+        await withJsonErrors(isJson(), async () => {
+            const adapter = await getAdapter();
+            if (!(adapter instanceof HyperliquidAdapter)) {
+                console.error(chalk.red("\n  HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid.\n"));
+                return;
+            }
+            const dexes = await adapter.listDeployedDexes();
+            if (isJson())
+                return printJson(jsonOk(dexes));
+            if (dexes.length === 0) {
+                console.log(chalk.gray("\n  No deployed dexes found.\n"));
+                return;
+            }
+            console.log(chalk.cyan.bold("\n  HIP-3 Deployed Perp DEXes\n"));
+            const rows = dexes.map(d => [
+                chalk.white.bold(d.name),
+                chalk.gray(d.deployer.slice(0, 10) + "..."),
+                String(d.assets.length),
+                d.assets.slice(0, 5).join(", ") + (d.assets.length > 5 ? ` +${d.assets.length - 5}` : ""),
+            ]);
+            console.log(makeTable(["DEX", "Deployer", "Assets", "Markets"], rows));
+            console.log(chalk.gray(`\n  Use --dex <name> to trade on a deployed dex.\n`));
+            console.log(chalk.gray(`  Example: perp -e hyperliquid --dex xyz market list\n`));
+        });
+    });
+    // ── dex markets <dex-name> ──
+    dex
+        .command("markets <dexName>")
+        .description("List all markets on a specific HIP-3 dex")
+        .action(async (dexName) => {
+        await withJsonErrors(isJson(), async () => {
+            const adapter = await getAdapter();
+            if (!(adapter instanceof HyperliquidAdapter)) {
+                console.error(chalk.red("\n  HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid.\n"));
+                return;
+            }
+            // Temporarily switch dex, fetch markets, then restore
+            const prevDex = adapter.dex;
+            adapter.setDex(dexName);
+            try {
+                const markets = await adapter.getMarkets();
+                if (isJson())
+                    return printJson(jsonOk({ dex: dexName, markets }));
+                if (markets.length === 0) {
+                    console.log(chalk.gray(`\n  No markets found on dex "${dexName}".\n`));
+                    return;
+                }
+                console.log(chalk.cyan.bold(`\n  ${dexName.toUpperCase()} DEX Markets\n`));
+                const rows = markets.map(m => [
+                    chalk.white.bold(m.symbol),
+                    `$${formatUsd(m.markPrice)}`,
+                    m.fundingRate !== "0" ? `${(Number(m.fundingRate) * 100).toFixed(4)}%` : chalk.gray("-"),
+                    `$${formatUsd(m.volume24h)}`,
+                    `$${formatUsd(m.openInterest)}`,
+                    `${m.maxLeverage}x`,
+                ]);
+                console.log(makeTable(["Symbol", "Mark Price", "Funding", "24h Volume", "OI", "Max Lev"], rows));
+                console.log(chalk.gray(`\n  Trade: perp -e hyperliquid --dex ${dexName} trade market <symbol> <side> <size>\n`));
+            }
+            finally {
+                adapter.setDex(prevDex);
+            }
+        });
+    });
+    // ── dex balance <dex-name> ──
+    dex
+        .command("balance <dexName>")
+        .description("Show balance on a specific HIP-3 dex")
+        .action(async (dexName) => {
+        await withJsonErrors(isJson(), async () => {
+            const adapter = await getAdapter();
+            if (!(adapter instanceof HyperliquidAdapter)) {
+                console.error(chalk.red("\n  HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid.\n"));
+                return;
+            }
+            const prevDex = adapter.dex;
+            adapter.setDex(dexName);
+            try {
+                const [balance, positions] = await Promise.all([
+                    adapter.getBalance(),
+                    adapter.getPositions(),
+                ]);
+                if (isJson())
+                    return printJson(jsonOk({ dex: dexName, balance, positions }));
+                console.log(chalk.cyan.bold(`\n  ${dexName.toUpperCase()} DEX Balance\n`));
+                console.log(`  Equity:      $${formatUsd(balance.equity)}`);
+                console.log(`  Available:   $${formatUsd(balance.available)}`);
+                console.log(`  Margin Used: $${formatUsd(balance.marginUsed)}`);
+                console.log(`  uPnL:        $${formatUsd(balance.unrealizedPnl)}`);
+                if (positions.length > 0) {
+                    console.log(chalk.white.bold("\n  Positions:"));
+                    for (const p of positions) {
+                        const color = p.side === "long" ? chalk.green : chalk.red;
+                        console.log(`    ${color(p.side.toUpperCase().padEnd(5))} ${chalk.white(p.symbol.padEnd(16))} ${p.size.padEnd(10)} entry: $${Number(p.entryPrice).toFixed(2)}  pnl: $${Number(p.unrealizedPnl).toFixed(2)}`);
+                    }
+                }
+                console.log();
+            }
+            finally {
+                adapter.setDex(prevDex);
+            }
+        });
+    });
+}

package/dist/commands/env.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerEnvCommands(program: Command, isJson: () => boolean): void;

package/dist/commands/env.js

@@ -0,0 +1,136 @@
+import chalk from "chalk";
+import { printJson, jsonOk } from "../utils.js";
+import { ENV_FILE, loadEnvFile, setEnvVar, EXCHANGE_ENV_MAP, validateKey } from "./init.js";
+// Resolve exchange alias → env var key
+function resolveEnvKey(nameOrKey) {
+    // Direct env var name
+    const upper = nameOrKey.toUpperCase();
+    for (const info of Object.values(EXCHANGE_ENV_MAP)) {
+        if (info.envKey === upper)
+            return { envKey: info.envKey, chain: info.chain };
+    }
+    // Exchange name alias
+    const info = EXCHANGE_ENV_MAP[nameOrKey.toLowerCase()];
+    if (info)
+        return { envKey: info.envKey, chain: info.chain };
+    // Common aliases
+    const aliases = { hl: "hyperliquid", pac: "pacifica", lt: "lighter" };
+    const aliased = aliases[nameOrKey.toLowerCase()];
+    if (aliased)
+        return resolveEnvKey(aliased);
+    return null;
+}
+export function registerEnvCommands(program, isJson) {
+    const env = program.command("env").description("Manage ~/.perp/.env configuration");
+    // ── perp env show ──
+    env
+        .command("show")
+        .description("Show current configuration")
+        .action(async () => {
+        const stored = loadEnvFile();
+        const entries = [];
+        for (const [exchange, info] of Object.entries(EXCHANGE_ENV_MAP)) {
+            const fromFile = stored[info.envKey];
+            const fromEnv = process.env[info.envKey];
+            if (fromFile) {
+                entries.push({ name: exchange, chain: info.chain, key: fromFile, source: "~/.perp/.env" });
+            }
+            else if (fromEnv) {
+                entries.push({ name: exchange, chain: info.chain, key: fromEnv, source: "environment" });
+            }
+        }
+        // Derive addresses
+        const results = [];
+        for (const entry of entries) {
+            const { valid, address } = await validateKey(entry.chain, entry.key);
+            results.push({ name: entry.name, address: valid ? address : "(invalid key)", source: entry.source });
+        }
+        if (isJson()) {
+            const data = results.map((r) => ({ exchange: r.name, address: r.address, source: r.source }));
+            return printJson(jsonOk({ envFile: ENV_FILE, exchanges: data }));
+        }
+        console.log(chalk.cyan.bold("\n  perp-cli Configuration\n"));
+        console.log(`  File: ${chalk.gray(ENV_FILE)}\n`);
+        if (results.length === 0) {
+            console.log(chalk.gray("  No keys configured. Run 'perp init' or 'perp env set <exchange> <key>'\n"));
+            return;
+        }
+        for (const { name, address, source } of results) {
+            console.log(`  ${chalk.cyan(name.padEnd(14))} ${chalk.green(address)}  ${chalk.gray(source)}`);
+        }
+        console.log();
+    });
+    // ── perp env set <exchange|key> <value> ──
+    env
+        .command("set <name> <value>")
+        .description("Set a key (exchange name or env var name)")
+        .action(async (name, value) => {
+        const resolved = resolveEnvKey(name);
+        if (resolved) {
+            // Validate the key
+            const { valid, address } = await validateKey(resolved.chain, value);
+            if (!valid) {
+                if (isJson()) {
+                    const { jsonError } = await import("../utils.js");
+                    return printJson(jsonError("INVALID_PARAMS", `Invalid ${resolved.chain} private key`));
+                }
+                console.error(chalk.red(`\n  Invalid ${resolved.chain} private key.\n`));
+                process.exit(1);
+            }
+            const normalized = resolved.chain === "evm"
+                ? (value.startsWith("0x") ? value : `0x${value}`)
+                : value;
+            setEnvVar(resolved.envKey, normalized);
+            if (isJson())
+                return printJson(jsonOk({ key: resolved.envKey, address, file: ENV_FILE }));
+            console.log(chalk.green(`\n  ${resolved.envKey} set.`));
+            console.log(`  Address: ${chalk.gray(address)}`);
+            console.log(`  File:    ${chalk.gray("~/.perp/.env")}\n`);
+        }
+        else {
+            // Raw env var (e.g. LIGHTER_API_KEY, custom vars)
+            setEnvVar(name, value);
+            if (isJson())
+                return printJson(jsonOk({ key: name, file: ENV_FILE }));
+            console.log(chalk.green(`\n  ${name} set.`));
+            console.log(`  File: ${chalk.gray("~/.perp/.env")}\n`);
+        }
+    });
+    // ── perp env remove <name> ──
+    env
+        .command("remove <name>")
+        .description("Remove a key from ~/.perp/.env")
+        .action(async (name) => {
+        const resolved = resolveEnvKey(name);
+        const envKey = resolved?.envKey || name;
+        const env = loadEnvFile();
+        if (!(envKey in env)) {
+            if (isJson()) {
+                const { jsonError } = await import("../utils.js");
+                return printJson(jsonError("NOT_FOUND", `${envKey} not found in ~/.perp/.env`));
+            }
+            console.log(chalk.gray(`\n  ${envKey} not found in ~/.perp/.env\n`));
+            return;
+        }
+        delete env[envKey];
+        // Rewrite file
+        const { writeFileSync } = await import("fs");
+        const lines = ["# perp-cli configuration", "# Generated by 'perp init' — edit freely", ""];
+        for (const [k, v] of Object.entries(env))
+            lines.push(`${k}=${v}`);
+        lines.push("");
+        writeFileSync(ENV_FILE, lines.join("\n"), { mode: 0o600 });
+        if (isJson())
+            return printJson(jsonOk({ removed: envKey }));
+        console.log(chalk.yellow(`\n  ${envKey} removed from ~/.perp/.env\n`));
+    });
+    // ── perp env path ──
+    env
+        .command("path")
+        .description("Print env file path")
+        .action(() => {
+        if (isJson())
+            return printJson(jsonOk({ path: ENV_FILE }));
+        console.log(ENV_FILE);
+    });
+}

package/dist/commands/funding.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerFundingCommands(program: Command, isJson: () => boolean): void;

package/dist/commands/funding.js

@@ -0,0 +1,347 @@
+import chalk from "chalk";
+import { makeTable, formatPercent, formatUsd, printJson, jsonOk } from "../utils.js";
+import { fetchAllFundingRates, fetchSymbolFundingRates, TOP_SYMBOLS, } from "../funding-rates.js";
+import { annualizeHourlyRate } from "../funding.js";
+import { saveFundingSnapshot, getHistoricalRates, getCompoundedAnnualReturn, getExchangeCompoundingHours, } from "../funding-history.js";
+export function registerFundingCommands(program, isJson) {
+    const funding = program.command("funding").description("Funding rate comparison across exchanges");
+    // ── perp funding rates ── (default: show top symbols)
+    funding
+        .command("rates")
+        .description("Show funding rates across all 3 DEXs for top symbols")
+        .option("-s, --symbol <symbol>", "Filter to a specific symbol")
+        .option("--symbols <list>", "Comma-separated list of symbols")
+        .option("--all", "Show all available symbols (not just top ones)")
+        .option("--min-spread <pct>", "Minimum annual spread % to show", "0")
+        .action(async (opts) => {
+        const minSpread = parseFloat(opts.minSpread);
+        let filterSymbols;
+        if (opts.symbol) {
+            filterSymbols = [opts.symbol.toUpperCase()];
+        }
+        else if (opts.symbols) {
+            filterSymbols = opts.symbols.split(",").map(s => s.trim().toUpperCase());
+        }
+        else if (!opts.all) {
+            filterSymbols = TOP_SYMBOLS;
+        }
+        if (!isJson())
+            console.log(chalk.cyan("  Fetching funding rates from all exchanges...\n"));
+        const snapshot = await fetchAllFundingRates({
+            symbols: filterSymbols,
+            minSpread,
+        });
+        // Persist snapshot for historical tracking (moved from fetchAllFundingRates to avoid side effect)
+        try {
+            const allRates = snapshot.symbols.flatMap(s => s.rates);
+            if (allRates.length > 0)
+                saveFundingSnapshot(allRates);
+        }
+        catch { /* non-critical */ }
+        if (isJson())
+            return printJson(jsonOk(snapshot));
+        printSnapshotTable(snapshot);
+        printExchangeStatus(snapshot);
+        console.log(chalk.gray("  * Rates shown are current predictions. Actual settled rates may differ.\n"));
+    });
+    // ── perp funding compare <symbol> ── (detailed single-symbol view)
+    funding
+        .command("compare <symbol>")
+        .description("Detailed funding rate comparison for a single symbol")
+        .action(async (symbol) => {
+        if (!isJson())
+            console.log(chalk.cyan(`  Fetching funding rates for ${symbol.toUpperCase()}...\n`));
+        const comparison = await fetchSymbolFundingRates(symbol);
+        if (!comparison) {
+            if (isJson())
+                return printJson(jsonOk({ symbol: symbol.toUpperCase(), available: false }));
+            console.log(chalk.gray(`  ${symbol.toUpperCase()} not found on at least 2 exchanges.\n`));
+            return;
+        }
+        if (isJson())
+            return printJson(jsonOk(comparison));
+        printDetailedComparison(comparison);
+    });
+    // ── perp funding spread ── (sorted by spread opportunities)
+    funding
+        .command("spread")
+        .description("Show best funding rate arb opportunities sorted by spread")
+        .option("--min <pct>", "Min annual spread to show", "10")
+        .option("--top <n>", "Show top N opportunities", "20")
+        .action(async (opts) => {
+        const minSpread = parseFloat(opts.min);
+        const topN = parseInt(opts.top);
+        if (!isJson())
+            console.log(chalk.cyan("  Scanning funding rate spreads across all exchanges...\n"));
+        const snapshot = await fetchAllFundingRates({ minSpread });
+        const shown = snapshot.symbols.slice(0, topN);
+        if (isJson())
+            return printJson(jsonOk(shown));
+        if (shown.length === 0) {
+            console.log(chalk.gray(`  No opportunities above ${minSpread}% annual spread.\n`));
+            return;
+        }
+        console.log(chalk.cyan.bold("  Funding Rate Arb Opportunities\n"));
+        console.log(chalk.gray("  Strategy: Long on low-funding exchange, Short on high-funding exchange\n"));
+        const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : "LT";
+        const rows = shown.map(s => {
+            const pacRate = s.rates.find(r => r.exchange === "pacifica");
+            const hlRate = s.rates.find(r => r.exchange === "hyperliquid");
+            const ltRate = s.rates.find(r => r.exchange === "lighter");
+            const spreadColor = s.maxSpreadAnnual >= 50 ? chalk.green.bold
+                : s.maxSpreadAnnual >= 20 ? chalk.green
+                    : chalk.yellow;
+            return [
+                chalk.white.bold(s.symbol),
+                `$${formatUsd(s.bestMarkPrice)}`,
+                pacRate ? formatPercent(pacRate.fundingRate) : chalk.gray("-"),
+                hlRate ? formatPercent(hlRate.fundingRate) : chalk.gray("-"),
+                ltRate ? formatPercent(ltRate.fundingRate) : chalk.gray("-"),
+                spreadColor(`${s.maxSpreadAnnual.toFixed(1)}%`),
+                getAvgSpread(s, "avg24h"),
+                `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}`,
+                `$${s.estHourlyIncomeUsd.toFixed(4)}/hr`,
+            ];
+        });
+        console.log(makeTable(["Symbol", "Price", "Pacifica", "Hyperliquid", "Lighter", "Ann.Spread", "Avg Spread(24h)", "Direction", "Est.Income/$1K"], rows));
+        console.log(chalk.gray(`\n  ${shown.length} opportunities above ${minSpread}% annual spread`));
+        console.log(chalk.gray(`  Income estimated for $1,000 notional per leg`));
+        console.log(chalk.gray(`  Use 'perp arb auto --min-spread ${minSpread}' to auto-trade`));
+        console.log(chalk.gray("\n  * Rates shown are current predictions. Actual settled rates may differ.\n"));
+    });
+    // ── perp funding history ── (rate trend over time)
+    funding
+        .command("history")
+        .description("Show funding rate trend over time for a symbol")
+        .requiredOption("-s, --symbol <symbol>", "Symbol to show history for")
+        .option("--hours <n>", "Number of hours to look back", "24")
+        .option("--exchange <ex>", "Filter to a specific exchange")
+        .action(async (opts) => {
+        const symbol = opts.symbol.toUpperCase();
+        const hours = parseInt(opts.hours);
+        const exchanges = opts.exchange
+            ? [opts.exchange.toLowerCase()]
+            : ["hyperliquid", "pacifica", "lighter"];
+        const endTime = new Date();
+        const startTime = new Date(endTime.getTime() - hours * 60 * 60 * 1000);
+        if (isJson()) {
+            const data = {};
+            for (const ex of exchanges) {
+                const rates = getHistoricalRates(symbol, ex, startTime, endTime);
+                if (rates.length > 0)
+                    data[ex] = rates;
+            }
+            return printJson(jsonOk({ symbol, hours, startTime: startTime.toISOString(), endTime: endTime.toISOString(), rates: data }));
+        }
+        console.log(chalk.cyan.bold(`  ${symbol} Funding Rate History (last ${hours}h)\n`));
+        const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : "LT";
+        let hasData = false;
+        for (const ex of exchanges) {
+            const rates = getHistoricalRates(symbol, ex, startTime, endTime);
+            if (rates.length === 0)
+                continue;
+            hasData = true;
+            console.log(chalk.white.bold(`  ${exAbbr(ex)} (${rates.length} snapshots):`));
+            const rows = rates.map(r => {
+                const date = new Date(r.ts);
+                const timeStr = date.toLocaleString();
+                const hourlyPct = (r.hourlyRate * 100).toFixed(6);
+                const annualPct = annualizeHourlyRate(r.hourlyRate).toFixed(2);
+                const color = r.rate > 0 ? chalk.red : r.rate < 0 ? chalk.green : chalk.white;
+                return [
+                    chalk.gray(timeStr),
+                    color(formatPercent(r.rate)),
+                    `${hourlyPct}%/h`,
+                    `${annualPct}%/yr`,
+                ];
+            });
+            console.log(makeTable(["Time", "Raw Rate", "Hourly", "Annualized"], rows));
+            console.log();
+        }
+        if (!hasData) {
+            console.log(chalk.gray(`  No historical data found for ${symbol} in the last ${hours}h.`));
+            console.log(chalk.gray(`  Run 'perp funding rates' to start collecting data.\n`));
+        }
+    });
+    // ── perp funding monitor ── (live refreshing)
+    funding
+        .command("monitor")
+        .description("Live-monitor funding rates with auto-refresh")
+        .option("--min <pct>", "Min annual spread to show", "10")
+        .option("--interval <sec>", "Refresh interval in seconds", "30")
+        .option("--top <n>", "Show top N", "15")
+        .option("--symbols <list>", "Comma-separated symbols to watch")
+        .action(async (opts) => {
+        const minSpread = parseFloat(opts.min);
+        const intervalSec = parseInt(opts.interval);
+        const topN = parseInt(opts.top);
+        const filterSymbols = opts.symbols?.split(",").map(s => s.trim().toUpperCase());
+        let cycle = 0;
+        if (!isJson()) {
+            console.log(chalk.cyan.bold("\n  Funding Rate Monitor"));
+            console.log(chalk.gray(`  Min spread: ${minSpread}% | Refresh: ${intervalSec}s | Top: ${topN}`));
+            if (filterSymbols)
+                console.log(chalk.gray(`  Symbols: ${filterSymbols.join(", ")}`));
+            console.log(chalk.gray(`  Press Ctrl+C to stop\n`));
+        }
+        const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : "LT";
+        while (true) {
+            cycle++;
+            const ts = new Date().toLocaleTimeString();
+            try {
+                const snapshot = await fetchAllFundingRates({
+                    symbols: filterSymbols,
+                    minSpread,
+                });
+                const shown = snapshot.symbols.slice(0, topN);
+                if (isJson()) {
+                    printJson(jsonOk({ cycle, timestamp: ts, opportunities: shown }));
+                }
+                else {
+                    // Clear previous output
+                    if (cycle > 1) {
+                        const linesToClear = shown.length + 4;
+                        process.stdout.write(`\x1b[${linesToClear}A\x1b[J`);
+                    }
+                    console.log(chalk.gray(`  ${ts} -- Cycle ${cycle} | ${shown.length} opportunities >= ${minSpread}%\n`));
+                    if (shown.length === 0) {
+                        console.log(chalk.gray(`  No opportunities found.\n`));
+                    }
+                    else {
+                        for (const s of shown) {
+                            const direction = `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}`;
+                            const spreadColor = s.maxSpreadAnnual >= 50 ? chalk.green.bold
+                                : s.maxSpreadAnnual >= 30 ? chalk.green
+                                    : chalk.yellow;
+                            const rateStrs = [];
+                            for (const r of s.rates) {
+                                rateStrs.push(`${exAbbr(r.exchange)}:${(r.fundingRate * 100).toFixed(4)}%`);
+                            }
+                            console.log(`  ${chalk.white.bold(s.symbol.padEnd(8))} ` +
+                                `${spreadColor(`${s.maxSpreadAnnual.toFixed(1)}%`.padEnd(8))} ` +
+                                `${direction.padEnd(7)} ` +
+                                rateStrs.join(" "));
+                        }
+                        console.log();
+                    }
+                }
+            }
+            catch (err) {
+                if (!isJson()) {
+                    console.log(chalk.red(`  ${ts} Error: ${err instanceof Error ? err.message : err}\n`));
+                }
+            }
+            await new Promise(r => setTimeout(r, intervalSec * 1000));
+        }
+    });
+}
+// ── Display helpers ──
+function formatAvgRate(rate) {
+    if (rate == null)
+        return chalk.gray("-");
+    const annualPct = annualizeHourlyRate(rate);
+    const color = annualPct > 0 ? chalk.red : annualPct < 0 ? chalk.green : chalk.white;
+    return color(`${annualPct.toFixed(1)}%`);
+}
+/** Compute an "average spread" across rates that have avg24h data. */
+function getAvgSpread(s, windowKey) {
+    const avgs = s.rates
+        .filter(r => r.historicalAvg?.[windowKey] != null)
+        .map(r => r.historicalAvg[windowKey]);
+    if (avgs.length < 2)
+        return chalk.gray("-");
+    const maxH = Math.max(...avgs);
+    const minH = Math.min(...avgs);
+    const spreadPct = annualizeHourlyRate(maxH - minH);
+    return `${spreadPct.toFixed(1)}%`;
+}
+function printSnapshotTable(snapshot) {
+    const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : "LT";
+    if (snapshot.symbols.length === 0) {
+        console.log(chalk.gray("  No funding rate data available.\n"));
+        return;
+    }
+    const rows = snapshot.symbols.map(s => {
+        const pacRate = s.rates.find(r => r.exchange === "pacifica");
+        const hlRate = s.rates.find(r => r.exchange === "hyperliquid");
+        const ltRate = s.rates.find(r => r.exchange === "lighter");
+        const spreadColor = s.maxSpreadAnnual >= 30 ? chalk.green
+            : s.maxSpreadAnnual >= 10 ? chalk.yellow
+                : chalk.white;
+        // Use the highest-spread pair's historical averages for the avg columns
+        // Show the best exchange's avg for quick reference
+        const bestRate = hlRate ?? pacRate ?? ltRate;
+        const avg8h = bestRate?.historicalAvg?.avg8h;
+        const avg24h = bestRate?.historicalAvg?.avg24h;
+        const avg7d = bestRate?.historicalAvg?.avg7d;
+        return [
+            chalk.white.bold(s.symbol),
+            pacRate ? formatPercent(pacRate.fundingRate) : chalk.gray("-"),
+            hlRate ? formatPercent(hlRate.fundingRate) : chalk.gray("-"),
+            ltRate ? formatPercent(ltRate.fundingRate) : chalk.gray("-"),
+            spreadColor(`${s.maxSpreadAnnual.toFixed(1)}%`),
+            s.maxSpreadAnnual >= 5 ? `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}` : chalk.gray("-"),
+            formatAvgRate(avg8h),
+            formatAvgRate(avg24h),
+            formatAvgRate(avg7d),
+        ];
+    });
+    console.log(makeTable(["Symbol", "Pacifica", "Hyperliquid", "Lighter", "Ann. Spread", "Direction", "Avg 8h", "Avg 24h", "Avg 7d"], rows));
+    console.log(chalk.gray(`\n  ${snapshot.symbols.length} symbols compared across exchanges.`));
+    console.log(chalk.gray(`  Rates: All exchanges per 1h. Spread is normalized.`));
+    console.log(chalk.gray(`  Avg columns show best exchange's historical hourly rate annualized.\n`));
+}
+function printExchangeStatus(snapshot) {
+    const statuses = Object.entries(snapshot.exchangeStatus).map(([ex, status]) => {
+        const indicator = status === "ok" ? chalk.green("OK") : chalk.red("ERR");
+        return `${ex}: ${indicator}`;
+    });
+    console.log(chalk.gray(`  Exchange status: ${statuses.join("  ")}\n`));
+}
+function printDetailedComparison(comparison) {
+    const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : "LT";
+    console.log(chalk.cyan.bold(`  ${comparison.symbol} Funding Rate Comparison\n`));
+    console.log(`  Mark Price: $${formatUsd(comparison.bestMarkPrice)}\n`);
+    for (const r of comparison.rates) {
+        const hourlyPct = (r.hourlyRate * 100).toFixed(6);
+        const annualPct = r.annualizedPct.toFixed(2);
+        const compHours = getExchangeCompoundingHours(r.exchange);
+        const compoundedReturn = getCompoundedAnnualReturn(r.hourlyRate, compHours);
+        const compoundedPct = (compoundedReturn * 100).toFixed(2);
+        const color = r.fundingRate > 0 ? chalk.red : r.fundingRate < 0 ? chalk.green : chalk.white;
+        console.log(`  ${chalk.white.bold(exAbbr(r.exchange).padEnd(4))} ` +
+            `Raw: ${color(formatPercent(r.fundingRate).padEnd(14))} ` +
+            `Hourly: ${hourlyPct}%  ` +
+            `Annual: ${annualPct}%  ` +
+            `APY(compounded): ${compoundedPct}%`);
+    }
+    // Show historical averages if available
+    const hasHistorical = comparison.rates.some(r => r.historicalAvg != null);
+    if (hasHistorical) {
+        console.log(chalk.cyan("\n  Historical Averages (annualized):"));
+        for (const r of comparison.rates) {
+            if (!r.historicalAvg)
+                continue;
+            const avg8h = r.historicalAvg.avg8h != null ? `${annualizeHourlyRate(r.historicalAvg.avg8h).toFixed(1)}%` : "-";
+            const avg24h = r.historicalAvg.avg24h != null ? `${annualizeHourlyRate(r.historicalAvg.avg24h).toFixed(1)}%` : "-";
+            const avg7d = r.historicalAvg.avg7d != null ? `${annualizeHourlyRate(r.historicalAvg.avg7d).toFixed(1)}%` : "-";
+            console.log(`  ${chalk.white.bold(exAbbr(r.exchange).padEnd(4))} ` +
+                `8h: ${avg8h.padEnd(10)} 24h: ${avg24h.padEnd(10)} 7d: ${avg7d}`);
+        }
+    }
+    console.log();
+    const spreadColor = comparison.maxSpreadAnnual >= 30 ? chalk.green.bold
+        : comparison.maxSpreadAnnual >= 10 ? chalk.yellow
+            : chalk.white;
+    console.log(`  Max Spread:     ${spreadColor(`${comparison.maxSpreadAnnual.toFixed(1)}%`)} annual`);
+    console.log(`  Direction:      Long ${exAbbr(comparison.longExchange)} / Short ${exAbbr(comparison.shortExchange)}`);
+    console.log(`  Est. Income:    $${comparison.estHourlyIncomeUsd.toFixed(4)}/hr per $1K notional`);
+    // Show income at different position sizes
+    const sizes = [1000, 5000, 10000, 50000];
+    console.log(chalk.gray("\n  Estimated daily income by position size:"));
+    for (const size of sizes) {
+        const daily = (comparison.estHourlyIncomeUsd / 1000) * size * 24;
+        console.log(chalk.gray(`    $${formatUsd(size)} notional -> $${daily.toFixed(2)}/day`));
+    }
+    console.log(chalk.gray("\n  * Rates shown are current predictions. Actual settled rates may differ.\n"));
+}

package/dist/commands/gap.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerGapCommands(program: Command, isJson: () => boolean): void;