perp-cli 0.4.2 → 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/signer/evm-local.d.ts

@@ -0,0 +1,12 @@
+import type { EvmSigner } from "./interface.js";
+export declare class LocalEvmSigner implements EvmSigner {
+    private _wallet;
+    private constructor();
+    static create(privateKey: string): Promise<LocalEvmSigner>;
+    getAddress(): string;
+    signTypedData(domain: Record<string, unknown>, types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>, value: Record<string, unknown>): Promise<string>;
+    signMessage(message: string | Uint8Array): Promise<string>;
+}

package/dist/signer/evm-local.js

@@ -0,0 +1,19 @@
+export class LocalEvmSigner {
+    _wallet;
+    constructor() { }
+    static async create(privateKey) {
+        const { ethers } = await import("ethers");
+        const signer = new LocalEvmSigner();
+        signer._wallet = new ethers.Wallet(privateKey);
+        return signer;
+    }
+    getAddress() {
+        return this._wallet.address;
+    }
+    async signTypedData(domain, types, value) {
+        return this._wallet.signTypedData(domain, types, value);
+    }
+    async signMessage(message) {
+        return this._wallet.signMessage(message);
+    }
+}

package/dist/signer/index.d.ts

@@ -0,0 +1,3 @@
+export type { EvmSigner, SolanaSigner } from "./interface.js";
+export { LocalEvmSigner } from "./evm-local.js";
+export { LocalSolanaSigner } from "./solana-local.js";

package/dist/signer/index.js

@@ -0,0 +1,2 @@
+export { LocalEvmSigner } from "./evm-local.js";
+export { LocalSolanaSigner } from "./solana-local.js";

package/dist/signer/interface.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Signer interfaces for exchange adapters.
+ *
+ * Separates signing logic from adapters so it can be injected
+ * (e.g., HSM, hardware wallet, delegated signing).
+ */
+/** EVM signer (Hyperliquid + Lighter L1) */
+export interface EvmSigner {
+    getAddress(): string;
+    /** EIP-712 typed data signing — returns flat hex signature (0x...) */
+    signTypedData(domain: Record<string, unknown>, types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>, value: Record<string, unknown>): Promise<string>;
+    /** EIP-191 personal message signing — returns hex signature */
+    signMessage(message: string | Uint8Array): Promise<string>;
+}
+/** Solana signer (Pacifica) */
+export interface SolanaSigner {
+    getPublicKeyBase58(): string;
+    /** Ed25519 detached signature */
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+    /** Sign a Solana transaction (full sign) */
+    signTransaction(tx: {
+        sign(keypair: unknown): void;
+    }): void;
+    /** Partially sign a Solana transaction */
+    partialSignTransaction(tx: {
+        partialSign(keypair: unknown): void;
+    }): void;
+}

package/dist/signer/interface.js

@@ -0,0 +1,7 @@
+/**
+ * Signer interfaces for exchange adapters.
+ *
+ * Separates signing logic from adapters so it can be injected
+ * (e.g., HSM, hardware wallet, delegated signing).
+ */
+export {};

package/dist/signer/solana-local.d.ts

@@ -0,0 +1,13 @@
+import type { SolanaSigner } from "./interface.js";
+export declare class LocalSolanaSigner implements SolanaSigner {
+    private _keypair;
+    constructor(keypair: import("@solana/web3.js").Keypair);
+    getPublicKeyBase58(): string;
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+    signTransaction(tx: {
+        sign(keypair: unknown): void;
+    }): void;
+    partialSignTransaction(tx: {
+        partialSign(keypair: unknown): void;
+    }): void;
+}

package/dist/signer/solana-local.js

@@ -0,0 +1,19 @@
+export class LocalSolanaSigner {
+    _keypair;
+    constructor(keypair) {
+        this._keypair = keypair;
+    }
+    getPublicKeyBase58() {
+        return this._keypair.publicKey.toBase58();
+    }
+    async signMessage(message) {
+        const nacl = await import("tweetnacl");
+        return nacl.default.sign.detached(message, this._keypair.secretKey);
+    }
+    signTransaction(tx) {
+        tx.sign(this._keypair);
+    }
+    partialSignTransaction(tx) {
+        tx.partialSign(this._keypair);
+    }
+}

package/dist/smart-order.js

@@ -30,15 +30,26 @@ function inferTickSize(levels) {
         return decimals > 0 ? Math.pow(10, -decimals) : 1;
     }
     // Use minimum difference between adjacent price levels
+    // Determine max decimal places from the orderbook to round away float noise
+    let maxDecimals = 0;
+    for (let i = 0; i < Math.min(levels.length, 5); i++) {
+        const p = levels[i][0];
+        const d = p.includes(".") ? p.split(".")[1].length : 0;
+        if (d > maxDecimals)
+            maxDecimals = d;
+    }
     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;
+    if (minDiff === Infinity) {
+        return Math.pow(10, -maxDecimals);
+    }
+    // Round to orderbook precision to eliminate floating-point noise
+    // e.g., 0.10000000000000142 → 0.1
+    return Number(minDiff.toFixed(maxDecimals));
 }
 /**
  * Get price precision (decimal places) from a price string.

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/dist/utils.js

@@ -107,7 +107,13 @@ export function printJson(data) {
         const fields = process.argv[fieldsArg + 1].split(",").map(f => f.trim());
         const envelope = output;
         if (envelope.ok && envelope.data && typeof envelope.data === "object") {
-            envelope.data = pickFields(envelope.data, fields);
+            // If data is an array, apply pickFields to each element
+            if (Array.isArray(envelope.data)) {
+                envelope.data = envelope.data.map((item) => pickFields(item, fields));
+            }
+            else {
+                envelope.data = pickFields(envelope.data, fields);
+            }
         }
         output = envelope;
     }