perp-cli 0.4.0 → 0.4.8

package/dist/funding/rates.d.ts

@@ -43,3 +43,39 @@ export declare function fetchAllFundingRates(opts?: {
  * Fetch rates for a single symbol across all exchanges.
  */
 export declare function fetchSymbolFundingRates(symbol: string): Promise<SymbolFundingComparison | null>;
+export interface SpotPerpSpread {
+    symbol: string;
+    /** Perp exchange with the highest absolute funding rate */
+    perpExchange: string;
+    /** Spot exchange(s) available for the hedge leg */
+    spotExchanges: string[];
+    /** Perp funding rate (raw) */
+    perpFundingRate: number;
+    /** Perp funding hourly rate */
+    perpHourlyRate: number;
+    /** Annualized spread % (spot funding = 0, so spread = |perp annual rate|) */
+    annualSpreadPct: number;
+    /** Best mark price */
+    bestMarkPrice: number;
+    /** Direction: "long-spot-short-perp" when perp funding > 0, else "sell-spot-long-perp" */
+    direction: "long-spot-short-perp" | "sell-spot-long-perp";
+    /** Estimated hourly income for $1000 notional */
+    estHourlyIncomeUsd: number;
+}
+/**
+ * Fetch spot+perp funding rate spreads.
+ * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
+ * Only includes symbols available on at least one spot exchange (HL or LT).
+ *
+ * Key safety checks:
+ * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN
+ * - Price validation: spot mid price must be within 5% of perp mark price
+ *   (filters out same-ticker-different-token issues like HIP-1 TRUMP ≠ perp TRUMP)
+ */
+export declare function fetchSpotPerpSpreads(opts?: {
+    symbols?: string[];
+    minSpread?: number;
+}): Promise<{
+    timestamp: string;
+    spreads: SpotPerpSpread[];
+}>;

package/dist/funding/rates.js

@@ -8,6 +8,7 @@
 import { toHourlyRate, annualizeRate, computeAnnualSpread, estimateHourlyFunding } from "./normalize.js";
 import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates as fetchLtFundingRates, } from "../shared-api.js";
 import { getHistoricalAverages } from "./history.js";
+import { SPOT_PERP_TOKEN_MAP, MAX_PRICE_DEVIATION_PCT } from "../exchanges/spot-interface.js";
 // ── Default top symbols to track ──
 export const TOP_SYMBOLS = [
     "BTC", "ETH", "SOL", "DOGE", "SUI", "AVAX", "LINK", "ARB",
@@ -170,3 +171,148 @@ export async function fetchSymbolFundingRates(symbol) {
     const snapshot = await fetchAllFundingRates({ symbols: [symbol.toUpperCase()] });
     return snapshot.symbols[0] ?? null;
 }
+/**
+ * Fetch spot+perp funding rate spreads.
+ * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
+ * Only includes symbols available on at least one spot exchange (HL or LT).
+ *
+ * Key safety checks:
+ * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN
+ * - Price validation: spot mid price must be within 5% of perp mark price
+ *   (filters out same-ticker-different-token issues like HIP-1 TRUMP ≠ perp TRUMP)
+ */
+export async function fetchSpotPerpSpreads(opts) {
+    // Fetch all perp funding rates
+    const [hlRates, ltRates, pacRates] = await Promise.all([
+        fetchHyperliquidRates(),
+        fetchLighterRates(),
+        fetchPacificaRates(),
+    ]);
+    // Build actual spot availability maps + spot prices for cross-validation
+    // hlSpotByPerp: perpSymbol → { spotToken, exchange }
+    const hlSpotByPerp = new Map(); // perpSymbol → spotTokenName
+    const hlSpotPrices = new Map(); // perpSymbol → spot mid price
+    const ltSpotSymbols = new Set();
+    const ltSpotPrices = new Map(); // symbol → spot mid price
+    try {
+        // HL: spotMetaAndAssetCtxs → universe + prices in one call
+        const hlMetaCtx = await fetch("https://api.hyperliquid.xyz/info", {
+            method: "POST", headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ type: "spotMetaAndAssetCtxs" }),
+        }).then(r => r.json());
+        const meta = hlMetaCtx[0];
+        const ctxs = hlMetaCtx[1] ?? [];
+        const tokenNames = new Map();
+        for (const t of meta.tokens ?? [])
+            tokenNames.set(t.index, t.name);
+        const usdcIdx = meta.tokens?.find(t => t.name === "USDC")?.index ?? 0;
+        // We need to match universe entries to ctxs by index.
+        // API returns ctxs in same order as universe entries.
+        for (let i = 0; i < (meta.universe ?? []).length; i++) {
+            const u = meta.universe[i];
+            if (u.tokens[1] !== usdcIdx)
+                continue; // only /USDC pairs
+            const base = tokenNames.get(u.tokens[0])?.toUpperCase();
+            if (!base)
+                continue;
+            const ctx = ctxs[i];
+            const spotPrice = Number(ctx?.midPx ?? ctx?.markPx ?? 0);
+            // Map to perp symbol: UBTC→BTC, or direct if no mapping
+            const perpSymbol = SPOT_PERP_TOKEN_MAP[base] ?? base;
+            // Only keep the best-priced entry per perp symbol (prefer higher-volume)
+            if (!hlSpotByPerp.has(perpSymbol) || spotPrice > 0) {
+                hlSpotByPerp.set(perpSymbol, base);
+                if (spotPrice > 0)
+                    hlSpotPrices.set(perpSymbol, spotPrice);
+            }
+        }
+    }
+    catch { /* non-critical */ }
+    try {
+        // LT: explorer API → symbols with "/"
+        const ltMarkets = await fetch("https://explorer.elliot.ai/api/markets")
+            .then(r => r.json());
+        for (const m of ltMarkets) {
+            if (m.symbol.includes("/")) {
+                ltSpotSymbols.add(m.symbol.split("/")[0].toUpperCase());
+            }
+        }
+        // Fetch LT spot prices from orderbook for price validation
+        for (const sym of ltSpotSymbols) {
+            try {
+                const book = await fetch(`https://mainnet.zklighter.elliot.ai/api/v1/orderBookOrders?market_id=${
+                // We don't have market_id here, skip detailed price fetch for LT
+                // LT tokens (ETH, LINK, etc.) are direct names, low risk of mismatch
+                ""}`);
+                // Skip — LT uses direct token names, not indices
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* non-critical */ }
+    // Merge all perp rates by symbol
+    const perpRateMap = new Map();
+    for (const r of [...hlRates, ...ltRates, ...pacRates]) {
+        if (!r.symbol)
+            continue;
+        if (opts?.symbols && !opts.symbols.includes(r.symbol.toUpperCase()))
+            continue;
+        const key = r.symbol.toUpperCase();
+        if (!perpRateMap.has(key))
+            perpRateMap.set(key, []);
+        perpRateMap.get(key).push(r);
+    }
+    const spreads = [];
+    const minSpread = opts?.minSpread ?? 0;
+    for (const [symbol, rates] of perpRateMap) {
+        rates.sort((a, b) => Math.abs(b.hourlyRate) - Math.abs(a.hourlyRate));
+        const bestPerp = rates[0];
+        // Spot exchanges: only include if symbol has a verified spot market
+        const uniqueSpot = [];
+        // HL spot: check U-token mapped availability
+        if (hlSpotByPerp.has(symbol)) {
+            // Price cross-validation: spot price must be close to perp mark price
+            const spotPrice = hlSpotPrices.get(symbol);
+            const perpPrice = bestPerp.markPrice;
+            if (spotPrice && perpPrice > 0) {
+                const deviation = Math.abs(spotPrice - perpPrice) / perpPrice * 100;
+                if (deviation <= MAX_PRICE_DEVIATION_PCT) {
+                    uniqueSpot.push("hyperliquid");
+                }
+                // else: same ticker, different token (e.g., HIP-1 TRUMP ≠ perp TRUMP) → skip
+            }
+            else if (spotPrice === undefined) {
+                // No price data (empty orderbook) → skip, can't verify
+            }
+        }
+        // LT spot: direct token names, low mismatch risk
+        if (ltSpotSymbols.has(symbol))
+            uniqueSpot.push("lighter");
+        if (uniqueSpot.length === 0)
+            continue;
+        const annualSpreadPct = Math.abs(bestPerp.annualizedPct);
+        if (annualSpreadPct < minSpread)
+            continue;
+        const direction = bestPerp.hourlyRate > 0
+            ? "long-spot-short-perp"
+            : "sell-spot-long-perp";
+        const notional = 1000;
+        const estHourlyIncomeUsd = Math.abs(bestPerp.hourlyRate) * notional;
+        spreads.push({
+            symbol,
+            perpExchange: bestPerp.exchange,
+            spotExchanges: uniqueSpot,
+            perpFundingRate: bestPerp.fundingRate,
+            perpHourlyRate: bestPerp.hourlyRate,
+            annualSpreadPct,
+            bestMarkPrice: bestPerp.markPrice,
+            direction,
+            estHourlyIncomeUsd,
+        });
+    }
+    spreads.sort((a, b) => b.annualSpreadPct - a.annualSpreadPct);
+    return {
+        timestamp: new Date().toISOString(),
+        spreads,
+    };
+}

package/dist/index.js

@@ -7,7 +7,8 @@ config({ path: resolve(process.env.HOME || "~", ".perp", ".env") });
 config();
 import { Command } from "commander";
 import chalk from "chalk";
-import { loadPrivateKey, parseSolanaKeypair } from "./config.js";
+import { Keypair } from "@solana/web3.js";
+import { tryLoadPrivateKey, parseSolanaKeypair } from "./config.js";
 import { PacificaAdapter } from "./exchanges/pacifica.js";
 import { HyperliquidAdapter } from "./exchanges/hyperliquid.js";
 import { registerMarketCommands } from "./commands/market.js";
@@ -32,6 +33,8 @@ import { registerPortfolioCommands } from "./commands/portfolio.js";
 import { registerRiskCommands } from "./commands/risk.js";
 import { registerHistoryCommands } from "./commands/history.js";
 import { registerAnalyticsCommands } from "./commands/analytics.js";
+import { registerPnlCommands } from "./commands/pnl.js";
+import { registerMultilegCommands } from "./commands/multileg.js";
 import { registerSettingsCommands } from "./commands/settings.js";
 import { registerDexCommands } from "./commands/dex.js";
 import { registerPlanCommands } from "./commands/plan.js";
@@ -80,71 +83,81 @@ let _adapter = null;
 let _pacificaAdapter = null;
 let _hlAdapter = null;
 let _lighterAdapter = null;
+/** Map short aliases to canonical exchange names. Full names pass through. */
+function resolveExchangeAlias(name) {
+    const aliases = {
+        hl: "hyperliquid",
+        lt: "lighter",
+        pac: "pacifica",
+    };
+    return aliases[name.toLowerCase()] ?? name.toLowerCase();
+}
 function getExchange() {
-    return program.opts().exchange;
+    return resolveExchangeAlias(program.opts().exchange);
 }
 async function getAdapter() {
     if (_adapter)
         return _adapter;
     const opts = program.opts();
-    const exchange = opts.exchange;
+    const exchange = resolveExchangeAlias(opts.exchange);
     const network = opts.network;
     const isTestnet = network === "testnet";
+    // Try to load key — null means no key configured (read-only mode)
+    const pk = await tryLoadPrivateKey(exchange, opts.privateKey);
     switch (exchange) {
         case "pacifica": {
-            const pk = await loadPrivateKey("pacifica", opts.privateKey);
-            const keypair = parseSolanaKeypair(pk);
+            const keypair = pk ? parseSolanaKeypair(pk) : Keypair.generate();
             const pacNetwork = (isTestnet ? "testnet" : "mainnet");
             const settings = loadSettings();
             const builderCode = process.env.PACIFICA_BUILDER_CODE || settings.referralCodes.pacifica || "PERPCLI";
-            _pacificaAdapter = new PacificaAdapter(keypair, pacNetwork, builderCode);
+            _pacificaAdapter = new PacificaAdapter(keypair, pacNetwork, builderCode, !!pk);
             _adapter = _pacificaAdapter;
             break;
         }
         case "hyperliquid": {
-            const pk = await loadPrivateKey("hyperliquid", opts.privateKey);
-            _hlAdapter = new HyperliquidAdapter(pk, isTestnet);
+            _hlAdapter = new HyperliquidAdapter(pk ?? undefined, isTestnet);
             if (opts.dex)
                 _hlAdapter.setDex(opts.dex);
             await _hlAdapter.init();
-            const hlSettings = loadSettings();
-            if (hlSettings.referrals && !hlSettings.referralApplied.hyperliquid) {
-                const hlRef = process.env.HL_REFERRAL_CODE || hlSettings.referralCodes.hyperliquid;
-                if (hlRef) {
-                    _hlAdapter.autoSetReferrer(hlRef).then(() => {
-                        const s = loadSettings();
-                        s.referralApplied.hyperliquid = true;
-                        saveSettings(s);
-                    }).catch(() => {
-                        // Already referred or API error — mark as done either way
-                        const s = loadSettings();
-                        s.referralApplied.hyperliquid = true;
-                        saveSettings(s);
-                    });
+            if (pk) {
+                const hlSettings = loadSettings();
+                if (hlSettings.referrals && !hlSettings.referralApplied.hyperliquid) {
+                    const hlRef = process.env.HL_REFERRAL_CODE || hlSettings.referralCodes.hyperliquid;
+                    if (hlRef) {
+                        _hlAdapter.autoSetReferrer(hlRef).then(() => {
+                            const s = loadSettings();
+                            s.referralApplied.hyperliquid = true;
+                            saveSettings(s);
+                        }).catch(() => {
+                            const s = loadSettings();
+                            s.referralApplied.hyperliquid = true;
+                            saveSettings(s);
+                        });
+                    }
                 }
             }
             _adapter = _hlAdapter;
             break;
         }
         case "lighter": {
-            const pk = await loadPrivateKey("lighter", opts.privateKey);
             const { LighterAdapter } = await import("./exchanges/lighter.js");
-            _lighterAdapter = new LighterAdapter(pk, isTestnet);
+            _lighterAdapter = new LighterAdapter(pk ?? "", isTestnet);
             await _lighterAdapter.init();
-            const ltSettings = loadSettings();
-            if (ltSettings.referrals && !ltSettings.referralApplied.lighter) {
-                const ltRef = process.env.LIGHTER_REFERRAL_CODE || ltSettings.referralCodes.lighter;
-                if (ltRef) {
-                    _lighterAdapter.useReferralCode(ltRef).then(() => {
-                        const s = loadSettings();
-                        s.referralApplied.lighter = true;
-                        saveSettings(s);
-                    }).catch(() => {
-                        // Already referred or API error — mark as done either way
-                        const s = loadSettings();
-                        s.referralApplied.lighter = true;
-                        saveSettings(s);
-                    });
+            if (pk) {
+                const ltSettings = loadSettings();
+                if (ltSettings.referrals && !ltSettings.referralApplied.lighter) {
+                    const ltRef = process.env.LIGHTER_REFERRAL_CODE || ltSettings.referralCodes.lighter;
+                    if (ltRef) {
+                        _lighterAdapter.useReferralCode(ltRef).then(() => {
+                            const s = loadSettings();
+                            s.referralApplied.lighter = true;
+                            saveSettings(s);
+                        }).catch(() => {
+                            const s = loadSettings();
+                            s.referralApplied.lighter = true;
+                            saveSettings(s);
+                        });
+                    }
                 }
             }
             _adapter = _lighterAdapter;
@@ -162,7 +175,7 @@ function getAdapterSync() {
     return _adapter;
 }
 function isJson() {
-    return !!program.opts().json;
+    return !!program.opts().json || process.argv.includes("--ndjson");
 }
 function isDryRun() {
     return !!program.opts().dryRun;
@@ -190,20 +203,21 @@ registerBridgeCommands(program, isJson);
 registerDepositCommands(program, getAdapter, isJson, () => program.opts().network);
 registerAlertCommands(program, isJson, getAdapterForExchange);
 // Helper to get adapter for a specific exchange (used by arb-auto)
-async function getAdapterForExchange(exchange) {
+async function getAdapterForExchange(rawExchange) {
+    const exchange = resolveExchangeAlias(rawExchange);
     const opts = program.opts();
     const network = opts.network;
     const isTestnet = network === "testnet";
+    const pk = await tryLoadPrivateKey(exchange, opts.privateKey);
     switch (exchange) {
         case "pacifica": {
             if (_pacificaAdapter)
                 return _pacificaAdapter;
-            const pk = await loadPrivateKey("pacifica", opts.privateKey);
-            const keypair = parseSolanaKeypair(pk);
+            const keypair = pk ? parseSolanaKeypair(pk) : Keypair.generate();
             const pacNetwork = (isTestnet ? "testnet" : "mainnet");
             const s1 = loadSettings();
             const builderCode = process.env.PACIFICA_BUILDER_CODE || s1.referralCodes.pacifica || "PERPCLI";
-            _pacificaAdapter = new PacificaAdapter(keypair, pacNetwork, builderCode);
+            _pacificaAdapter = new PacificaAdapter(keypair, pacNetwork, builderCode, !!pk);
             if (!_adapter)
                 _adapter = _pacificaAdapter;
             return _pacificaAdapter;
@@ -211,24 +225,25 @@ async function getAdapterForExchange(exchange) {
         case "hyperliquid": {
             if (_hlAdapter)
                 return _hlAdapter;
-            const pk = await loadPrivateKey("hyperliquid", opts.privateKey);
-            _hlAdapter = new HyperliquidAdapter(pk, isTestnet);
+            _hlAdapter = new HyperliquidAdapter(pk ?? undefined, isTestnet);
             if (opts.dex)
                 _hlAdapter.setDex(opts.dex);
             await _hlAdapter.init();
-            const s2 = loadSettings();
-            if (s2.referrals && !s2.referralApplied.hyperliquid) {
-                const hlRef = process.env.HL_REFERRAL_CODE || s2.referralCodes.hyperliquid;
-                if (hlRef) {
-                    _hlAdapter.autoSetReferrer(hlRef).then(() => {
-                        const s = loadSettings();
-                        s.referralApplied.hyperliquid = true;
-                        saveSettings(s);
-                    }).catch(() => {
-                        const s = loadSettings();
-                        s.referralApplied.hyperliquid = true;
-                        saveSettings(s);
-                    });
+            if (pk) {
+                const s2 = loadSettings();
+                if (s2.referrals && !s2.referralApplied.hyperliquid) {
+                    const hlRef = process.env.HL_REFERRAL_CODE || s2.referralCodes.hyperliquid;
+                    if (hlRef) {
+                        _hlAdapter.autoSetReferrer(hlRef).then(() => {
+                            const s = loadSettings();
+                            s.referralApplied.hyperliquid = true;
+                            saveSettings(s);
+                        }).catch(() => {
+                            const s = loadSettings();
+                            s.referralApplied.hyperliquid = true;
+                            saveSettings(s);
+                        });
+                    }
                 }
             }
             if (!_adapter)
@@ -238,23 +253,24 @@ async function getAdapterForExchange(exchange) {
         case "lighter": {
             if (_lighterAdapter)
                 return _lighterAdapter;
-            const pk = await loadPrivateKey("lighter", opts.privateKey);
             const { LighterAdapter } = await import("./exchanges/lighter.js");
-            _lighterAdapter = new LighterAdapter(pk, isTestnet);
+            _lighterAdapter = new LighterAdapter(pk ?? "", isTestnet);
             await _lighterAdapter.init();
-            const s3 = loadSettings();
-            if (s3.referrals && !s3.referralApplied.lighter) {
-                const ltRef = process.env.LIGHTER_REFERRAL_CODE || s3.referralCodes.lighter;
-                if (ltRef) {
-                    _lighterAdapter.useReferralCode(ltRef).then(() => {
-                        const s = loadSettings();
-                        s.referralApplied.lighter = true;
-                        saveSettings(s);
-                    }).catch(() => {
-                        const s = loadSettings();
-                        s.referralApplied.lighter = true;
-                        saveSettings(s);
-                    });
+            if (pk) {
+                const s3 = loadSettings();
+                if (s3.referrals && !s3.referralApplied.lighter) {
+                    const ltRef = process.env.LIGHTER_REFERRAL_CODE || s3.referralCodes.lighter;
+                    if (ltRef) {
+                        _lighterAdapter.useReferralCode(ltRef).then(() => {
+                            const s = loadSettings();
+                            s.referralApplied.lighter = true;
+                            saveSettings(s);
+                        }).catch(() => {
+                            const s = loadSettings();
+                            s.referralApplied.lighter = true;
+                            saveSettings(s);
+                        });
+                    }
                 }
             }
             if (!_adapter)
@@ -271,8 +287,8 @@ async function getHLAdapterForDex(dex) {
     if (_dexAdapters.has(dex))
         return _dexAdapters.get(dex);
     const opts = program.opts();
-    const pk = await loadPrivateKey("hyperliquid", opts.privateKey);
-    const adapter = new HyperliquidAdapter(pk, opts.network === "testnet");
+    const pk = await tryLoadPrivateKey("hyperliquid", opts.privateKey);
+    const adapter = new HyperliquidAdapter(pk ?? undefined, opts.network === "testnet");
     if (dex !== "hl")
         adapter.setDex(dex);
     await adapter.init();
@@ -297,10 +313,12 @@ registerPortfolioCommands(program, getAdapterForExchange, isJson);
 registerRiskCommands(program, getAdapterForExchange, isJson);
 registerHistoryCommands(program, isJson);
 registerAnalyticsCommands(program, getAdapterForExchange, isJson);
-registerSettingsCommands(program, isJson);
+registerPnlCommands(program, getAdapterForExchange, isJson);
+registerMultilegCommands(program, getAdapterForExchange, isJson);
+registerSettingsCommands(program, isJson, getAdapterForExchange);
 registerDexCommands(program, getAdapter, isJson);
 registerPlanCommands(program, getAdapter, isJson);
-registerFundingCommands(program, isJson);
+registerFundingCommands(program, isJson, getAdapterForExchange);
 registerBacktestCommands(program, isJson);
 registerDashboardCommands(program, getAdapterForExchange, isJson, getHLAdapterForDex);
 registerInitCommand(program);
@@ -322,36 +340,67 @@ program
     const adapter = await getAdapter();
     const json = isJson();
     try {
-        const [balance, positions, orders] = await Promise.all([
+        // Use allSettled to handle unfunded/404 accounts gracefully
+        const [balanceResult, positionsResult, ordersResult] = await Promise.allSettled([
             adapter.getBalance(),
             adapter.getPositions(),
             adapter.getOpenOrders(),
         ]);
+        const balance = balanceResult.status === "fulfilled" ? balanceResult.value : { equity: "0", available: "0", marginUsed: "0", unrealizedPnl: "0" };
+        const positions = positionsResult.status === "fulfilled" ? positionsResult.value : [];
+        const orders = ordersResult.status === "fulfilled" ? ordersResult.value : [];
+        // Collect errors for reporting
+        const errors = [];
+        if (balanceResult.status === "rejected")
+            errors.push(`balance: ${balanceResult.reason instanceof Error ? balanceResult.reason.message : String(balanceResult.reason)}`);
+        if (positionsResult.status === "rejected")
+            errors.push(`positions: ${positionsResult.reason instanceof Error ? positionsResult.reason.message : String(positionsResult.reason)}`);
+        if (ordersResult.status === "rejected")
+            errors.push(`orders: ${ordersResult.reason instanceof Error ? ordersResult.reason.message : String(ordersResult.reason)}`);
+        // Detect unfunded account (all calls failed, likely 404)
+        const allFailed = errors.length === 3;
+        const isUnfunded = allFailed && errors.some(e => e.includes("404") || e.includes("not found") || e.includes("does not exist"));
         if (json) {
             const { jsonOk, printJson } = await import("./utils.js");
-            return printJson(jsonOk({ exchange: adapter.name, balance, positions, orders }));
+            return printJson(jsonOk({
+                exchange: adapter.name,
+                balance,
+                positions,
+                orders,
+                ...(isUnfunded ? { warning: "Account not yet initialized on this exchange. Deposit funds to get started." } : {}),
+                ...(errors.length > 0 && !isUnfunded ? { errors } : {}),
+            }));
         }
         console.log(chalk.cyan.bold(`\n  ${adapter.name.toUpperCase()} Account Status\n`));
-        console.log(`  Equity:      $${Number(balance.equity).toFixed(2)}`);
-        console.log(`  Available:   $${Number(balance.available).toFixed(2)}`);
-        console.log(`  Margin Used: $${Number(balance.marginUsed).toFixed(2)}`);
-        console.log(`  Positions:   ${positions.length}`);
-        console.log(`  Open Orders: ${orders.length}`);
-        if (positions.length > 0) {
-            console.log(chalk.cyan.bold("\n  Positions:"));
-            positions.forEach((p) => {
-                const color = p.side === "long" ? chalk.green : chalk.red;
-                const pnlNum = Number(p.unrealizedPnl);
-                const pnlColor = pnlNum >= 0 ? chalk.green : chalk.red;
-                console.log(`    ${color(p.side.toUpperCase().padEnd(5))} ${chalk.white(p.symbol.padEnd(12))} ${p.size.padEnd(10)} entry: $${Number(p.entryPrice).toFixed(2)}  pnl: ${pnlColor(pnlNum >= 0 ? "+" : "")}$${pnlNum.toFixed(2)}`);
-            });
+        if (isUnfunded) {
+            console.log(chalk.yellow("  Account not yet initialized on this exchange."));
+            console.log(chalk.gray("  Deposit funds to get started: perp deposit <exchange> <amount>\n"));
         }
-        if (orders.length > 0) {
-            console.log(chalk.cyan.bold("\n  Open Orders:"));
-            orders.forEach((o) => {
-                const color = o.side === "buy" ? chalk.green : chalk.red;
-                console.log(`    ${color(o.side.toUpperCase().padEnd(4))} ${chalk.white(o.symbol.padEnd(12))} ${o.type.padEnd(8)} $${Number(o.price).toFixed(2)} x ${o.size}`);
-            });
+        else {
+            console.log(`  Equity:      $${Number(balance.equity).toFixed(2)}`);
+            console.log(`  Available:   $${Number(balance.available).toFixed(2)}`);
+            console.log(`  Margin Used: $${Number(balance.marginUsed).toFixed(2)}`);
+            console.log(`  Positions:   ${positions.length}`);
+            console.log(`  Open Orders: ${orders.length}`);
+            if (positions.length > 0) {
+                console.log(chalk.cyan.bold("\n  Positions:"));
+                positions.forEach((p) => {
+                    const color = p.side === "long" ? chalk.green : chalk.red;
+                    const pnlNum = Number(p.unrealizedPnl);
+                    const pnlColor = pnlNum >= 0 ? chalk.green : chalk.red;
+                    console.log(`    ${color(p.side.toUpperCase().padEnd(5))} ${chalk.white(p.symbol.padEnd(12))} ${p.size.padEnd(10)} entry: $${Number(p.entryPrice).toFixed(2)}  pnl: ${pnlColor(pnlNum >= 0 ? "+" : "")}$${pnlNum.toFixed(2)}`);
+                });
+            }
+            if (orders.length > 0) {
+                console.log(chalk.cyan.bold("\n  Open Orders:"));
+                orders.forEach((o) => {
+                    const color = o.side === "buy" ? chalk.green : chalk.red;
+                    console.log(`    ${color(o.side.toUpperCase().padEnd(4))} ${chalk.white(o.symbol.padEnd(12))} ${o.type.padEnd(8)} $${Number(o.price).toFixed(2)} x ${o.size}`);
+                });
+            }
+            if (errors.length > 0) {
+                console.log(chalk.yellow(`\n  Warnings: ${errors.join(", ")}`));
+            }
         }
         console.log();
     }
@@ -375,7 +424,7 @@ program.hook("preAction", () => {
 });
 // Smart landing page: `perp` with no subcommand
 const rawArgs = process.argv.slice(2);
-const hasSubcommand = rawArgs.some((a) => !a.startsWith("-") && !["pacifica", "hyperliquid", "lighter", "mainnet", "testnet"].includes(a));
+const hasSubcommand = rawArgs.some((a) => !a.startsWith("-") && !["pacifica", "hyperliquid", "lighter", "hl", "lt", "pac", "mainnet", "testnet"].includes(a));
 if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawArgs.includes("--help") && !rawArgs.includes("-V") && !rawArgs.includes("--version"))) {
     // No subcommand — show smart landing instead of help dump
     (async () => {

package/dist/liquidity.d.ts

@@ -1,4 +1,5 @@
 import type { ExchangeAdapter } from "./exchanges/interface.js";
+import type { SpotAdapter } from "./exchanges/spot-interface.js";
 export interface LiquidityCheck {
     /** Max executable size (base) within slippage tolerance */
     maxSize: number;
@@ -32,3 +33,14 @@ export declare function checkArbLiquidity(longAdapter: ExchangeAdapter, shortAda
     longSlippage: number;
     shortSlippage: number;
 }>;
+/**
+ * Check liquidity for a spot+perp arb pair.
+ * Spot side uses asks (for buy) or bids (for sell).
+ * Perp side uses bids (for short entry) or asks (for long entry).
+ */
+export declare function checkSpotPerpLiquidity(spotAdapter: SpotAdapter, perpAdapter: ExchangeAdapter, spotSymbol: string, perpSymbol: string, sizeUsd: number, maxSlippagePct?: number, log?: (msg: string) => void): Promise<{
+    viable: boolean;
+    adjustedSizeUsd: number;
+    spotSlippage: number;
+    perpSlippage: number;
+}>;

package/dist/liquidity.js

@@ -98,3 +98,46 @@ export async function checkArbLiquidity(longAdapter, shortAdapter, symbol, sizeU
         return { viable: false, adjustedSizeUsd: 0, longSlippage: 0, shortSlippage: 0 };
     }
 }
+/**
+ * Check liquidity for a spot+perp arb pair.
+ * Spot side uses asks (for buy) or bids (for sell).
+ * Perp side uses bids (for short entry) or asks (for long entry).
+ */
+export async function checkSpotPerpLiquidity(spotAdapter, perpAdapter, spotSymbol, perpSymbol, sizeUsd, maxSlippagePct = 0.5, log) {
+    try {
+        const [spotOB, perpOB] = await Promise.all([
+            spotAdapter.getSpotOrderbook(spotSymbol),
+            perpAdapter.getOrderbook(perpSymbol),
+        ]);
+        // Spot buy = consume asks; Perp short = consume bids
+        const spotCheck = computeExecutableSize(spotOB.asks, sizeUsd, maxSlippagePct);
+        const perpCheck = computeExecutableSize(perpOB.bids, sizeUsd, maxSlippagePct);
+        // Cross-market price gap check (spot vs perp)
+        if (spotOB.asks.length > 0 && perpOB.bids.length > 0) {
+            const bestSpotAsk = Number(spotOB.asks[0][0]);
+            const bestPerpBid = Number(perpOB.bids[0][0]);
+            const gapPct = Math.abs(bestSpotAsk - bestPerpBid) / Math.min(bestSpotAsk, bestPerpBid) * 100;
+            if (gapPct > 2) {
+                log?.(`[LIQ] spot-perp ${spotSymbol}: price gap ${gapPct.toFixed(2)}% too wide`);
+                return { viable: false, adjustedSizeUsd: 0, spotSlippage: spotCheck.slippagePct, perpSlippage: perpCheck.slippagePct };
+            }
+        }
+        const executableUsd = Math.min(spotCheck.maxSize * spotCheck.avgFillPrice, perpCheck.maxSize * perpCheck.avgFillPrice);
+        const minViable = sizeUsd * 0.2;
+        if (executableUsd < minViable) {
+            log?.(`[LIQ] spot-perp ${spotSymbol}: only $${executableUsd.toFixed(0)} executable (need min $${minViable.toFixed(0)})`);
+            return { viable: false, adjustedSizeUsd: 0, spotSlippage: spotCheck.slippagePct, perpSlippage: perpCheck.slippagePct };
+        }
+        const adjustedSizeUsd = Math.min(sizeUsd, executableUsd);
+        return {
+            viable: true,
+            adjustedSizeUsd,
+            spotSlippage: spotCheck.slippagePct,
+            perpSlippage: perpCheck.slippagePct,
+        };
+    }
+    catch {
+        log?.(`[LIQ] spot-perp ${spotSymbol}: orderbook fetch failed`);
+        return { viable: false, adjustedSizeUsd: 0, spotSlippage: 0, perpSlippage: 0 };
+    }
+}