perp-cli 0.4.0 → 0.4.2

package/dist/smart-order.d.ts

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

package/dist/smart-order.js

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

package/dist/trade-validator.js

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

package/package.json

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

package/skills/perp-cli/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.4.0"
+  version: "0.4.2"
 ---
 
 # perp-cli Agent Guide
@@ -59,7 +59,9 @@ perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage <N> --isolated  # e
 
 # Single exchange trading (when not doing arb)
 perp --json -e <EX> trade market <SYM> buy <SIZE>
+perp --json -e <EX> trade market <SYM> buy <SIZE> --smart  # IOC limit at best ask + 1 tick (less slippage)
 perp --json -e <EX> trade close <SYM>
+perp --json -e <EX> trade close <SYM> --smart              # smart close at best bid/ask
 
 # Risk (only if you need to set limits — portfolio already includes risk)
 perp --json risk limits --max-leverage 5
@@ -87,6 +89,13 @@ perp --json --ndjson -e <EX> market list
 
 # Prevent duplicate orders with client ID
 perp --json -e <EX> trade market <SYM> buy <SIZE> --client-id <UNIQUE_ID>
+
+# Smart order: IOC limit at best bid/ask + 1 tick instead of raw market order
+# Fills only at top-of-book price — no multi-level sweep slippage
+perp --json -e <EX> trade market <SYM> buy <SIZE> --smart
+perp --json -e <EX> trade close <SYM> --smart
+perp --json arb exec <SYM> <longEx> <shortEx> <$> --smart   # smart arb entry
+perp --json arb close <SYM> --smart                          # smart arb close
 ```
 
 All string outputs are auto-sanitized (control chars stripped, prompt injection patterns blocked).