perp-cli 0.4.2 → 0.4.9

package/dist/ws/market-feed.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Unified market data feeds for CLI streaming commands.
+ *
+ * - Hyperliquid: native WebSocket (allMids, l2Book, trades, candle)
+ * - Lighter: REST polling (no public market data WS)
+ * - Pacifica: handled via existing PacificaWSClient in stream.ts
+ */
+import { EventEmitter } from "events";
+export interface PriceUpdate {
+    symbol: string;
+    mid: number;
+    funding?: number;
+}
+export interface BookUpdate {
+    bids: [string, string][];
+    asks: [string, string][];
+}
+export interface TradeUpdate {
+    side: string;
+    price: string;
+    size: string;
+    time: number;
+}
+export interface CandleUpdate {
+    o: string;
+    h: string;
+    l: string;
+    c: string;
+    v: string;
+    t: number;
+}
+export declare class HyperliquidMarketFeed extends EventEmitter {
+    private ws;
+    private closed;
+    private reconnectTimer;
+    private subs;
+    get wsUrl(): string;
+    connect(): Promise<void>;
+    private send;
+    private sub;
+    private scheduleReconnect;
+    subscribePrices(): void;
+    subscribeBook(symbol: string): void;
+    subscribeTrades(symbol: string): void;
+    subscribeCandle(symbol: string, interval: string): void;
+    private handleMessage;
+    close(): void;
+}
+export interface LighterFeedOpts {
+    /** Polling interval for prices in ms (default: 3000) */
+    pricesIntervalMs?: number;
+    /** Polling interval for book/trades in ms (default: 2000) */
+    bookIntervalMs?: number;
+    /** Polling interval for candles in ms (default: 5000) */
+    candleIntervalMs?: number;
+}
+export declare class LighterMarketFeed extends EventEmitter {
+    private closed;
+    private timers;
+    private marketMap;
+    private pricesMs;
+    private bookMs;
+    private candleMs;
+    constructor(opts?: LighterFeedOpts);
+    connect(): Promise<void>;
+    private getMarketId;
+    private poll;
+    subscribePrices(): void;
+    subscribeBook(symbol: string): void;
+    subscribeTrades(symbol: string): void;
+    subscribeCandle(symbol: string, interval: string): void;
+    close(): void;
+}
+export declare function createMarketFeed(exchange: string): HyperliquidMarketFeed | LighterMarketFeed;

package/dist/ws/market-feed.js

@@ -0,0 +1,227 @@
+/**
+ * Unified market data feeds for CLI streaming commands.
+ *
+ * - Hyperliquid: native WebSocket (allMids, l2Book, trades, candle)
+ * - Lighter: REST polling (no public market data WS)
+ * - Pacifica: handled via existing PacificaWSClient in stream.ts
+ */
+import { EventEmitter } from "events";
+// ── Hyperliquid Market Feed (native WebSocket) ──
+export class HyperliquidMarketFeed extends EventEmitter {
+    ws = null;
+    closed = false;
+    reconnectTimer = null;
+    subs = [];
+    get wsUrl() { return "wss://api.hyperliquid.xyz/ws"; }
+    async connect() {
+        const { WebSocket } = await import("ws");
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(this.wsUrl);
+            this.ws.on("open", () => {
+                // Re-subscribe on reconnect
+                for (const sub of this.subs)
+                    this.send({ method: "subscribe", subscription: sub });
+                this.emit("connected");
+                resolve();
+            });
+            this.ws.on("error", (err) => {
+                if (!this.closed)
+                    reject(err);
+            });
+            this.ws.on("close", () => {
+                if (!this.closed) {
+                    this.emit("disconnected");
+                    this.scheduleReconnect();
+                }
+            });
+            this.ws.on("message", (raw) => {
+                try {
+                    this.handleMessage(JSON.parse(String(raw)));
+                }
+                catch { /* ignore */ }
+            });
+        });
+    }
+    send(data) {
+        if (this.ws?.readyState === 1)
+            this.ws.send(JSON.stringify(data));
+    }
+    sub(subscription) {
+        this.subs.push(subscription);
+        this.send({ method: "subscribe", subscription });
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        this.reconnectTimer = setTimeout(async () => {
+            try {
+                await this.connect();
+            }
+            catch {
+                this.scheduleReconnect();
+            }
+        }, 3000);
+    }
+    subscribePrices() { this.sub({ type: "allMids" }); }
+    subscribeBook(symbol) { this.sub({ type: "l2Book", coin: symbol.toUpperCase() }); }
+    subscribeTrades(symbol) { this.sub({ type: "trades", coin: symbol.toUpperCase() }); }
+    subscribeCandle(symbol, interval) {
+        this.sub({ type: "candle", coin: symbol.toUpperCase(), interval });
+    }
+    handleMessage(msg) {
+        const channel = String(msg.channel ?? "");
+        const data = msg.data;
+        if (!data)
+            return;
+        if (channel === "allMids") {
+            const mids = (data.mids ?? data);
+            const updates = Object.entries(mids).map(([symbol, mid]) => ({
+                symbol, mid: Number(mid),
+            }));
+            this.emit("prices", updates);
+        }
+        else if (channel === "l2Book") {
+            const d = data;
+            const levels = d.levels;
+            if (levels) {
+                this.emit("book", {
+                    bids: levels[0].map((l) => [l.px, l.sz]),
+                    asks: levels[1].map((l) => [l.px, l.sz]),
+                });
+            }
+        }
+        else if (channel === "trades") {
+            const trades = Array.isArray(data) ? data : [];
+            for (const t of trades) {
+                // HL side: "A" = sell (ask), "B" = buy (bid)
+                const rawSide = String(t.side ?? "");
+                this.emit("trade", {
+                    side: rawSide === "A" ? "sell" : rawSide === "B" ? "buy" : rawSide,
+                    price: String(t.px ?? ""),
+                    size: String(t.sz ?? ""),
+                    time: Number(t.time ?? Date.now()),
+                });
+            }
+        }
+        else if (channel === "candle") {
+            const d = data;
+            this.emit("candle", {
+                o: String(d.o ?? ""), h: String(d.h ?? ""), l: String(d.l ?? ""),
+                c: String(d.c ?? ""), v: String(d.v ?? ""), t: Number(d.t ?? 0),
+            });
+        }
+    }
+    close() {
+        this.closed = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+}
+// ── Lighter Market Feed (REST polling) ──
+const LIGHTER_BASE = "https://mainnet.zklighter.elliot.ai/api/v1";
+export class LighterMarketFeed extends EventEmitter {
+    closed = false;
+    timers = [];
+    marketMap = new Map();
+    pricesMs;
+    bookMs;
+    candleMs;
+    constructor(opts) {
+        super();
+        this.pricesMs = opts?.pricesIntervalMs ?? 3000;
+        this.bookMs = opts?.bookIntervalMs ?? 2000;
+        this.candleMs = opts?.candleIntervalMs ?? 5000;
+    }
+    async connect() {
+        const res = await fetch(`${LIGHTER_BASE}/orderBookDetails`);
+        const json = await res.json();
+        for (const m of json.order_book_details ?? []) {
+            if (m.market_type === "perp")
+                this.marketMap.set(m.symbol.toUpperCase(), m.market_id);
+        }
+        this.emit("connected");
+    }
+    getMarketId(symbol) {
+        const id = this.marketMap.get(symbol.toUpperCase());
+        if (id === undefined)
+            throw new Error(`Unknown Lighter market: ${symbol}`);
+        return id;
+    }
+    poll(fn, intervalMs) {
+        fn().catch(() => { });
+        this.timers.push(setInterval(() => { if (!this.closed)
+            fn().catch(() => { }); }, intervalMs));
+    }
+    subscribePrices() {
+        this.poll(async () => {
+            const res = await fetch(`${LIGHTER_BASE}/orderBookDetails`);
+            const json = await res.json();
+            const updates = (json.order_book_details ?? [])
+                .filter(m => m.market_type === "perp")
+                .map(m => ({ symbol: m.symbol, mid: m.last_trade_price }));
+            this.emit("prices", updates);
+        }, this.pricesMs);
+    }
+    subscribeBook(symbol) {
+        const marketId = this.getMarketId(symbol);
+        this.poll(async () => {
+            const res = await fetch(`${LIGHTER_BASE}/orderBookOrders?market_id=${marketId}&limit=20`);
+            const json = await res.json();
+            this.emit("book", {
+                bids: (json.bids ?? []).map(b => [b.price, b.remaining_base_amount]),
+                asks: (json.asks ?? []).map(a => [a.price, a.remaining_base_amount]),
+            });
+        }, this.bookMs);
+    }
+    subscribeTrades(symbol) {
+        const marketId = this.getMarketId(symbol);
+        let lastTid = 0;
+        this.poll(async () => {
+            const res = await fetch(`${LIGHTER_BASE}/recentTrades?market_id=${marketId}&limit=20`);
+            const json = await res.json();
+            for (const t of json.trades ?? []) {
+                if (t.timestamp > lastTid) {
+                    lastTid = t.timestamp;
+                    this.emit("trade", {
+                        side: t.is_maker_ask ? "buy" : "sell",
+                        price: t.price,
+                        size: t.size,
+                        time: t.timestamp,
+                    });
+                }
+            }
+        }, this.bookMs);
+    }
+    subscribeCandle(symbol, interval) {
+        const marketId = this.getMarketId(symbol);
+        this.poll(async () => {
+            const now = Math.floor(Date.now() / 1000);
+            const res = await fetch(`${LIGHTER_BASE}/candles?market_id=${marketId}&resolution=${interval}&count_back=1&end_timestamp=${now}`);
+            const json = await res.json();
+            const c = json.candles?.[0];
+            if (c) {
+                this.emit("candle", {
+                    o: c.open, h: c.high, l: c.low, c: c.close, v: c.volume, t: c.timestamp,
+                });
+            }
+        }, this.candleMs);
+    }
+    close() {
+        this.closed = true;
+        for (const t of this.timers)
+            clearInterval(t);
+        this.timers = [];
+    }
+}
+// ── Factory ──
+export function createMarketFeed(exchange) {
+    if (exchange === "hyperliquid")
+        return new HyperliquidMarketFeed();
+    if (exchange === "lighter")
+        return new LighterMarketFeed();
+    throw new Error(`Use PacificaWSClient for pacifica, not createMarketFeed`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.4.2",
+  "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, bridge USDC, manage positions, scan arbitrage opportunities, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, or Lighter exchanges."
+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:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.4.2"
+  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,11 +98,17 @@ 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).
 
-## Arb Workflow
+## Arb Workflow (Perp-Perp)
 
 ```
 1. perp --json portfolio                    → check balances across all exchanges
@@ -119,6 +127,39 @@ All string outputs are auto-sanitized (control chars stripped, prompt injection
    → --pair <longEx>:<shortEx>: specify which pair if multiple
 ```
 
+## Spot+Perp Arb Workflow
+
+Spot has 0 funding cost → spread = |perp funding rate|. Only needs 1 exchange with spot + any exchange with perp.
+
+**Spot exchanges:** HL (Hyperliquid), LT (Lighter). Pacifica is perp-only.
+**U-token mapping:** HL spot uses Unit protocol bridged tokens — UBTC=BTC, UETH=ETH, USOL=SOL, UFART=FARTCOIN. Resolved automatically.
+
+```
+1. perp --json arb scan --mode spot-perp    → find spot+perp opportunities
+   perp --json arb scan --mode all          → perp-perp + spot-perp combined
+2. [Show opportunity to user, get confirmation]
+3. perp --json arb spot-exec <SYM> <spotEx> <perpEx> <$>
+   Examples:
+     perp --json arb spot-exec ETH hl hl 100        # ETH spot(HL/UETH) + perp(HL)
+     perp --json arb spot-exec BTC hl lt 50          # BTC spot(HL/UBTC) + perp(LT)
+     perp --json arb spot-exec LINK lt hl 100        # LINK spot(LT) + perp(HL)
+   → cross-validates spot vs perp price (>5% deviation = abort, wrong token)
+   → sequential execution if same exchange (nonce collision avoidance)
+   → parallel execution if different exchanges
+   → auto-rollback if one leg fails
+   Options:
+     --leverage <N>   set perp leverage before entry
+     --isolated       use isolated margin on perp side
+4. perp --json arb status                   → shows spot-perp positions (spot leg labeled)
+5. perp --json arb spot-close <SYM> --spot-exch <hl|lt>
+   → sells spot + buys back perp simultaneously
+```
+
+**Available spot+perp pairs (13):**
+- HL spot: BTC (UBTC), ETH (UETH), SOL (USOL), FARTCOIN (UFART), HYPE, AZTEC, STABLE
+- LT spot: ETH, AZTEC, AAVE, LINK, UNI, LIT, LDO, SKY
+- All have perps on HL and LT. Pacifica perps available when API is up.
+
 ## Position Sizing
 
 - Single position < **80%** of that exchange's available balance
@@ -165,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 |
@@ -175,6 +216,41 @@ 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
+
+**User: "펀딩레이트 아비트라지 기회 찾아줘"**
+```bash
+perp --json portfolio                         # check balances
+perp --json arb scan --mode all --min 5       # scan perp-perp + spot-perp
+# → show results, recommend best opportunity, ask for confirmation
+```
+
+**User: "ETH spot-perp 아비트라지 실행해줘 $100"**
+```bash
+perp --json arb scan --mode spot-perp         # verify opportunity exists
+perp --json --dry-run arb spot-exec ETH hl hl 100  # dry-run first
+# → show dry-run result, ask for confirmation
+perp --json arb spot-exec ETH hl hl 100       # execute after confirmation
+perp --json arb status                        # verify positions
+```
+
+**User: "내 포지션 상태 확인해줘"**
+```bash
+perp --json portfolio                         # balances + positions + risk
+perp --json arb status                        # arb-specific PnL + funding
+```
+
+**User: "Hyperliquid에서 SOL 롱 0.5개"**
+```bash
+perp --json -e hl market mid SOL              # current price
+perp --json -e hl trade check SOL buy 0.5     # pre-validate
+perp --json --dry-run -e hl trade market SOL buy 0.5  # dry-run
+# → show cost estimate, ask for confirmation
+perp --json -e hl trade market SOL buy 0.5 --smart    # execute with smart order
+```
 
 ## Referrals (Optional)
 

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.
 

package/skills/perp-cli/references/commands.md

@@ -7,16 +7,17 @@ All commands support `--json` for structured output. Always use `--json` when ca
 perp --json market list                    # all markets with prices, funding, volume
 perp --json market prices                  # cross-exchange price comparison
 perp --json market mid <SYMBOL>            # mid price (fast)
-perp --json market info <SYMBOL>           # tick size, min order, max leverage
+perp --json market info <SYMBOL>           # mark/index price, funding, volume, OI, max leverage
 perp --json market book <SYMBOL>           # orderbook (bids/asks)
 perp --json market trades <SYMBOL>         # recent trades
 perp --json market funding <SYMBOL>        # funding rate history
 perp --json market kline <SYM> <INTERVAL>  # OHLCV candles (1m,5m,15m,1h,4h,1d)
+perp --json market hip3                    # list HIP-3 deployed perp dexes (Hyperliquid only)
 ```
 
 ## Account (read-only, safe)
 ```bash
-perp --json account info                   # balance, equity, margin, PnL
+perp --json account balance                # perp balance + spot holdings + 24h funding (alias: account info)
 perp --json account positions              # open positions
 perp --json account orders                 # open/pending orders
 perp --json account history                # order history
@@ -24,7 +25,6 @@ perp --json account trades                 # trade fill history
 perp --json account funding-history        # funding payments
 perp --json account pnl                    # profit & loss
 perp --json account margin <SYMBOL>        # position margin info
-perp --json status                         # combined: balance + positions + orders
 perp --json portfolio                      # cross-exchange unified view
 ```
 
@@ -60,22 +60,29 @@ perp --json trade leverage <SYMBOL> <N>     # set leverage
 # Advanced orders
 perp --json trade scale-tp <SYMBOL> --levels '<PRICE1>:<PCT>,<PRICE2>:<PCT>'
 perp --json trade scale-in <SYMBOL> <SIDE> --levels '<PRICE1>:<SIZE>,<PRICE2>:<SIZE>'
-perp --json trade trailing-stop <SYMBOL>    # trailing stop with callback %
-perp --json trade twap <SYMBOL> <SIDE> <SIZE> <DURATION>
 perp --json trade pnl-track                 # real-time PnL tracker
+
+# Split execution (orderbook-aware)
+perp --json trade split <SYMBOL> <buy|sell> <USD>   # split large order into depth-based slices
+perp --json trade split <SYM> buy 5000 --max-slippage 0.5 --max-slices 5 --delay 2000 --min-slice 200
+perp --json trade market <SYM> buy <SIZE> --split   # split via market command flag
+perp --json trade market <SYM> buy <SIZE> --split --max-slippage 0.5
 ```
 
-## Deposit & Withdraw
+## Funds (Deposit, Withdraw, Transfer, Bridge)
 ```bash
-perp --json deposit pacifica <AMOUNT>
-perp --json deposit hyperliquid <AMOUNT>
-perp --json deposit lighter ethereum <AMOUNT>         # L1 direct (min 1 USDC)
-perp --json deposit lighter cctp arbitrum <AMOUNT>    # CCTP (min 5 USDC)
-perp --json deposit lighter info                      # all Lighter deposit routes
-perp --json withdraw pacifica <AMOUNT>
-perp --json withdraw hyperliquid <AMOUNT>
-perp --json deposit info                    # deposit instructions
-perp --json withdraw info                   # withdrawal instructions
+perp --json funds deposit pacifica <AMOUNT>
+perp --json funds deposit hyperliquid <AMOUNT>
+perp --json funds deposit lighter ethereum <AMOUNT>         # L1 direct (min 1 USDC)
+perp --json funds deposit lighter cctp arbitrum <AMOUNT>    # CCTP (min 5 USDC)
+perp --json funds deposit lighter info                      # all Lighter deposit routes
+perp --json funds withdraw pacifica <AMOUNT>
+perp --json funds withdraw hyperliquid <AMOUNT>
+perp --json funds withdraw lighter <AMOUNT>
+perp --json funds transfer <AMOUNT> <ADDRESS>     # HL internal transfer (instant)
+perp --json funds bridge --from <CHAIN> --to <CHAIN> --amount <AMT> --recipient <ADDR>  # CCTP bridge
+perp --json funds bridge-status --hash <HASH>     # check CCTP bridge status
+perp --json funds info                            # combined deposit & withdrawal info
 ```
 
 ## Bridge (Cross-chain USDC)
@@ -89,11 +96,26 @@ perp --json bridge status <ORDER_ID>
 
 ## Arbitrage
 ```bash
+# Perp-Perp arb
 perp --json arb scan --min <BPS>            # find opportunities (>N bps spread) — PRIMARY command
-perp --json arb funding                     # detailed funding analysis
+perp --json arb exec <SYM> <longEx> <shortEx> <$>  # execute perp-perp arb
+perp --json arb close <SYM>                 # close perp-perp arb
+perp --json arb status                      # monitor open arb positions
+perp --json arb funding-earned              # actual funding payments
+
+# Spot+Perp arb (spot funding = 0, spread = |perp funding|)
+perp --json arb scan --mode spot-perp       # scan spot+perp opportunities
+perp --json arb scan --mode all             # both perp-perp + spot-perp
+perp --json arb spot-exec <SYM> <spotEx> <perpEx> <$>  # execute spot+perp arb
+perp --json arb spot-close <SYM> --spot-exch <hl|lt>   # close spot+perp arb
+# spotEx: hl (Hyperliquid) or lt (Lighter). perpEx: hl, lt, pac.
+# HL spot uses U-tokens: BTC→UBTC, ETH→UETH, SOL→USOL (auto-resolved)
+
+# Other arb tools
+perp --json arb rates                       # funding rates across all DEXs (detailed)
+perp --json arb prices                      # cross-exchange price gaps
 perp --json arb dex                         # HIP-3 cross-dex arb (Hyperliquid)
-perp --json gap show                        # cross-exchange price gaps
-# NOTE: 'arb rates' is deprecated — use 'arb scan' instead
+# Deprecated: 'gap show' → use 'arb prices'; 'funding rates/spread' → use 'arb rates/scan'
 ```
 
 ## Wallet Management
@@ -115,30 +137,30 @@ perp --json risk liquidation-distance       # % distance from liquidation for AL
 perp --json risk limits                     # view current risk limits
 perp --json risk limits --min-liq-distance 30 --max-leverage 5  # set risk limits
 perp --json risk check --notional 1000 --leverage 3  # pre-trade risk check
-perp --json health                          # exchange connectivity & latency
-perp --json analytics summary              # trading performance
-perp --json analytics pnl                   # P&L breakdown
+perp --json agent ping                      # exchange connectivity & latency
+perp --json history summary                 # trading performance
+perp --json history pnl                     # P&L breakdown by exchange
+perp --json history funding                 # funding payment aggregation
+perp --json history report                  # full performance report (summary + pnl + funding)
+perp --json history perf --period daily     # daily PnL breakdown (replaces daily-pnl)
+perp --json history perf --period weekly    # weekly PnL breakdown (replaces weekly-pnl)
+perp --json history perf --period summary   # performance summary stats
 perp --json history list                    # execution audit trail
 ```
 
-## Automated Strategies
+## Automated Strategies (bot)
 ```bash
-perp --json run grid <SYMBOL> --range <PCT> --grids <N> --size <USD>
-perp --json run dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL>
-perp --json run funding-arb                 # auto funding arb
+perp --json bot twap <SYMBOL> <SIDE> <SIZE> <DURATION>    # TWAP execution
+perp --json bot grid <SYMBOL> --range <PCT> --grids <N> --size <USD>
+perp --json bot dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL>
+perp --json bot trailing-stop <SYMBOL>      # trailing stop with callback %
+perp --json bot funding-arb                 # auto funding arb
 perp --json bot quick-grid <SYMBOL>         # quick grid bot
 perp --json bot quick-arb                   # quick arb bot
 perp --json jobs list                       # list running jobs
 perp --json jobs stop <ID>                  # stop a job
 ```
 
-## Alerts
-```bash
-perp --json alert add                       # add price/funding/pnl/liquidation alert
-perp --json alert list                      # list active alerts
-perp --json alert remove <ID>              # remove alert
-```
-
 ## Command Discovery
 ```bash
 perp schema                       # Full CLI schema as JSON