perp-cli 0.3.19 → 0.4.2

package/dist/index.js

@@ -297,7 +297,7 @@ registerPortfolioCommands(program, getAdapterForExchange, isJson);
 registerRiskCommands(program, getAdapterForExchange, isJson);
 registerHistoryCommands(program, isJson);
 registerAnalyticsCommands(program, getAdapterForExchange, isJson);
-registerSettingsCommands(program, isJson);
+registerSettingsCommands(program, isJson, getAdapterForExchange);
 registerDexCommands(program, getAdapter, isJson);
 registerPlanCommands(program, getAdapter, isJson);
 registerFundingCommands(program, isJson);
@@ -388,20 +388,20 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                 process.env.LIGHTER_PRIVATE_KEY);
             if (!status.hasWallets && !hasEnvKey && !settings.defaultExchange) {
                 // Fresh install — onboarding
-                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.7\n"));
+                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray(`  v${_pkg.version}\n`));
                 console.log("  Multi-DEX perpetual futures CLI for Pacifica, Hyperliquid, and Lighter.\n");
-                console.log(`  Get started:  ${chalk.cyan("perp init")}`);
+                console.log(`  Get started:  ${chalk.cyan("perp wallet set <exchange> <key>")}`);
                 console.log(chalk.gray(`\n  Or explore without a wallet:`));
                 console.log(`    ${chalk.green("perp market list")}              available markets`);
                 console.log(`    ${chalk.green("perp -e hyperliquid market list")}  Hyperliquid markets`);
-                console.log(`    ${chalk.green("perp arb rates")}                funding rate comparison`);
+                console.log(`    ${chalk.green("perp arb scan")}                 funding rate arbitrage`);
                 console.log(`    ${chalk.green("perp --help")}                   all commands\n`);
             }
             else {
                 // Configured — show status overview
                 const defaultEx = settings.defaultExchange || "pacifica";
                 const activeEntries = Object.entries(status.active);
-                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.7\n"));
+                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray(`  v${_pkg.version}\n`));
                 console.log(`  Default exchange: ${chalk.cyan(defaultEx)}`);
                 if (activeEntries.length > 0) {
                     console.log(chalk.white.bold("\n  Wallets:"));
@@ -432,10 +432,10 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                     }
                 }
                 console.log(chalk.white.bold("\n  Quick commands:"));
-                console.log(`    ${chalk.green("perp status")}       account overview`);
+                console.log(`    ${chalk.green("perp portfolio")}     balances + positions + risk`);
                 console.log(`    ${chalk.green("perp market list")}   available markets`);
+                console.log(`    ${chalk.green("perp arb scan")}      funding rate arbitrage`);
                 console.log(`    ${chalk.green("perp dashboard")}     live monitoring`);
-                console.log(`    ${chalk.green("perp arb rates")}     funding rate comparison`);
                 console.log(`    ${chalk.green("perp --help")}        all commands\n`);
             }
         }

package/dist/mcp-server.js

@@ -333,7 +333,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: `perp -e ${ex} --json account orders`, description: "List open orders to find order ID" }, { step: 2, command: `perp -e ${ex} --json trade edit <symbol> <orderId> <newPrice> <newSize>`, description: "Modify the order", dangerous: true });
         }
         else if (g.includes("arb") || g.includes("arbitrage")) {
-            steps.push({ step: 1, command: "perp --json arb rates", description: "Compare funding rates across exchanges" }, { step: 2, command: "perp --json arb scan", description: "Find high-spread opportunities" }, { step: 3, command: "perp --json gap show", description: "Check cross-exchange price gaps" }, { step: 4, command: "perp --json arb dex", description: "HIP-3 cross-dex arb opportunities (Hyperliquid)" });
+            steps.push({ step: 1, command: "perp --json arb scan --min 5", description: "Scan funding rate arbitrage opportunities" }, { step: 2, command: "perp --json arb scan", description: "Find high-spread opportunities" }, { step: 3, command: "perp --json gap show", description: "Check cross-exchange price gaps" }, { step: 4, command: "perp --json arb dex", description: "HIP-3 cross-dex arb opportunities (Hyperliquid)" });
         }
         else if (g.includes("funding")) {
             const symbol = extractSymbol(g);
@@ -712,7 +712,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: [],
                 category: "read",
-                relatedCommands: ["perp status", "perp portfolio"],
+                relatedCommands: ["perp portfolio", "perp portfolio"],
             };
         }
         else if (category === "arb") {
@@ -731,7 +731,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: ["auto" === sub ? "Auto-executes trades on both exchanges" : ""].filter(Boolean),
                 category: sub === "auto" || sub === "close" ? "write" : "analysis",
-                relatedCommands: ["perp arb rates", "perp arb scan", "perp gap show"],
+                relatedCommands: ["perp arb scan", "perp arb scan", "perp gap show"],
             };
         }
         else if (category === "bridge") {
@@ -837,7 +837,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: [],
                 category: "read",
-                relatedCommands: ["perp funding rates", "perp arb rates"],
+                relatedCommands: ["perp funding rates", "perp arb scan"],
             };
         }
         else if (category === "backtest") {
@@ -1028,7 +1028,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
             arb: {
                 description: "Funding rate arbitrage & basis trading",
                 subcommands: {
-                    rates: { usage: "perp arb rates", description: "Compare funding rates" },
+                    rates: { usage: "perp arb scan", description: "Compare funding rates" },
                     scan: { usage: "perp arb scan --min <bps>", description: "Find arb opportunities" },
                     funding: { usage: "perp arb funding", description: "Detailed funding analysis" },
                     dex: { usage: "perp arb dex", description: "HIP-3 cross-dex arb" },
@@ -1167,7 +1167,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
             deposit: { usage: "perp deposit <exchange> <amount>", description: "Deposit USDC to exchange" },
             withdraw: { usage: "perp withdraw <exchange> <amount>", description: "Withdraw USDC from exchange" },
             portfolio: { usage: "perp portfolio", description: "Cross-exchange portfolio summary" },
-            status: { usage: "perp status", description: "Full account overview" },
+            status: { usage: "perp portfolio", description: "Full account overview" },
             health: { usage: "perp health", description: "Exchange connectivity check" },
             settings: {
                 description: "CLI settings",

package/dist/settings.d.ts

@@ -1,3 +1,7 @@
+export interface ExchangeFees {
+    taker: number;
+    maker: number;
+}
 export interface Settings {
     /** Default exchange when -e flag is omitted */
     defaultExchange: string;
@@ -14,6 +18,8 @@ export interface Settings {
         hyperliquid: boolean;
         lighter: boolean;
     };
+    /** Per-exchange fee tiers (fetched from exchange APIs) */
+    fees: Record<string, ExchangeFees>;
 }
 export declare function loadSettings(): Settings;
 export declare function saveSettings(settings: Settings): void;

package/dist/settings.js

@@ -14,12 +14,27 @@ const DEFAULTS = {
         hyperliquid: false,
         lighter: false,
     },
+    fees: {
+        hyperliquid: { taker: 0.00035, maker: 0.00002 },
+        pacifica: { taker: 0.00035, maker: 0.0001 },
+        lighter: { taker: 0, maker: 0 },
+    },
 };
 export function loadSettings() {
     if (!existsSync(SETTINGS_FILE))
-        return { ...DEFAULTS, referralCodes: { ...DEFAULTS.referralCodes } };
+        return { ...DEFAULTS, referralCodes: { ...DEFAULTS.referralCodes }, fees: { ...DEFAULTS.fees } };
     try {
         const stored = JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
+        // Merge stored fees with defaults (so new exchanges get defaults)
+        const fees = { ...DEFAULTS.fees };
+        if (stored.fees && typeof stored.fees === "object") {
+            for (const [ex, f] of Object.entries(stored.fees)) {
+                const fee = f;
+                if (fee && typeof fee.taker === "number" && typeof fee.maker === "number") {
+                    fees[ex] = { taker: fee.taker, maker: fee.maker };
+                }
+            }
+        }
         return {
             defaultExchange: stored.defaultExchange ?? DEFAULTS.defaultExchange,
             referrals: stored.referrals ?? DEFAULTS.referrals,
@@ -32,10 +47,11 @@ export function loadSettings() {
                 hyperliquid: stored.referralApplied?.hyperliquid ?? DEFAULTS.referralApplied.hyperliquid,
                 lighter: stored.referralApplied?.lighter ?? DEFAULTS.referralApplied.lighter,
             },
+            fees,
         };
     }
     catch {
-        return { ...DEFAULTS, referralCodes: { ...DEFAULTS.referralCodes } };
+        return { ...DEFAULTS, referralCodes: { ...DEFAULTS.referralCodes }, fees: { ...DEFAULTS.fees } };
     }
 }
 export function saveSettings(settings) {

package/dist/smart-order.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Smart Order Execution — best bid/ask + 1 tick pricing.
+ *
+ * Instead of `marketOrder()` which can sweep deep into the book (Hyperliquid
+ * DEX uses 5% slippage by default), this fetches the orderbook and places an
+ * order at exactly the best available price plus one tick.
+ *
+ * For buys:  limit price = best ask + 1 tick  (fills at best ask or better)
+ * For sells: limit price = best bid - 1 tick  (fills at best bid or better)
+ *
+ * Uses IOC (Immediate-Or-Cancel) so the order fills instantly at the best
+ * level and any unfilled remainder is cancelled — no resting orders left.
+ *
+ * Benefits:
+ * - Fills only at the top-of-book price (no multi-level sweep)
+ * - Saves 5-50+ bps vs raw market orders on thin books
+ * - Predictable execution price
+ *
+ * Fallback: if the IOC limit fails, falls back to market order.
+ */
+import type { ExchangeAdapter } from "./exchanges/interface.js";
+export interface SmartOrderOpts {
+    /** Extra ticks of tolerance beyond best price. Default: 1 */
+    tickTolerance?: number;
+    /** Fall back to market order if IOC limit fails. Default: true */
+    fallback?: boolean;
+    /** Reduce only flag for closing positions. Default: false */
+    reduceOnly?: boolean;
+}
+export interface SmartOrderResult {
+    result: unknown;
+    method: "limit_ioc" | "market_fallback";
+    /** The actual limit price used for the order */
+    price: string;
+    /** The best price from the orderbook */
+    bestBookPrice: string;
+    /** Tick size inferred from orderbook */
+    tickSize: string;
+}
+/**
+ * Execute a smart order at best bid/ask + 1 tick.
+ * Drop-in replacement for `adapter.marketOrder()`.
+ */
+export declare function smartOrder(adapter: ExchangeAdapter, symbol: string, side: "buy" | "sell", size: string, opts?: SmartOrderOpts): Promise<SmartOrderResult>;

package/dist/smart-order.js

@@ -0,0 +1,134 @@
+/**
+ * Smart Order Execution — best bid/ask + 1 tick pricing.
+ *
+ * Instead of `marketOrder()` which can sweep deep into the book (Hyperliquid
+ * DEX uses 5% slippage by default), this fetches the orderbook and places an
+ * order at exactly the best available price plus one tick.
+ *
+ * For buys:  limit price = best ask + 1 tick  (fills at best ask or better)
+ * For sells: limit price = best bid - 1 tick  (fills at best bid or better)
+ *
+ * Uses IOC (Immediate-Or-Cancel) so the order fills instantly at the best
+ * level and any unfilled remainder is cancelled — no resting orders left.
+ *
+ * Benefits:
+ * - Fills only at the top-of-book price (no multi-level sweep)
+ * - Saves 5-50+ bps vs raw market orders on thin books
+ * - Predictable execution price
+ *
+ * Fallback: if the IOC limit fails, falls back to market order.
+ */
+/**
+ * Infer tick size from orderbook prices.
+ * Uses the minimum price increment visible in the book.
+ */
+function inferTickSize(levels) {
+    if (levels.length < 2) {
+        // Single level: infer from decimal places (e.g., "1.234" → tick = 0.001)
+        const price = levels[0]?.[0] ?? "1";
+        const decimals = price.includes(".") ? price.split(".")[1].length : 0;
+        return decimals > 0 ? Math.pow(10, -decimals) : 1;
+    }
+    // Use minimum difference between adjacent price levels
+    let minDiff = Infinity;
+    for (let i = 1; i < Math.min(levels.length, 5); i++) {
+        const diff = Math.abs(Number(levels[i][0]) - Number(levels[i - 1][0]));
+        if (diff > 0 && diff < minDiff)
+            minDiff = diff;
+    }
+    return minDiff === Infinity
+        ? Math.pow(10, -(levels[0][0].includes(".") ? levels[0][0].split(".")[1].length : 0))
+        : minDiff;
+}
+/**
+ * Get price precision (decimal places) from a price string.
+ */
+function pricePrecision(priceStr) {
+    return priceStr.includes(".") ? priceStr.split(".")[1].length : 0;
+}
+/**
+ * Check if an order response contains an embedded error (not thrown).
+ * Some exchanges (e.g., Hyperliquid) return success at HTTP level but include
+ * error statuses inside the response body.
+ */
+function hasOrderError(result) {
+    if (!result || typeof result !== "object")
+        return false;
+    const r = result;
+    // Hyperliquid: { response: { data: { statuses: [{ error: "..." }] } } }
+    const resp = r.response;
+    const data = resp?.data;
+    const statuses = data?.statuses;
+    if (Array.isArray(statuses) && statuses.length > 0 && statuses[0].error)
+        return true;
+    // Generic: { ok: false } or { success: false }
+    if (r.ok === false || r.success === false)
+        return true;
+    return false;
+}
+/**
+ * Execute a smart order at best bid/ask + 1 tick.
+ * Drop-in replacement for `adapter.marketOrder()`.
+ */
+export async function smartOrder(adapter, symbol, side, size, opts = {}) {
+    const { tickTolerance = 1, fallback = true, reduceOnly = false } = opts;
+    // 1. Fetch orderbook
+    const book = await adapter.getOrderbook(symbol);
+    // 2. Validate book has liquidity on the relevant side
+    const relevantSide = side === "buy" ? book.asks : book.bids;
+    if (relevantSide.length === 0) {
+        if (!fallback)
+            throw new Error(`No ${side === "buy" ? "asks" : "bids"} in orderbook for ${symbol}`);
+        const result = await adapter.marketOrder(symbol, side, size);
+        return { result, method: "market_fallback", price: "0", bestBookPrice: "0", tickSize: "0" };
+    }
+    // 3. Get best price and tick size
+    const bestEntry = relevantSide[0];
+    const bestPrice = Number(bestEntry[0]);
+    const tick = inferTickSize(relevantSide);
+    const decimals = pricePrecision(bestEntry[0]);
+    // 4. Calculate limit price: best price + N ticks in favorable direction
+    const limitPrice = side === "buy"
+        ? bestPrice + tick * tickTolerance // 1 tick above best ask
+        : bestPrice - tick * tickTolerance; // 1 tick below best bid
+    const formattedPrice = limitPrice.toFixed(decimals);
+    // 5. Place IOC limit order at calculated price
+    try {
+        const result = await adapter.limitOrder(symbol, side, formattedPrice, size, {
+            tif: "IOC",
+            reduceOnly,
+        });
+        // Check for exchange-level rejection inside a "success" response
+        // (e.g., Hyperliquid returns { status: "ok", response: { data: { statuses: [{ error: "..." }] } } })
+        if (fallback && hasOrderError(result)) {
+            const fallbackResult = await adapter.marketOrder(symbol, side, size);
+            return {
+                result: fallbackResult,
+                method: "market_fallback",
+                price: formattedPrice,
+                bestBookPrice: bestEntry[0],
+                tickSize: tick.toFixed(decimals),
+            };
+        }
+        return {
+            result,
+            method: "limit_ioc",
+            price: formattedPrice,
+            bestBookPrice: bestEntry[0],
+            tickSize: tick.toFixed(decimals),
+        };
+    }
+    catch (err) {
+        if (!fallback)
+            throw err;
+        // Fallback to raw market order for reliability
+        const result = await adapter.marketOrder(symbol, side, size);
+        return {
+            result,
+            method: "market_fallback",
+            price: formattedPrice,
+            bestBookPrice: bestEntry[0],
+            tickSize: tick.toFixed(decimals),
+        };
+    }
+}

package/dist/trade-validator.js

@@ -1,5 +1,6 @@
 import { symbolMatch } from "./utils.js";
-const DEFAULT_TAKER_FEE = 0.0005; // 0.05%
+import { DEFAULT_TAKER_FEE } from "./constants.js";
+// Use centralized DEFAULT_TAKER_FEE from constants.ts (0.035%)
 const DEFAULT_MAX_SLIPPAGE = 0.005; // 0.5%
 /**
  * Validate a trade before execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.3.19",
+  "version": "0.4.2",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.3.19"
+  version: "0.4.2"
 ---
 
 # perp-cli Agent Guide
@@ -21,12 +21,21 @@ Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), L
 5. **NEVER trade without user confirmation.**
 6. **NEVER read ~/.perp/.env or key files.**
 
-## Install
+## Install (run this FIRST)
 
 ```bash
-npm install -g perp-cli
+# 1. Check if perp exists and is current (must be ≥ 0.3.19)
+perp --version 2>/dev/null
+
+# 2. If not found or outdated:
+npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
+
+# 3. If version is still old (npx cache), clear cache first:
+npx -y clear-npx-cache 2>/dev/null; npx -y perp-cli@latest --json --version
 ```
-No sudo: `npm install -g perp-cli --prefix ~/.npm-global && export PATH="$HOME/.npm-global/bin:$PATH"`
+
+**IMPORTANT:** Always use `@latest` with npx — without it, npx uses a stale cached version.
+Use `perp` if global install works, otherwise `npx -y perp-cli@latest` as prefix for all commands.
 
 ## Wallet Setup
 
@@ -50,7 +59,9 @@ perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage <N> --isolated  # e
 
 # Single exchange trading (when not doing arb)
 perp --json -e <EX> trade market <SYM> buy <SIZE>
+perp --json -e <EX> trade market <SYM> buy <SIZE> --smart  # IOC limit at best ask + 1 tick (less slippage)
 perp --json -e <EX> trade close <SYM>
+perp --json -e <EX> trade close <SYM> --smart              # smart close at best bid/ask
 
 # Risk (only if you need to set limits — portfolio already includes risk)
 perp --json risk limits --max-leverage 5
@@ -78,6 +89,13 @@ perp --json --ndjson -e <EX> market list
 
 # Prevent duplicate orders with client ID
 perp --json -e <EX> trade market <SYM> buy <SIZE> --client-id <UNIQUE_ID>
+
+# Smart order: IOC limit at best bid/ask + 1 tick instead of raw market order
+# Fills only at top-of-book price — no multi-level sweep slippage
+perp --json -e <EX> trade market <SYM> buy <SIZE> --smart
+perp --json -e <EX> trade close <SYM> --smart
+perp --json arb exec <SYM> <longEx> <shortEx> <$> --smart   # smart arb entry
+perp --json arb close <SYM> --smart                          # smart arb close
 ```
 
 All string outputs are auto-sanitized (control chars stripped, prompt injection patterns blocked).
@@ -94,7 +112,11 @@ All string outputs are auto-sanitized (control chars stripped, prompt injection
    → executes BOTH legs simultaneously
    → verifies positions exist after execution
    → auto-rollback if one leg fails
-5. perp --json portfolio                    → verify positions
+5. perp --json arb status                   → monitor: PnL, funding income, daily estimate, breakeven
+6. perp --json arb funding-earned           → actual funding payments received/paid + APR
+7. perp --json arb close <SYM>             → close both legs simultaneously (retry + verify)
+   → --dry-run: preview without executing
+   → --pair <longEx>:<shortEx>: specify which pair if multiple
 ```
 
 ## Position Sizing
@@ -128,10 +150,11 @@ Check `canTrade` before any order. If `false`, do NOT trade.
 ## Monitoring (while positions open)
 
 ```
-Every 15 min: perp --json portfolio
-Every 1 hour: perp --json arb scan --min 5
+Every 15 min: perp --json arb status               → PnL, daily income, breakeven analysis
+Every 1 hour: perp --json arb scan --min 5          → check if spread still profitable
+Daily:        perp --json arb funding-earned         → verify actual funding payments
 Exit if: spread < breakeven or one leg closed unexpectedly.
-Close both: perp --json -e <EX1> trade close <SYM> & perp --json -e <EX2> trade close <SYM>
+Close:        perp --json arb close <SYM>            → close both legs with retry + verification
 ```
 
 ## Error Handling