perp-cli 0.4.2 → 0.4.9

package/README.md

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

package/dist/arb/reconcile.d.ts

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

package/dist/arb/reconcile.js

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

package/dist/arb/sizing.d.ts

@@ -5,7 +5,18 @@ import type { ExchangeAdapter } from "../exchanges/interface.js";
  *
  * @returns size string that works for both exchanges, or null if not viable
  */
-export declare function computeMatchedSize(sizeUsd: number, price: number, longExchange: string, shortExchange: string): {
+export declare function computeMatchedSize(sizeUsd: number, price: number, longExchange: string, shortExchange: string, opts?: {
+    longSizeDecimals?: number;
+    shortSizeDecimals?: number;
+}): {
+    size: string;
+    notional: number;
+} | null;
+/**
+ * Compute matched size for spot-perp arb.
+ * Uses spot exchange's size decimals for the spot leg.
+ */
+export declare function computeSpotPerpMatchedSize(sizeUsd: number, price: number, spotExchange: string, perpExchange: string, spotSizeDecimals?: number): {
     size: string;
     notional: number;
 } | null;

package/dist/arb/sizing.js

@@ -4,12 +4,12 @@
  *
  * @returns size string that works for both exchanges, or null if not viable
  */
-export function computeMatchedSize(sizeUsd, price, longExchange, shortExchange) {
+export function computeMatchedSize(sizeUsd, price, longExchange, shortExchange, opts) {
     if (price <= 0)
         return null;
     const rawSize = sizeUsd / price;
-    // Size decimals per exchange (conservative defaults)
-    const szDecimals = Math.min(getSizeDecimals(longExchange), getSizeDecimals(shortExchange));
+    // Use explicitly provided decimals if available, else conservative defaults
+    const szDecimals = Math.min(opts?.longSizeDecimals ?? getSizeDecimals(longExchange), opts?.shortSizeDecimals ?? getSizeDecimals(shortExchange));
     // Round DOWN to the least precise exchange's decimals
     const factor = Math.pow(10, szDecimals);
     const roundedSize = Math.floor(rawSize * factor) / factor;
@@ -30,12 +30,15 @@ export function computeMatchedSize(sizeUsd, price, longExchange, shortExchange)
     }
     return { size: roundedSize.toFixed(szDecimals), notional };
 }
-/** Size decimal precision by exchange */
+/** Size decimal precision by exchange (conservative fallbacks — prefer explicit decimals via opts) */
 function getSizeDecimals(exchange) {
     switch (exchange.toLowerCase()) {
-        case "hyperliquid": return 1; // Most HL perps use 1 decimal
+        case "hyperliquid": return 2; // HL perps range 0-5; 2 is safe middle ground
         case "lighter": return 2;
         case "pacifica": return 4;
+        // Spot exchanges
+        case "spot:hyperliquid": return 2;
+        case "spot:lighter": return 2;
         default: return 2;
     }
 }
@@ -45,9 +48,39 @@ function getMinNotional(exchange) {
         case "hyperliquid": return 10;
         case "lighter": return 10;
         case "pacifica": return 1;
+        case "spot:hyperliquid": return 10;
+        case "spot:lighter": return 10;
         default: return 10;
     }
 }
+/**
+ * Compute matched size for spot-perp arb.
+ * Uses spot exchange's size decimals for the spot leg.
+ */
+export function computeSpotPerpMatchedSize(sizeUsd, price, spotExchange, perpExchange, spotSizeDecimals) {
+    if (price <= 0)
+        return null;
+    // If explicit spot decimals provided, use them; otherwise derive from exchange
+    const spotDec = spotSizeDecimals ?? getSizeDecimals(`spot:${spotExchange}`);
+    const perpDec = getSizeDecimals(perpExchange);
+    const szDecimals = Math.min(spotDec, perpDec);
+    const rawSize = sizeUsd / price;
+    const factor = Math.pow(10, szDecimals);
+    const roundedSize = Math.floor(rawSize * factor) / factor;
+    if (roundedSize <= 0)
+        return null;
+    const notional = roundedSize * price;
+    const minNotional = Math.max(getMinNotional(`spot:${spotExchange}`), getMinNotional(perpExchange));
+    if (notional < minNotional) {
+        const roundedUp = Math.ceil(rawSize * factor) / factor;
+        const notionalUp = roundedUp * price;
+        if (notionalUp <= sizeUsd * 1.2) {
+            return { size: roundedUp.toFixed(szDecimals), notional: notionalUp };
+        }
+        return null;
+    }
+    return { size: roundedSize.toFixed(szDecimals), notional };
+}
 /**
  * After both legs are submitted, verify actual fills match.
  * If there's a size mismatch, place a correction order on the larger side.

package/dist/arb/state.d.ts

@@ -13,6 +13,12 @@ export interface ArbPositionState {
     entryShortPrice: number;
     accumulatedFunding: number;
     lastCheckTime: string;
+    /** "perp-perp" (default) or "spot-perp" */
+    mode?: "perp-perp" | "spot-perp";
+    /** Spot leg exchange name (for spot-perp mode) */
+    spotExchange?: string;
+    /** Spot symbol, e.g. "ETH/USDC" (for spot-perp mode) */
+    spotSymbol?: string;
 }
 export interface ArbDaemonState {
     version: 1;

package/dist/cli-spec.d.ts

@@ -1,7 +1,3 @@
-/**
- * Generates a structured CLI spec from Commander's program tree.
- * Used by `perp api-spec` so agents can discover all commands programmatically.
- */
 import type { Command } from "commander";
 interface ArgSpec {
     name: string;

package/dist/cli-spec.js

@@ -1,3 +1,10 @@
+/**
+ * Generates a structured CLI spec from Commander's program tree.
+ * Used by `perp api-spec` so agents can discover all commands programmatically.
+ */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const { version: pkgVersion } = require("../package.json");
 function extractCommand(cmd) {
     const args = cmd._args ?? [];
     const options = cmd.options.map((opt) => ({
@@ -27,7 +34,7 @@ export function getCliSpec(program) {
     }));
     return {
         name: "perp",
-        version: "0.1.0",
+        version: pkgVersion,
         description: "Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter)",
         globalOptions,
         commands,

package/dist/commands/account.d.ts

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