perp-cli 0.3.6 → 0.3.8

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

@@ -51,7 +51,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 +90,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

@@ -586,31 +586,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(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(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/index.js

@@ -48,7 +48,7 @@ const _defaultExchange = _settings.defaultExchange || "pacifica";
 program
     .name("perp")
     .description("Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter)")
-    .version("0.3.6")
+    .version("0.3.7")
     .option("-e, --exchange <exchange>", `Exchange: pacifica, hyperliquid, lighter (default: ${_defaultExchange})`, _defaultExchange)
     .option("-n, --network <network>", "Network: mainnet or testnet", "mainnet")
     .option("-k, --private-key <key>", "Private key")
@@ -383,7 +383,7 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                 process.env.LIGHTER_PRIVATE_KEY);
             if (!status.hasWallets && !hasEnvKey && !settings.defaultExchange) {
                 // Fresh install — onboarding
-                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.6\n"));
+                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.7\n"));
                 console.log("  Multi-DEX perpetual futures CLI for Pacifica, Hyperliquid, and Lighter.\n");
                 console.log(`  Get started:  ${chalk.cyan("perp init")}`);
                 console.log(chalk.gray(`\n  Or explore without a wallet:`));
@@ -396,7 +396,7 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                 // Configured — show status overview
                 const defaultEx = settings.defaultExchange || "pacifica";
                 const activeEntries = Object.entries(status.active);
-                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.6\n"));
+                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.7\n"));
                 console.log(`  Default exchange: ${chalk.cyan(defaultEx)}`);
                 if (activeEntries.length > 0) {
                     console.log(chalk.white.bold("\n  Wallets:"));

package/dist/mcp-server.js

@@ -56,7 +56,7 @@ function err(error, meta) {
     return JSON.stringify({ ok: false, error, meta }, null, 2);
 }
 // ── MCP Server ──
-const server = new McpServer({ name: "perp-cli", version: "0.3.6" }, { capabilities: { tools: {}, resources: {} } });
+const server = new McpServer({ name: "perp-cli", version: "0.3.7" }, { capabilities: { tools: {}, resources: {} } });
 // ============================================================
 // Market Data tools (read-only, no private key needed)
 // ============================================================

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.6",
+  "version": "0.3.8",
   "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.6"
+  version: "0.3.8"
   mcp-server: perp-cli
 ---
 
@@ -79,15 +79,52 @@ perp --json portfolio                        # unified multi-exchange view
 
 ### Trade execution (MANDATORY checklist)
 ```
+BEFORE ANY TRADE:
+0. perp --json portfolio                       → check TOTAL equity + per-exchange balances
+   - Single position notional < 25% of TOTAL equity
+   - Each exchange MUST have sufficient balance for its leg
+   - Notional ≠ margin required. Check available balance on EACH exchange.
+   - If balance is insufficient, bridge first or reduce size.
+
 1. perp --json risk status                     → check risk level (STOP if critical)
-2. perp --json -e <EX> account info            → verify balance
+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
+```
+
+### Post-entry monitoring (MANDATORY while positions are open)
+```
+Every 15 minutes:
+  perp --json risk status                      → overall risk level + violations
+  perp --json risk liquidation-distance        → % from liq price for ALL positions
+  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 portfolio                        → total equity across exchanges
+  Compare both legs' unrealized P&L — they should roughly offset
+
+Exit triggers:
+  - Spread below breakeven (including fees) → show exit plan, get user approval
+  - risk status level = "critical" or canTrade = false → reduce immediately
+  - One leg closed unexpectedly → close the other leg IMMEDIATELY
+  - Target hold duration reached → re-evaluate or exit
+```
+
+### Knowing your capital (CHECK BEFORE ANY DECISION)
+```
+perp --json wallet show                        → configured wallets + addresses
+perp --json wallet balance                     → on-chain USDC (in wallet, NOT on exchange)
+perp --json -e <EX> account info               → exchange balance (available for trading)
+perp --json portfolio                          → unified view: equity, margin, P&L per exchange
 ```
+**On-chain balance ≠ exchange balance.** Always check both. Capital must be deposited to exchange before trading.
 
 For full command reference, see `references/commands.md`.
 For agent-specific operations (setup flows, deposit/withdraw, order types, idempotency), see `references/agent-operations.md`.

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

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

@@ -236,18 +236,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)
@@ -310,6 +316,26 @@ Rules of thumb:
 - **Total margin used < 60% of total equity** — leave buffer for adverse moves
 - **Capital in transit (bridging) counts as "at risk"** — it's not available for margin
 
+### Per-Exchange Balance Constraints
+
+**CRITICAL: You can only trade with the balance available ON THAT EXCHANGE.**
+
+Each exchange holds its own separate balance. Before entering any arb:
+```bash
+perp --json -e <EX_A> account info           # check available balance on exchange A
+perp --json -e <EX_B> account info           # check available balance on exchange B
+```
+
+**Size each leg to fit the available balance on that exchange:**
+```
+Wrong:  total portfolio = $65 → 25% = $16 per leg → but Exchange A only has $10
+Right:  Exchange A has $10, Exchange B has $15 → max leg size = $10 (limited by smaller side)
+```
+
+If one exchange has insufficient balance:
+- Reduce position size to fit the smaller balance, OR
+- Bridge capital first (but account for bridge fees + time + unhedged risk during transit)
+
 ### Stop Loss for Arb Positions
 
 Even "market-neutral" arb can lose money if: