perp-cli 0.4.8 → 0.4.10

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
 
@@ -35,6 +36,30 @@ 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
@@ -48,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
 ```
@@ -92,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/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;