perp-cli 0.4.8 → 0.4.9

package/dist/mcp-server.js

@@ -318,6 +318,12 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             const symbol = extractSymbol(g) || "<symbol>";
             steps.push({ step: 1, command: `perp -e ${ex} --json account positions`, description: "Check current position" }, { step: 2, command: `perp -e ${ex} --json trade stop ${symbol} <side> <stopPrice> <size>`, description: "Place stop order", dangerous: true });
         }
+        else if (g.includes("split") || g.includes("depth") || (g.includes("large") && (g.includes("order") || g.includes("buy") || g.includes("sell")))) {
+            const symbol = extractSymbol(g) || "<symbol>";
+            const amount = extractNumber(g) || "<usd>";
+            const side = g.includes("sell") || g.includes("short") ? "sell" : "buy";
+            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook depth` }, { step: 2, command: `perp -e ${ex} --json account info`, description: "Check available balance" }, { step: 3, command: `perp -e ${ex} --json trade split ${symbol} ${side} ${amount}`, description: `Split ${side} $${amount} ${symbol} into depth-based slices`, dangerous: true }, { step: 4, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
+        }
         else if (g.includes("twap")) {
             const symbol = extractSymbol(g) || "<symbol>";
             const size = extractNumber(g) || "<size>";
@@ -338,19 +344,16 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         else if (g.includes("funding")) {
             const symbol = extractSymbol(g);
             if (symbol) {
-                steps.push({ step: 1, command: `perp --json funding compare ${symbol}`, description: `Compare ${symbol} funding rates` }, { step: 2, command: `perp -e ${ex} --json market funding ${symbol}`, description: `${symbol} funding history` });
+                steps.push({ step: 1, command: `perp --json arb rates`, description: `Funding rates across all exchanges` }, { step: 2, command: `perp -e ${ex} --json market funding ${symbol}`, description: `${symbol} funding history` });
             }
             else {
-                steps.push({ step: 1, command: "perp --json funding rates", description: "Funding rates across all exchanges" }, { step: 2, command: "perp --json funding spread", description: "Funding rate spreads" });
+                steps.push({ step: 1, command: "perp --json arb rates", description: "Funding rates across all exchanges" }, { step: 2, command: "perp --json arb scan --min 5", description: "Funding rate arb opportunities" });
             }
         }
         else if (g.includes("bridge") || g.includes("transfer") || g.includes("cross-chain")) {
             const amount = extractNumber(g) || "<amount>";
             steps.push({ step: 1, command: "perp --json bridge chains", description: "List supported chains" }, { step: 2, command: `perp --json bridge quote --from <chain> --to <chain> --amount ${amount}`, description: "Get bridge quote with fees" }, { step: 3, command: `perp --json bridge send --from <chain> --to <chain> --amount ${amount}`, description: "Execute bridge transfer", dangerous: true }, { step: 4, command: "perp --json bridge status <orderId>", description: "Track bridge completion" });
         }
-        else if (g.includes("alert") || g.includes("notify") || g.includes("alarm")) {
-            steps.push({ step: 1, command: "perp --json alert list", description: "List existing alerts" }, { step: 2, command: "perp --json alert add", description: "Add a new price/funding/pnl/liquidation alert" }, { step: 3, command: "perp --json alert daemon", description: "Start alert monitoring daemon" });
-        }
         else if (g.includes("grid") || g.includes("dca") || g.includes("bot")) {
             const symbol = extractSymbol(g) || "<symbol>";
             if (g.includes("grid")) {
@@ -407,7 +410,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: "perp --json jobs list", description: "List running background jobs" });
         }
         else if (g.includes("dex") || g.includes("hip-3") || g.includes("hip3")) {
-            steps.push({ step: 1, command: "perp --json dex list", description: "List HIP-3 deployed dexes" }, { step: 2, command: "perp --json dex markets <dexName>", description: "Show markets on a specific dex" });
+            steps.push({ step: 1, command: "perp --json -e hl market hip3", description: "List HIP-3 deployed dexes" }, { step: 2, command: "perp --json -e hl --dex <name> market list", description: "Show markets on a specific dex" });
         }
         else if (g.includes("plan") || g.includes("composite") || g.includes("multi-step")) {
             steps.push({ step: 1, command: "perp plan example", description: "Show example execution plan format" }, { step: 2, command: "perp --json plan validate <file>", description: "Validate plan file" }, { step: 3, command: "perp --json plan execute <file> --dry-run", description: "Dry-run the plan", dangerous: true });
@@ -417,11 +420,11 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         }
         else if (g.includes("deposit")) {
             const amount = extractNumber(g) || "<amount>";
-            steps.push({ step: 1, command: "perp --json wallet balance", description: "Check wallet balance" }, { step: 2, command: `perp --json deposit ${ex} ${amount}`, description: `Deposit $${amount} to ${ex}`, dangerous: true }, { step: 3, command: `perp -e ${ex} --json account info`, description: "Verify deposit arrived" });
+            steps.push({ step: 1, command: "perp --json wallet balance", description: "Check wallet balance" }, { step: 2, command: `perp --json funds deposit ${ex} ${amount}`, description: `Deposit $${amount} to ${ex}`, dangerous: true }, { step: 3, command: `perp -e ${ex} --json account info`, description: "Verify deposit arrived" });
         }
         else if (g.includes("withdraw")) {
             const amount = extractNumber(g) || "<amount>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json account info`, description: "Check available balance" }, { step: 2, command: `perp --json withdraw ${ex} ${amount}`, description: `Withdraw $${amount} from ${ex}`, dangerous: true }, { step: 3, command: "perp --json wallet balance", description: "Verify withdrawal received" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json account info`, description: "Check available balance" }, { step: 2, command: `perp --json funds withdraw ${ex} ${amount}`, description: `Withdraw $${amount} from ${ex}`, dangerous: true }, { step: 3, command: "perp --json wallet balance", description: "Verify withdrawal received" });
         }
         else if (g.includes("leverage")) {
             const symbol = extractSymbol(g) || "<symbol>";
@@ -450,7 +453,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: "perp settings show", description: "Show current settings" }, { step: 2, command: "perp settings referrals on", description: "Enable referral codes (no extra fees, just volume tracking)" });
         }
         else {
-            steps.push({ step: 1, command: "perp agent capabilities", description: "List all available CLI capabilities" }, { step: 2, command: `perp -e ${ex} --json status`, description: "Check account status" }, { step: 3, command: "perp --json health", description: "Check exchange connectivity" });
+            steps.push({ step: 1, command: "perp agent capabilities", description: "List all available CLI capabilities" }, { step: 2, command: `perp -e ${ex} --json status`, description: "Check account status" }, { step: 3, command: "perp --json agent ping", description: "Check exchange connectivity" });
         }
         return {
             content: [{
@@ -750,11 +753,12 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 relatedCommands: ["perp bridge chains", "perp bridge quote"],
             };
         }
-        else if (category === "deposit" || category === "withdraw") {
+        else if (category === "funds") {
+            const sub = args[1]; // deposit or withdraw
             explanation = {
                 command,
-                description: category === "deposit" ? `Deposits USDC into ${args[1] || "an exchange"} account` : `Withdraws USDC from ${args[1] || "an exchange"} account`,
-                parameters: [{ name: "amount", value: args[2] || args[1], description: "Amount in USDC" }],
+                description: sub === "deposit" ? `Deposits USDC into ${args[2] || "an exchange"} account` : sub === "withdraw" ? `Withdraws USDC from ${args[2] || "an exchange"} account` : "Funds management (deposit, withdraw, bridge, transfer)",
+                parameters: [{ name: "amount", value: args[3] || args[2], description: "Amount in USDC" }],
                 risks: ["Moves real funds — verify amount before executing"],
                 category: "write",
                 relatedCommands: ["perp wallet balance", "perp account info"],
@@ -777,7 +781,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: [],
                 category: "read",
-                relatedCommands: ["perp alert list", "perp alert add"],
+                relatedCommands: ["perp risk status", "perp risk limits"],
             };
         }
         else if (category === "bot" || category === "run") {
@@ -790,24 +794,14 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 relatedCommands: ["perp jobs list", "perp jobs stop"],
             };
         }
-        else if (category === "stream") {
-            explanation = {
-                command,
-                description: `Live WebSocket stream: ${sub}. Outputs NDJSON in real-time.`,
-                parameters: args.slice(2).map((a, i) => ({ name: `arg${i}`, value: a, description: "See --help" })),
-                risks: [],
-                category: "read",
-                relatedCommands: ["perp stream prices", "perp stream events"],
-            };
-        }
-        else if (category === "analytics") {
+        else if (category === "history") {
             explanation = {
                 command,
-                description: { summary: "Trading performance summary", pnl: "P&L breakdown by symbol and time period", funding: "Funding payment history and totals", report: "Detailed performance report" }[sub] || `Analytics: ${sub}`,
+                description: { summary: "Trading performance summary", pnl: "P&L breakdown by symbol and time period", funding: "Funding payment history and totals", report: "Detailed performance report", perf: "Performance breakdown (daily/weekly/summary)" }[sub] || `History: ${sub}`,
                 parameters: [],
                 risks: [],
                 category: "read",
-                relatedCommands: ["perp analytics summary", "perp history list"],
+                relatedCommands: ["perp history summary", "perp history list"],
             };
         }
         else if (category === "wallet") {
@@ -830,16 +824,6 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 relatedCommands: ["perp gap show", "perp arb scan"],
             };
         }
-        else if (category === "funding") {
-            explanation = {
-                command,
-                description: { rates: "Compare funding rates across exchanges", compare: "Compare a specific symbol's funding", spread: "Show funding rate spreads", history: "Funding rate history", monitor: "Live funding rate monitor" }[sub] || `Funding: ${sub}`,
-                parameters: [],
-                risks: [],
-                category: "read",
-                relatedCommands: ["perp funding rates", "perp arb scan"],
-            };
-        }
         else if (category === "backtest") {
             explanation = {
                 command,
@@ -861,7 +845,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
             };
         }
         else {
-            const writeCommands = new Set(["trade", "deposit", "withdraw", "manage", "rebalance"]);
+            const writeCommands = new Set(["trade", "funds", "manage", "rebalance"]);
             explanation = {
                 command,
                 description: `CLI command: ${command}. Run 'perp ${category} --help' for detailed usage.`,
@@ -1056,32 +1040,16 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     status: { usage: "perp bridge status <orderId>", description: "Track bridge status" },
                 },
             },
-            alert: {
-                description: "Price, funding, PnL, and liquidation alerts",
-                subcommands: {
-                    add: { usage: "perp alert add", description: "Add alert" },
-                    list: { usage: "perp alert list", description: "List alerts" },
-                    remove: { usage: "perp alert remove <id>", description: "Remove alert" },
-                    daemon: { usage: "perp alert daemon", description: "Start alert monitoring" },
-                },
-            },
             bot: {
                 description: "Automated trading bots",
                 subcommands: {
-                    start: { usage: "perp bot start <config>", description: "Start bot from config" },
+                    twap: { usage: "perp bot twap <symbol> <side> <size> <duration>", description: "TWAP execution" },
+                    grid: { usage: "perp bot grid <symbol> --range <pct> --grids <n> --size <usd>", description: "Grid trading bot" },
+                    dca: { usage: "perp bot dca <symbol> <side> <amount> <interval>", description: "DCA bot" },
+                    "trailing-stop": { usage: "perp bot trailing-stop <symbol>", description: "Trailing stop bot" },
                     "quick-grid": { usage: "perp bot quick-grid <symbol>", description: "Quick grid bot" },
                     "quick-dca": { usage: "perp bot quick-dca <symbol> <side> <amount> <interval>", description: "Quick DCA bot" },
                     "quick-arb": { usage: "perp bot quick-arb", description: "Quick arb bot" },
-                    "preset-list": { usage: "perp bot preset-list", description: "List bot presets" },
-                },
-            },
-            stream: {
-                description: "Live WebSocket streams (NDJSON output)",
-                subcommands: {
-                    prices: { usage: "perp stream prices", description: "Live prices" },
-                    book: { usage: "perp stream book <symbol>", description: "Live orderbook" },
-                    trades: { usage: "perp stream trades <symbol>", description: "Live trades" },
-                    events: { usage: "perp stream events", description: "Account events (fills, liquidations)" },
                 },
             },
             wallet: {
@@ -1092,37 +1060,15 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     generate: { usage: "perp wallet generate solana|evm", description: "Generate new wallet" },
                 },
             },
-            analytics: {
-                description: "Trading performance analytics",
-                subcommands: {
-                    summary: { usage: "perp analytics summary", description: "Performance summary" },
-                    pnl: { usage: "perp analytics pnl", description: "P&L breakdown" },
-                    funding: { usage: "perp analytics funding", description: "Funding payment history" },
-                    report: { usage: "perp analytics report --since <period>", description: "Detailed report" },
-                },
-            },
             history: {
-                description: "Execution log & audit trail",
+                description: "Execution log, performance & audit trail",
                 subcommands: {
                     list: { usage: "perp history list", description: "Execution log" },
-                    stats: { usage: "perp history stats", description: "Execution statistics" },
-                    positions: { usage: "perp history positions", description: "Position history" },
-                },
-            },
-            funding: {
-                description: "Funding rate comparison",
-                subcommands: {
-                    rates: { usage: "perp funding rates", description: "Rates across exchanges" },
-                    compare: { usage: "perp funding compare <symbol>", description: "Compare symbol's funding" },
-                    spread: { usage: "perp funding spread", description: "Funding rate spreads" },
-                    monitor: { usage: "perp funding monitor", description: "Live funding monitor" },
-                },
-            },
-            gap: {
-                description: "Cross-exchange price gap analysis",
-                subcommands: {
-                    show: { usage: "perp gap show", description: "Current price gaps" },
-                    watch: { usage: "perp gap watch --min <pct>", description: "Live gap monitor" },
+                    summary: { usage: "perp history summary", description: "Performance summary" },
+                    pnl: { usage: "perp history pnl", description: "P&L breakdown" },
+                    funding: { usage: "perp history funding", description: "Funding payment history" },
+                    report: { usage: "perp history report", description: "Full performance report" },
+                    perf: { usage: "perp history perf --period daily|weekly|summary", description: "Performance breakdown" },
                 },
             },
             backtest: {
@@ -1132,14 +1078,6 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     grid: { usage: "perp backtest grid", description: "Backtest grid strategy" },
                 },
             },
-            dex: {
-                description: "HIP-3 deployed perp dexes (Hyperliquid)",
-                subcommands: {
-                    list: { usage: "perp dex list", description: "List dexes" },
-                    markets: { usage: "perp dex markets <name>", description: "Dex markets" },
-                    balance: { usage: "perp dex balance <name>", description: "Dex balance" },
-                },
-            },
             plan: {
                 description: "Composite multi-step execution plans",
                 subcommands: {
@@ -1164,11 +1102,20 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     logs: { usage: "perp jobs logs <id>", description: "View job logs" },
                 },
             },
-            deposit: { usage: "perp deposit <exchange> <amount>", description: "Deposit USDC to exchange" },
-            withdraw: { usage: "perp withdraw <exchange> <amount>", description: "Withdraw USDC from exchange" },
+            funds: {
+                usage: "perp funds <deposit|withdraw|transfer|bridge> ...",
+                description: "Deposit, withdraw, bridge & transfer funds",
+                subcommands: {
+                    "deposit <exchange> <amount>": "Deposit USDC to exchange",
+                    "withdraw <exchange> <amount>": "Withdraw USDC from exchange",
+                    "transfer <amount> <address>": "HL internal transfer",
+                    "bridge --from <chain> --to <chain> --amount <n> --recipient <addr>": "CCTP bridge",
+                    info: "Show all deposit/withdraw routes & limits",
+                },
+            },
             portfolio: { usage: "perp portfolio", description: "Cross-exchange portfolio summary" },
             status: { usage: "perp portfolio", description: "Full account overview" },
-            health: { usage: "perp health", description: "Exchange connectivity check" },
+            health: { usage: "perp agent ping", description: "Exchange connectivity check" },
             settings: {
                 description: "CLI settings",
                 subcommands: {

package/dist/strategies/split-order.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Orderbook-aware split order execution.
+ *
+ * Unlike TWAP (time-based splitting), this strategy reads the orderbook
+ * before each slice and calculates optimal slice sizes based on available
+ * depth. Each slice is placed as an IOC limit order at the worst acceptable
+ * price within the slippage tolerance, ensuring no sweep beyond the target.
+ *
+ * Flow per slice:
+ *   1. Fetch fresh orderbook
+ *   2. Walk levels via computeExecutableSize to find fillable amount
+ *   3. Place IOC limit at best price + slippage tolerance
+ *   4. Wait for book to refresh, then repeat
+ */
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export interface SplitOrderParams {
+    symbol: string;
+    side: "buy" | "sell";
+    totalSizeUsd: number;
+    maxSlippagePct?: number;
+    maxSlices?: number;
+    delayMs?: number;
+    minSliceUsd?: number;
+}
+export interface SplitSlice {
+    index: number;
+    size: string;
+    price: string;
+    notionalUsd: number;
+    slippagePct: number;
+    method: "limit_ioc" | "market";
+    status: "filled" | "partial" | "failed";
+}
+export interface SplitOrderResult {
+    symbol: string;
+    side: "buy" | "sell";
+    requestedUsd: number;
+    filledUsd: number;
+    filledSize: number;
+    avgPrice: number;
+    totalSlippagePct: number;
+    slices: SplitSlice[];
+    status: "complete" | "partial" | "failed";
+    runtime: number;
+}
+/**
+ * Execute a split order: orderbook-aware slicing with IOC limits.
+ */
+export declare function runSplitOrder(adapter: ExchangeAdapter, params: SplitOrderParams, log?: (msg: string) => void): Promise<SplitOrderResult>;

package/dist/strategies/split-order.js

@@ -0,0 +1,138 @@
+/**
+ * Orderbook-aware split order execution.
+ *
+ * Unlike TWAP (time-based splitting), this strategy reads the orderbook
+ * before each slice and calculates optimal slice sizes based on available
+ * depth. Each slice is placed as an IOC limit order at the worst acceptable
+ * price within the slippage tolerance, ensuring no sweep beyond the target.
+ *
+ * Flow per slice:
+ *   1. Fetch fresh orderbook
+ *   2. Walk levels via computeExecutableSize to find fillable amount
+ *   3. Place IOC limit at best price + slippage tolerance
+ *   4. Wait for book to refresh, then repeat
+ */
+import { computeExecutableSize } from "../liquidity.js";
+import { logExecution } from "../execution-log.js";
+/**
+ * Infer price precision (decimal places) from an orderbook price string.
+ */
+function pricePrecision(priceStr) {
+    return priceStr.includes(".") ? priceStr.split(".")[1].length : 0;
+}
+/**
+ * Execute a split order: orderbook-aware slicing with IOC limits.
+ */
+export async function runSplitOrder(adapter, params, log = console.log) {
+    const { symbol, side, totalSizeUsd, maxSlippagePct = 0.3, maxSlices = 10, delayMs = 1000, minSliceUsd = 100, } = params;
+    const startedAt = Date.now();
+    const slices = [];
+    let remainingUsd = totalSizeUsd;
+    let totalFilledSize = 0;
+    let totalFilledNotional = 0;
+    // Capture initial best price for overall slippage calculation
+    let initialBestPrice = 0;
+    try {
+        const initialBook = await adapter.getOrderbook(symbol);
+        const initialLevels = side === "buy" ? initialBook.asks : initialBook.bids;
+        if (initialLevels.length > 0) {
+            initialBestPrice = Number(initialLevels[0][0]);
+        }
+    }
+    catch {
+        // Will be recaptured on first slice
+    }
+    log(`[SPLIT] ${side.toUpperCase()} $${totalSizeUsd.toFixed(0)} of ${symbol} | max slippage: ${maxSlippagePct}% | max slices: ${maxSlices}`);
+    for (let i = 0; i < maxSlices && remainingUsd >= minSliceUsd; i++) {
+        // 1. Fetch fresh orderbook
+        const book = await adapter.getOrderbook(symbol);
+        const levels = side === "buy" ? book.asks : book.bids;
+        if (levels.length === 0) {
+            log(`[SPLIT] No ${side === "buy" ? "asks" : "bids"} in orderbook, stopping`);
+            break;
+        }
+        // Capture initial best if we missed it
+        if (initialBestPrice === 0) {
+            initialBestPrice = Number(levels[0][0]);
+        }
+        // 2. Calculate how much we can execute within slippage on this depth
+        const check = computeExecutableSize(levels, remainingUsd, maxSlippagePct);
+        if (check.maxSize <= 0) {
+            log(`[SPLIT] Insufficient liquidity within ${maxSlippagePct}% slippage, stopping`);
+            break;
+        }
+        // Slice size: what we can fill within slippage, capped by remaining
+        const sliceNotional = Math.min(check.maxSize * check.avgFillPrice, remainingUsd);
+        const sliceSize = sliceNotional / check.avgFillPrice;
+        // 3. Calculate IOC limit price (worst acceptable within slippage)
+        const bestPrice = Number(levels[0][0]);
+        const limitPrice = side === "buy"
+            ? bestPrice * (1 + maxSlippagePct / 100)
+            : bestPrice * (1 - maxSlippagePct / 100);
+        const decimals = pricePrecision(levels[0][0]);
+        const formattedPrice = limitPrice.toFixed(decimals);
+        const formattedSize = sliceSize.toFixed(6);
+        log(`[SPLIT] Slice ${i + 1}: ${formattedSize} @ limit $${formattedPrice} (~$${sliceNotional.toFixed(0)}) | depth: $${check.depthUsd.toFixed(0)}`);
+        // 4. Execute IOC limit order
+        let slice;
+        try {
+            await adapter.limitOrder(symbol, side, formattedPrice, formattedSize, { tif: "IOC" });
+            slice = {
+                index: i,
+                size: formattedSize,
+                price: formattedPrice,
+                notionalUsd: sliceNotional,
+                slippagePct: check.slippagePct,
+                method: "limit_ioc",
+                status: "filled",
+            };
+            totalFilledSize += sliceSize;
+            totalFilledNotional += sliceNotional;
+            remainingUsd -= sliceNotional;
+            logExecution({
+                type: "limit_order", exchange: adapter.name, symbol,
+                side, size: formattedSize, price: formattedPrice,
+                notional: sliceNotional, status: "success", dryRun: false,
+                meta: { action: "split-order", slice: i + 1, totalSlices: maxSlices },
+            });
+        }
+        catch (err) {
+            log(`[SPLIT] Slice ${i + 1} failed: ${err instanceof Error ? err.message : String(err)}`);
+            slice = {
+                index: i, size: formattedSize, price: formattedPrice,
+                notionalUsd: 0, slippagePct: 0, method: "limit_ioc", status: "failed",
+            };
+            logExecution({
+                type: "limit_order", exchange: adapter.name, symbol,
+                side, size: formattedSize, price: formattedPrice,
+                notional: 0, status: "failed", dryRun: false,
+                error: err instanceof Error ? err.message : String(err),
+                meta: { action: "split-order", slice: i + 1, totalSlices: maxSlices },
+            });
+        }
+        slices.push(slice);
+        // 5. Delay before next slice (let the book refresh)
+        if (remainingUsd >= minSliceUsd && i < maxSlices - 1) {
+            await new Promise(r => setTimeout(r, delayMs));
+        }
+    }
+    const avgPrice = totalFilledSize > 0 ? totalFilledNotional / totalFilledSize : 0;
+    const totalSlippage = initialBestPrice > 0
+        ? Math.abs((avgPrice - initialBestPrice) / initialBestPrice) * 100
+        : 0;
+    const status = totalFilledNotional >= totalSizeUsd * 0.95 ? "complete"
+        : totalFilledNotional > 0 ? "partial"
+            : "failed";
+    log(`[SPLIT] Done: ${slices.length} slices | filled $${totalFilledNotional.toFixed(0)}/$${totalSizeUsd.toFixed(0)} | avg price: $${avgPrice.toFixed(2)} | slippage: ${totalSlippage.toFixed(3)}%`);
+    return {
+        symbol, side,
+        requestedUsd: totalSizeUsd,
+        filledUsd: totalFilledNotional,
+        filledSize: totalFilledSize,
+        avgPrice,
+        totalSlippagePct: totalSlippage,
+        slices,
+        status,
+        runtime: (Date.now() - startedAt) / 1000,
+    };
+}

package/package.json

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

package/skills/perp-cli/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: perp-cli
 description: "Multi-DEX perpetual futures trading CLI for Pacifica (Solana), Hyperliquid (EVM), and Lighter (Ethereum). Use when user asks to: trade perps, check funding rates, scan arbitrage (perp-perp or spot-perp), delta-neutral strategies, bridge USDC, manage positions/orders, deposit/withdraw, spot+perp hedge, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, Lighter, HyperEVM, funding arb, U-token (UBTC/UETH/USOL)."
-allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*), Bash(bash scripts/*.sh:*)"
+allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.4.7"
+  version: "0.4.9"
 ---
 
 # perp-cli Agent Guide
@@ -60,6 +60,8 @@ 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 market <SYM> buy <SIZE> --split  # orderbook-aware split for large orders
+perp --json -e <EX> trade split <SYM> buy 5000             # dedicated split command (USD notional)
 perp --json -e <EX> trade close <SYM>
 perp --json -e <EX> trade close <SYM> --smart              # smart close at best bid/ask
 
@@ -96,6 +98,12 @@ 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
+
+# Split order: orderbook-aware execution for large orders
+# Reads depth before each slice, IOC limit within slippage tolerance
+perp --json -e <EX> trade split <SYM> buy 5000               # split $5000 into depth-based slices
+perp --json -e <EX> trade split <SYM> sell 10000 --max-slices 5 --delay 2000
+perp --json -e <EX> trade market <SYM> buy <SIZE> --split     # split via market command flag
 ```
 
 All string outputs are auto-sanitized (control chars stripped, prompt injection patterns blocked).
@@ -198,7 +206,7 @@ If `error.retryable` is `false`, do NOT retry — fix the cause first.
 
 | Error | Action |
 |-------|--------|
-| `RATE_LIMITED` | wait 5s, retry (max 3) |
+| `RATE_LIMITED` | wait 5-10s, retry (max 3). Lighter rate limits are strict — space commands 3s+ apart |
 | `EXCHANGE_UNREACHABLE` | wait 10s, retry. 3x fail → skip that exchange |
 | `TIMEOUT` | wait 5s, retry (max 3) |
 | `INSUFFICIENT_BALANCE` | reduce size or bridge funds to that exchange |
@@ -208,6 +216,8 @@ If `error.retryable` is `false`, do NOT retry — fix the cause first.
 | `MARGIN_INSUFFICIENT` | reduce leverage or close existing positions |
 | `DUPLICATE_ORDER` | already submitted — check positions, don't retry |
 | Lighter `invalid signature` | check ~/.perp/.env or `perp --json -e lighter manage setup-api-key` |
+| Lighter `invalid account index` | rate limit caused init failure — wait 10s and retry the command |
+| Lighter `--smart` not filling | Lighter IOC limit orders may not fill — use regular market order (without `--smart`) |
 
 ## Examples
 
@@ -254,29 +264,6 @@ perp --json settings referrals off          # disable anytime
 When setting up wallets for the first time, ask the user:
 > "perp-cli 개발을 지원하는 레퍼럴 기능을 켜시겠어요? 추가 수수료 없이 거래소 리베이트만 활용됩니다."
 
-## Scripts
-
-Executable automation scripts in `scripts/`. Run with `bash scripts/<name>.sh`.
-Scripts auto-detect `perp` (global install) or fall back to `npx -y perp-cli@latest` — no global install required.
-
-| Script | Purpose | Usage |
-|--------|---------|-------|
-| `preflight.sh` | Pre-trade validation (install, wallet, connectivity, balance, risk) | `bash scripts/preflight.sh --json` |
-| `validate-arb.sh` | Validate arb opportunity before execution (price, liquidity, balance, risk, dry-run) | `bash scripts/validate-arb.sh ETH hl lt 100 --leverage 2` |
-| `spot-perp-scan.sh` | Combined spot+perp and perp-perp scan with portfolio context | `bash scripts/spot-perp-scan.sh --json --mode all --min 10` |
-| `arb-monitor.sh` | Monitor open arb positions (PnL, funding, liquidation distance) | `bash scripts/arb-monitor.sh --json --min-spread 5` |
-| `funding-analysis.sh` | Funding rate analysis across all exchanges | `bash scripts/funding-analysis.sh --json --symbol ETH` |
-
-All scripts support `--json` for structured output. Use in automation pipelines:
-```bash
-# Full arb workflow with validation
-bash scripts/preflight.sh --json        # 1. system ready?
-bash scripts/spot-perp-scan.sh --json   # 2. find opportunities
-bash scripts/validate-arb.sh ETH hl lt 100  # 3. validate before exec
-# 4. [user confirms] → perp --json arb exec ...
-bash scripts/arb-monitor.sh --json      # 5. monitor positions
-```
-
 ## References
 
 - `references/commands.md` — full command reference

package/skills/perp-cli/references/agent-operations.md

@@ -123,27 +123,28 @@ perp --json -e hl account info           # USDC deposited on exchange
 ### Deposit to Exchange
 ```bash
 # Hyperliquid (from Arbitrum wallet)
-perp --json deposit hyperliquid 100
+perp --json funds deposit hyperliquid 100
 
 # Pacifica (from Solana wallet)
-perp --json deposit pacifica 100
+perp --json funds deposit pacifica 100
 
 # Lighter (multiple routes)
-perp --json deposit lighter info         # show all available routes
-perp --json deposit lighter cctp arb 100 # via CCTP from Arbitrum
+perp --json funds deposit lighter info         # show all available routes
+perp --json funds deposit lighter cctp arbitrum 100 # via CCTP from Arbitrum
 ```
 
 ### Withdraw from Exchange
 ```bash
-perp --json withdraw hyperliquid 100
-perp --json withdraw pacifica 100
+perp --json funds withdraw hyperliquid 100
+perp --json funds withdraw pacifica 100
+perp --json funds withdraw lighter 100
 ```
 
 ### Bridge Between Chains
 When you need to move USDC between exchanges on different chains:
 ```bash
 # 1. Withdraw from source exchange
-perp --json withdraw pacifica 500
+perp --json funds withdraw pacifica 500
 
 # 2. Quote the bridge
 perp --json bridge quote --from solana --to arbitrum --amount 500
@@ -155,7 +156,7 @@ perp --json bridge send --from solana --to arbitrum --amount 500
 perp --json bridge status <orderId>
 
 # 5. Deposit to destination exchange
-perp --json deposit hyperliquid 500
+perp --json funds deposit hyperliquid 500
 ```
 
 ## Order Types & Execution
@@ -168,6 +169,15 @@ perp --json -e hl trade buy BTC 0.01              # shorthand
 perp --json -e hl trade sell BTC 0.01             # shorthand
 ```
 
+### Split Orders (orderbook-aware, for large orders)
+```bash
+perp --json -e hl trade split BTC buy 5000        # split $5000 into depth-based slices
+perp --json -e hl trade split BTC sell 10000 --max-slippage 0.5 --max-slices 5
+perp --json -e hl trade market BTC buy 0.5 --split   # split via market command flag
+```
+Returns `{ slices[], filledUsd, avgPrice, totalSlippagePct, status }`.
+Status: `complete` (all filled), `partial` (some filled), `failed` (none filled).
+
 ### Limit Orders (execute at specific price)
 ```bash
 perp --json -e hl trade buy BTC 0.01 -p 60000    # buy at $60,000
@@ -238,7 +248,7 @@ Error case:
 - `trade market`, `trade buy`, `trade sell` — will open duplicate positions
 - `trade close` — may error if already closed, but harmless
 - `bridge send` — will send duplicate transfers
-- `deposit`, `withdraw` — will move funds twice
+- `funds deposit`, `funds withdraw` — will move funds twice
 
 **For non-idempotent commands:** always verify the result before retrying. Check positions or balances to confirm whether the first attempt succeeded.