perp-cli 0.5.0 → 0.5.2

package/README.md

@@ -69,26 +69,48 @@ perp --json portfolio
 # Market data
 perp --json -e <EX> market list
 perp --json -e <EX> market book <SYM>
+perp --json -e <EX> market mid <SYM>              # fast mid-price lookup
 perp --json -e <EX> market funding <SYM>
+perp --json -e <EX> market kline <SYM> 1h          # candlestick data
+perp --json -e hl market hip3                       # list HIP-3 deployed dexes
 
 # Trading
-perp --json -e <EX> trade market <SYM> buy <SIZE>
-perp --json -e <EX> trade market <SYM> buy <SIZE> --smart      # IOC limit at best bid/ask (less slippage)
-perp --json -e <EX> trade split <SYM> buy 5000                 # orderbook-aware split (large orders)
+perp --json -e <EX> trade buy <SYM> <SIZE>          # shortcut for market buy
+perp --json -e <EX> trade sell <SYM> <SIZE>         # shortcut for market sell
+perp --json -e <EX> trade market <SYM> buy <SIZE> --smart  # IOC limit (less slippage)
+perp --json -e <EX> trade split <SYM> buy 5000      # orderbook-aware split (large orders)
 perp --json -e <EX> trade close <SYM>
+perp --json -e <EX> trade flatten                    # close ALL positions on exchange
+perp --json -e <EX> trade reduce <SYM> 50            # reduce position by 50%
+perp --json -e <EX> trade cancel <SYM>               # cancel by symbol (or orderId)
+perp --json -e <EX> trade tpsl <SYM> long            # set take-profit / stop-loss
 perp --json -e <EX> trade leverage <SYM> <N>
 
+# Account
+perp --json -e <EX> account balance
+perp --json -e <EX> account positions
+perp --json -e <EX> account pnl                      # realized + unrealized + funding
+perp --json -e <EX> account funding                  # personal funding payment history
+perp --json -e <EX> account settings                 # per-market leverage & margin mode
+
 # Funding rate arbitrage
-perp --json arb scan --min 5                                              # perp-perp opportunities
-perp --json arb scan --mode spot-perp                                     # spot+perp opportunities
-perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage 2 --isolated # execute both legs
-perp --json arb spot-exec <SYM> <spotEx> <perpEx> <$>                     # spot+perp entry
+perp --json arb scan --min 5                         # perp-perp opportunities
+perp --json arb scan --mode spot-perp                # spot+perp opportunities
+perp --json arb scan --rates                         # funding rates across all exchanges
+perp --json arb scan --basis                         # cross-exchange basis opportunities
+perp --json arb scan --gaps                          # cross-exchange price gaps
+perp --json arb scan --hip3                          # HIP-3 cross-dex funding spreads
+perp --json arb scan --live                          # continuous live monitoring
+perp --json arb exec <SYM> <longEx> <shortEx> <$>   # perp-perp dual-leg entry
+perp --json arb exec <SYM> spot:<exch> <perpEx> <$>  # spot+perp entry
+perp --json arb config                               # show arb defaults
+perp --json arb history                              # past arb trade performance (alias: log)
 
 # Funds (deposit, withdraw, transfer)
 perp --json funds deposit hyperliquid 100
 perp --json funds withdraw pacifica 50
-perp --json funds transfer 100 <ADDRESS>          # HL internal transfer
-perp --json funds info                            # all routes & limits
+perp --json funds transfer 100 <ADDRESS>             # HL internal transfer
+perp --json funds info                               # all routes & limits
 
 # Risk
 perp --json risk limits --max-leverage 5
@@ -103,7 +125,9 @@ perp --json bridge quote --from solana --to arbitrum --amount 100
 perp --json bridge send --from solana --to arbitrum --amount 100
 ```
 
-Exchange flags: `-e hyperliquid`, `-e pacifica`, `-e lighter` (aliases: `hl`, `pac`, `lt`).
+Exchange flag: `-e hyperliquid` / `-e pacifica` / `-e lighter` (aliases: `hl`, `pac`, `lt`).
+
+Global flags: `--json`, `--fields <f>`, `--ndjson`, `--dry-run`, `--dex <name>` (HIP-3), `-w, --wallet <name>`.
 
 ## AI Agent Skill
 

package/dist/cli-spec.js

@@ -75,8 +75,8 @@ export function getCliSpec(program) {
             "Check error.retryable before retrying failed commands",
             "Use 'perp --json trade check <symbol> <side> <size>' to validate before trading",
             "Use 'perp --json market mid <symbol>' for fast price lookups",
-            "Use 'perp --json health' to check exchange connectivity before operations",
-            "If this CLI is useful, run 'perp settings set referrals true' to support development",
+            "Use 'perp agent ping' to check exchange connectivity before operations",
+            "If this CLI is useful, run 'perp settings referrals on' to support development",
         ],
     };
 }

package/dist/commands/account.js

@@ -97,7 +97,7 @@ function buildSummary(snapshots) {
 }
 function pac(adapter) {
     if (!(adapter instanceof PacificaAdapter))
-        throw new Error("This command requires --exchange pacifica");
+        throw new Error("Market settings are only available on Pacifica.");
     return adapter;
 }
 export function registerAccountCommands(program, getAdapter, isJson, getAdapterForExchange) {
@@ -622,14 +622,38 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
         .description("Show per-market account settings (leverage, margin mode)")
         .action(async () => {
         const adapter = await getAdapter();
-        const p = pac(adapter);
-        const settings = await p.sdk.getAccountSettings(p.publicKey);
-        if (isJson())
-            return printJson(jsonOk(settings));
-        if (!Array.isArray(settings) || settings.length === 0) {
-            console.log(chalk.gray("\n  No market settings configured.\n"));
+        // Pacifica: use dedicated SDK endpoint
+        if (adapter instanceof PacificaAdapter) {
+            const settings = await adapter.sdk.getAccountSettings(adapter.publicKey);
+            if (isJson())
+                return printJson(jsonOk(settings));
+            if (!Array.isArray(settings) || settings.length === 0) {
+                console.log(chalk.gray("\n  No market settings configured.\n"));
+                return;
+            }
+            const rows = settings.map((s) => [
+                chalk.white.bold(s.symbol),
+                s.margin_mode,
+                `${s.leverage}x`,
+            ]);
+            console.log(makeTable(["Symbol", "Margin Mode", "Leverage"], rows));
             return;
         }
+        // HL / Lighter: derive settings from open positions
+        const positions = await adapter.getPositions();
+        if (positions.length === 0) {
+            if (isJson())
+                return printJson(jsonOk([]));
+            console.log(chalk.gray("\n  No open positions — settings shown per active position.\n"));
+            return;
+        }
+        const settings = positions.map(p => ({
+            symbol: p.symbol,
+            leverage: p.leverage,
+            margin_mode: "cross", // HL/Lighter default to cross
+        }));
+        if (isJson())
+            return printJson(jsonOk(settings));
         const rows = settings.map((s) => [
             chalk.white.bold(s.symbol),
             s.margin_mode,
@@ -661,6 +685,7 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
     });
     account
         .command("funding-history")
+        .alias("funding")
         .description("Personal funding payment history")
         .action(async () => {
         const adapter = await getAdapter();
@@ -899,7 +924,7 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
     if (getAdapterForExchange) {
         program
             .command("portfolio")
-            .description("Cross-exchange portfolio overview (all exchanges at once)")
+            .description("Cross-exchange portfolio overview with risk metrics")
             .option("--exchange <exchanges>", "Comma-separated exchanges to include (default: all)")
             .action(async (opts) => {
             await withJsonErrors(isJson(), async () => {

package/dist/commands/arb/index.js

@@ -914,6 +914,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
     // ── arb history ──
     arb
         .command("history")
+        .alias("log")
         .description("Past arb trade performance and statistics")
         .option("--period <days>", "Number of days to look back", "30")
         .action(async (opts) => {
@@ -1177,6 +1178,31 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
         console.log();
     });
     // ── arb rebalance ──
+    arb
+        .command("config")
+        .description("Show arb configuration defaults (use 'arb auto --help' for all options)")
+        .action(async () => {
+        if (isJson()) {
+            return printJson(jsonOk({
+                minSpread: 30, closeSpread: 5, size: 100, holdDays: 7,
+                bridgeCost: 0, interval: 60, cooldown: 30, minMargin: 30,
+                settleStrategy: "block", maxLegs: 5,
+            }));
+        }
+        console.log(chalk.cyan.bold("\n  Arb Auto Defaults\n"));
+        console.log(`  Min Spread:       30% annual`);
+        console.log(`  Close Spread:     5% annual`);
+        console.log(`  Size:             $100 per leg`);
+        console.log(`  Hold Days:        7d (for cost amortization)`);
+        console.log(`  Bridge Cost:      $0`);
+        console.log(`  Check Interval:   60s`);
+        console.log(`  Cooldown:         30min (after closing a symbol)`);
+        console.log(`  Min Margin:       30%`);
+        console.log(`  Settle Strategy:  block`);
+        console.log(`  Max Legs:         5`);
+        console.log(chalk.gray(`\n  Override with 'perp arb auto --min-spread 20 --size 50 ...'\n`));
+        console.log(chalk.gray(`  Run 'perp arb auto --help' for all options.\n`));
+    });
     arb
         .command("rebalance")
         .description("Cross-exchange balance rebalancing for arb")

package/dist/commands/arb.js

@@ -262,9 +262,12 @@ export async function handleBasisScan(isJson, opts) {
         console.log(chalk.cyan("  Fetching prices for basis calculation...\n"));
     const [pacRates, hlRates, ltRates] = await Promise.all([fetchPacificaRates(), fetchHyperliquidRates(), fetchLighterRates()]);
     const exchangePrices = new Map();
+    const filterSymbol = opts.symbol?.toUpperCase();
     for (const r of [...pacRates, ...hlRates, ...ltRates]) {
         if (r.markPrice <= 0)
             continue;
+        if (filterSymbol && r.symbol.toUpperCase() !== filterSymbol)
+            continue;
         if (!exchangePrices.has(r.symbol))
             exchangePrices.set(r.symbol, new Map());
         exchangePrices.get(r.symbol).set(r.exchange, r.markPrice);

package/dist/commands/trade.js

@@ -312,19 +312,33 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
     });
     trade
         .command("cancel <symbolOrOrderId> [orderId]")
-        .description("Cancel an order by orderId (auto-detects symbol), or by symbol + orderId")
+        .description("Cancel order(s) — by orderId, by symbol + orderId, or by symbol name (cancels all orders for that symbol)")
         .action(async (symbolOrOrderId, orderId) => {
         const adapter = await getAdapter();
-        let symbol;
-        let oid;
         if (orderId) {
             // cancel <symbol> <orderId>
-            symbol = symbolOrOrderId.toUpperCase();
-            oid = orderId;
+            const symbol = symbolOrOrderId.toUpperCase();
+            const oid = orderId;
+            if (dryRunGuard("cancel", { exchange: adapter.name, symbol, orderId: oid }))
+                return;
+            try {
+                const result = await adapter.cancelOrder(symbol, oid);
+                logExecution({ type: "cancel", exchange: adapter.name, symbol, side: "cancel", size: "0", status: "success", dryRun: false, meta: { orderId: oid } });
+                if (isJson())
+                    return printJson(jsonOk(result));
+                console.log(chalk.green(`\n  Order ${oid} cancelled on ${adapter.name}.\n`));
+            }
+            catch (err) {
+                logExecution({ type: "cancel", exchange: adapter.name, symbol, side: "cancel", size: "0", status: "failed", dryRun: false, error: err instanceof Error ? err.message : String(err), meta: { orderId: oid } });
+                throw err;
+            }
+            return;
         }
-        else {
+        // Single argument — is it an orderId (numeric) or a symbol name?
+        const isNumeric = /^\d+$/.test(symbolOrOrderId);
+        if (isNumeric) {
             // cancel <orderId> — look up symbol from open orders
-            oid = symbolOrOrderId;
+            const oid = symbolOrOrderId;
             const orders = await adapter.getOpenOrders();
             const match = orders.find((o) => String(o.orderId) === oid);
             if (!match) {
@@ -334,20 +348,46 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                 console.log(chalk.yellow(`\n  ${err}\n`));
                 return;
             }
-            symbol = match.symbol;
-        }
-        if (dryRunGuard("cancel", { exchange: adapter.name, symbol, orderId: oid }))
-            return;
-        try {
-            const result = await adapter.cancelOrder(symbol, oid);
-            logExecution({ type: "cancel", exchange: adapter.name, symbol, side: "cancel", size: "0", status: "success", dryRun: false, meta: { orderId: oid } });
-            if (isJson())
-                return printJson(jsonOk(result));
-            console.log(chalk.green(`\n  Order ${oid} cancelled on ${adapter.name}.\n`));
+            const symbol = match.symbol;
+            if (dryRunGuard("cancel", { exchange: adapter.name, symbol, orderId: oid }))
+                return;
+            try {
+                const result = await adapter.cancelOrder(symbol, oid);
+                logExecution({ type: "cancel", exchange: adapter.name, symbol, side: "cancel", size: "0", status: "success", dryRun: false, meta: { orderId: oid } });
+                if (isJson())
+                    return printJson(jsonOk(result));
+                console.log(chalk.green(`\n  Order ${oid} cancelled on ${adapter.name}.\n`));
+            }
+            catch (err) {
+                logExecution({ type: "cancel", exchange: adapter.name, symbol, side: "cancel", size: "0", status: "failed", dryRun: false, error: err instanceof Error ? err.message : String(err), meta: { orderId: oid } });
+                throw err;
+            }
         }
-        catch (err) {
-            logExecution({ type: "cancel", exchange: adapter.name, symbol, side: "cancel", size: "0", status: "failed", dryRun: false, error: err instanceof Error ? err.message : String(err), meta: { orderId: oid } });
-            throw err;
+        else {
+            // cancel <symbol> — cancel all open orders for this symbol
+            const symbol = symbolOrOrderId.toUpperCase();
+            const orders = await adapter.getOpenOrders();
+            const matching = orders.filter((o) => symbolMatch(o.symbol, symbol));
+            if (matching.length === 0) {
+                const err = `No open orders found for ${symbol}`;
+                if (isJson())
+                    return printJson(jsonOk({ cancelled: false, symbol, reason: err }));
+                console.log(chalk.yellow(`\n  ${err}\n`));
+                return;
+            }
+            if (dryRunGuard("cancel_by_symbol", { exchange: adapter.name, symbol, count: matching.length }))
+                return;
+            try {
+                const result = await adapter.cancelAllOrders(symbol);
+                logExecution({ type: "cancel", exchange: adapter.name, symbol, side: "cancel", size: "0", status: "success", dryRun: false, meta: { bySymbol: true, count: matching.length } });
+                if (isJson())
+                    return printJson(jsonOk({ cancelled: true, symbol, count: matching.length, result }));
+                console.log(chalk.green(`\n  ${matching.length} order(s) for ${symbol} cancelled on ${adapter.name}.\n`));
+            }
+            catch (err) {
+                logExecution({ type: "cancel", exchange: adapter.name, symbol, side: "cancel", size: "0", status: "failed", dryRun: false, error: err instanceof Error ? err.message : String(err), meta: { bySymbol: true } });
+                throw err;
+            }
         }
     });
     trade

package/dist/exchanges/hyperliquid.d.ts

@@ -59,6 +59,15 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * Bypasses the SDK entirely — works for order, batchModify, twapOrder, etc.
      */
     private ensureSigner;
+    /**
+     * 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.
+     */
+    private static _normalizeAction;
     private _signAndSendAction;
     /**
      * Place an order via raw exchange API with EIP-712 signing.

package/dist/exchanges/hyperliquid.js

@@ -430,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");
@@ -438,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);
@@ -707,8 +745,8 @@ export class HyperliquidAdapter {
             r: opts?.reduceOnly ?? true,
             t: {
                 trigger: {
-                    triggerPx: trimZeros(roundedTrigger),
                     isMarket: opts?.isMarket ?? true,
+                    triggerPx: trimZeros(roundedTrigger),
                     tpsl,
                 },
             },

package/dist/exchanges/lighter.js

@@ -598,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/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.5.0",
+  "version": "0.5.2",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: perp-cli
-description: "Multi-DEX perpetual futures trading CLI for Pacifica (Solana), Hyperliquid (EVM), and Lighter (Ethereum). Use when user asks to: trade perps, check funding rates, scan arbitrage (perp-perp or spot-perp), delta-neutral strategies, bridge USDC, manage positions/orders, deposit/withdraw, spot+perp hedge, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, Lighter, HyperEVM, funding arb, U-token (UBTC/UETH/USOL)."
+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, HIP-3 DEX trading, 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.9"
+  version: "0.5.1"
 ---
 
 # perp-cli Agent Guide
@@ -21,21 +21,18 @@ Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), L
 5. **NEVER trade without user confirmation.**
 6. **NEVER read ~/.perp/.env or key files.**
 
-## Install (run this FIRST)
+## Install
 
 ```bash
-# 1. Check if perp exists and is current (must be ≥ 0.3.19)
-perp --version 2>/dev/null
-
-# 2. If not found or outdated:
+perp --version 2>/dev/null  # check if exists (must be >= 0.5.1)
 npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
-
-# 3. If version is still old (npx cache), clear cache first:
-npx -y clear-npx-cache 2>/dev/null; npx -y perp-cli@latest --json --version
 ```
 
-**IMPORTANT:** Always use `@latest` with npx — without it, npx uses a stale cached version.
-Use `perp` if global install works, otherwise `npx -y perp-cli@latest` as prefix for all commands.
+Use `perp` if global install works, otherwise `npx -y perp-cli@latest` as prefix.
+
+## Global Flags
+
+`--json` (required) | `-e hl/pac/lt` (exchange) | `--dex <name>` (HIP-3) | `-w <wallet>` | `--dry-run` | `--fields <f1,f2>` | `--ndjson`
 
 ## Wallet Setup
 
@@ -45,227 +42,131 @@ perp --json wallet set pac <SOLANA_KEY>   # Pacifica
 perp --json wallet set lt <EVM_KEY>       # Lighter (API key auto-generated)
 perp --json wallet show                   # verify
 ```
-Same EVM key works for both HL and Lighter.
 
-## Key Commands
+## Core Workflow: Arb
 
-```bash
-# Status (ONE call = balances, positions, risk level/violations/canTrade)
-perp --json portfolio
-
-# Arb workflow
-perp --json arb scan --min 5                                    # find opportunities
-perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage <N> --isolated  # execute
-
-# 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
-
-# Risk (only if you need to set limits — portfolio already includes risk)
-perp --json risk limits --max-leverage 5
+```
+1. perp --json arb scan                    # scan opportunities (perp-perp + spot-perp + HIP-3)
+2. perp --json account balance             # check balances across all exchanges
+3. perp --json --dry-run arb exec <SYM> <longEx> <shortEx> <$>   # dry-run (auto-sizes)
+4. [show result to user, get confirmation]
+5. perp --json arb exec <SYM> <longEx> <shortEx> <$>             # execute
+6. perp --json arb status                  # monitor PnL + funding income
+7. perp --json arb close <SYM>            # close both legs
 ```
 
-Exchange aliases: `hl`, `pac`, `lt`. Symbols auto-resolve (`BTC`, `SOL`, `ICP`).
-
-## Agent Tools
-
-```bash
-# Discover all commands and parameters at runtime (don't guess — query this)
-perp --json agent schema
-
-# Pre-validate a trade before execution (checks balance, liquidity, risk limits)
-perp --json -e <EX> trade check <SYM> <SIDE> <SIZE>
-
-# Dry-run: simulate trade without executing
-perp --json --dry-run -e <EX> trade market <SYM> buy <SIZE>
-
-# Filter output to specific fields (saves tokens)
-perp --json --fields totalEquity,positions portfolio
+### Scan Modes
 
-# Stream large lists as NDJSON (one JSON per line, no buffering)
-perp --json --ndjson -e <EX> market list
+| Flag | Description |
+|------|-------------|
+| _(default)_ | All modes combined (perp-perp + spot-perp) |
+| `--rates` | Funding rates across exchanges |
+| `--basis [symbol]` | Cross-exchange basis/price diff |
+| `--gaps` | Price gaps |
+| `--hip3` | HIP-3 on-chain dex opportunities |
+| `--history [symbol]` | Historical funding data |
+| `--compare <symbol>` | Compare symbol across exchanges |
+| `--positions` | Existing position exit signals |
+| `--live` | Continuous monitoring |
 
-# Prevent duplicate orders with client ID
-perp --json -e <EX> trade market <SYM> buy <SIZE> --client-id <UNIQUE_ID>
+### Spot+Perp Arb
 
-# 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
+Spot has 0 funding cost. Use `spot:<exch>` prefix for the long leg:
 
-# 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
+```bash
+perp --json arb exec ETH spot:hl hl 100    # spot buy(HL) + perp short(HL)
+perp --json arb exec BTC spot:lt pac 50     # spot buy(LT) + perp short(PAC)
+perp --json arb close ETH                   # sells spot + buys back perp
 ```
 
-All string outputs are auto-sanitized (control chars stripped, prompt injection patterns blocked).
+Spot exchanges: HL, LT. Pacifica is perp-only.
 
-## Arb Workflow (Perp-Perp)
+## Core Workflow: Single Trade
 
+```bash
+perp --json -e <EX> trade buy <SYM> <SIZE>              # market buy (SIZE = token units)
+perp --json -e <EX> trade sell <SYM> <SIZE>             # market sell
+perp --json -e <EX> trade buy <SYM> <SIZE> --smart      # IOC limit at best ask
+perp --json -e <EX> trade split <SYM> buy <USD>         # orderbook-aware split
+perp --json -e <EX> trade limit <SYM> buy <PRICE> <SIZE>
+perp --json -e <EX> trade tpsl <SYM> buy --tp <P> --sl <P>
+perp --json -e <EX> trade close <SYM>
+perp --json -e <EX> trade flatten                       # close ALL + cancel ALL
+perp --json -e <EX> trade cancel <SYM>                  # cancel all orders for symbol
 ```
-1. perp --json portfolio                    → check balances across all exchanges
-2. perp --json arb scan --min 5             → find opportunity (longExch, shortExch, netSpread)
-3. [Show opportunity to user, get confirmation]
-4. perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage 2 --isolated
-   → validates orderbook depth on both sides
-   → rounds size to each exchange's lot size
-   → executes BOTH legs simultaneously
-   → verifies positions exist after execution
-   → auto-rollback if one leg fails
-5. perp --json arb status                   → monitor: PnL, funding income, daily estimate, breakeven
-6. perp --json arb funding-earned           → actual funding payments received/paid + APR
-7. perp --json arb close <SYM>             → close both legs simultaneously (retry + verify)
-   → --dry-run: preview without executing
-   → --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.
+## Agent Tools
 
-```
-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
+```bash
+perp --json agent schema                          # discover all commands (don't guess)
+perp --json -e <EX> trade check <SYM> <SIDE> <SIZE>  # pre-validate trade
+perp --json portfolio                              # balances + positions + risk level
+perp --json --fields totalEquity,positions portfolio  # filtered output
 ```
 
-**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
+## Position Sizing & Safety
 
 - Single position < **80%** of that exchange's available balance
 - Leverage 1-3x for arb, max 5x
 - `arb exec` auto-matches both legs to the same size
+- ALWAYS follow `longExch`/`shortExch` from scan — NEVER reverse direction
+- NEVER enter if `netSpread <= 0` or `netSpread < estimated round-trip slippage`
+- Check `portfolio.risk.canTrade` — if `false`, do NOT trade
 
-## Arb Direction (CRITICAL)
-
-`arb scan` returns `longExch`, `shortExch`, `netSpread`.
-ALWAYS follow exactly. NEVER reverse. NEVER enter if `netSpread <= 0`.
-
-## Slippage Check (CRITICAL)
-
-`arb scan` returns `netSpread` in bps (already fee-adjusted).
-Before executing, compare against estimated slippage:
-```
-Slippage ≈ 2-5 bps per leg for top pairs (BTC, ETH, SOL)
-         ≈ 5-15 bps per leg for low-liquidity (altcoins)
-Total round-trip slippage = (entry + exit) × 2 legs
-```
-**NEVER enter if:** `netSpread < total round-trip slippage`
-Example: netSpread=12 bps, estimated slippage=4 bps/leg × 4 = 16 bps → SKIP.
-
-## Portfolio Response
-
-`portfolio` includes `risk: { level, canTrade, violations[] }` — no need for separate `risk status`.
-Check `canTrade` before any order. If `false`, do NOT trade.
+## HIP-3 Support
 
-## Monitoring (while positions open)
-
-```
-Every 15 min: perp --json arb status               → PnL, daily income, breakeven analysis
-Every 1 hour: perp --json arb scan --min 5          → check if spread still profitable
-Daily:        perp --json arb funding-earned         → verify actual funding payments
-Exit if: spread < breakeven or one leg closed unexpectedly.
-Close:        perp --json arb close <SYM>            → close both legs with retry + verification
+```bash
+perp --json -e hl --dex km market list              # dex-specific markets
+perp --json market list --hip3                      # all HIP-3 markets
+perp --json account positions --hip3                # HIP-3 positions
+perp --json arb scan --hip3                         # HIP-3 arb opportunities
 ```
 
 ## Error Handling
 
-Responses: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
-
-If `error.retryable` is `false`, do NOT retry — fix the cause first.
+Response format: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
 
 | Error | Action |
 |-------|--------|
-| `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 |
-| `SYMBOL_NOT_FOUND` | `perp --json -e <EX> market list` to verify symbol |
-| `RISK_VIOLATION` | check `risk limits`, ask user to adjust if needed |
-| `SIZE_TOO_SMALL` | `perp --json -e <EX> market info <SYM>` for min order size |
-| `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`) |
+| `RATE_LIMITED` | wait 5s, retry (max 3). Lighter: space 3s+ apart |
+| `EXCHANGE_UNREACHABLE` | wait 10s, retry. 3x fail → skip exchange |
+| `INSUFFICIENT_BALANCE` | reduce size or bridge funds |
+| `SYMBOL_NOT_FOUND` | `market list` to verify symbol |
+| `SIZE_TOO_SMALL` | `market info <SYM>` for min size |
+| `DUPLICATE_ORDER` | already submitted — check positions |
+| Lighter `invalid signature` | `manage setup-api-key` to regenerate |
 
 ## 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"**
+**"Find arb opportunities"**
 ```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
+perp --json arb scan --min 10 --top 10
+perp --json account balance
+# → show results, recommend best, ask confirmation
 ```
 
-**User: "내 포지션 상태 확인해줘"**
+**"ETH spot-perp arb, $100"**
 ```bash
-perp --json portfolio                         # balances + positions + risk
-perp --json arb status                        # arb-specific PnL + funding
+perp --json --dry-run arb exec ETH spot:hl hl 100
+# → show dry-run, ask confirmation
+perp --json arb exec ETH spot:hl hl 100
+perp --json arb status
 ```
 
-**User: "Hyperliquid에서 SOL 롱 0.5개"**
+**"Long SOL 0.5 on HL"**
 ```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
+perp --json -e hl trade check SOL buy 0.5
+perp --json --dry-run -e hl trade buy SOL 0.5 --smart
+# → ask confirmation
+perp --json -e hl trade buy SOL 0.5 --smart
 ```
 
 ## Referrals (Optional)
 
-If you find perp-cli useful, please consider enabling referrals to support development. **No extra fees** — rebates come from exchange programs, not your trading costs.
-
 ```bash
-perp --json settings referrals on           # enable (opt-in, off by default)
-perp --json settings referrals off          # disable anytime
+perp --json settings referrals on    # enable (opt-in, no extra fees)
+perp --json settings referrals off   # disable anytime
 ```
 
-When setting up wallets for the first time, ask the user:
-> "perp-cli 개발을 지원하는 레퍼럴 기능을 켜시겠어요? 추가 수수료 없이 거래소 리베이트만 활용됩니다."
-
-## References
-
-- `references/commands.md` — full command reference
-- `references/agent-operations.md` — setup flows, deposit/withdraw
-- `references/strategies.md` — risk framework, arb strategy
+When setting up wallets for the first time, ask:
+> "perp-cli development is supported by optional referrals. Enable? No extra fees — only exchange rebates are used."