perp-cli 0.3.7 → 0.3.9

package/README.md

@@ -288,7 +288,7 @@ perp settings set referralCodes.hyperliquid MYCODE
 - **TypeScript** + Node.js (ESM)
 - **Solana**: `@solana/web3.js`, `tweetnacl`, `bs58`
 - **EVM**: `ethers` v6
-- **Exchanges**: `hyperliquid` SDK, `lighter-sdk` (WASM), `@pacifica/sdk`
+- **Exchanges**: `hyperliquid` SDK, `lighter-ts-sdk` (WASM), `@pacifica/sdk`
 - **Bridge**: Circle CCTP V2 (Solana ↔ EVM), deBridge DLN (fallback)
 - **Testing**: Vitest (860+ tests)
 

package/dist/__tests__/risk-assessment.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { assessRisk, preTradeCheck, calcLiquidationDistance, getLiquidationDistances, LIQUIDATION_DISTANCE_HARD_CAP } from "../risk.js";
+import { assessRisk, preTradeCheck, calcLiquidationDistance, getLiquidationDistances, effectiveLimit, LIQUIDATION_DISTANCE_HARD_CAP } from "../risk.js";
 const defaultLimits = {
     maxDrawdownUsd: 500,
     maxPositionUsd: 5000,
@@ -264,3 +264,42 @@ describe("LIQUIDATION_DISTANCE_HARD_CAP", () => {
         expect(LIQUIDATION_DISTANCE_HARD_CAP).toBe(20);
     });
 });
+describe("Percentage-based Risk Limits", () => {
+    it("effectiveLimit should return min of USD and pct-of-equity", () => {
+        expect(effectiveLimit(500, 10, 1000)).toBe(100); // 10% of $1000 = $100 < $500
+        expect(effectiveLimit(500, 10, 10000)).toBe(500); // 10% of $10000 = $1000 > $500
+        expect(effectiveLimit(500, undefined, 1000)).toBe(500); // no pct → use USD
+        expect(effectiveLimit(500, 10, 0)).toBe(500); // zero equity → use USD
+    });
+    it("should use pct-based drawdown when equity is small", () => {
+        const limits = { ...defaultLimits, maxDrawdownPct: 10 };
+        // equity = $100, 10% = $10 effective drawdown limit. uPnL = -$15 > $10 → critical
+        const balances = [{ exchange: "test", balance: makeBalance(100, 80, 20, -15) }];
+        const positions = [{ exchange: "test", position: makePosition("BTC", "long", 0.0001, 100000, 2, -15) }];
+        const result = assessRisk(balances, positions, limits);
+        expect(result.violations.some(v => v.rule === "max_drawdown")).toBe(true);
+        expect(result.level).toBe("critical");
+    });
+    it("should use pct-based position limit when equity is small", () => {
+        const limits = { ...defaultLimits, maxPositionPct: 25 };
+        // equity = $200, 25% = $50 effective position limit. Position = $100 > $50 → violation
+        const balances = [{ exchange: "test", balance: makeBalance(200, 150, 50, 0) }];
+        const positions = [{ exchange: "test", position: makePosition("BTC", "long", 0.001, 100000, 2, 0) }]; // $100
+        const result = assessRisk(balances, positions, limits);
+        expect(result.violations.some(v => v.rule === "max_position_size")).toBe(true);
+    });
+    it("preTradeCheck should use pct-based limits", () => {
+        const limits = { ...defaultLimits, maxPositionPct: 25 };
+        // equity = $200, 25% = $50 effective position limit
+        const assessment = assessRisk([{ exchange: "test", balance: makeBalance(200, 150, 50, 0) }], [], limits);
+        expect(preTradeCheck(assessment, 60, 2).allowed).toBe(false); // $60 > $50
+        expect(preTradeCheck(assessment, 40, 2).allowed).toBe(true); // $40 < $50
+    });
+    it("should use stricter of USD and pct limits", () => {
+        const limits = { ...defaultLimits, maxPositionUsd: 100, maxPositionPct: 25 };
+        // equity = $1000, 25% = $250. USD limit = $100. Effective = $100 (USD is stricter)
+        const assessment = assessRisk([{ exchange: "test", balance: makeBalance(1000, 800, 200, 0) }], [], limits);
+        expect(preTradeCheck(assessment, 120, 2).allowed).toBe(false); // $120 > $100
+        expect(preTradeCheck(assessment, 80, 2).allowed).toBe(true); // $80 < $100
+    });
+});

package/dist/commands/manage.js

@@ -292,6 +292,7 @@ export function registerManageCommands(program, getAdapter, isJson, getPacificaA
         // Auto-save to .env
         setEnvVar("LIGHTER_API_KEY", privateKey);
         setEnvVar("LIGHTER_ACCOUNT_INDEX", String(adapter.accountIndex));
+        setEnvVar("LIGHTER_API_KEY_INDEX", String(keyIndex));
         if (isJson()) {
             return printJson(jsonOk({
                 privateKey,

package/dist/commands/risk.js

@@ -90,10 +90,14 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
     risk
         .command("limits")
         .description("View or set risk limits")
-        .option("--max-drawdown <usd>", "Max unrealized loss before closing all")
-        .option("--max-position <usd>", "Max single position notional")
-        .option("--max-exposure <usd>", "Max total exposure across all positions")
-        .option("--daily-loss <usd>", "Daily realized loss limit")
+        .option("--max-drawdown <usd>", "Max unrealized loss (USD)")
+        .option("--max-drawdown-pct <pct>", "Max unrealized loss (% of equity)")
+        .option("--max-position <usd>", "Max single position notional (USD)")
+        .option("--max-position-pct <pct>", "Max single position (% of equity)")
+        .option("--max-exposure <usd>", "Max total exposure (USD)")
+        .option("--max-exposure-pct <pct>", "Max total exposure (% of equity)")
+        .option("--daily-loss <usd>", "Daily realized loss limit (USD)")
+        .option("--daily-loss-pct <pct>", "Daily loss limit (% of equity)")
         .option("--max-positions <n>", "Max number of simultaneous positions")
         .option("--max-leverage <n>", "Max leverage per position")
         .option("--max-margin <pct>", "Max margin utilization %")
@@ -101,24 +105,33 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
         .option("--reset", "Reset all limits to defaults")
         .action(async (opts) => {
         let limits = loadRiskLimits();
-        const hasUpdate = opts.maxDrawdown || opts.maxPosition || opts.maxExposure ||
-            opts.dailyLoss || opts.maxPositions || opts.maxLeverage || opts.maxMargin ||
+        const hasUpdate = opts.maxDrawdown || opts.maxDrawdownPct || opts.maxPosition || opts.maxPositionPct ||
+            opts.maxExposure || opts.maxExposurePct || opts.dailyLoss || opts.dailyLossPct ||
+            opts.maxPositions || opts.maxLeverage || opts.maxMargin ||
             opts.minLiqDistance || opts.reset;
         if (opts.reset) {
             limits = {
                 maxDrawdownUsd: 500, maxPositionUsd: 5000, maxTotalExposureUsd: 20000,
                 dailyLossLimitUsd: 200, maxPositions: 10, maxLeverage: 20, maxMarginUtilization: 80,
-                minLiquidationDistance: 30,
+                minLiquidationDistance: 30, maxDrawdownPct: 10, maxPositionPct: 25,
             };
         }
         if (opts.maxDrawdown)
             limits.maxDrawdownUsd = parseFloat(opts.maxDrawdown);
+        if (opts.maxDrawdownPct)
+            limits.maxDrawdownPct = parseFloat(opts.maxDrawdownPct);
         if (opts.maxPosition)
             limits.maxPositionUsd = parseFloat(opts.maxPosition);
+        if (opts.maxPositionPct)
+            limits.maxPositionPct = parseFloat(opts.maxPositionPct);
         if (opts.maxExposure)
             limits.maxTotalExposureUsd = parseFloat(opts.maxExposure);
+        if (opts.maxExposurePct)
+            limits.maxExposurePct = parseFloat(opts.maxExposurePct);
         if (opts.dailyLoss)
             limits.dailyLossLimitUsd = parseFloat(opts.dailyLoss);
+        if (opts.dailyLossPct)
+            limits.dailyLossPct = parseFloat(opts.dailyLossPct);
         if (opts.maxPositions)
             limits.maxPositions = parseInt(opts.maxPositions);
         if (opts.maxLeverage)
@@ -140,15 +153,22 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
             saveRiskLimits(limits);
         if (isJson())
             return printJson(jsonOk(limits));
+        const fmtLimit = (usd, pct) => {
+            const parts = [`$${formatUsd(usd)}`];
+            if (pct != null)
+                parts.push(chalk.cyan(`${pct}% of equity`));
+            return parts.join(" / ");
+        };
         console.log(chalk.cyan.bold(`\n  Risk Limits ${hasUpdate ? "(updated)" : ""}\n`));
-        console.log(`  Max Drawdown:          $${formatUsd(limits.maxDrawdownUsd)}`);
-        console.log(`  Max Position Size:     $${formatUsd(limits.maxPositionUsd)}`);
-        console.log(`  Max Total Exposure:    $${formatUsd(limits.maxTotalExposureUsd)}`);
-        console.log(`  Daily Loss Limit:      $${formatUsd(limits.dailyLossLimitUsd)}`);
+        console.log(`  Max Drawdown:          ${fmtLimit(limits.maxDrawdownUsd, limits.maxDrawdownPct)}`);
+        console.log(`  Max Position Size:     ${fmtLimit(limits.maxPositionUsd, limits.maxPositionPct)}`);
+        console.log(`  Max Total Exposure:    ${fmtLimit(limits.maxTotalExposureUsd, limits.maxExposurePct)}`);
+        console.log(`  Daily Loss Limit:      ${fmtLimit(limits.dailyLossLimitUsd, limits.dailyLossPct)}`);
         console.log(`  Max Positions:         ${limits.maxPositions}`);
         console.log(`  Max Leverage:          ${limits.maxLeverage}x`);
         console.log(`  Max Margin Util:       ${limits.maxMarginUtilization}%`);
-        console.log(`  Min Liq Distance:      ${limits.minLiquidationDistance}% ${chalk.gray(`(hard cap: ${LIQUIDATION_DISTANCE_HARD_CAP}%)`)}\n`);
+        console.log(`  Min Liq Distance:      ${limits.minLiquidationDistance}% ${chalk.gray(`(hard cap: ${LIQUIDATION_DISTANCE_HARD_CAP}%)`)}`);
+        console.log(chalk.gray(`\n  When both USD and % are set, the stricter limit applies.\n`));
         console.log(chalk.gray(`  Config file: ~/.perp/risk.json\n`));
     });
     // ── risk check ── (pre-trade check, for agent use)

package/dist/commands/wallet.js

@@ -389,9 +389,11 @@ export function registerWalletCommands(program, isJson) {
                 const { LighterAdapter } = await import("../exchanges/lighter.js");
                 const adapter = new LighterAdapter(normalized);
                 await adapter.init();
-                const { privateKey: apiKey } = await adapter.setupApiKey();
+                const apiKeyIndex = 2;
+                const { privateKey: apiKey } = await adapter.setupApiKey(apiKeyIndex);
                 setEnvVar("LIGHTER_API_KEY", apiKey);
                 setEnvVar("LIGHTER_ACCOUNT_INDEX", String(adapter.accountIndex));
+                setEnvVar("LIGHTER_API_KEY_INDEX", String(apiKeyIndex));
                 lighterApiSetup = { apiKey, accountIndex: adapter.accountIndex };
             }
             catch (e) {

package/dist/exchanges/hyperliquid.d.ts

@@ -20,6 +20,11 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     init(): Promise<void>;
     /** Load asset index map — supports native and HIP-3 dex. */
     private _loadAssetMap;
+    /**
+     * Resolve a symbol to the canonical name in the asset map.
+     * Handles: "ICP" → "ICP-PERP", "BTC-PERP" → "BTC-PERP", "km:GOOGL" → "km:GOOGL"
+     */
+    resolveSymbol(symbol: string): string;
     getAssetIndex(symbol: string): number;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
     getOrderbook(symbol: string): Promise<{
@@ -51,7 +56,7 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     cancelOrder(symbol: string, orderId: string): Promise<import("hyperliquid").CancelOrderResponse>;
     cancelAllOrders(symbol?: string): Promise<import("hyperliquid").CancelOrderResponse[]>;
     editOrder(symbol: string, orderId: string, price: string, size: string): Promise<unknown>;
-    setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<unknown>;
+    setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<any>;
     stopOrder(symbol: string, side: "buy" | "sell", size: string, triggerPrice: string, opts?: {
         limitPrice?: string;
         reduceOnly?: boolean;
@@ -90,14 +95,14 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     twapCancel(symbol: string, twapId: number): Promise<unknown>;
     /**
      * Update leverage for a symbol.
-     * Python SDK: update_leverage(leverage, name, is_cross)
+     * Uses SDK's built-in updateLeverage method.
      */
-    updateLeverage(symbol: string, leverage: number, isCross?: boolean): Promise<unknown>;
+    updateLeverage(symbol: string, leverage: number, isCross?: boolean): Promise<any>;
     /**
      * Update isolated margin for a position.
      * amount > 0 to add margin, amount < 0 to remove
      */
-    updateIsolatedMargin(symbol: string, amount: number): Promise<unknown>;
+    updateIsolatedMargin(symbol: string, amount: number): Promise<any>;
     /**
      * Withdraw from Hyperliquid L1 bridge.
      * Python SDK: withdraw_from_bridge(amount, destination) → action type "withdraw3"

package/dist/exchanges/hyperliquid.js

@@ -93,24 +93,34 @@ export class HyperliquidAdapter {
             // non-critical
         }
     }
-    getAssetIndex(symbol) {
+    /**
+     * Resolve a symbol to the canonical name in the asset map.
+     * Handles: "ICP" → "ICP-PERP", "BTC-PERP" → "BTC-PERP", "km:GOOGL" → "km:GOOGL"
+     */
+    resolveSymbol(symbol) {
         const sym = symbol.toUpperCase();
-        // Try exact match first (handles both "BTC" for native and "km:GOOGL" for dex)
-        let idx = this._assetMap.get(sym);
-        if (idx !== undefined)
-            return idx;
-        // For dex: try lowercase prefix (API returns "km:GOOGL" but input may be "KM:GOOGL")
+        if (this._assetMap.has(sym))
+            return sym;
+        if (this._assetMap.has(`${sym}-PERP`))
+            return `${sym}-PERP`;
+        if (sym.endsWith("-PERP") && this._assetMap.has(sym.replace(/-PERP$/, "")))
+            return sym.replace(/-PERP$/, "");
         if (sym.includes(":")) {
             const [prefix, base] = sym.split(":");
-            idx = this._assetMap.get(`${prefix.toLowerCase()}:${base}`);
-            if (idx !== undefined)
-                return idx;
-            // Try base name only (e.g., "GOOGL")
-            idx = this._assetMap.get(base);
-            if (idx !== undefined)
-                return idx;
+            const lower = `${prefix.toLowerCase()}:${base}`;
+            if (this._assetMap.has(lower))
+                return lower;
+            if (this._assetMap.has(base))
+                return base;
         }
-        throw new Error(`Unknown symbol: ${symbol}`);
+        return sym; // return as-is, let downstream error
+    }
+    getAssetIndex(symbol) {
+        const resolved = this.resolveSymbol(symbol);
+        const idx = this._assetMap.get(resolved);
+        if (idx !== undefined)
+            return idx;
+        throw new Error(`Unknown asset: ${symbol}`);
     }
     async getMarkets() {
         let universe;
@@ -586,31 +596,17 @@ export class HyperliquidAdapter {
     }
     /**
      * Update leverage for a symbol.
-     * Python SDK: update_leverage(leverage, name, is_cross)
+     * Uses SDK's built-in updateLeverage method.
      */
     async updateLeverage(symbol, leverage, isCross = true) {
-        const assetIndex = this.getAssetIndex(symbol);
-        const action = {
-            type: "updateLeverage",
-            asset: assetIndex,
-            isCross,
-            leverage,
-        };
-        return this._sendExchangeAction(action);
+        return this.sdk.exchange.updateLeverage(this.resolveSymbol(symbol), isCross ? "cross" : "isolated", leverage);
     }
     /**
      * Update isolated margin for a position.
      * amount > 0 to add margin, amount < 0 to remove
      */
     async updateIsolatedMargin(symbol, amount) {
-        const assetIndex = this.getAssetIndex(symbol);
-        const action = {
-            type: "updateIsolatedMargin",
-            asset: assetIndex,
-            isBuy: true,
-            ntli: Math.round(amount * 1e6), // USD to 6 decimals
-        };
-        return this._sendExchangeAction(action);
+        return this.sdk.exchange.updateIsolatedMargin(this.resolveSymbol(symbol), amount > 0, Math.round(Math.abs(amount) * 1e6));
     }
     /**
      * Withdraw from Hyperliquid L1 bridge.

package/dist/exchanges/lighter.d.ts

@@ -1,9 +1,10 @@
 import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
-type LighterSignerClientType = import("lighter-sdk").LighterSignerClient;
+import type { WasmSignerClient as WasmSignerClientType } from "lighter-ts-sdk";
 export declare class LighterAdapter implements ExchangeAdapter {
     readonly name = "lighter";
     private _signer;
     private _accountIndex;
+    private _apiKeyIndex;
     private _address;
     private _marketMap;
     private _marketDecimals;
@@ -23,7 +24,11 @@ export declare class LighterAdapter implements ExchangeAdapter {
         apiKey?: string;
         accountIndex?: number;
     });
-    get signer(): LighterSignerClientType;
+    get signer(): {
+        createAuthToken(deadline: number): Promise<{
+            authToken: string;
+        }>;
+    } & WasmSignerClientType;
     get accountIndex(): number;
     get address(): string;
     get evmKey(): string;
@@ -137,12 +142,13 @@ export declare class LighterAdapter implements ExchangeAdapter {
     private sendTx;
     private restGet;
     private ensureSigner;
-    private static getWasmOps;
+    private static _wasmClient;
+    private static getWasmClient;
     /**
      * Generate a new Lighter API key pair using the WASM signer.
      * Returns { privateKey, publicKey } (both 0x-prefixed, 40 bytes).
      */
-    static generateApiKey(seed?: string): Promise<{
+    static generateApiKey(): Promise<{
         privateKey: string;
         publicKey: string;
     }>;
@@ -156,4 +162,3 @@ export declare class LighterAdapter implements ExchangeAdapter {
         publicKey: string;
     }>;
 }
-export {};

package/dist/exchanges/lighter.js

@@ -1,11 +1,8 @@
-import { createRequire } from "node:module";
-// Use createRequire to load the CJS build of lighter-sdk
-// (the ESM build has a broken require polyfill that fails on Node built-ins)
-const require = createRequire(import.meta.url);
 export class LighterAdapter {
     name = "lighter";
     _signer;
     _accountIndex = -1;
+    _apiKeyIndex;
     _address;
     _marketMap = new Map(); // symbol → marketIndex
     _marketDecimals = new Map(); // symbol → decimals
@@ -26,6 +23,7 @@ export class LighterAdapter {
         this._evmKey = evmKey;
         this._apiKey = opts?.apiKey || process.env.LIGHTER_API_KEY || "";
         this._accountIndexInit = opts?.accountIndex ?? parseInt(process.env.LIGHTER_ACCOUNT_INDEX || "-1");
+        this._apiKeyIndex = parseInt(process.env.LIGHTER_API_KEY_INDEX || "2");
         this._address = "";
         this._testnet = testnet;
         this._readOnly = !this._apiKey;
@@ -35,7 +33,16 @@ export class LighterAdapter {
         this._chainId = testnet ? 300 : 304;
     }
     get signer() {
-        return this._signer;
+        const self = this;
+        // Compatibility wrapper: ws-feeds.ts expects createAuthToken(deadline) → { authToken }
+        return Object.create(this._signer, {
+            createAuthToken: {
+                value: async (deadline) => {
+                    const token = await self._signer.createAuthToken(deadline, self._apiKeyIndex, self._accountIndex);
+                    return { authToken: token };
+                },
+            },
+        });
     }
     get accountIndex() {
         return this._accountIndex;
@@ -65,33 +72,37 @@ export class LighterAdapter {
         // Auto-generate API key if we have PK but no API key and account exists
         if (!this._apiKey && this._accountIndex >= 0) {
             try {
-                const { privateKey: apiKey } = await this.setupApiKey();
+                const autoKeyIndex = 2; // default for auto-setup
+                const { privateKey: apiKey } = await this.setupApiKey(autoKeyIndex);
                 this._apiKey = apiKey;
+                this._apiKeyIndex = autoKeyIndex;
                 // Save to .env for future use
                 try {
                     const { setEnvVar } = await import("../commands/init.js");
                     setEnvVar("LIGHTER_API_KEY", apiKey);
                     setEnvVar("LIGHTER_ACCOUNT_INDEX", String(this._accountIndex));
+                    setEnvVar("LIGHTER_API_KEY_INDEX", String(autoKeyIndex));
                 }
                 catch { /* non-critical — env save may fail in some contexts */ }
             }
-            catch {
-                // Auto-setup failed (no gas, network issue, etc.) — continue in read-only mode
+            catch (e) {
+                // Auto-setup failed — log the error and continue in read-only mode
+                const msg = e instanceof Error ? e.message : String(e);
+                console.error(`[lighter] API key auto-setup failed: ${msg}. Trading will be read-only. Run 'perp -e lighter manage setup-api-key' to retry.`);
             }
         }
         // Initialize signer for trading if we have an API key
         if (this._apiKey) {
-            const { LighterSignerClient } = require("lighter-sdk");
-            this._signer = new LighterSignerClient({
+            const { WasmSignerClient } = await import("lighter-ts-sdk");
+            this._signer = new WasmSignerClient({});
+            await this._signer.initialize();
+            await this._signer.createClient({
                 url: this._baseUrl,
                 privateKey: this._apiKey,
                 chainId: this._chainId,
+                apiKeyIndex: this._apiKeyIndex,
                 accountIndex: this._accountIndex,
-                apiKeyIndex: parseInt(process.env.LIGHTER_API_KEY_INDEX || "3"),
-                loaderType: "wasm",
             });
-            // Only initialize (load WASM + create client), skip checkClient which does HTTP from WASM
-            await this._signer.initialize();
             this._readOnly = false;
         }
         // Build symbol → marketIndex map + decimals from orderBookDetails
@@ -230,8 +241,7 @@ export class LighterAdapter {
         if (this._readOnly)
             throw new Error("Auth requires API key");
         const deadline = Math.floor(Date.now() / 1000) + 3600;
-        const auth = await this._signer.createAuthToken(deadline);
-        return auth.authToken;
+        return this._signer.createAuthToken(deadline, this._apiKeyIndex, this._accountIndex);
     }
     async restGetAuth(path, params) {
         const auth = await this.getAuthToken();
@@ -291,7 +301,7 @@ export class LighterAdapter {
             baseAmount,
             price: Math.max(slippageTicks, 1),
             isAsk: side === "sell" ? 1 : 0,
-            type: 1, // ORDER_TYPE_MARKET
+            orderType: 1, // ORDER_TYPE_MARKET
             timeInForce: 0, // IOC (Immediate or Cancel)
             reduceOnly: 0,
             triggerPrice: 0,
@@ -311,7 +321,7 @@ export class LighterAdapter {
             baseAmount,
             price: priceTicks,
             isAsk: side === "sell" ? 1 : 0,
-            type: 0, // ORDER_TYPE_LIMIT
+            orderType: 0, // ORDER_TYPE_LIMIT
             timeInForce: 1, // GTT (Good Till Time) — rests on orderbook
             reduceOnly: opts?.reduceOnly ? 1 : 0,
             triggerPrice: 0,
@@ -324,13 +334,19 @@ export class LighterAdapter {
         this.ensureSigner();
         const nonce = await this.getNextNonce();
         const marketIndex = this.getMarketIndex(symbol);
-        const signed = await this._signer.signCancelOrder(marketIndex, parseInt(orderId), nonce);
+        const signed = await this._signer.signCancelOrder({
+            marketIndex, orderIndex: parseInt(orderId), nonce,
+            apiKeyIndex: this._apiKeyIndex, accountIndex: this._accountIndex,
+        });
         return this.sendTx(signed);
     }
     async cancelAllOrders(_symbol) {
         this.ensureSigner();
         const nonce = await this.getNextNonce();
-        const signed = await this._signer.signCancelAllOrders(0, Math.floor(Date.now() / 1000) + 86400, nonce);
+        const signed = await this._signer.signCancelAllOrders({
+            timeInForce: 0, time: Math.floor(Date.now() / 1000) + 86400, nonce,
+            apiKeyIndex: this._apiKeyIndex, accountIndex: this._accountIndex,
+        });
         return this.sendTx(signed);
     }
     async modifyOrder(symbol, orderId, price, size) {
@@ -345,6 +361,8 @@ export class LighterAdapter {
             price: priceTicks,
             triggerPrice: 0,
             nonce,
+            apiKeyIndex: this._apiKeyIndex,
+            accountIndex: this._accountIndex,
         });
         if (signed.error) {
             throw new Error(`Signer: ${signed.error}`);
@@ -374,7 +392,7 @@ export class LighterAdapter {
             baseAmount,
             price: Math.max(priceTicks, 1),
             isAsk: side === "sell" ? 1 : 0,
-            type: isMarket ? 1 : 0,
+            orderType: isMarket ? 1 : 0,
             timeInForce: isMarket ? 0 : 1, // IOC for market, GTT for limit
             reduceOnly: opts?.reduceOnly ? 1 : 0,
             triggerPrice: triggerTicks,
@@ -390,16 +408,22 @@ export class LighterAdapter {
         // fraction = initial margin fraction in basis points: 10000/leverage
         const fraction = Math.round(10000 / leverage);
         const mode = marginMode === "isolated" ? 1 : 0;
-        const signed = await this._signer.signUpdateLeverage(marketIndex, fraction, mode, nonce);
+        const signed = await this._signer.signUpdateLeverage({
+            marketIndex, fraction, marginMode: mode, nonce,
+            apiKeyIndex: this._apiKeyIndex, accountIndex: this._accountIndex,
+        });
         if (signed.error) {
             throw new Error(`Signer: ${signed.error}`);
         }
         return this.sendTx(signed);
     }
-    async withdraw(amount, assetId = 2, routeType = 0) {
+    async withdraw(amount, assetId = 3, routeType = 0) {
         this.ensureSigner();
         const nonce = await this.getNextNonce();
-        const signed = await this._signer.signWithdraw(amount, assetId, routeType, nonce);
+        const signed = await this._signer.signWithdraw({
+            usdcAmount: amount, assetIndex: assetId, routeType, nonce,
+            apiKeyIndex: this._apiKeyIndex, accountIndex: this._accountIndex,
+        });
         return this.sendTx(signed);
     }
     // ── Interface aliases ──
@@ -680,16 +704,19 @@ export class LighterAdapter {
      * Direct REST GET helper.
      */
     async getNextNonce() {
-        const apiKeyIndex = parseInt(process.env.LIGHTER_API_KEY_INDEX || "3");
         const res = await this.restGet("/nextNonce", {
             account_index: String(this._accountIndex),
-            api_key_index: String(apiKeyIndex),
+            api_key_index: String(this._apiKeyIndex),
         });
         return res.nonce ?? res.next_nonce ?? 0;
     }
     async signOrder(params) {
         try {
-            const result = await this._signer.signCreateOrder(params);
+            const result = await this._signer.signCreateOrder({
+                ...params,
+                apiKeyIndex: this._apiKeyIndex,
+                accountIndex: this._accountIndex,
+            });
             if (result.error) {
                 throw new Error(`Signer: ${result.error}`);
             }
@@ -737,23 +764,23 @@ export class LighterAdapter {
                 "then set LIGHTER_API_KEY in your .env");
         }
     }
-    static async getWasmOps() {
-        const { WasmLoader } = require("lighter-sdk");
-        const loader = WasmLoader.getInstance();
-        await loader.load({});
-        return loader.getOperations();
+    static _wasmClient = null;
+    static async getWasmClient() {
+        if (LighterAdapter._wasmClient)
+            return LighterAdapter._wasmClient;
+        const { WasmSignerClient } = await import("lighter-ts-sdk");
+        const client = new WasmSignerClient({});
+        await client.initialize();
+        LighterAdapter._wasmClient = client;
+        return client;
     }
     /**
      * Generate a new Lighter API key pair using the WASM signer.
      * Returns { privateKey, publicKey } (both 0x-prefixed, 40 bytes).
      */
-    static async generateApiKey(seed) {
-        const ops = await LighterAdapter.getWasmOps();
-        const result = ops
-            .GenerateAPIKey(seed ?? `pacifica-cli-${Date.now()}-${Math.random()}`);
-        if (result.err)
-            throw new Error(`GenerateAPIKey failed: ${result.err}`);
-        return { privateKey: result.privateKey, publicKey: result.publicKey };
+    static async generateApiKey() {
+        const client = await LighterAdapter.getWasmClient();
+        return client.generateAPIKey();
     }
     /**
      * Generate an API key and register it on-chain via ChangePubKey.
@@ -769,14 +796,23 @@ export class LighterAdapter {
             account_index: String(this._accountIndex),
             api_key_index: String(apiKeyIndex),
         });
-        const nonce = nonceRes.next_nonce ?? 0;
+        const nonce = nonceRes.nonce ?? nonceRes.next_nonce ?? 0;
         // 3. Create signer client with new key and sign ChangePubKey
-        const ops = await LighterAdapter.getWasmOps();
-        const opsAny = ops;
-        // CreateClient with the new API key
-        opsAny.CreateClient(this._baseUrl, privateKey, this._chainId, apiKeyIndex, this._accountIndex);
+        const client = await LighterAdapter.getWasmClient();
+        await client.createClient({
+            url: this._baseUrl,
+            privateKey,
+            chainId: this._chainId,
+            apiKeyIndex,
+            accountIndex: this._accountIndex,
+        });
         // Sign ChangePubKey
-        const signed = await opsAny.SignChangePubKey(publicKey, nonce, apiKeyIndex, this._accountIndex);
+        const signed = await client.signChangePubKey({
+            pubkey: publicKey,
+            nonce,
+            apiKeyIndex,
+            accountIndex: this._accountIndex,
+        });
         if (signed.error)
             throw new Error(`SignChangePubKey failed: ${signed.error}`);
         if (!signed.txInfo || !signed.messageToSign) {

package/dist/risk.d.ts

@@ -8,7 +8,13 @@ export interface RiskLimits {
     maxLeverage: number;
     maxMarginUtilization: number;
     minLiquidationDistance: number;
+    maxDrawdownPct?: number;
+    maxPositionPct?: number;
+    maxExposurePct?: number;
+    dailyLossPct?: number;
 }
+/** Resolve effective USD limit: min of fixed USD and pct-of-equity (if both set) */
+export declare function effectiveLimit(usdLimit: number, pctLimit: number | undefined, totalEquity: number): number;
 /** Hard cap: liquidation distance can NEVER be set below this % */
 export declare const LIQUIDATION_DISTANCE_HARD_CAP = 20;
 export declare function loadRiskLimits(): RiskLimits;

package/dist/risk.js

@@ -9,7 +9,16 @@ const DEFAULT_LIMITS = {
     maxLeverage: 20,
     maxMarginUtilization: 80,
     minLiquidationDistance: 30,
+    maxDrawdownPct: 10,
+    maxPositionPct: 25,
 };
+/** Resolve effective USD limit: min of fixed USD and pct-of-equity (if both set) */
+export function effectiveLimit(usdLimit, pctLimit, totalEquity) {
+    if (pctLimit == null || totalEquity <= 0)
+        return usdLimit;
+    const pctInUsd = (pctLimit / 100) * totalEquity;
+    return Math.min(usdLimit, pctInUsd);
+}
 /** Hard cap: liquidation distance can NEVER be set below this % */
 export const LIQUIDATION_DISTANCE_HARD_CAP = 20;
 const PERP_DIR = resolve(process.env.HOME || "~", ".perp");
@@ -87,32 +96,36 @@ export function assessRisk(balances, positions, limits) {
             maxLeverageUsed = lev;
     }
     const marginUtilization = totalEquity > 0 ? (totalMarginUsed / totalEquity) * 100 : 0;
+    // Resolve effective limits (min of USD and % of equity)
+    const effDrawdown = effectiveLimit(lim.maxDrawdownUsd, lim.maxDrawdownPct, totalEquity);
+    const effPosition = effectiveLimit(lim.maxPositionUsd, lim.maxPositionPct, totalEquity);
+    const effExposure = effectiveLimit(lim.maxTotalExposureUsd, lim.maxExposurePct, totalEquity);
     // Check violations
-    if (totalUnrealizedPnl < -lim.maxDrawdownUsd) {
+    if (totalUnrealizedPnl < -effDrawdown) {
         violations.push({
             rule: "max_drawdown",
             severity: "critical",
-            message: `Unrealized loss $${Math.abs(totalUnrealizedPnl).toFixed(2)} exceeds max drawdown $${lim.maxDrawdownUsd}`,
+            message: `Unrealized loss $${Math.abs(totalUnrealizedPnl).toFixed(2)} exceeds max drawdown $${effDrawdown.toFixed(2)}${lim.maxDrawdownPct != null ? ` (${lim.maxDrawdownPct}% of equity)` : ""}`,
             current: Math.abs(totalUnrealizedPnl),
-            limit: lim.maxDrawdownUsd,
+            limit: effDrawdown,
         });
     }
-    if (largestPositionUsd > lim.maxPositionUsd) {
+    if (largestPositionUsd > effPosition) {
         violations.push({
             rule: "max_position_size",
             severity: "high",
-            message: `Largest position $${largestPositionUsd.toFixed(2)} exceeds limit $${lim.maxPositionUsd}`,
+            message: `Largest position $${largestPositionUsd.toFixed(2)} exceeds limit $${effPosition.toFixed(2)}${lim.maxPositionPct != null ? ` (${lim.maxPositionPct}% of equity)` : ""}`,
             current: largestPositionUsd,
-            limit: lim.maxPositionUsd,
+            limit: effPosition,
         });
     }
-    if (totalExposure > lim.maxTotalExposureUsd) {
+    if (totalExposure > effExposure) {
         violations.push({
             rule: "max_total_exposure",
             severity: "high",
-            message: `Total exposure $${totalExposure.toFixed(2)} exceeds limit $${lim.maxTotalExposureUsd}`,
+            message: `Total exposure $${totalExposure.toFixed(2)} exceeds limit $${effExposure.toFixed(2)}${lim.maxExposurePct != null ? ` (${lim.maxExposurePct}% of equity)` : ""}`,
             current: totalExposure,
-            limit: lim.maxTotalExposureUsd,
+            limit: effExposure,
         });
     }
     if (positions.length > lim.maxPositions) {
@@ -205,11 +218,14 @@ export function preTradeCheck(assessment, newOrderNotional, newOrderLeverage) {
         return { allowed: false, reason: "Trading suspended: critical risk violation active" };
     }
     const lim = assessment.limits;
-    if (newOrderNotional > lim.maxPositionUsd) {
-        return { allowed: false, reason: `Order notional $${newOrderNotional.toFixed(0)} exceeds max position size $${lim.maxPositionUsd}` };
-    }
-    if (assessment.metrics.totalExposure + newOrderNotional > lim.maxTotalExposureUsd) {
-        return { allowed: false, reason: `Would exceed total exposure limit ($${(assessment.metrics.totalExposure + newOrderNotional).toFixed(0)} > $${lim.maxTotalExposureUsd})` };
+    const equity = assessment.metrics.totalEquity;
+    const effPosition = effectiveLimit(lim.maxPositionUsd, lim.maxPositionPct, equity);
+    const effExposure = effectiveLimit(lim.maxTotalExposureUsd, lim.maxExposurePct, equity);
+    if (newOrderNotional > effPosition) {
+        return { allowed: false, reason: `Order notional $${newOrderNotional.toFixed(0)} exceeds max position size $${effPosition.toFixed(0)}${lim.maxPositionPct != null ? ` (${lim.maxPositionPct}% of $${equity.toFixed(0)} equity)` : ""}` };
+    }
+    if (assessment.metrics.totalExposure + newOrderNotional > effExposure) {
+        return { allowed: false, reason: `Would exceed total exposure limit ($${(assessment.metrics.totalExposure + newOrderNotional).toFixed(0)} > $${effExposure.toFixed(0)})` };
     }
     if (assessment.metrics.positionCount + 1 > lim.maxPositions) {
         return { allowed: false, reason: `Would exceed max positions (${assessment.metrics.positionCount + 1} > ${lim.maxPositions})` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "./dist/index.js",
@@ -46,7 +46,7 @@
     "dotenv": "^16.5.0",
     "ethers": "^6.13.2",
     "hyperliquid": "^1.7.7",
-    "lighter-sdk": "^0.0.17",
+    "lighter-ts-sdk": "^1.0.10",
     "tweetnacl": "^1.0.3",
     "ws": "^8.19.0",
     "yaml": "^2.8.2",

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.3.7"
+  version: "0.3.9"
   mcp-server: perp-cli
 ---
 
@@ -66,6 +66,12 @@ perp --json -e lighter ...        # Lighter (Ethereum)
 ```
 If a default exchange is set, `-e` can be omitted.
 
+### Symbol naming
+Symbols are auto-resolved across exchanges. Use bare symbols (e.g., `BTC`, `SOL`, `ICP`) everywhere — the CLI handles exchange-specific naming:
+- **Hyperliquid**: `ICP` → `ICP-PERP` (auto-resolved, `-PERP` suffix added)
+- **Pacifica / Lighter**: bare symbols as-is
+- `arb scan` returns bare symbols — pass them directly to any exchange command.
+
 ### Common operations
 ```bash
 perp --json wallet show                      # check configured wallets
@@ -73,10 +79,19 @@ perp --json -e hl account info               # balance & margin
 perp --json -e hl account positions          # open positions
 perp --json -e hl market list                # available markets
 perp --json -e hl market mid BTC             # BTC mid price
-perp --json arb rates                        # cross-exchange funding rates
+perp --json arb scan --min 5                 # find funding arb opportunities (>5bps spread)
 perp --json portfolio                        # unified multi-exchange view
 ```
 
+### Funding arb direction (CRITICAL — do NOT reverse)
+```
+arb scan returns: longExch, shortExch, netSpread
+→ ALWAYS follow longExch/shortExch exactly. NEVER reverse the direction.
+→ NEVER enter if netSpread ≤ 0 (= loss after fees)
+→ Positive funding = longs pay shorts → be SHORT to receive
+→ Negative funding = shorts pay longs → be LONG to receive
+```
+
 ### Trade execution (MANDATORY checklist)
 ```
 BEFORE ANY TRADE:
@@ -89,12 +104,51 @@ BEFORE ANY TRADE:
 1. perp --json risk status                     → check risk level (STOP if critical)
 2. perp --json -e <EX> account info            → verify EXCHANGE-SPECIFIC balance
 3. perp --json -e <EX> market mid <SYM>        → current price
-4. perp --json risk check --notional <$> --leverage <L> → risk pre-check
-5. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE>  → trade validation
-6. [Show order details + risk assessment to user, get explicit confirmation]
-7. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE>  → execute
-8. perp --json -e <EX> account positions       → verify result + check liquidation price
+4. perp --json -e <EX> trade leverage <SYM> <N> --isolated → set leverage + isolated margin FIRST
+5. perp --json risk check --notional <$> --leverage <L> → risk pre-check
+6. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L> → trade validation
+   ⚠ trade check does NOT read exchange-set leverage. ALWAYS pass --leverage explicitly.
+7. [Show order details + risk assessment to user, get explicit confirmation]
+8. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE>  → execute
+9. perp --json -e <EX> account positions       → verify result + check liquidation price
+```
+
+### Exchange-specific constraints
+```
+Minimum order values (notional, enforced by exchange):
+  - Hyperliquid: $10 minimum per order
+  - Pacifica: varies by symbol (usually ~$1)
+  - Lighter: varies by symbol
+
+If your calculated size falls below the minimum, increase to meet it or skip the opportunity.
+trade check returns valid: true/false but is ADVISORY — it does NOT block execution.
+The exchange itself will reject orders below its minimum.
+```
+
+### Arb order sizing (CRITICAL — both legs MUST match)
+```
+For funding arb, BOTH legs must have the EXACT SAME SIZE. Size mismatch = directional exposure.
+
+1. Check orderbook depth on BOTH exchanges:
+   perp --json -e <LONG_EX> market book <SYM>    → asks (you're buying)
+   perp --json -e <SHORT_EX> market book <SYM>   → bids (you're selling)
+
+2. Compute ORDER_SIZE:
+   - fillable_long = sum of ask sizes at best 2-3 levels
+   - fillable_short = sum of bid sizes at best 2-3 levels
+   - ORDER_SIZE = min(fillable_long, fillable_short, desired_size)
+   - Must be ≥ BOTH exchanges' minimum order value (e.g. HL requires ≥$10 notional)
+
+3. Execute BOTH legs with the SAME ORDER_SIZE:
+   perp --json -e <LONG_EX> trade market <SYM> buy <ORDER_SIZE>
+   → verify fill via account positions
+   perp --json -e <SHORT_EX> trade market <SYM> sell <ORDER_SIZE>
+   → verify fill via account positions
+
+4. Confirm matched: both positions must show identical size.
+   If mismatch (partial fill), adjust the larger to match the smaller.
 ```
+See `references/strategies.md` for detailed execution strategy (chunked orders, limit orders, failure handling).
 
 ### Post-entry monitoring (MANDATORY while positions are open)
 ```
@@ -104,7 +158,7 @@ Every 15 minutes:
   perp --json -e <EX> account positions        → check each position P&L
 
 Every 1 hour (at funding settlement):
-  perp --json arb rates                        → is spread still profitable?
+  perp --json arb scan --min 5                  → is spread still profitable?
   perp --json portfolio                        → total equity across exchanges
   Compare both legs' unrealized P&L — they should roughly offset
 

package/skills/perp-cli/references/agent-operations.md

@@ -78,7 +78,7 @@ perp --json bridge send --from solana --to arbitrum --amount 500
 perp --json bridge status <orderId>     # wait for completion
 
 # 5. Verify both sides have balance, then start arb
-perp --json arb rates
+perp --json arb scan --min 5
 ```
 
 ### Lighter API Key Setup
@@ -229,7 +229,7 @@ Error case:
 - `wallet show`, `wallet balance` — read-only
 - `account info`, `account positions`, `account orders` — read-only
 - `market list`, `market mid`, `market book` — read-only
-- `arb rates`, `arb scan` — read-only
+- `arb scan` — read-only (`arb rates` is deprecated)
 - `portfolio`, `risk overview` — read-only
 - `bridge quote` — read-only
 - `bridge status` — read-only
@@ -242,6 +242,29 @@ Error case:
 
 **For non-idempotent commands:** always verify the result before retrying. Check positions or balances to confirm whether the first attempt succeeded.
 
+## Symbol Naming Across Exchanges
+
+Symbols are auto-resolved by the CLI. **Always use bare symbols** (e.g., `BTC`, `SOL`, `ICP`) — the CLI handles exchange-specific naming automatically:
+
+| Input | Hyperliquid | Pacifica | Lighter |
+|-------|-------------|----------|---------|
+| `ICP` | → `ICP-PERP` | → `ICP` | → `ICP` |
+| `BTC` | → `BTC` | → `BTC` | → `BTC` |
+| `SOL` | → `SOL` | → `SOL` | → `SOL` |
+
+- `arb scan` returns bare symbols — pass them directly to trade/leverage commands on any exchange.
+- Do NOT manually add `-PERP` suffix — the CLI resolves this automatically.
+
+## Exchange-Specific Constraints
+
+| Exchange | Min Order (notional) | Notes |
+|----------|---------------------|-------|
+| Hyperliquid | **$10** | Rejects orders below $10 notional |
+| Pacifica | ~$1 (varies by symbol) | Lower minimums |
+| Lighter | Varies by symbol | Check market info |
+
+**`trade check` is advisory only** — it returns `valid: true/false` but does NOT block execution. The exchange itself enforces minimums and will reject with an error if the order is too small.
+
 ## Common Agent Mistakes
 
 1. **Using `perp init`** — interactive, will hang forever. Use `wallet set` instead.
@@ -250,3 +273,5 @@ Error case:
 4. **Retrying a trade without checking** — leads to double positions. Always check `account positions` after a trade, even if it seemed to fail.
 5. **Bridging without quoting** — always run `bridge quote` first to show the user fees and estimated time.
 6. **Assuming deposit is instant** — after `bridge send`, wait for `bridge status` to confirm completion before depositing to the destination exchange.
+7. **Manually adding `-PERP` suffix** — the CLI auto-resolves symbols. Just use bare names like `ICP`, `SOL`, `BTC`.
+8. **Order below exchange minimum** — Hyperliquid requires $10+ notional. Compute `size × price` before submitting.

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

@@ -47,6 +47,8 @@ perp --json trade edit <SYMBOL> <ORDER_ID> <PRICE> <SIZE>
 perp --json trade cancel <SYMBOL> <ORDER_ID>
 perp --json trade cancel-all
 perp --json trade check <SYMBOL> <SIDE> <SIZE>    # pre-flight validation (no execution)
+perp --json trade check <SYM> <SIDE> <SIZE> --leverage 3  # check with specific leverage
+# NOTE: trade check does NOT read exchange-set leverage. Always pass --leverage explicitly.
 
 # Position management
 perp --json trade close <SYMBOL>            # close single position
@@ -87,11 +89,11 @@ perp --json bridge status <ORDER_ID>
 
 ## Arbitrage
 ```bash
-perp --json arb rates                       # compare funding rates across exchanges
-perp --json arb scan --min <BPS>            # find opportunities (>N bps spread)
+perp --json arb scan --min <BPS>            # find opportunities (>N bps spread) — PRIMARY command
 perp --json arb funding                     # detailed funding analysis
 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
 ```
 
 ## Wallet Management

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

@@ -9,7 +9,7 @@ You are not expected to follow rigid rules — use this as a decision framework
 - Funding rates settle **every 1 hour** on all supported exchanges
 - Positive rate = longs pay shorts, negative rate = shorts pay longs
 - Rates are annualized in display but applied hourly: `hourly = annual / 8760`
-- Scan rates: `perp --json arb rates`
+- Scan opportunities: `perp --json arb scan --min 5` (shows spread, longExch, shortExch, netSpread)
 
 ### Opportunity Cost Awareness
 
@@ -56,10 +56,29 @@ During transition, you are **unhedged**. Price can move against you. Factor this
 
 ### Discovery Loop
 ```bash
-perp --json arb rates                    # compare rates across exchanges
-perp --json arb scan --min 10            # find spreads > 10 bps
+perp --json arb scan --min 5             # find spreads > 5 bps (shows longExch/shortExch/netSpread)
+# NOTE: 'arb rates' is deprecated — use 'arb scan' instead
 ```
 
+### CRITICAL: Reading arb scan Results
+
+The `arb scan` output tells you EXACTLY what to do:
+
+```
+longExch: "hyperliquid"   → open LONG on this exchange
+shortExch: "pacifica"     → open SHORT on this exchange
+netSpread: 12.87          → profit after fees (bps/hour)
+```
+
+**Rules:**
+1. **ALWAYS follow longExch/shortExch directions exactly.** DO NOT reverse them.
+2. **NEVER enter if netSpread ≤ 0.** Negative netSpread = loss after fees.
+3. The direction logic: go LONG where funding is negative (longs receive), go SHORT where funding is positive (shorts receive).
+
+**Why these directions?**
+- Positive funding (+) = longs pay shorts → you want to be SHORT to receive
+- Negative funding (-) = shorts pay longs → you want to be LONG to receive
+
 ### Decision Framework
 When evaluating an arb opportunity:
 
@@ -118,53 +137,102 @@ Actual hold: 6h | Actual net: ~130 bps
 perp --json portfolio                    # unified multi-exchange view
 perp --json risk overview                # cross-exchange risk assessment
 perp --json -e <EX> account positions    # per-exchange positions
-perp --json arb rates                    # are current rates still favorable?
+perp --json arb scan --min 5             # are current rates still favorable?
 ```
 
-### Order Execution: Sequential Leg Management
+### Order Execution: Matched Size, Sequential Legs
+
+**The #1 rule of arb execution: BOTH LEGS MUST HAVE THE EXACT SAME SIZE.** A size mismatch means you have net directional exposure — the whole point of arb is to be delta-neutral.
 
-**NEVER close or open both legs of an arb at once with market orders.** You must manage execution carefully.
+#### Step 1: Determine Matched Order Size
 
-#### Why This Matters
-Orderbooks have limited depth at each price level. A large market order will eat through multiple ticks and suffer heavy slippage. Worse, if you close one leg but fail to close the other (exchange error, rate limit, network issue), you are left with naked directional exposure.
+Before placing ANY order, compute a single `ORDER_SIZE` that BOTH exchanges can fill:
 
-#### Pre-Execution: Check Orderbook Depth
-Before executing, verify that the orderbook can absorb your size at acceptable prices on BOTH sides:
 ```bash
-perp --json -e <EX_A> market book <SYM>    # check bids/asks depth
-perp --json -e <EX_B> market book <SYM>    # check bids/asks depth
-```
-
-Look at the size available at the best tick. If your order size exceeds what's available at the best 2-3 ticks, you MUST split the order.
-
-#### Execution Strategy
-1. **Determine executable chunk size** — the largest size both orderbooks can absorb at the best tick without excessive slippage
-2. **Execute in sequential chunks:**
-   ```
-   Chunk 1: close X on Exchange A → immediately open X on Exchange B
-   Chunk 2: close X on Exchange A → immediately open X on Exchange B
-   ... repeat until full size is executed
-   ```
-3. **Verify each chunk** before proceeding to the next:
-   ```bash
-   perp --json -e <EX_A> account positions    # confirm partial close
-   perp --json -e <EX_B> account positions    # confirm partial open
-   ```
-4. **Re-check the orderbook** between chunks — liquidity may have changed
-
-#### Paired Execution Rule
-Each chunk must be a **matched pair**: close on one side, open on the other. Never execute multiple closes without the corresponding opens. If one leg fails:
-- STOP immediately
-- Assess your current exposure
-- Decide whether to retry the failed leg or unwind the completed leg
-- Do NOT continue with remaining chunks
+# 1. Check orderbook depth on BOTH sides
+perp --json -e <LONG_EX> market book <SYM>     # check asks (you're buying)
+perp --json -e <SHORT_EX> market book <SYM>     # check bids (you're selling)
+
+# 2. Find immediately fillable size at best 2-3 ticks
+#    LONG side: sum ask sizes at best 2-3 ask levels → fillable_long
+#    SHORT side: sum bid sizes at best 2-3 bid levels → fillable_short
+
+# 3. ORDER_SIZE = min(fillable_long, fillable_short, desired_size)
+#    The SMALLER side limits your matched size.
+```
+
+**Example:**
+```
+LONG exchange asks:  $85.00 × 0.5, $85.01 × 0.3 → fillable = 0.8
+SHORT exchange bids: $85.10 × 0.4, $85.09 × 0.2 → fillable = 0.6
+Desired size: 1.0
+
+→ ORDER_SIZE = min(0.8, 0.6, 1.0) = 0.6
+→ Both legs get exactly 0.6
+```
+
+**CRITICAL: Each exchange has its own minimum order size and step size.**
+```bash
+perp --json -e <EX> market info <SYM>    # check minOrderSize, stepSize
+```
+Round `ORDER_SIZE` to the coarser step size of the two exchanges. If the matched size falls below either exchange's minimum, the arb is NOT executable at this size — reduce target or skip.
+
+#### Step 2: Execute Legs Sequentially with Same Size
+
+Once you have a single `ORDER_SIZE`, execute both legs using THAT EXACT SIZE:
+
+```bash
+# Leg 1: Open on exchange A
+perp --json -e <LONG_EX> trade market <SYM> buy <ORDER_SIZE>
+
+# Verify leg 1 filled
+perp --json -e <LONG_EX> account positions
+
+# Leg 2: Open on exchange B with SAME size
+perp --json -e <SHORT_EX> trade market <SYM> sell <ORDER_SIZE>
+
+# Verify leg 2 filled
+perp --json -e <SHORT_EX> account positions
+```
+
+**After both legs, verify sizes match:**
+```bash
+perp --json -e <LONG_EX> account positions    # size = X
+perp --json -e <SHORT_EX> account positions   # size must = X
+```
+If sizes differ (partial fill, rounding), immediately adjust the larger position to match the smaller one.
+
+#### Step 3: Split Large Orders into Matched Chunks
+
+If your desired size exceeds what the orderbooks can absorb at best ticks, split into chunks — but **every chunk must be a matched pair with identical size on both sides**:
+
+```
+Chunk 1: buy 0.3 on Exchange A → sell 0.3 on Exchange B → verify both
+Chunk 2: buy 0.3 on Exchange A → sell 0.3 on Exchange B → verify both
+... repeat until full size is executed
+```
+
+**Rules:**
+1. Re-check orderbook depth between chunks — liquidity changes
+2. Each chunk: same size on both sides, no exceptions
+3. If one leg fails → STOP immediately, do NOT continue
+4. Assess exposure: retry the failed leg, or unwind the completed leg
+5. NEVER execute multiple orders on one side without matching the other
 
 #### Using Limit Orders for Better Execution
-For non-urgent transitions, consider limit orders at the best bid/ask instead of market orders:
+For non-urgent entries, use limit orders at best bid/ask instead of market:
+```bash
+perp --json -e <EX> trade buy <SYM> <ORDER_SIZE> -p <PRICE>    # limit order
+```
+This avoids crossing the spread but risks not getting filled. Set a timeout and fall back to market if unfilled. **Both legs must still use the same `ORDER_SIZE`.**
+
+#### Closing Arb Positions: Same Rules Apply
+When exiting, close BOTH legs with the SAME size:
 ```bash
-perp --json -e <EX> trade sell <SYM> <SIZE> -p <PRICE>    # limit order
+perp --json -e <LONG_EX> trade close <SYM>     # closes full position
+perp --json -e <SHORT_EX> trade close <SYM>     # closes full position
 ```
-This avoids crossing the spread, but you risk not getting filled. Set a reasonable timeout and fall back to market if not filled.
+If positions already have mismatched sizes, close to the smaller size first, then close the remaining delta on the larger side.
 
 ### When to Exit
 - Spread compressed below your breakeven (including fees)
@@ -236,18 +304,24 @@ perp --json -e <EX> account settings         # shows leverage and margin_mode pe
 
 ### Risk Limits — Configure Before Trading
 
-Set your risk limits FIRST, before any trading activity:
+Set your risk limits FIRST, before any trading activity.
+Limits can be set in **USD or % of equity** (when both are set, the stricter one applies):
 ```bash
 perp --json risk limits \
   --max-leverage 5 \
   --max-margin 60 \
+  --max-drawdown-pct 10 \
+  --max-position-pct 25 \
+  --max-drawdown 500 \
   --max-position 5000 \
   --max-exposure 20000 \
-  --max-drawdown 500 \
   --daily-loss 200 \
   --min-liq-distance 30
 ```
 
+**Use % limits for small portfolios.** A $65 portfolio with `--max-drawdown 500` is meaningless.
+With `--max-drawdown-pct 10`, the effective limit auto-adjusts to $6.50.
+
 **IMPORTANT: Ask the user about their risk tolerance BEFORE setting limits.** Key questions:
 - "How much leverage are you comfortable with?" (default: 5x for arb)
 - "What's your maximum acceptable loss?" (default: $500)
@@ -281,7 +355,7 @@ Check the output:
 #### Every hour (at funding settlement):
 ```bash
 perp --json portfolio                        # total equity across exchanges
-perp --json arb rates                        # are rates still favorable?
+perp --json arb scan --min 5                  # are rates still favorable?
 perp --json -e <EX_A> account positions      # P&L on leg A
 perp --json -e <EX_B> account positions      # P&L on leg B
 ```

package/skills/perp-cli/templates/arb-scan.sh

@@ -11,9 +11,5 @@ echo "=== Funding Rate Arbitrage Scanner ==="
 echo "Minimum spread: ${MIN_SPREAD} bps"
 echo ""
 
-echo "1. Cross-exchange rates:"
-perp --json arb rates
-
-echo ""
-echo "2. Opportunities (>= ${MIN_SPREAD} bps):"
+echo "1. Opportunities (>= ${MIN_SPREAD} bps):"
 perp --json arb scan --min "$MIN_SPREAD"