perp-cli 0.4.0 → 0.4.8

package/dist/commands/dex.js

@@ -1,6 +1,6 @@
 import chalk from "chalk";
 import { HyperliquidAdapter } from "../exchanges/hyperliquid.js";
-import { printJson, jsonOk, makeTable, formatUsd, withJsonErrors } from "../utils.js";
+import { printJson, jsonOk, jsonError, 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 ──
@@ -11,6 +11,8 @@ export function registerDexCommands(program, getAdapter, isJson) {
         await withJsonErrors(isJson(), async () => {
             const adapter = await getAdapter();
             if (!(adapter instanceof HyperliquidAdapter)) {
+                if (isJson())
+                    return printJson(jsonError("INVALID_EXCHANGE", "HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid."));
                 console.error(chalk.red("\n  HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid.\n"));
                 return;
             }
@@ -41,6 +43,8 @@ export function registerDexCommands(program, getAdapter, isJson) {
         await withJsonErrors(isJson(), async () => {
             const adapter = await getAdapter();
             if (!(adapter instanceof HyperliquidAdapter)) {
+                if (isJson())
+                    return printJson(jsonError("INVALID_EXCHANGE", "HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid."));
                 console.error(chalk.red("\n  HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid.\n"));
                 return;
             }
@@ -80,6 +84,8 @@ export function registerDexCommands(program, getAdapter, isJson) {
         await withJsonErrors(isJson(), async () => {
             const adapter = await getAdapter();
             if (!(adapter instanceof HyperliquidAdapter)) {
+                if (isJson())
+                    return printJson(jsonError("INVALID_EXCHANGE", "HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid."));
                 console.error(chalk.red("\n  HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid.\n"));
                 return;
             }

package/dist/commands/funding.d.ts

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

package/dist/commands/funding.js

@@ -1,9 +1,10 @@
 import chalk from "chalk";
-import { makeTable, formatPercent, formatUsd, printJson, jsonOk } from "../utils.js";
+import { makeTable, formatPercent, formatUsd, formatPnl, printJson, jsonOk, jsonError, withJsonErrors } from "../utils.js";
 import { fetchAllFundingRates, fetchSymbolFundingRates, TOP_SYMBOLS, } from "../funding-rates.js";
-import { annualizeHourlyRate } from "../funding.js";
+import { estimateHourlyFunding, annualizeHourlyRate, annualizeRate, toHourlyRate } from "../funding.js";
 import { saveFundingSnapshot, getHistoricalRates, getCompoundedAnnualReturn, getExchangeCompoundingHours, } from "../funding-history.js";
-export function registerFundingCommands(program, isJson) {
+const ALL_EXCHANGES = ["hyperliquid", "pacifica", "lighter"];
+export function registerFundingCommands(program, isJson, getAdapterForExchange) {
     const funding = program.command("funding").description("Funding rate comparison across exchanges");
     // ── perp funding rates ── (default: show top symbols)
     funding
@@ -38,8 +39,15 @@ export function registerFundingCommands(program, isJson) {
                 saveFundingSnapshot(allRates);
         }
         catch { /* non-critical */ }
-        if (isJson())
+        if (isJson()) {
+            // When --ndjson or --fields is used, return the symbols array directly
+            // so each symbol gets its own line / fields can be picked per element.
+            // Otherwise return the full snapshot (includes exchangeStatus metadata).
+            if (process.argv.includes("--ndjson") || process.argv.includes("--fields")) {
+                return printJson(jsonOk(snapshot.symbols));
+            }
             return printJson(jsonOk(snapshot));
+        }
         printSnapshotTable(snapshot);
         printExchangeStatus(snapshot);
         console.log(chalk.gray("  * Rates shown are current predictions. Actual settled rates may differ.\n"));
@@ -234,6 +242,205 @@ export function registerFundingCommands(program, isJson) {
             await new Promise(r => setTimeout(r, intervalSec * 1000));
         }
     });
+    // ── perp funding positions ── (funding impact on open positions)
+    funding
+        .command("positions")
+        .description("Show funding rate impact on your current positions")
+        .option("--exchanges <list>", "Comma-separated exchanges to check (default: all with keys)")
+        .action(async (opts) => {
+        if (!getAdapterForExchange) {
+            const msg = "funding positions requires adapter access";
+            if (isJson())
+                return printJson(jsonError("INTERNAL", msg));
+            console.log(chalk.red(`  ${msg}\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, fundingPayments] = await Promise.all([
+                        adapter.getPositions(),
+                        adapter.getMarkets(),
+                        adapter.getFundingPayments(100).catch(() => []),
+                    ]);
+                    if (positions.length === 0)
+                        return;
+                    // Build symbol → funding rate map
+                    const fundingMap = new Map();
+                    for (const m of markets) {
+                        const sym = m.symbol.toUpperCase().replace(/-PERP$/, "");
+                        fundingMap.set(sym, {
+                            rate: Number(m.fundingRate) || 0,
+                            markPrice: Number(m.markPrice) || 0,
+                        });
+                    }
+                    // Aggregate actual funding payments per symbol (last 24h)
+                    const now = Date.now();
+                    const dayAgo = now - 24 * 60 * 60 * 1000;
+                    const actualFunding = new Map();
+                    for (const fp of fundingPayments) {
+                        if (fp.time < dayAgo)
+                            continue;
+                        const sym = fp.symbol.toUpperCase().replace(/-PERP$/, "");
+                        const amt = Number(fp.payment) || 0;
+                        if (!actualFunding.has(sym))
+                            actualFunding.set(sym, { received: 0, paid: 0 });
+                        const entry = actualFunding.get(sym);
+                        if (amt > 0)
+                            entry.received += amt;
+                        else
+                            entry.paid += Math.abs(amt);
+                    }
+                    for (const pos of positions) {
+                        const sym = pos.symbol.toUpperCase().replace(/-PERP$/, "");
+                        const fdata = fundingMap.get(sym);
+                        const fundingRate = fdata?.rate ?? 0;
+                        const mark = Number(pos.markPrice) || fdata?.markPrice || 0;
+                        const size = Math.abs(Number(pos.size));
+                        const notionalUsd = size * mark;
+                        const hourlyRate = toHourlyRate(fundingRate, exchange);
+                        const annualPct = annualizeRate(fundingRate, exchange);
+                        const hourlyPayment = estimateHourlyFunding(fundingRate, exchange, notionalUsd, pos.side);
+                        const dailyPayment = hourlyPayment * 24;
+                        const actual = actualFunding.get(sym);
+                        const actualReceived24h = actual?.received ?? 0;
+                        const actualPaid24h = actual?.paid ?? 0;
+                        const actualNet24h = actualReceived24h - actualPaid24h;
+                        results.push({
+                            exchange,
+                            symbol: sym,
+                            side: pos.side,
+                            size: pos.size,
+                            entryPrice: pos.entryPrice,
+                            markPrice: pos.markPrice,
+                            unrealizedPnl: pos.unrealizedPnl,
+                            leverage: pos.leverage,
+                            notionalUsd,
+                            fundingRate,
+                            hourlyRate,
+                            annualPct,
+                            hourlyPayment,
+                            dailyPayment,
+                            actualReceived24h,
+                            actualPaid24h,
+                            actualNet24h,
+                        });
+                    }
+                }
+                catch (err) {
+                    exchangeErrors[exchange] = err instanceof Error ? err.message : String(err);
+                }
+            }));
+            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 found on any exchange.\n"));
+                if (Object.keys(exchangeErrors).length > 0) {
+                    for (const [ex, err] of Object.entries(exchangeErrors)) {
+                        console.log(chalk.yellow(`  ${ex}: ${err}`));
+                    }
+                    console.log();
+                }
+                return;
+            }
+            // Sort: biggest daily payment impact first
+            results.sort((a, b) => Math.abs(b.dailyPayment) - Math.abs(a.dailyPayment));
+            const totalHourly = results.reduce((s, r) => s + r.hourlyPayment, 0);
+            const totalDaily = results.reduce((s, r) => s + r.dailyPayment, 0);
+            const totalNotional = results.reduce((s, r) => s + r.notionalUsd, 0);
+            const totalActualNet = 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: Number(r.notionalUsd.toFixed(2)),
+                        fundingRate: r.fundingRate,
+                        annualPct: Number(r.annualPct.toFixed(2)),
+                        predicted: {
+                            hourly: Number(r.hourlyPayment.toFixed(6)),
+                            daily: Number(r.dailyPayment.toFixed(4)),
+                        },
+                        actual24h: {
+                            received: Number(r.actualReceived24h.toFixed(6)),
+                            paid: Number(r.actualPaid24h.toFixed(6)),
+                            net: Number(r.actualNet24h.toFixed(6)),
+                        },
+                        unrealizedPnl: r.unrealizedPnl,
+                    })),
+                    totals: {
+                        predicted: {
+                            hourly: Number(totalHourly.toFixed(6)),
+                            daily: Number(totalDaily.toFixed(4)),
+                        },
+                        actual24h: {
+                            net: Number(totalActualNet.toFixed(6)),
+                        },
+                        notionalUsd: Number(totalNotional.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 sideColor = r.side === "long" ? chalk.green : chalk.red;
+                const rateColor = r.fundingRate > 0 ? chalk.red : r.fundingRate < 0 ? chalk.green : chalk.white;
+                // actual net: positive = received, negative = paid
+                const actualColor = r.actualNet24h > 0 ? chalk.green : r.actualNet24h < 0 ? chalk.red : chalk.gray;
+                const actualStr = r.actualNet24h !== 0
+                    ? actualColor(`${r.actualNet24h > 0 ? "+" : ""}$${r.actualNet24h.toFixed(4)}`)
+                    : chalk.gray("-");
+                return [
+                    chalk.white.bold(exAbbr(r.exchange)),
+                    chalk.white.bold(r.symbol),
+                    sideColor(r.side.toUpperCase()),
+                    `$${formatUsd(r.notionalUsd)}`,
+                    rateColor(formatPercent(r.fundingRate)),
+                    rateColor(`${r.annualPct.toFixed(1)}%`),
+                    actualStr,
+                    formatPnl(r.unrealizedPnl),
+                ];
+            });
+            console.log(makeTable(["Ex", "Symbol", "Side", "Notional", "Rate(now)", "Annual(now)", "Actual 24h", "uPnL"], rows));
+            // Summary
+            const actualNetColor = totalActualNet >= 0 ? chalk.green : chalk.red;
+            const predictColor = totalDaily >= 0 ? chalk.red : chalk.green;
+            const predictSign = totalDaily >= 0 ? "-" : "+";
+            console.log();
+            console.log(`  Total Notional:      $${formatUsd(totalNotional)}`);
+            console.log(`  Actual Net (24h):    ${actualNetColor(`${totalActualNet >= 0 ? "+" : ""}$${totalActualNet.toFixed(4)}`)}`);
+            console.log(`  Predicted (now rate): ${predictColor(`${predictSign}$${Math.abs(totalDaily).toFixed(4)}/d`)}`);
+            if (Object.keys(exchangeErrors).length > 0) {
+                console.log();
+                for (const [ex, err] of Object.entries(exchangeErrors)) {
+                    console.log(chalk.yellow(`  ${exAbbr(ex)}: ${err}`));
+                }
+            }
+            console.log(chalk.gray("\n  Actual 24h: real funding received/paid in the last 24 hours."));
+            console.log(chalk.gray("  Predicted: based on current rate only (changes every hour)."));
+            console.log(chalk.gray("  + = received, - = paid\n"));
+        });
+    });
 }
 // ── Display helpers ──
 function formatAvgRate(rate) {

package/dist/commands/manage.js

@@ -274,7 +274,7 @@ export function registerManageCommands(program, getAdapter, isJson, getPacificaA
     manage
         .command("setup-api-key")
         .description("Generate & register a Lighter API key (required for trading)")
-        .option("--key-index <n>", "API key index (2-254, default: 2)", "2")
+        .option("--key-index <n>", "API key index (4-254, default: 4)", "4")
         .action(async (opts) => {
         const adapter = await getAdapter();
         const { LighterAdapter } = await import("../exchanges/lighter.js");

package/dist/commands/market.js

@@ -139,7 +139,7 @@ export function registerMarketCommands(program, getAdapter, isJson) {
         const rows = history.map((h) => [
             new Date(h.time).toLocaleString(),
             formatPercent(h.rate),
-            `$${formatUsd(h.price)}`,
+            h.price != null ? `$${formatUsd(h.price)}` : chalk.gray("n/a"),
         ]);
         console.log(makeTable(["Time", "Funding Rate", "Oracle"], rows));
     });

package/dist/commands/multileg.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Multi-leg order command.
+ *
+ * Executes multiple orders across exchanges simultaneously using Promise.allSettled.
+ * Supports automatic rollback if one leg fails.
+ *
+ * Usage:
+ *   perp multi "hl:ETH:buy:0.01" "pac:ETH:sell:0.01"
+ *   perp multi "hl:BTC:buy:0.001" "lighter:BTC:sell:0.001" --smart
+ *   perp multi "hl:ETH:buy:0.01" "pac:SOL:buy:1" "lighter:BTC:sell:0.0001"
+ *
+ * Leg format: exchange:symbol:side:size
+ */
+import { Command } from "commander";
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export declare function registerMultilegCommands(program: Command, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;

package/dist/commands/multileg.js

@@ -0,0 +1,174 @@
+/**
+ * Multi-leg order command.
+ *
+ * Executes multiple orders across exchanges simultaneously using Promise.allSettled.
+ * Supports automatic rollback if one leg fails.
+ *
+ * Usage:
+ *   perp multi "hl:ETH:buy:0.01" "pac:ETH:sell:0.01"
+ *   perp multi "hl:BTC:buy:0.001" "lighter:BTC:sell:0.001" --smart
+ *   perp multi "hl:ETH:buy:0.01" "pac:SOL:buy:1" "lighter:BTC:sell:0.0001"
+ *
+ * Leg format: exchange:symbol:side:size
+ */
+import chalk from "chalk";
+import { printJson, jsonOk, jsonError, withJsonErrors } from "../utils.js";
+import { logExecution } from "../execution-log.js";
+import { smartOrder } from "../smart-order.js";
+function parseLeg(spec) {
+    const parts = spec.split(":");
+    if (parts.length !== 4) {
+        throw new Error(`Invalid leg format "${spec}" — expected exchange:symbol:side:size`);
+    }
+    const [exchange, symbol, side, size] = parts;
+    // Normalize exchange aliases
+    const exMap = {
+        hl: "hyperliquid", pac: "pacifica", lit: "lighter",
+        hyperliquid: "hyperliquid", pacifica: "pacifica", lighter: "lighter",
+    };
+    const normalizedExchange = exMap[exchange.toLowerCase()];
+    if (!normalizedExchange) {
+        throw new Error(`Unknown exchange "${exchange}" in leg spec`);
+    }
+    if (side !== "buy" && side !== "sell") {
+        throw new Error(`Invalid side "${side}" — must be "buy" or "sell"`);
+    }
+    if (isNaN(Number(size)) || Number(size) <= 0) {
+        throw new Error(`Invalid size "${size}" — must be a positive number`);
+    }
+    return { exchange: normalizedExchange, symbol: symbol.toUpperCase(), side, size };
+}
+export function registerMultilegCommands(program, getAdapterForExchange, isJson) {
+    program
+        .command("multi <legs...>")
+        .description("Execute multi-leg orders simultaneously (exchange:symbol:side:size)")
+        .option("--smart", "Use smart order (IOC limit + fallback) for each leg")
+        .option("--rollback", "Auto-rollback filled legs if any leg fails", true)
+        .option("--no-rollback", "Disable auto-rollback")
+        .option("--timeout <ms>", "Per-leg timeout in milliseconds", "30000")
+        .action(async (legSpecs, opts) => {
+        await withJsonErrors(isJson(), async () => {
+            // Parse legs
+            const legs = legSpecs.map(parseLeg);
+            if (legs.length < 2) {
+                const err = "Multi-leg requires at least 2 legs";
+                if (isJson()) {
+                    printJson(jsonError("INVALID_ARGS", err));
+                    return;
+                }
+                throw new Error(err);
+            }
+            if (!isJson()) {
+                console.log(chalk.cyan.bold("Multi-Leg Order\n"));
+                for (const l of legs) {
+                    const color = l.side === "buy" ? chalk.green : chalk.red;
+                    console.log(`  ${l.exchange.padEnd(14)} ${color(l.side.toUpperCase())} ${l.symbol} x ${l.size}`);
+                }
+                console.log();
+            }
+            // Get adapters (deduplicated)
+            const adapters = new Map();
+            for (const l of legs) {
+                if (!adapters.has(l.exchange)) {
+                    adapters.set(l.exchange, await getAdapterForExchange(l.exchange));
+                }
+            }
+            // Execute all legs simultaneously
+            const timeoutMs = parseInt(opts.timeout);
+            const results = await Promise.allSettled(legs.map(async (leg) => {
+                const adapter = adapters.get(leg.exchange);
+                const orderPromise = opts.smart
+                    ? smartOrder(adapter, leg.symbol, leg.side, leg.size).then(r => r.result)
+                    : adapter.marketOrder(leg.symbol, leg.side, leg.size);
+                // Apply timeout
+                const result = await Promise.race([
+                    orderPromise,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Leg timeout")), timeoutMs)),
+                ]);
+                // Log execution
+                logExecution({
+                    type: "multi_leg",
+                    exchange: leg.exchange,
+                    symbol: leg.symbol,
+                    side: leg.side,
+                    size: leg.size,
+                    status: "success",
+                    dryRun: false,
+                    meta: { result, smart: opts.smart },
+                });
+                return { leg, status: "filled", result };
+            }));
+            // Process results
+            const legResults = results.map((r, i) => {
+                if (r.status === "fulfilled")
+                    return r.value;
+                return {
+                    leg: legs[i],
+                    status: "failed",
+                    error: r.reason instanceof Error ? r.reason.message : String(r.reason),
+                };
+            });
+            const filled = legResults.filter(r => r.status === "filled");
+            const failed = legResults.filter(r => r.status === "failed");
+            // Rollback if partial fill and rollback enabled
+            if (failed.length > 0 && filled.length > 0 && opts.rollback) {
+                if (!isJson()) {
+                    console.log(chalk.yellow(`\n  ${failed.length} leg(s) failed — rolling back ${filled.length} filled leg(s)...\n`));
+                }
+                for (const fr of filled) {
+                    const adapter = adapters.get(fr.leg.exchange);
+                    const reverseSide = fr.leg.side === "buy" ? "sell" : "buy";
+                    try {
+                        await adapter.marketOrder(fr.leg.symbol, reverseSide, fr.leg.size);
+                        fr.status = "rolled_back";
+                        logExecution({
+                            type: "multi_leg_rollback",
+                            exchange: fr.leg.exchange,
+                            symbol: fr.leg.symbol,
+                            side: reverseSide,
+                            size: fr.leg.size,
+                            status: "success",
+                            dryRun: false,
+                        });
+                        if (!isJson()) {
+                            console.log(chalk.gray(`  Rolled back: ${fr.leg.exchange} ${reverseSide} ${fr.leg.symbol} x ${fr.leg.size}`));
+                        }
+                    }
+                    catch (err) {
+                        if (!isJson()) {
+                            console.log(chalk.red(`  Rollback failed: ${fr.leg.exchange} ${fr.leg.symbol} — ${err instanceof Error ? err.message : err}`));
+                        }
+                    }
+                }
+            }
+            if (isJson()) {
+                printJson(jsonOk({
+                    legs: legResults.map(r => ({
+                        exchange: r.leg.exchange,
+                        symbol: r.leg.symbol,
+                        side: r.leg.side,
+                        size: r.leg.size,
+                        status: r.status,
+                        error: r.error,
+                    })),
+                    summary: {
+                        total: legs.length,
+                        filled: legResults.filter(r => r.status === "filled").length,
+                        failed: failed.length,
+                        rolledBack: legResults.filter(r => r.status === "rolled_back").length,
+                    },
+                }));
+            }
+            else {
+                console.log(chalk.cyan.bold("\nResults:\n"));
+                for (const r of legResults) {
+                    const icon = r.status === "filled" ? chalk.green("OK") :
+                        r.status === "rolled_back" ? chalk.yellow("ROLLBACK") :
+                            chalk.red("FAIL");
+                    console.log(`  ${icon} ${r.leg.exchange.padEnd(14)} ${r.leg.side} ${r.leg.symbol} x ${r.leg.size}${r.error ? ` — ${r.error}` : ""}`);
+                }
+                console.log(`\n  Total: ${legs.length}  Filled: ${filled.length}  Failed: ${failed.length}  Rolled back: ${legResults.filter(r => r.status === "rolled_back").length}`);
+            }
+        });
+    });
+}

package/dist/commands/pnl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PnL Tracker CLI commands.
+ *
+ * perp pnl snapshot  — take one-time equity snapshots across exchanges
+ * perp pnl track     — continuous equity tracking (foreground)
+ * perp pnl daily     — daily PnL breakdown table
+ * perp pnl weekly    — weekly PnL breakdown table
+ * perp pnl summary   — performance summary (Sharpe, drawdown, win rate)
+ */
+import { Command } from "commander";
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export declare function registerPnlCommands(program: Command, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;