perp-cli 0.4.11 → 0.5.0

package/dist/commands/arb.js

@@ -1,4 +1,4 @@
-import { makeTable, formatUsd, formatPercent, formatPnl, printJson, jsonOk, jsonError, withJsonErrors } from "../utils.js";
+import { makeTable, formatUsd, formatPercent, formatPnl, printJson, jsonOk, withJsonErrors } from "../utils.js";
 import chalk from "chalk";
 import { annualizeRate, toHourlyRate, estimateHourlyFunding, annualizeHourlyRate } from "../funding.js";
 import { fetchAllFundingRates, fetchSymbolFundingRates, TOP_SYMBOLS, } from "../funding-rates.js";
@@ -53,183 +53,10 @@ async function fetchLighterRates() {
 // annualize moved to ../funding.ts — use annualizeRate() / computeAnnualSpread()
 export function registerArbCommands(program, isJson, getAdapterForExchange) {
     const arb = program.command("arb").description("Funding rate arbitrage & basis trading");
-    // Deprecated: arb funding → use 'perp arb rates'
-    const fundingCmd = arb.command("funding").description("Use 'perp arb rates'");
-    fundingCmd._hidden = true;
-    fundingCmd.action(() => console.log("Use 'perp arb rates --min-spread 5' instead."));
-    arb
-        .command("basis")
-        .description("Show basis (spot vs perp price) opportunities across exchanges")
-        .option("--min-basis <pct>", "Minimum annual basis % to show", "3")
-        .action(async (opts) => {
-        if (!isJson())
-            console.log(chalk.cyan("  Fetching prices for basis calculation...\n"));
-        const [pacRates, hlRates, ltRates] = await Promise.all([
-            fetchPacificaRates(),
-            fetchHyperliquidRates(),
-            fetchLighterRates(),
-        ]);
-        // Compare mark prices across all exchanges for cross-exchange basis
-        const exchangePrices = new Map();
-        for (const r of [...pacRates, ...hlRates, ...ltRates]) {
-            if (r.markPrice <= 0)
-                continue;
-            if (!exchangePrices.has(r.symbol))
-                exchangePrices.set(r.symbol, new Map());
-            exchangePrices.get(r.symbol).set(r.exchange, r.markPrice);
-        }
-        const opps = [];
-        for (const [symbol, prices] of exchangePrices.entries()) {
-            if (prices.size < 2)
-                continue;
-            // Find cheapest and most expensive exchange
-            let minEx = "", maxEx = "", minPrice = Infinity, maxPrice = 0;
-            for (const [ex, price] of prices) {
-                if (price < minPrice) {
-                    minPrice = price;
-                    minEx = ex;
-                }
-                if (price > maxPrice) {
-                    maxPrice = price;
-                    maxEx = ex;
-                }
-            }
-            if (minEx === maxEx)
-                continue;
-            const diff = maxPrice - minPrice;
-            const avgPrice = (maxPrice + minPrice) / 2;
-            const pctDiff = (diff / avgPrice) * 100;
-            if (pctDiff * 365 >= parseFloat(opts.minBasis)) {
-                const priceObj = {};
-                for (const [ex, p] of prices)
-                    priceObj[ex] = p;
-                opps.push({
-                    symbol,
-                    prices: priceObj,
-                    priceDiff: diff,
-                    pctDiff,
-                    buyOn: minEx,
-                    sellOn: maxEx,
-                });
-            }
-        }
-        opps.sort((a, b) => b.pctDiff - a.pctDiff);
-        if (isJson())
-            return printJson(jsonOk(opps));
-        if (opps.length === 0) {
-            console.log(chalk.gray(`  No basis opportunities above ${opts.minBasis}% threshold.\n`));
-            return;
-        }
-        console.log(chalk.cyan.bold("  Cross-Exchange Basis Opportunities\n"));
-        console.log(chalk.gray("  Strategy: Buy cheap, sell expensive, profit from convergence.\n"));
-        const rows = opps.map((o) => [
-            chalk.white.bold(o.symbol),
-            o.prices.pacifica ? `$${formatUsd(o.prices.pacifica)}` : chalk.gray("-"),
-            o.prices.hyperliquid ? `$${formatUsd(o.prices.hyperliquid)}` : chalk.gray("-"),
-            o.prices.lighter ? `$${formatUsd(o.prices.lighter)}` : chalk.gray("-"),
-            `$${formatUsd(o.priceDiff)}`,
-            `${o.pctDiff.toFixed(4)}%`,
-            chalk.green(o.buyOn),
-            chalk.red(o.sellOn),
-        ]);
-        console.log(makeTable(["Symbol", "Pacifica", "Hyperliquid", "Lighter", "Diff", "Basis %", "Buy On", "Sell On"], rows));
-    });
-    // ── arb dex ── (HIP-3 cross-dex funding arb scan)
-    arb
-        .command("dex")
-        .description("Scan HIP-3 cross-dex funding arb opportunities on Hyperliquid")
-        .option("--min-spread <pct>", "Min annual spread % to show", "5")
-        .option("--max-gap <pct>", "Max price gap % to treat as same asset", "5")
-        .option("--include-native", "Include native HL perps in comparison", true)
-        .option("--no-include-native", "Exclude native HL perps")
-        .option("--top <n>", "Show top N opportunities", "30")
-        .action(async (opts) => {
-        if (!isJson())
-            console.log(chalk.cyan("  Scanning HIP-3 deployed dex funding spreads...\n"));
-        const pairs = await scanDexArb({
-            minAnnualSpread: parseFloat(opts.minSpread),
-            maxPriceGapPct: parseFloat(opts.maxGap),
-            includeNative: opts.includeNative,
-        });
-        const topN = parseInt(opts.top);
-        const shown = pairs.slice(0, topN);
-        if (isJson())
-            return printJson(jsonOk(shown.map(p => ({
-                underlying: p.underlying,
-                longDex: p.long.dex,
-                longSymbol: p.long.raw,
-                longFunding: p.long.fundingRate,
-                longPrice: p.long.markPrice,
-                longOiUsd: p.long.openInterest * p.long.markPrice,
-                longVolume24h: p.long.volume24h,
-                shortDex: p.short.dex,
-                shortSymbol: p.short.raw,
-                shortFunding: p.short.fundingRate,
-                shortPrice: p.short.markPrice,
-                shortOiUsd: p.short.openInterest * p.short.markPrice,
-                shortVolume24h: p.short.volume24h,
-                annualSpread: p.annualSpread,
-                priceGapPct: p.priceGapPct,
-                minOiUsd: p.minOiUsd,
-                minVolume24hUsd: p.minVolume24hUsd,
-                viability: p.viability,
-            }))));
-        if (shown.length === 0) {
-            console.log(chalk.gray(`  No cross-dex opportunities above ${opts.minSpread}% annual spread.\n`));
-            return;
-        }
-        console.log(chalk.cyan.bold("  HIP-3 Cross-Dex Funding Arb Opportunities\n"));
-        console.log(chalk.gray("  Strategy: Long on low-funding dex, Short on high-funding dex (same underlying)\n"));
-        const rows = shown.map((p) => {
-            const spreadColor = p.annualSpread >= 50 ? chalk.green.bold
-                : p.annualSpread >= 20 ? chalk.green
-                    : chalk.yellow;
-            const viabilityColor = p.viability === "A" ? chalk.green.bold
-                : p.viability === "B" ? chalk.green
-                    : p.viability === "C" ? chalk.yellow
-                        : chalk.red;
-            const fmtOi = p.minOiUsd >= 1_000_000 ? `$${(p.minOiUsd / 1_000_000).toFixed(1)}M`
-                : p.minOiUsd >= 1_000 ? `$${(p.minOiUsd / 1_000).toFixed(0)}K`
-                    : `$${p.minOiUsd.toFixed(0)}`;
-            const fmtVol = p.minVolume24hUsd >= 1_000_000 ? `$${(p.minVolume24hUsd / 1_000_000).toFixed(1)}M`
-                : p.minVolume24hUsd >= 1_000 ? `$${(p.minVolume24hUsd / 1_000).toFixed(0)}K`
-                    : `$${p.minVolume24hUsd.toFixed(0)}`;
-            return [
-                chalk.white.bold(p.underlying),
-                `${p.long.dex}:${p.long.base}`,
-                formatPercent(p.long.fundingRate),
-                `${p.short.dex}:${p.short.base}`,
-                formatPercent(p.short.fundingRate),
-                `$${formatUsd(p.long.markPrice)}`,
-                spreadColor(`${p.annualSpread.toFixed(1)}%`),
-                p.priceGapPct < 0.1 ? chalk.green(`${p.priceGapPct.toFixed(3)}%`) : chalk.yellow(`${p.priceGapPct.toFixed(3)}%`),
-                viabilityColor(p.viability),
-                viabilityColor(fmtOi),
-                chalk.gray(fmtVol),
-            ];
-        });
-        console.log(makeTable(["Asset", "Long On", "L.Fund", "Short On", "S.Fund", "Price", "Ann.Spread", "Gap", "Grade", "MinOI", "MinVol"], rows));
-        // Summary
-        const dexes = new Set();
-        for (const p of shown) {
-            dexes.add(p.long.dex);
-            dexes.add(p.short.dex);
-        }
-        const gradeCount = { A: 0, B: 0, C: 0, D: 0 };
-        for (const p of shown)
-            gradeCount[p.viability]++;
-        console.log(chalk.gray(`\n  ${shown.length}/${pairs.length} opportunities | Dexes: ${[...dexes].sort().join(", ")}`));
-        console.log(chalk.gray(`  Grade: ${chalk.green.bold(`A(${gradeCount.A})`)} ${chalk.green(`B(${gradeCount.B})`)} ${chalk.yellow(`C(${gradeCount.C})`)} ${chalk.red(`D(${gradeCount.D})`)}`));
-        console.log(chalk.gray(`  A: OI>$1M  B: OI>$100K  C: OI>$10K  D: OI<$10K (thin — high risk)`));
-        console.log(chalk.gray(`  Note: HIP-3 dexes charge 2x fees. Factor into net profitability.\n`));
-    });
-    // ── arb watch/track/alert ── (promoted from arb gap)
-    registerGapDirectCommands(arb, isJson);
-    // ── Funding subcommands (merged from funding.ts) ──
-    registerFundingSubcommands(arb, isJson, getAdapterForExchange);
-    // Deprecated aliases removed — use arb prices/watch/track/alert/rates directly
+    // basis, dex, rates, compare, funding-history, funding-positions, gaps, live monitor
+    // → consolidated into 'arb scan' (in arb-auto.ts) with routing options
 }
-async function fetchAllPrices() {
+export async function fetchAllPrices() {
     const [pacRes, hlRes, ltRes] = await Promise.all([
         fetchPacificaPricesRaw(),
         fetchHyperliquidAllMidsRaw(),
@@ -289,14 +116,14 @@ async function fetchAllPrices() {
     }
     return snapshots.sort((a, b) => b.maxGapPct - a.maxGapPct);
 }
-function formatGapPrice(p) {
+export function formatGapPrice(p) {
     if (p >= 1000)
         return p.toFixed(2);
     if (p >= 1)
         return p.toFixed(4);
     return p.toFixed(6);
 }
-function printGapTable(snapshots, minGap) {
+export function printGapTable(snapshots, minGap) {
     const filtered = snapshots.filter((s) => s.maxGapPct >= minGap);
     if (filtered.length === 0) {
         console.log(chalk.gray(`\n  No gaps above ${minGap}%\n`));
@@ -322,7 +149,7 @@ function printGapTable(snapshots, minGap) {
     const top = filtered[0];
     console.log(chalk.gray(`\n  ${filtered.length} pairs | Avg gap: ${avgGap.toFixed(4)}% | Max: ${top.symbol} ${top.maxGapPct.toFixed(4)}%\n`));
 }
-function printTrackSummary(symbol, samples) {
+export function printTrackSummary(symbol, samples) {
     if (samples.length === 0) {
         console.log(chalk.gray("\n  No samples collected.\n"));
         return;
@@ -346,194 +173,6 @@ function printTrackSummary(symbol, samples) {
     }
     console.log();
 }
-/**
- * Register gap-related commands directly on the arb parent (promoted from arb gap).
- * - arb prices: snapshot of cross-exchange prices (was arb gap show)
- * - arb watch: live monitoring (was arb gap watch)
- * - arb track: track gap over time (was arb gap track)
- * - arb alert: threshold alert (was arb gap alert)
- */
-function registerGapDirectCommands(arb, isJson) {
-    // ── arb prices (was arb gap show) ──
-    arb
-        .command("prices")
-        .description("Show current prices across all exchanges with gap analysis")
-        .option("--min <pct>", "Minimum gap % to display", "0.01")
-        .option("--symbol <sym>", "Filter by symbol (e.g. BTC, ETH)")
-        .option("--top <n>", "Show top N gaps only")
-        .action(async (opts) => {
-        const minGap = parseFloat(opts.min);
-        if (!isJson())
-            console.log(chalk.cyan("\n  Fetching prices from Pacifica, Hyperliquid & Lighter...\n"));
-        let snapshots = await fetchAllPrices();
-        if (opts.symbol) {
-            const sym = opts.symbol.toUpperCase();
-            snapshots = snapshots.filter((s) => s.symbol.includes(sym));
-        }
-        if (opts.top) {
-            snapshots = snapshots.slice(0, parseInt(opts.top));
-        }
-        if (isJson())
-            return printJson(jsonOk(snapshots.filter((s) => s.maxGapPct >= minGap)));
-        printGapTable(snapshots, minGap);
-    });
-    // ── arb watch (was arb gap watch) ──
-    arb
-        .command("watch")
-        .description("Live-monitor price gaps across exchanges (auto-refresh)")
-        .option("--min <pct>", "Minimum gap % to display", "0.05")
-        .option("--interval <seconds>", "Refresh interval", "5")
-        .option("--symbol <sym>", "Filter by symbol")
-        .option("--beep", "Beep on gaps above 0.5%")
-        .action(async (opts) => {
-        const minGap = parseFloat(opts.min);
-        const intervalMs = parseInt(opts.interval) * 1000;
-        const beep = !!opts.beep;
-        if (!isJson()) {
-            console.log(chalk.cyan.bold("\n  Price Gap Monitor"));
-            console.log(`  Min gap:   ${minGap}%`);
-            console.log(`  Interval:  ${opts.interval}s`);
-            if (opts.symbol)
-                console.log(`  Symbol:    ${opts.symbol.toUpperCase()}`);
-            console.log(chalk.gray("  Ctrl+C to stop\n"));
-        }
-        const cycle = async () => {
-            try {
-                let snapshots = await fetchAllPrices();
-                if (opts.symbol) {
-                    const sym = opts.symbol.toUpperCase();
-                    snapshots = snapshots.filter((s) => s.symbol.includes(sym));
-                }
-                process.stdout.write("\x1B[2J\x1B[0f");
-                const now = new Date().toLocaleTimeString();
-                console.log(chalk.cyan.bold(`  Price Gap Monitor`) +
-                    chalk.gray(`  ${now}  (refresh: ${opts.interval}s)\n`));
-                printGapTable(snapshots, minGap);
-                const bigGaps = snapshots.filter((s) => s.maxGapPct >= 0.5);
-                if (bigGaps.length > 0) {
-                    console.log(chalk.red.bold(`  !! ${bigGaps.length} large gap(s): ` +
-                        bigGaps
-                            .map((s) => `${s.symbol}(${s.maxGapPct.toFixed(3)}%)`)
-                            .join(", ")));
-                    if (beep)
-                        process.stdout.write("\x07");
-                }
-            }
-            catch (err) {
-                console.error(chalk.gray(`  Error: ${err instanceof Error ? err.message : String(err)}`));
-            }
-        };
-        await cycle();
-        setInterval(cycle, intervalMs);
-        await new Promise(() => { }); // keep alive
-    });
-    // ── arb track (was arb gap track) ──
-    arb
-        .command("track")
-        .description("Track a symbol's price gap over time and print stats")
-        .requiredOption("-s, --symbol <sym>", "Symbol to track (e.g. BTC)")
-        .option("--duration <minutes>", "How long to track (minutes)", "10")
-        .option("--interval <seconds>", "Sample interval", "10")
-        .action(async (opts) => {
-        const symbol = opts.symbol.toUpperCase();
-        const durationMs = parseInt(opts.duration) * 60 * 1000;
-        const intervalMs = parseInt(opts.interval) * 1000;
-        const endTime = Date.now() + durationMs;
-        const samples = [];
-        if (!isJson()) {
-            console.log(chalk.cyan.bold(`\n  Tracking ${symbol} price gap\n`));
-            console.log(`  Duration:  ${opts.duration} min`);
-            console.log(`  Interval:  ${opts.interval}s`);
-            console.log(chalk.gray("  Collecting samples...\n"));
-        }
-        const sample = async () => {
-            const snapshots = await fetchAllPrices();
-            const s = snapshots.find((x) => x.symbol === symbol);
-            if (!s) {
-                console.log(chalk.gray(`  ${new Date().toLocaleTimeString()} — ${symbol} not found on both exchanges`));
-                return;
-            }
-            samples.push({
-                time: new Date().toLocaleTimeString(),
-                gap: s.maxGap,
-                gapPct: s.maxGapPct,
-                direction: `${s.cheapest}→${s.expensive}`,
-            });
-            const gapColor = s.maxGapPct >= 0.1 ? chalk.yellow : chalk.gray;
-            const parts = [`PAC: ${s.pacPrice !== null ? "$" + formatGapPrice(s.pacPrice) : "-"}`];
-            parts.push(`HL: ${s.hlPrice !== null ? "$" + formatGapPrice(s.hlPrice) : "-"}`);
-            parts.push(`LT: ${s.ltPrice !== null ? "$" + formatGapPrice(s.ltPrice) : "-"}`);
-            console.log(`  ${chalk.white(s.symbol.padEnd(6))} ` +
-                `${parts.join("  ")}  ` +
-                `${gapColor(`${s.maxGapPct.toFixed(4)}%`)}  ${s.cheapest}→${s.expensive}`);
-        };
-        await sample();
-        const timer = setInterval(async () => {
-            if (Date.now() >= endTime) {
-                clearInterval(timer);
-                printTrackSummary(symbol, samples);
-                return;
-            }
-            await sample();
-        }, intervalMs);
-        await new Promise((resolve) => {
-            setTimeout(resolve, durationMs + 1000);
-        });
-    });
-    // ── arb alert (was arb gap alert) ──
-    arb
-        .command("alert")
-        .description("Wait until a symbol's price gap exceeds a threshold, then exit")
-        .requiredOption("-s, --symbol <sym>", "Symbol to watch")
-        .requiredOption("--above <pct>", "Gap % threshold to trigger")
-        .option("--interval <seconds>", "Check interval", "5")
-        .action(async (opts) => {
-        const symbol = opts.symbol.toUpperCase();
-        const threshold = parseFloat(opts.above);
-        const intervalMs = parseInt(opts.interval) * 1000;
-        if (!isJson())
-            console.log(chalk.cyan(`\n  Waiting for ${symbol} gap > ${threshold}%...\n`));
-        const check = async () => {
-            const snapshots = await fetchAllPrices();
-            const s = snapshots.find((x) => x.symbol === symbol);
-            if (!s)
-                return false;
-            const now = new Date().toLocaleTimeString();
-            if (!isJson())
-                console.log(chalk.gray(`  ${now} ${symbol} gap: ${s.maxGapPct.toFixed(4)}%`));
-            if (s.maxGapPct >= threshold) {
-                if (isJson()) {
-                    printJson(jsonOk(s));
-                }
-                else {
-                    console.log(chalk.green.bold(`\n  TRIGGERED! ${symbol} gap: ${s.maxGapPct.toFixed(4)}% (> ${threshold}%)`));
-                    const lines = [];
-                    if (s.pacPrice !== null)
-                        lines.push(`  Pacifica:    $${formatGapPrice(s.pacPrice)}`);
-                    if (s.hlPrice !== null)
-                        lines.push(`  Hyperliquid: $${formatGapPrice(s.hlPrice)}`);
-                    if (s.ltPrice !== null)
-                        lines.push(`  Lighter:     $${formatGapPrice(s.ltPrice)}`);
-                    lines.push(`  Gap:         $${s.maxGap.toFixed(4)} (${s.cheapest}→${s.expensive})`);
-                    console.log(lines.join("\n") + "\n");
-                }
-                return true;
-            }
-            return false;
-        };
-        if (await check())
-            return;
-        await new Promise((resolve) => {
-            const timer = setInterval(async () => {
-                if (await check()) {
-                    clearInterval(timer);
-                    resolve();
-                }
-            }, intervalMs);
-        });
-    });
-}
-// registerGapSubcommands removed — use arb prices/watch/track/alert directly
 // ────────────────────────────────────────────────────────
 // Funding subcommands (merged from funding.ts)
 // ────────────────────────────────────────────────────────
@@ -590,162 +229,245 @@ function printDetailedComparison(comparison) {
     console.log(`  Direction:      Long ${exAbbr(comparison.longExchange)} / Short ${exAbbr(comparison.shortExchange)}`);
     console.log(`  Est. Income:    $${comparison.estHourlyIncomeUsd.toFixed(4)}/hr per $1K notional\n`);
 }
-function registerFundingSubcommands(parent, isJson, getAdapterForExchange) {
-    parent.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").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 });
-        try {
-            const allRates = snapshot.symbols.flatMap(s => s.rates);
-            if (allRates.length > 0)
-                saveFundingSnapshot(allRates);
+// registerFundingSubcommands removed — use 'arb scan --rates/--compare/--history/--positions' instead
+// ── Exported handler functions for use by arb-auto.ts scan routing ──
+export async function handleRates(isJson, 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 });
+    try {
+        const allRates = snapshot.symbols.flatMap(s => s.rates);
+        if (allRates.length > 0)
+            saveFundingSnapshot(allRates);
+    }
+    catch { /* non-critical */ }
+    if (isJson()) {
+        if (process.argv.includes("--ndjson") || process.argv.includes("--fields"))
+            return printJson(jsonOk(snapshot.symbols));
+        return printJson(jsonOk(snapshot));
+    }
+    printSnapshotTable(snapshot);
+    printFundingExchangeStatus(snapshot);
+}
+export async function handleBasisScan(isJson, opts) {
+    if (!isJson())
+        console.log(chalk.cyan("  Fetching prices for basis calculation...\n"));
+    const [pacRates, hlRates, ltRates] = await Promise.all([fetchPacificaRates(), fetchHyperliquidRates(), fetchLighterRates()]);
+    const exchangePrices = new Map();
+    for (const r of [...pacRates, ...hlRates, ...ltRates]) {
+        if (r.markPrice <= 0)
+            continue;
+        if (!exchangePrices.has(r.symbol))
+            exchangePrices.set(r.symbol, new Map());
+        exchangePrices.get(r.symbol).set(r.exchange, r.markPrice);
+    }
+    const opps = [];
+    for (const [symbol, prices] of exchangePrices.entries()) {
+        if (prices.size < 2)
+            continue;
+        let minEx = "", maxEx = "", minPrice = Infinity, maxPrice = 0;
+        for (const [ex, price] of prices) {
+            if (price < minPrice) {
+                minPrice = price;
+                minEx = ex;
+            }
+            if (price > maxPrice) {
+                maxPrice = price;
+                maxEx = ex;
+            }
         }
-        catch { /* non-critical */ }
-        if (isJson()) {
-            if (process.argv.includes("--ndjson") || process.argv.includes("--fields"))
-                return printJson(jsonOk(snapshot.symbols));
-            return printJson(jsonOk(snapshot));
+        if (minEx === maxEx)
+            continue;
+        const diff = maxPrice - minPrice;
+        const avgPrice = (maxPrice + minPrice) / 2;
+        const pctDiff = (diff / avgPrice) * 100;
+        if (pctDiff * 365 >= parseFloat(opts.minBasis)) {
+            const priceObj = {};
+            for (const [ex, p] of prices)
+                priceObj[ex] = p;
+            opps.push({ symbol, prices: priceObj, priceDiff: diff, pctDiff, buyOn: minEx, sellOn: maxEx });
         }
-        printSnapshotTable(snapshot);
-        printFundingExchangeStatus(snapshot);
+    }
+    opps.sort((a, b) => b.pctDiff - a.pctDiff);
+    if (isJson())
+        return printJson(jsonOk(opps));
+    if (opps.length === 0) {
+        console.log(chalk.gray(`  No basis opportunities above ${opts.minBasis}% threshold.\n`));
+        return;
+    }
+    console.log(chalk.cyan.bold("  Cross-Exchange Basis Opportunities\n"));
+    console.log(chalk.gray("  Strategy: Buy cheap, sell expensive, profit from convergence.\n"));
+    const rows = opps.map((o) => [
+        chalk.white.bold(o.symbol),
+        o.prices.pacifica ? `$${formatUsd(o.prices.pacifica)}` : chalk.gray("-"),
+        o.prices.hyperliquid ? `$${formatUsd(o.prices.hyperliquid)}` : chalk.gray("-"),
+        o.prices.lighter ? `$${formatUsd(o.prices.lighter)}` : chalk.gray("-"),
+        `$${formatUsd(o.priceDiff)}`, `${o.pctDiff.toFixed(4)}%`, chalk.green(o.buyOn), chalk.red(o.sellOn),
+    ]);
+    console.log(makeTable(["Symbol", "Pacifica", "Hyperliquid", "Lighter", "Diff", "Basis %", "Buy On", "Sell On"], rows));
+}
+export async function handleDexScan(isJson, opts) {
+    if (!isJson())
+        console.log(chalk.cyan("  Scanning HIP-3 deployed dex funding spreads...\n"));
+    const pairs = await scanDexArb({ minAnnualSpread: parseFloat(opts.minSpread), maxPriceGapPct: parseFloat(opts.maxGap), includeNative: opts.includeNative });
+    const topN = parseInt(opts.top);
+    const shown = pairs.slice(0, topN);
+    if (isJson())
+        return printJson(jsonOk(shown.map(p => ({
+            underlying: p.underlying, longDex: p.long.dex, longSymbol: p.long.raw, longFunding: p.long.fundingRate,
+            longPrice: p.long.markPrice, longOiUsd: p.long.openInterest * p.long.markPrice, longVolume24h: p.long.volume24h,
+            shortDex: p.short.dex, shortSymbol: p.short.raw, shortFunding: p.short.fundingRate, shortPrice: p.short.markPrice,
+            shortOiUsd: p.short.openInterest * p.short.markPrice, shortVolume24h: p.short.volume24h,
+            annualSpread: p.annualSpread, priceGapPct: p.priceGapPct, minOiUsd: p.minOiUsd, minVolume24hUsd: p.minVolume24hUsd, viability: p.viability,
+        }))));
+    if (shown.length === 0) {
+        console.log(chalk.gray(`  No cross-dex opportunities above ${opts.minSpread}% annual spread.\n`));
+        return;
+    }
+    console.log(chalk.cyan.bold("  HIP-3 Cross-Dex Funding Arb Opportunities\n"));
+    console.log(chalk.gray("  Strategy: Long on low-funding dex, Short on high-funding dex (same underlying)\n"));
+    const rows = shown.map((p) => {
+        const spreadColor = p.annualSpread >= 50 ? chalk.green.bold : p.annualSpread >= 20 ? chalk.green : chalk.yellow;
+        const viabilityColor = p.viability === "A" ? chalk.green.bold : p.viability === "B" ? chalk.green : p.viability === "C" ? chalk.yellow : chalk.red;
+        const fmtOi = p.minOiUsd >= 1_000_000 ? `$${(p.minOiUsd / 1_000_000).toFixed(1)}M` : p.minOiUsd >= 1_000 ? `$${(p.minOiUsd / 1_000).toFixed(0)}K` : `$${p.minOiUsd.toFixed(0)}`;
+        const fmtVol = p.minVolume24hUsd >= 1_000_000 ? `$${(p.minVolume24hUsd / 1_000_000).toFixed(1)}M` : p.minVolume24hUsd >= 1_000 ? `$${(p.minVolume24hUsd / 1_000).toFixed(0)}K` : `$${p.minVolume24hUsd.toFixed(0)}`;
+        return [chalk.white.bold(p.underlying), `${p.long.dex}:${p.long.base}`, formatPercent(p.long.fundingRate), `${p.short.dex}:${p.short.base}`, formatPercent(p.short.fundingRate), `$${formatUsd(p.long.markPrice)}`, spreadColor(`${p.annualSpread.toFixed(1)}%`), p.priceGapPct < 0.1 ? chalk.green(`${p.priceGapPct.toFixed(3)}%`) : chalk.yellow(`${p.priceGapPct.toFixed(3)}%`), viabilityColor(p.viability), viabilityColor(fmtOi), chalk.gray(fmtVol)];
     });
-    parent.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;
-        }
+    console.log(makeTable(["Asset", "Long On", "L.Fund", "Short On", "S.Fund", "Price", "Ann.Spread", "Gap", "Grade", "MinOI", "MinVol"], rows));
+    const dexes = new Set();
+    for (const p of shown) {
+        dexes.add(p.long.dex);
+        dexes.add(p.short.dex);
+    }
+    const gradeCount = { A: 0, B: 0, C: 0, D: 0 };
+    for (const p of shown)
+        gradeCount[p.viability]++;
+    console.log(chalk.gray(`\n  ${shown.length}/${pairs.length} opportunities | Dexes: ${[...dexes].sort().join(", ")}`));
+    console.log(chalk.gray(`  Grade: ${chalk.green.bold(`A(${gradeCount.A})`)} ${chalk.green(`B(${gradeCount.B})`)} ${chalk.yellow(`C(${gradeCount.C})`)} ${chalk.red(`D(${gradeCount.D})`)}`));
+    console.log(chalk.gray(`  A: OI>$1M  B: OI>$100K  C: OI>$10K  D: OI<$10K (thin — high risk)`));
+    console.log(chalk.gray(`  Note: HIP-3 dexes charge 2x fees. Factor into net profitability.\n`));
+}
+export async function handleCompare(isJson, 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(comparison));
-        printDetailedComparison(comparison);
-    });
-    parent.command("funding-history").description("Show funding rate trend over time for a symbol")
-        .requiredOption("-s, --symbol <symbol>", "Symbol").option("--hours <n>", "Hours to look back", "24").option("--exchange <ex>", "Filter 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 * 3600000);
-        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;
+            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);
+}
+export async function handleFundingHistory(isJson, 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 * 3600000);
+    if (isJson()) {
+        const data = {};
         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 color = r.rate > 0 ? chalk.red : r.rate < 0 ? chalk.green : chalk.white; return [chalk.gray(new Date(r.ts).toLocaleString()), color(formatPercent(r.rate)), `${(r.hourlyRate * 100).toFixed(6)}%/h`, `${annualizeHourlyRate(r.hourlyRate).toFixed(2)}%/yr`]; });
-            console.log(makeTable(["Time", "Raw Rate", "Hourly", "Annualized"], rows));
-            console.log();
+            if (rates.length > 0)
+                data[ex] = rates;
         }
-        if (!hasData)
-            console.log(chalk.gray(`  No historical data. Run 'perp arb rates' to start collecting.\n`));
-    });
-    // funding-monitor removed — use 'perp arb monitor' (more features, includes liquidity data)
-    parent.command("funding-positions").description("Show funding rate impact on your current positions")
-        .option("--exchanges <list>", "Comma-separated exchanges")
-        .action(async (opts) => {
-        if (!getAdapterForExchange) {
-            if (isJson())
-                return printJson(jsonError("INTERNAL", "requires adapter"));
-            console.log(chalk.red("  requires adapter access\n"));
-            return;
-        }
-        await withJsonErrors(isJson(), async () => {
-            const targetExchanges = opts.exchanges ? opts.exchanges.split(",").map(s => s.trim().toLowerCase()) : [...ALL_EXCHANGES];
-            if (!isJson())
-                console.log(chalk.cyan("  Fetching positions and funding rates...\n"));
-            const results = [];
-            const exchangeErrors = {};
-            await Promise.all(targetExchanges.map(async (exchange) => {
-                try {
-                    const adapter = await getAdapterForExchange(exchange);
-                    const [positions, markets, fp] = await Promise.all([adapter.getPositions(), adapter.getMarkets(), adapter.getFundingPayments(100).catch(() => [])]);
-                    if (positions.length === 0)
-                        return;
-                    const fm = new Map();
-                    for (const m of markets) {
-                        const sym = m.symbol.toUpperCase().replace(/-PERP$/, "");
-                        fm.set(sym, { rate: Number(m.fundingRate) || 0, markPrice: Number(m.markPrice) || 0 });
-                    }
-                    const dayAgo = Date.now() - 86400000;
-                    const af = new Map();
-                    for (const f of fp) {
-                        if (f.time < dayAgo)
-                            continue;
-                        const sym = f.symbol.toUpperCase().replace(/-PERP$/, "");
-                        const amt = Number(f.payment) || 0;
-                        if (!af.has(sym))
-                            af.set(sym, { received: 0, paid: 0 });
-                        const e = af.get(sym);
-                        if (amt > 0)
-                            e.received += amt;
-                        else
-                            e.paid += Math.abs(amt);
-                    }
-                    for (const pos of positions) {
-                        const sym = pos.symbol.toUpperCase().replace(/-PERP$/, "");
-                        const fd = fm.get(sym);
-                        const fr = fd?.rate ?? 0;
-                        const mk = Number(pos.markPrice) || fd?.markPrice || 0;
-                        const sz = Math.abs(Number(pos.size));
-                        const nu = sz * mk;
-                        const hr = toHourlyRate(fr, exchange);
-                        const ap = annualizeRate(fr, exchange);
-                        const hp = estimateHourlyFunding(fr, exchange, nu, pos.side);
-                        const a = af.get(sym);
-                        results.push({ exchange, symbol: sym, side: pos.side, size: pos.size, entryPrice: pos.entryPrice, markPrice: pos.markPrice, unrealizedPnl: pos.unrealizedPnl, leverage: pos.leverage, notionalUsd: nu, fundingRate: fr, hourlyRate: hr, annualPct: ap, hourlyPayment: hp, dailyPayment: hp * 24, actualReceived24h: a?.received ?? 0, actualPaid24h: a?.paid ?? 0, actualNet24h: (a?.received ?? 0) - (a?.paid ?? 0) });
-                    }
+        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 color = r.rate > 0 ? chalk.red : r.rate < 0 ? chalk.green : chalk.white; return [chalk.gray(new Date(r.ts).toLocaleString()), color(formatPercent(r.rate)), `${(r.hourlyRate * 100).toFixed(6)}%/h`, `${annualizeHourlyRate(r.hourlyRate).toFixed(2)}%/yr`]; });
+        console.log(makeTable(["Time", "Raw Rate", "Hourly", "Annualized"], rows));
+        console.log();
+    }
+    if (!hasData)
+        console.log(chalk.gray(`  No historical data. Run 'perp arb rates' to start collecting.\n`));
+}
+export async function handleFundingPositions(isJson, getAdapterForExchange, opts) {
+    await withJsonErrors(isJson(), async () => {
+        const targetExchanges = opts.exchanges ? opts.exchanges.split(",").map(s => s.trim().toLowerCase()) : [...ALL_EXCHANGES];
+        if (!isJson())
+            console.log(chalk.cyan("  Fetching positions and funding rates...\n"));
+        const results = [];
+        const exchangeErrors = {};
+        await Promise.all(targetExchanges.map(async (exchange) => {
+            try {
+                const adapter = await getAdapterForExchange(exchange);
+                const [positions, markets, fp] = await Promise.all([adapter.getPositions(), adapter.getMarkets(), adapter.getFundingPayments(100).catch(() => [])]);
+                if (positions.length === 0)
+                    return;
+                const fm = new Map();
+                for (const m of markets) {
+                    const sym = m.symbol.toUpperCase().replace(/-PERP$/, "");
+                    fm.set(sym, { rate: Number(m.fundingRate) || 0, markPrice: Number(m.markPrice) || 0 });
+                }
+                const dayAgo = Date.now() - 86400000;
+                const af = new Map();
+                for (const f of fp) {
+                    if (f.time < dayAgo)
+                        continue;
+                    const sym = f.symbol.toUpperCase().replace(/-PERP$/, "");
+                    const amt = Number(f.payment) || 0;
+                    if (!af.has(sym))
+                        af.set(sym, { received: 0, paid: 0 });
+                    const e = af.get(sym);
+                    if (amt > 0)
+                        e.received += amt;
+                    else
+                        e.paid += Math.abs(amt);
                 }
-                catch (err) {
-                    exchangeErrors[exchange] = err instanceof Error ? err.message : String(err);
+                for (const pos of positions) {
+                    const sym = pos.symbol.toUpperCase().replace(/-PERP$/, "");
+                    const fd = fm.get(sym);
+                    const fr = fd?.rate ?? 0;
+                    const mk = Number(pos.markPrice) || fd?.markPrice || 0;
+                    const sz = Math.abs(Number(pos.size));
+                    const nu = sz * mk;
+                    const hr = toHourlyRate(fr, exchange);
+                    const ap = annualizeRate(fr, exchange);
+                    const hp = estimateHourlyFunding(fr, exchange, nu, pos.side);
+                    const a = af.get(sym);
+                    results.push({ exchange, symbol: sym, side: pos.side, size: pos.size, entryPrice: pos.entryPrice, markPrice: pos.markPrice, unrealizedPnl: pos.unrealizedPnl, leverage: pos.leverage, notionalUsd: nu, fundingRate: fr, hourlyRate: hr, annualPct: ap, hourlyPayment: hp, dailyPayment: hp * 24, actualReceived24h: a?.received ?? 0, actualPaid24h: a?.paid ?? 0, actualNet24h: (a?.received ?? 0) - (a?.paid ?? 0) });
                 }
-            }));
-            if (results.length === 0) {
-                if (isJson())
-                    return printJson(jsonOk({ positions: [], totals: { predicted: { hourly: 0, daily: 0 }, actual24h: { net: 0 }, notionalUsd: 0 }, errors: exchangeErrors }));
-                console.log(chalk.gray("  No open positions.\n"));
-                return;
             }
-            results.sort((a, b) => Math.abs(b.dailyPayment) - Math.abs(a.dailyPayment));
-            const tH = results.reduce((s, r) => s + r.hourlyPayment, 0);
-            const tD = results.reduce((s, r) => s + r.dailyPayment, 0);
-            const tN = results.reduce((s, r) => s + r.notionalUsd, 0);
-            const tA = results.reduce((s, r) => s + r.actualNet24h, 0);
+            catch (err) {
+                exchangeErrors[exchange] = err instanceof Error ? err.message : String(err);
+            }
+        }));
+        if (results.length === 0) {
             if (isJson())
-                return printJson(jsonOk({ positions: results.map(r => ({ exchange: r.exchange, symbol: r.symbol, side: r.side, size: r.size, notionalUsd: +r.notionalUsd.toFixed(2), fundingRate: r.fundingRate, annualPct: +r.annualPct.toFixed(2), predicted: { hourly: +r.hourlyPayment.toFixed(6), daily: +r.dailyPayment.toFixed(4) }, actual24h: { received: +r.actualReceived24h.toFixed(6), paid: +r.actualPaid24h.toFixed(6), net: +r.actualNet24h.toFixed(6) }, unrealizedPnl: r.unrealizedPnl })), totals: { predicted: { hourly: +tH.toFixed(6), daily: +tD.toFixed(4) }, actual24h: { net: +tA.toFixed(6) }, notionalUsd: +tN.toFixed(2) }, errors: Object.keys(exchangeErrors).length > 0 ? exchangeErrors : undefined }));
-            const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : e === "lighter" ? "LT" : e.toUpperCase();
-            console.log(chalk.cyan.bold("  Position Funding Impact\n"));
-            const rows = results.map(r => { const sc = r.side === "long" ? chalk.green : chalk.red; const rc = r.fundingRate > 0 ? chalk.red : r.fundingRate < 0 ? chalk.green : chalk.white; const as = r.actualNet24h !== 0 ? (r.actualNet24h > 0 ? chalk.green : chalk.red)(`${r.actualNet24h > 0 ? "+" : ""}$${r.actualNet24h.toFixed(4)}`) : chalk.gray("-"); return [chalk.white.bold(exAbbr(r.exchange)), chalk.white.bold(r.symbol), sc(r.side.toUpperCase()), `$${formatUsd(r.notionalUsd)}`, rc(formatPercent(r.fundingRate)), rc(`${r.annualPct.toFixed(1)}%`), as, formatPnl(r.unrealizedPnl)]; });
-            console.log(makeTable(["Ex", "Symbol", "Side", "Notional", "Rate(now)", "Annual(now)", "Actual 24h", "uPnL"], rows));
-            console.log(`\n  Total: $${formatUsd(tN)} | Actual 24h: ${tA >= 0 ? "+" : ""}$${tA.toFixed(4)} | Predicted: ${tD >= 0 ? "-" : "+"}$${Math.abs(tD).toFixed(4)}/d\n`);
-        });
+                return printJson(jsonOk({ positions: [], totals: { predicted: { hourly: 0, daily: 0 }, actual24h: { net: 0 }, notionalUsd: 0 }, errors: exchangeErrors }));
+            console.log(chalk.gray("  No open positions.\n"));
+            return;
+        }
+        results.sort((a, b) => Math.abs(b.dailyPayment) - Math.abs(a.dailyPayment));
+        const tH = results.reduce((s, r) => s + r.hourlyPayment, 0);
+        const tD = results.reduce((s, r) => s + r.dailyPayment, 0);
+        const tN = results.reduce((s, r) => s + r.notionalUsd, 0);
+        const tA = results.reduce((s, r) => s + r.actualNet24h, 0);
+        if (isJson())
+            return printJson(jsonOk({ positions: results.map(r => ({ exchange: r.exchange, symbol: r.symbol, side: r.side, size: r.size, notionalUsd: +r.notionalUsd.toFixed(2), fundingRate: r.fundingRate, annualPct: +r.annualPct.toFixed(2), predicted: { hourly: +r.hourlyPayment.toFixed(6), daily: +r.dailyPayment.toFixed(4) }, actual24h: { received: +r.actualReceived24h.toFixed(6), paid: +r.actualPaid24h.toFixed(6), net: +r.actualNet24h.toFixed(6) }, unrealizedPnl: r.unrealizedPnl })), totals: { predicted: { hourly: +tH.toFixed(6), daily: +tD.toFixed(4) }, actual24h: { net: +tA.toFixed(6) }, notionalUsd: +tN.toFixed(2) }, errors: Object.keys(exchangeErrors).length > 0 ? exchangeErrors : undefined }));
+        const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : e === "lighter" ? "LT" : e.toUpperCase();
+        console.log(chalk.cyan.bold("  Position Funding Impact\n"));
+        const rows = results.map(r => { const sc = r.side === "long" ? chalk.green : chalk.red; const rc = r.fundingRate > 0 ? chalk.red : r.fundingRate < 0 ? chalk.green : chalk.white; const as = r.actualNet24h !== 0 ? (r.actualNet24h > 0 ? chalk.green : chalk.red)(`${r.actualNet24h > 0 ? "+" : ""}$${r.actualNet24h.toFixed(4)}`) : chalk.gray("-"); return [chalk.white.bold(exAbbr(r.exchange)), chalk.white.bold(r.symbol), sc(r.side.toUpperCase()), `$${formatUsd(r.notionalUsd)}`, rc(formatPercent(r.fundingRate)), rc(`${r.annualPct.toFixed(1)}%`), as, formatPnl(r.unrealizedPnl)]; });
+        console.log(makeTable(["Ex", "Symbol", "Side", "Notional", "Rate(now)", "Annual(now)", "Actual 24h", "uPnL"], rows));
+        console.log(`\n  Total: $${formatUsd(tN)} | Actual 24h: ${tA >= 0 ? "+" : ""}$${tA.toFixed(4)} | Predicted: ${tD >= 0 ? "-" : "+"}$${Math.abs(tD).toFixed(4)}/d\n`);
     });
 }