perp-cli 0.4.12 → 0.5.2

package/dist/exchanges/hyperliquid.js

@@ -72,17 +72,38 @@ export class HyperliquidAdapter {
     async _loadAssetMap() {
         try {
             if (this._dex) {
-                // HIP-3 deployed dex: use raw info POST with dex param
-                const meta = await this._infoPost({ type: "meta", dex: this._dex });
+                // HIP-3 deployed dex: asset indices use global offset scheme
+                // offset = 110000 + dexListIndex * 10000 (per Python SDK convention)
+                const [meta, dexList] = await Promise.all([
+                    this._infoPost({ type: "meta", dex: this._dex }),
+                    this._infoPost({ type: "perpDexs" }),
+                ]);
+                // Find this dex's position in the list (index 0 is native/null)
+                let dexOffset = 0;
+                for (let i = 1; i < dexList.length; i++) {
+                    if (dexList[i]?.name === this._dex) {
+                        dexOffset = 110000 + (i - 1) * 10000;
+                        break;
+                    }
+                }
+                if (dexOffset === 0) {
+                    console.error(`[hyperliquid] Dex "${this._dex}" not found in perpDexs list`);
+                }
                 if (meta?.universe) {
                     meta.universe.forEach((asset, idx) => {
+                        const globalIdx = dexOffset + idx;
                         // Store both with and without dex prefix for flexible lookup
                         // API returns "km:GOOGL" but callers may use "GOOGL" or "KM:GOOGL"
                         const fullName = asset.name; // e.g., "km:GOOGL"
                         const baseName = fullName.includes(":") ? fullName.split(":").pop() : fullName;
-                        this._assetMap.set(fullName, idx);
-                        this._assetMap.set(baseName, idx);
-                        this._assetMapReverse.set(idx, fullName);
+                        this._assetMap.set(fullName, globalIdx);
+                        this._assetMap.set(baseName, globalIdx);
+                        this._assetMapReverse.set(globalIdx, fullName);
+                        // Cache szDecimals for dex assets (critical for order sizing)
+                        if (asset.szDecimals !== undefined) {
+                            this._szDecimalsMap.set(fullName, asset.szDecimals);
+                            this._szDecimalsMap.set(baseName, asset.szDecimals);
+                        }
                     });
                 }
             }
@@ -168,8 +189,8 @@ export class HyperliquidAdapter {
             ctxs = meta[1] ?? [];
             mids = allMids;
         }
-        // Rebuild asset map if empty
-        if (this._assetMap.size === 0) {
+        // Rebuild asset map if empty (fallback — normally populated by init/_loadAssetMap)
+        if (this._assetMap.size === 0 && !this._dex) {
             universe.forEach((asset, i) => {
                 const sym = String(asset.name);
                 this._assetMap.set(sym, i);
@@ -191,8 +212,24 @@ export class HyperliquidAdapter {
         });
     }
     async getOrderbook(symbol) {
-        const book = await this.sdk.info.getL2Book(symbol.toUpperCase());
-        const levels = book?.levels ?? [[], []];
+        let levels;
+        if (this._dex) {
+            // HIP-3 dex: SDK's getL2Book() doesn't support dex parameter
+            // Resolve symbol to full dex-prefixed name (e.g. "US500" → "km:US500")
+            const resolved = this.resolveSymbol(symbol.toUpperCase());
+            // Ensure dex prefix is present (API requires it)
+            const coin = resolved.includes(":") ? resolved : `${this._dex}:${resolved}`;
+            const book = await this._infoPost({
+                type: "l2Book",
+                coin,
+                dex: this._dex,
+            });
+            levels = book?.levels ?? [[], []];
+        }
+        else {
+            const book = await this.sdk.info.getL2Book(symbol.toUpperCase());
+            levels = book?.levels ?? [[], []];
+        }
         return {
             bids: (levels[0] ?? []).map((l) => [
                 String(l.px ?? "0"),
@@ -291,6 +328,22 @@ export class HyperliquidAdapter {
     }
     async getOpenOrders() {
         this.ensureAddress();
+        if (this._dex) {
+            // HIP-3 dex: use frontendOpenOrders with dex parameter
+            const orders = await this._infoPost({
+                type: "frontendOpenOrders", user: this._address, dex: this._dex,
+            });
+            return (orders ?? []).map((o) => ({
+                orderId: String(o.oid ?? ""),
+                symbol: String(o.coin ?? ""),
+                side: String(o.side) === "B" ? "buy" : String(o.side) === "A" ? "sell" : String(o.side).toLowerCase(),
+                price: String(o.limitPx ?? "0"),
+                size: String(o.sz ?? "0"),
+                filled: "0",
+                status: "open",
+                type: "limit",
+            }));
+        }
         const orders = await this.sdk.info.getUserOpenOrders(this._address);
         return (orders ?? []).map((o) => ({
             orderId: String(o.oid ?? ""),
@@ -337,16 +390,20 @@ export class HyperliquidAdapter {
      */
     async _dexMarketOrder(symbol, side, size) {
         const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
-        // Get current mark price + szDecimals from dex meta
+        const szDec = this.getSzDecimals(symbol);
+        // Get current mark price from dex meta (lookup by coin name, not array index)
+        const resolved = this.resolveSymbol(symbol.toUpperCase());
+        const coin = resolved.includes(":") ? resolved : `${this._dex}:${resolved}`;
         const meta = await this._infoPost({
             type: "metaAndAssetCtxs",
             dex: this._dex,
         });
-        const ctx = (meta[1] ?? [])[assetIndex];
+        // Find local index by matching coin name in universe
+        const localIdx = meta[0]?.universe?.findIndex(a => a.name === coin) ?? -1;
+        const ctx = localIdx >= 0 ? (meta[1] ?? [])[localIdx] : undefined;
         const midPrice = Number(ctx?.markPx ?? 0);
         if (midPrice <= 0)
             throw new Error(`Cannot get price for ${symbol} on dex ${this._dex}`);
-        const szDec = meta[0]?.universe?.[assetIndex]?.szDecimals ?? 2;
         // HL official rounding: 5 significant figures, max 6 decimals for perps
         const MAX_DECIMALS_PERP = 6;
         const slippage = 0.05;
@@ -373,6 +430,40 @@ export class HyperliquidAdapter {
             throw new Error("No private key configured. Run: perp init");
         }
     }
+    /**
+     * Normalize trailing zeros from price ('p') and size ('s') string fields
+     * in an action object, recursively. Matches the SDK's normalizeTrailingZeros.
+     *
+     * The HL validator normalizes these fields before hashing; if we hash without
+     * normalizing, the recovered signer address won't match → "User or API Wallet
+     * does not exist" error.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static _normalizeAction(obj) {
+        if (!obj || typeof obj !== "object")
+            return obj;
+        if (Array.isArray(obj)) {
+            return obj.map(item => HyperliquidAdapter._normalizeAction(item));
+        }
+        const result = { ...obj };
+        for (const key in result) {
+            if (!Object.prototype.hasOwnProperty.call(result, key))
+                continue;
+            const value = result[key];
+            if (value && typeof value === "object") {
+                result[key] = HyperliquidAdapter._normalizeAction(value);
+            }
+            else if ((key === "p" || key === "s") && typeof value === "string") {
+                let v = value;
+                if (v.includes("."))
+                    v = v.replace(/\.?0+$/, "");
+                if (v === "-0")
+                    v = "0";
+                result[key] = v;
+            }
+        }
+        return result;
+    }
     async _signAndSendAction(action) {
         this.ensureSigner();
         const { encode } = await import("@msgpack/msgpack");
@@ -381,9 +472,13 @@ export class HyperliquidAdapter {
         const baseUrl = isMainnet
             ? "https://api.hyperliquid.xyz"
             : "https://api.hyperliquid-testnet.xyz";
+        // Normalize trailing zeros from 'p' and 's' fields before hashing.
+        // The HL validator does the same; without this, the hash differs and the
+        // recovered signer address is wrong → "User or API Wallet does not exist".
+        const normalizedAction = HyperliquidAdapter._normalizeAction(action);
         // Sign L1 action (replicates SDK's signL1Action)
         const nonce = Date.now();
-        const msgPackBytes = encode(action);
+        const msgPackBytes = encode(normalizedAction);
         const data = new Uint8Array(msgPackBytes.length + 9); // +8 nonce +1 vault flag
         data.set(msgPackBytes);
         const view = new DataView(data.buffer);
@@ -419,7 +514,14 @@ export class HyperliquidAdapter {
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(payload),
         });
-        const result = await res.json();
+        const text = await res.text();
+        let result;
+        try {
+            result = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`HL exchange API error (${res.status}): ${text.slice(0, 200)}`);
+        }
         if (result?.status === "err") {
             throw new Error(result.response ?? JSON.stringify(result));
         }
@@ -450,10 +552,7 @@ export class HyperliquidAdapter {
             orders: [orderWire],
             grouping: "na",
         };
-        // Add dex field for HIP-3 deployed perps
-        if (this._dex) {
-            action.dex = this._dex;
-        }
+        // No "dex" field needed — the global asset index (110000+) encodes the dex
         return this._signAndSendAction(action);
     }
     async limitOrder(symbol, side, price, size, opts) {
@@ -480,6 +579,16 @@ export class HyperliquidAdapter {
     }
     async cancelOrder(symbol, orderId) {
         this.ensureSigner();
+        if (this._dex) {
+            // HIP-3 dex: use raw cancel action with global asset index
+            const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+            const result = await this._signAndSendAction({
+                type: "cancel",
+                cancels: [{ a: assetIndex, o: parseInt(orderId) }],
+            });
+            await this._invalidateAccountCache();
+            return result;
+        }
         // HL SDK expects coin in "ETH-PERP" format (internal symbol convention)
         const resolved = this.resolveSymbol(symbol);
         const result = await this.sdk.exchange.cancelOrder({
@@ -494,16 +603,25 @@ export class HyperliquidAdapter {
         const orders = await this.getOpenOrders();
         const toCancel = symbol
             ? orders.filter((o) => {
-                const norm = (s) => s.toUpperCase().replace(/-PERP$/, "");
+                const norm = (s) => s.toUpperCase().replace(/-PERP$/, "").replace(/^[^:]+:/, "");
                 return norm(o.symbol) === norm(symbol);
             })
             : orders;
         const results = [];
         for (const o of toCancel) {
-            results.push(await this.sdk.exchange.cancelOrder({
-                coin: o.symbol,
-                o: parseInt(o.orderId),
-            }));
+            if (this._dex) {
+                const assetIndex = await this.getAssetIndex(o.symbol);
+                results.push(await this._signAndSendAction({
+                    type: "cancel",
+                    cancels: [{ a: assetIndex, o: parseInt(o.orderId) }],
+                }));
+            }
+            else {
+                results.push(await this.sdk.exchange.cancelOrder({
+                    coin: o.symbol,
+                    o: parseInt(o.orderId),
+                }));
+            }
         }
         return results;
     }
@@ -608,22 +726,37 @@ export class HyperliquidAdapter {
      */
     async triggerOrder(symbol, side, size, triggerPrice, tpsl, opts) {
         this.ensureSigner();
-        const orderParams = {
-            coin: symbol.toUpperCase(),
-            is_buy: side === "buy",
-            sz: parseFloat(size),
-            limit_px: parseFloat(triggerPrice),
-            order_type: {
+        const assetIndex = await this.getAssetIndex(symbol.toUpperCase());
+        const szDec = this.getSzDecimals(symbol);
+        const roundedSize = Number(size).toFixed(szDec);
+        const roundedTrigger = this._hlRoundPrice(Number(triggerPrice), szDec);
+        // Remove trailing zeros (HL API requirement)
+        const trimZeros = (s) => {
+            if (!s.includes("."))
+                return s;
+            const n = s.replace(/\.?0+$/, "");
+            return n === "-0" ? "0" : n;
+        };
+        const orderWire = {
+            a: assetIndex,
+            b: side === "buy",
+            p: trimZeros(roundedTrigger),
+            s: trimZeros(roundedSize),
+            r: opts?.reduceOnly ?? true,
+            t: {
                 trigger: {
-                    triggerPx: triggerPrice,
                     isMarket: opts?.isMarket ?? true,
+                    triggerPx: trimZeros(roundedTrigger),
                     tpsl,
                 },
             },
-            reduce_only: opts?.reduceOnly ?? true,
+        };
+        const action = {
+            type: "order",
+            orders: [orderWire],
             grouping: opts?.grouping ?? "positionTpsl",
         };
-        return this.sdk.exchange.placeOrder(orderParams);
+        return this._signAndSendAction(action);
     }
     /**
      * Place a TWAP order.

package/dist/exchanges/lighter.js

@@ -240,10 +240,19 @@ export class LighterAdapter {
         if (!dec) {
             throw new Error(`No market decimals loaded for ${symbol}. Market data may not be initialized.`);
         }
-        return {
-            baseAmount: Math.round(size * Math.pow(10, dec.size)),
-            priceTicks: Math.round(price * Math.pow(10, dec.price)),
-        };
+        const baseAmount = Math.round(size * Math.pow(10, dec.size));
+        const priceTicks = Math.round(price * Math.pow(10, dec.price));
+        // Validate: size too small for this market's precision → baseAmount rounds to 0
+        if (size > 0 && baseAmount <= 0) {
+            const minSize = 1 / Math.pow(10, dec.size);
+            throw new Error(`Order size ${size} too small for ${symbol} (sizeDecimals=${dec.size}, min=${minSize}). ` +
+                `Increase size or use a different market.`);
+        }
+        if (price > 0 && priceTicks <= 0) {
+            const minPrice = 1 / Math.pow(10, dec.price);
+            throw new Error(`Order price ${price} too small for ${symbol} (priceDecimals=${dec.price}, min=${minPrice}).`);
+        }
+        return { baseAmount, priceTicks };
     }
     async getMarkets() {
         const markets = [];
@@ -338,9 +347,14 @@ export class LighterAdapter {
                     : "0"),
                 liquidationPrice: String(p.liquidation_price || "N/A"),
                 unrealizedPnl: String(p.unrealized_pnl || "0"),
-                leverage: Number(p.initial_margin_fraction || 0) > 0
-                    ? Math.round(10000 / Number(p.initial_margin_fraction))
-                    : 1,
+                // Compute actual leverage = notional / account equity (not max leverage from IMF)
+                leverage: (() => {
+                    const notional = Math.abs(Number(p.position_value || 0));
+                    const equity = Number(acct.total_asset_value || 0);
+                    if (equity > 0 && notional > 0)
+                        return Math.round(notional / equity * 10) / 10;
+                    return 1;
+                })(),
             };
         });
     }
@@ -584,7 +598,7 @@ export class LighterAdapter {
             // /recentTrades returns is_maker_ask: maker was asking → taker bought
             side: t.is_maker_ask ? "buy" : "sell",
             price: String(t.price ?? "0"),
-            size: String(t.base_amount ?? t.amount ?? ""),
+            size: String(t.size ?? t.base_amount ?? t.amount ?? ""),
             fee: String(t.fee ?? "0"),
         }));
     }

package/dist/liquidity.js

@@ -41,13 +41,15 @@ export function computeExecutableSize(levels, requestedSizeUsd, maxSlippagePct =
     const avgFillPrice = filledSize > 0 ? filledNotional / filledSize : bestPrice;
     const slippagePct = bestPrice > 0 ? ((avgFillPrice - bestPrice) / bestPrice) * 100 : 0;
     const canFillFull = filledNotional >= requestedSizeUsd * 0.95; // 95% fill = close enough
+    // 10% safety buffer — avoid filling at the very edge of liquidity
+    const bufferedSize = filledSize * 0.9;
     return {
         maxSize: filledSize,
         avgFillPrice,
         slippagePct: Math.abs(slippagePct),
         depthUsd: totalDepthUsd,
         canFillFull,
-        recommendedSize: filledSize,
+        recommendedSize: bufferedSize,
     };
 }
 /**

package/dist/mcp-server.js

@@ -339,15 +339,15 @@ 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 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)" });
+            steps.push({ step: 1, command: "perp --json arb scan --min 5", description: "Scan funding rate arbitrage opportunities" }, { step: 2, command: "perp --json arb scan --gaps", description: "Check cross-exchange price gaps" }, { step: 3, command: "perp --json arb scan --hip3", description: "HIP-3 cross-dex arb opportunities (Hyperliquid)" });
         }
         else if (g.includes("funding")) {
             const symbol = extractSymbol(g);
             if (symbol) {
-                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` });
+                steps.push({ step: 1, command: `perp --json arb scan --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 arb rates", description: "Funding rates across all exchanges" }, { step: 2, command: "perp --json arb scan --min 5", description: "Funding rate arb opportunities" });
+                steps.push({ step: 1, command: "perp --json arb scan --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")) {
@@ -386,22 +386,22 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: `perp -e ${ex} --json risk status`, description: "Portfolio risk overview" }, { step: 2, command: `perp -e ${ex} --json risk limits`, description: "Current position limits" });
         }
         else if (g.includes("analytic") || g.includes("performance") || g.includes("pnl") || g.includes("p&l")) {
-            steps.push({ step: 1, command: `perp -e ${ex} --json analytics summary`, description: "Trading performance summary" }, { step: 2, command: `perp -e ${ex} --json analytics pnl`, description: "P&L breakdown" }, { step: 3, command: `perp -e ${ex} --json analytics funding`, description: "Funding payment history" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json history summary`, description: "Trading performance summary" }, { step: 2, command: `perp -e ${ex} --json history pnl`, description: "P&L breakdown" }, { step: 3, command: `perp -e ${ex} --json history funding`, description: "Funding payment history" });
         }
         else if (g.includes("history") || g.includes("log") || g.includes("audit")) {
             steps.push({ step: 1, command: `perp -e ${ex} --json history list`, description: "Execution audit trail" }, { step: 2, command: `perp -e ${ex} --json history stats`, description: "Execution statistics" });
         }
-        else if (g.includes("stream") || g.includes("live") || g.includes("watch") || g.includes("realtime")) {
+        else if (g.includes("live") || g.includes("watch") || g.includes("realtime")) {
             const symbol = extractSymbol(g);
             if (symbol) {
-                steps.push({ step: 1, command: `perp -e ${ex} stream book ${symbol}`, description: `Live ${symbol} orderbook` }, { step: 2, command: `perp -e ${ex} stream trades ${symbol}`, description: `Live ${symbol} trades` });
+                steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `${symbol} orderbook` }, { step: 2, command: `perp -e ${ex} --json market trades ${symbol}`, description: `${symbol} recent trades` }, { step: 3, command: `perp --json arb scan --gaps --live`, description: "Live cross-exchange price gap monitor" });
             }
             else {
-                steps.push({ step: 1, command: `perp -e ${ex} stream prices`, description: "Live price stream" }, { step: 2, command: `perp -e ${ex} stream events`, description: "Live account events (fills, liquidations)" });
+                steps.push({ step: 1, command: "perp --json arb scan --gaps --live", description: "Live cross-exchange price gap monitor" }, { step: 2, command: `perp -e ${ex} --json market prices`, description: "Current prices across exchanges" });
             }
         }
         else if (g.includes("gap")) {
-            steps.push({ step: 1, command: "perp --json gap show", description: "Cross-exchange price gaps" }, { step: 2, command: "perp --json gap watch", description: "Live gap monitor" });
+            steps.push({ step: 1, command: "perp --json arb scan --gaps", description: "Cross-exchange price gaps" }, { step: 2, command: "perp --json arb scan --gaps --live", description: "Live gap monitor" });
         }
         else if (g.includes("rebalance")) {
             steps.push({ step: 1, command: "perp --json rebalance check", description: "Check balance distribution" }, { step: 2, command: "perp --json rebalance plan", description: "Generate rebalance plan" }, { step: 3, command: "perp --json rebalance execute", description: "Execute rebalance", dangerous: true });
@@ -446,7 +446,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
                 steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `${symbol} orderbook` }, { step: 2, command: `perp -e ${ex} --json market funding ${symbol}`, description: `${symbol} funding history` }, { step: 3, command: `perp -e ${ex} --json market kline ${symbol} 1h`, description: `${symbol} hourly candles` });
             }
             else {
-                steps.push({ step: 1, command: "perp --json market prices", description: "All market prices" }, { step: 2, command: "perp --json gap show", description: "Cross-exchange price gaps" });
+                steps.push({ step: 1, command: "perp --json market prices", description: "All market prices" }, { step: 2, command: "perp --json arb scan --gaps", description: "Cross-exchange price gaps" });
             }
         }
         else if (g.includes("setting") || g.includes("config") || g.includes("referral")) {
@@ -708,6 +708,8 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                     history: "Shows order history (filled, cancelled, etc.)",
                     trades: "Shows trade execution history with prices and fees",
                     "funding-history": "Shows funding payments received/paid",
+                    funding: "Shows funding payments received/paid (alias for funding-history)",
+                    "twap-orders": "Shows active TWAP orders",
                     pnl: "Shows profit & loss summary",
                     margin: `Shows margin info for ${args[2] || "a symbol"}`,
                     settings: "Shows account settings (leverage, margin mode per symbol)",
@@ -715,26 +717,26 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: [],
                 category: "read",
-                relatedCommands: ["perp portfolio", "perp portfolio"],
+                relatedCommands: ["perp portfolio", "perp account balance"],
             };
         }
         else if (category === "arb") {
             explanation = {
                 command,
                 description: {
-                    rates: "Compares funding rates across all 3 exchanges",
-                    scan: "Scans for funding rate arbitrage opportunities with the largest spreads",
-                    funding: "Detailed funding rate analysis across exchanges",
-                    dex: "HIP-3 cross-dex arbitrage opportunities on Hyperliquid",
+                    scan: "Scans for funding rate arbitrage opportunities. Use --rates for funding rates, --gaps for price gaps, --hip3 for cross-dex arb, --positions for funding impact, --basis for basis trading",
                     auto: "Auto-execute funding rate arbitrage (runs as background job)",
+                    exec: "Execute an arb trade (enter paired positions on two exchanges)",
                     status: "Shows current arb positions and P&L",
                     close: "Closes an arb position on both exchanges",
                     history: "Shows arb execution history",
+                    config: "View/edit arb configuration",
+                    rebalance: "Rebalance funds across exchanges for arb positions",
                 }[sub] || `Arbitrage command: ${sub}`,
                 parameters: [],
-                risks: ["auto" === sub ? "Auto-executes trades on both exchanges" : ""].filter(Boolean),
-                category: sub === "auto" || sub === "close" ? "write" : "analysis",
-                relatedCommands: ["perp arb scan", "perp arb scan", "perp gap show"],
+                risks: [sub === "auto" || sub === "exec" ? "Executes trades on exchanges" : ""].filter(Boolean),
+                category: sub === "auto" || sub === "close" || sub === "exec" || sub === "rebalance" ? "write" : "analysis",
+                relatedCommands: ["perp arb scan", "perp arb status", "perp arb scan --gaps"],
             };
         }
         else if (category === "bridge") {
@@ -774,16 +776,6 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 relatedCommands: ["perp account positions", "perp portfolio"],
             };
         }
-        else if (category === "alert") {
-            explanation = {
-                command,
-                description: { add: "Add a price, funding rate, PnL, or liquidation alert", list: "List all active alerts", remove: "Remove an alert by ID", daemon: "Start the alert monitoring daemon", test: "Send a test alert notification", config: "Configure alert notification channels (Telegram, Discord)" }[sub] || `Alert command: ${sub}`,
-                parameters: [],
-                risks: [],
-                category: "read",
-                relatedCommands: ["perp risk status", "perp risk limits"],
-            };
-        }
         else if (category === "bot" || category === "run") {
             explanation = {
                 command,
@@ -797,9 +789,9 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
         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", perf: "Performance breakdown (daily/weekly/summary)" }[sub] || `History: ${sub}`,
+                description: { list: "Execution audit trail", stats: "Execution statistics", positions: "Position history", summary: "Trading performance summary", pnl: "P&L breakdown by symbol and time period", funding: "Funding payment history and totals", report: "Detailed performance report", snapshot: "Portfolio snapshot", track: "Track position over time", perf: "Performance breakdown (daily/weekly/summary)", prune: "Prune old execution records" }[sub] || `History: ${sub}`,
                 parameters: [],
-                risks: [],
+                risks: sub === "prune" ? ["Permanently removes old execution records"] : [],
                 category: "read",
                 relatedCommands: ["perp history summary", "perp history list"],
             };
@@ -807,21 +799,11 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
         else if (category === "wallet") {
             explanation = {
                 command,
-                description: { list: "List configured wallets", balance: "Check on-chain USDC/SOL/ETH balances", generate: "Generate a new wallet keypair", use: "Set active wallet" }[sub] || `Wallet: ${sub}`,
+                description: { show: "Show configured wallets with public addresses", list: "List configured wallets", balance: "Check on-chain USDC/SOL/ETH balances", generate: "Generate a new wallet keypair", import: "Import an existing private key", set: "Set private key for an exchange", use: "Set active wallet", remove: "Remove a wallet", rename: "Rename a wallet" }[sub] || `Wallet: ${sub}`,
                 parameters: [],
-                risks: sub === "generate" ? ["Store the private key securely — it cannot be recovered"] : [],
+                risks: sub === "generate" ? ["Store the private key securely — it cannot be recovered"] : sub === "remove" ? ["Wallet will be removed — ensure you have the private key backed up"] : [],
                 category: "read",
-                relatedCommands: ["perp wallet list", "perp wallet balance"],
-            };
-        }
-        else if (category === "gap") {
-            explanation = {
-                command,
-                description: { show: "Shows cross-exchange price gaps for all symbols", watch: "Live monitor for price gaps above threshold", track: "Track gap history", alert: "Alert when gaps exceed threshold" }[sub] || `Gap analysis: ${sub}`,
-                parameters: [],
-                risks: [],
-                category: "analysis",
-                relatedCommands: ["perp gap show", "perp arb scan"],
+                relatedCommands: ["perp wallet show", "perp wallet balance"],
             };
         }
         else if (category === "backtest") {
@@ -976,7 +958,8 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     orders: { usage: "perp account orders", description: "Open/pending orders" },
                     history: { usage: "perp account history", description: "Order history" },
                     trades: { usage: "perp account trades", description: "Trade fill history" },
-                    "funding-history": { usage: "perp account funding-history", description: "Funding payments" },
+                    "funding-history|funding": { usage: "perp account funding-history", description: "Funding payments" },
+                    "twap-orders": { usage: "perp account twap-orders", description: "Active TWAP orders" },
                     pnl: { usage: "perp account pnl", description: "Profit & loss" },
                     margin: { usage: "perp account margin <symbol>", description: "Position margin info" },
                     settings: { usage: "perp account settings", description: "Account settings (leverage per symbol)" },
@@ -1007,19 +990,23 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     fills: { usage: "perp trade fills [symbol]", description: "Recent fills" },
                     status: { usage: "perp trade status <orderId>", description: "Check order status" },
                     "pnl-track": { usage: "perp trade pnl-track", description: "Real-time PnL tracker" },
+                    split: { usage: "perp trade split <symbol> <side> <usd>", description: "Split large order into depth-based slices" },
+                    multi: { usage: "perp trade multi <legs...>", description: "Execute multi-leg orders (exchange:symbol:side:size)" },
+                    "cancel-stop": { usage: "perp trade cancel-stop <symbol> <stopOrderId>", description: "Cancel a stop order" },
+                    "cancel-twap": { usage: "perp trade cancel-twap <symbol> <twapOrderId>", description: "Cancel a TWAP order" },
                 },
             },
             arb: {
                 description: "Funding rate arbitrage & basis trading",
                 subcommands: {
-                    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" },
-                    auto: { usage: "perp arb auto --min-spread <bps>", description: "Auto-execute funding arb" },
+                    scan: { usage: "perp arb scan --min <pct>", description: "Find arb opportunities (use --rates, --gaps, --hip3, --positions, --basis, --compare, --history, --live)" },
+                    auto: { usage: "perp arb auto --min-spread <pct>", description: "Auto-execute funding arb" },
+                    exec: { usage: "perp arb exec <symbol> <longEx> <shortEx> <size>", description: "Execute arb trade on two exchanges" },
                     status: { usage: "perp arb status", description: "Current arb positions" },
                     close: { usage: "perp arb close <symbol>", description: "Close arb position" },
-                    history: { usage: "perp arb history", description: "Arb execution history" },
+                    "history|log": { usage: "perp arb history", description: "Arb execution history" },
+                    config: { usage: "perp arb config", description: "View/edit arb configuration" },
+                    rebalance: { usage: "perp arb rebalance", description: "Rebalance funds across exchanges for arb" },
                 },
             },
             risk: {
@@ -1043,32 +1030,48 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
             bot: {
                 description: "Automated trading bots",
                 subcommands: {
+                    start: { usage: "perp bot start <config>", description: "Start bot from config file" },
                     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" },
+                    "funding-arb": { usage: "perp bot funding-arb", description: "Funding arb 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 available bot presets" },
+                    preset: { usage: "perp bot preset <name> [symbol]", description: "Run a bot preset" },
+                    example: { usage: "perp bot example", description: "Show example bot config" },
                 },
             },
             wallet: {
                 description: "Wallet management",
                 subcommands: {
+                    show: { usage: "perp wallet show", description: "Show configured wallets with public addresses" },
                     list: { usage: "perp wallet list", description: "List wallets" },
-                    balance: { usage: "perp wallet balance", description: "On-chain balances" },
+                    balance: { usage: "perp wallet balance [name]", description: "On-chain balances" },
                     generate: { usage: "perp wallet generate solana|evm", description: "Generate new wallet" },
+                    import: { usage: "perp wallet import solana|evm <privateKey>", description: "Import existing private key" },
+                    set: { usage: "perp wallet set <exchange> <key>", description: "Set private key for exchange" },
+                    use: { usage: "perp wallet use <name> [exchange]", description: "Set active wallet" },
+                    remove: { usage: "perp wallet remove <name>", description: "Remove a wallet" },
+                    rename: { usage: "perp wallet rename <oldName> <newName>", description: "Rename a wallet" },
                 },
             },
             history: {
                 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" },
                     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" },
+                    snapshot: { usage: "perp history snapshot", description: "Portfolio snapshot" },
+                    track: { usage: "perp history track", description: "Track position over time" },
                     perf: { usage: "perp history perf --period daily|weekly|summary", description: "Performance breakdown" },
+                    prune: { usage: "perp history prune", description: "Prune old execution records" },
                 },
             },
             backtest: {

package/package.json

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