perp-cli 0.4.0 → 0.4.8

package/README.md

@@ -33,6 +33,8 @@ 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.
+
 ## Core Commands
 
 ```bash

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/arb/utils.d.ts

@@ -2,6 +2,8 @@
  * Arb utilities: settlement timing strategy, basis risk monitoring, and webhook notifications.
  */
 import type { ExchangeAdapter } from "../exchanges/interface.js";
+/** Settlement schedules per exchange (UTC hours when settlement occurs) */
+export declare const SETTLEMENT_SCHEDULES: Record<string, number[]>;
 export type SettleStrategy = "block" | "aggressive" | "off";
 /**
  * Get the most recent settlement time for an exchange.

package/dist/arb/utils.js

@@ -3,7 +3,7 @@
  */
 // ── Settlement Timing Strategy ──
 /** Settlement schedules per exchange (UTC hours when settlement occurs) */
-const SETTLEMENT_SCHEDULES = {
+export const SETTLEMENT_SCHEDULES = {
     hyperliquid: Array.from({ length: 24 }, (_, i) => i), // every hour
     pacifica: Array.from({ length: 24 }, (_, i) => i), // every hour
     lighter: Array.from({ length: 24 }, (_, i) => i), // every hour

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/agent.js

@@ -1,6 +1,9 @@
+import { createRequire } from "node:module";
 import { printJson, jsonOk } from "../utils.js";
 import { ERROR_CODES } from "../errors.js";
 import chalk from "chalk";
+const _require = createRequire(import.meta.url);
+const _pkg = _require("../../package.json");
 /** Infer parameter type from commander flags/description */
 function inferType(flags, desc) {
     if (flags.includes("[boolean]") || !flags.includes("<") && !flags.includes("["))
@@ -72,7 +75,7 @@ export function registerAgentCommands(program, getAdapter, isJson) {
         }
         const envelope = {
             schemaVersion: "2.0",
-            cliVersion: "0.1.0",
+            cliVersion: _pkg.version,
             generatedAt: new Date().toISOString(),
             exchanges: ["pacifica", "hyperliquid", "lighter"],
             errorCodes: errorCodeDocs,
@@ -93,7 +96,7 @@ export function registerAgentCommands(program, getAdapter, isJson) {
         }
         const envelope = {
             schemaVersion: "2.0",
-            cliVersion: "0.1.0",
+            cliVersion: _pkg.version,
             generatedAt: new Date().toISOString(),
             exchanges: ["pacifica", "hyperliquid", "lighter"],
             errorCodes: errorCodeDocs,
@@ -110,7 +113,7 @@ export function registerAgentCommands(program, getAdapter, isJson) {
         .action(() => {
         printJson(jsonOk({
             name: "perp-cli",
-            version: "0.1.0",
+            version: _pkg.version,
             description: "Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter) with HIP-3 deployed dex support",
             exchanges: ["pacifica", "hyperliquid", "lighter"],
             capabilities: [
@@ -142,14 +145,14 @@ export function registerAgentCommands(program, getAdapter, isJson) {
                     category: "trading",
                     commands: [
                         "perp trade check <symbol> <side> <size> --json",
-                        "perp trade market <symbol> <buy|sell> <size> --json --client-id <id>",
+                        "perp trade market <symbol> <buy|sell> <size> --json [--smart] --client-id <id>",
                         "perp trade limit <symbol> <buy|sell> <price> <size> --json --client-id <id>",
                         "perp trade cancel <symbol> <orderId> --json",
                         "perp trade cancel-all --json",
-                        "perp trade close <symbol> --json",
-                        "perp trade close-all --json",
-                        "perp trade flatten --json",
-                        "perp trade reduce <symbol> <percent> --json",
+                        "perp trade close <symbol> --json [--smart]",
+                        "perp trade close-all --json [--smart]",
+                        "perp trade flatten --json [--smart]",
+                        "perp trade reduce <symbol> <percent> --json [--smart]",
                         "perp trade stop <symbol> <side> <stopPrice> <size> --json",
                         "perp trade tpsl <symbol> <side> --tp <price> --sl <price> --json",
                         "perp trade twap <symbol> <side> <size> <duration> --json",
@@ -276,7 +279,7 @@ export function registerAgentCommands(program, getAdapter, isJson) {
         .action(async () => {
         const results = {
             timestamp: new Date().toISOString(),
-            cli_version: "0.1.0",
+            cli_version: _pkg.version,
         };
         // Check exchange APIs
         const { pingPacifica, pingHyperliquid } = await import("../shared-api.js");

package/dist/commands/arb/index.js

@@ -4,12 +4,14 @@ import { readExecutionLog, logExecution } from "../../execution-log.js";
 import { computeAnnualSpread } from "../../funding.js";
 import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates, } from "../../shared-api.js";
 import { computeBasisRisk } from "../../arb-utils.js";
+import { smartOrder } from "../../smart-order.js";
+import { removePosition as persistRemovePosition } from "../../arb-state.js";
 import { fetchAllBalances, computeRebalancePlan } from "../../rebalance.js";
 import { EXCHANGE_TO_CHAIN, getBestQuote } from "../../bridge-engine.js";
 import { computeEnhancedStats } from "../../arb-history-stats.js";
 // ── Helpers ──
+import { DEFAULT_TAKER_FEE as TAKER_FEE } from "../../constants.js";
 const EXCHANGES = ["hyperliquid", "lighter", "pacifica"];
-const TAKER_FEE = 0.00035; // ~0.035% typical taker fee
 function formatDuration(ms) {
     const hours = Math.floor(ms / (1000 * 60 * 60));
     const days = Math.floor(hours / 24);
@@ -293,6 +295,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
         .description("Manually close an arb position on both exchanges")
         .option("--dry-run", "Show what would happen without executing")
         .option("--pair <pair>", "Specify arb pair as longExchange:shortExchange (e.g. pacifica:hyperliquid)")
+        .option("--smart", "Smart execution: IOC limit at best bid/ask + 1 tick (reduces slippage)")
         .action(async (symbol, opts) => {
         const sym = symbol.toUpperCase();
         const dryRun = !!opts.dryRun || process.argv.includes("--dry-run");
@@ -436,10 +439,15 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
             for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
                 try {
                     const adapter = await getAdapterForExchange(exchange);
-                    await adapter.marketOrder(rawSymbol, side, String(size));
+                    if (opts.smart) {
+                        await smartOrder(adapter, rawSymbol, side, String(size), { reduceOnly: true });
+                    }
+                    else {
+                        await adapter.marketOrder(rawSymbol, side, String(size));
+                    }
                     results.push({ exchange, action: `${side} (close ${label})`, status: "success", retries: attempt });
                     if (!isJson())
-                        console.log(chalk.green(`  Closed ${label} on ${exchange}: ${side.toUpperCase()} ${size} ${sym}${attempt > 0 ? ` (retry ${attempt})` : ""}`));
+                        console.log(chalk.green(`  Closed ${label} on ${exchange}: ${side.toUpperCase()} ${size} ${sym}${opts.smart ? " (smart)" : ""}${attempt > 0 ? ` (retry ${attempt})` : ""}`));
                     return;
                 }
                 catch (err) {
@@ -488,6 +496,13 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
                 console.log(chalk.yellow(`\n  Warning: Position may not be fully closed on: ${notClosed.map(v => v.exchange).join(", ")}`));
             }
         }
+        // Remove from persisted daemon state (so daemon doesn't try to re-close)
+        if (allSuccess) {
+            try {
+                persistRemovePosition(sym);
+            }
+            catch { /* state may not exist */ }
+        }
         // Log to execution log
         const arbPairId = `${sym}:${longPos.exchange}:${shortPos.exchange}`;
         logExecution({