perp-cli 0.3.3 → 0.3.5

package/README.md

@@ -178,21 +178,25 @@ perp alert daemon --interval 30
 
 ## Claude Code Agent Skill
 
-Install as a Claude Code plugin to let Claude trade for you:
+Install as a Claude Code plugin or via the universal skills CLI:
 
 ```bash
-# In Claude Code
+# Universal skill installer (works with Claude Code, Cursor, Codex, Gemini CLI, etc.)
+npx skills add hypurrquant/perp-cli
+
+# Or in Claude Code directly
 /plugin marketplace add hypurrquant/perp-cli
-/plugin install perp-trading@hypurrquant-perp-cli
+/plugin install perp-cli
 ```
 
-Once installed, use `/perp-trading` in Claude Code:
+Once installed, Claude can trade for you via natural language:
 
 ```
-/perp-trading status                          # Check all exchanges
-/perp-trading BTC 0.01 long on hyperliquid    # Natural language trading
-/perp-trading scan arb opportunities          # Find funding rate arb
-/perp-trading bridge 100 USDC solana to arb   # Cross-chain bridge
+perp --json wallet show                       # Check configured wallets
+perp --json -e hl market list                 # Browse markets
+perp --json -e hl trade buy BTC 0.01          # Execute trades
+perp --json arb rates                         # Find funding rate arb
+perp --json bridge quote --from solana --to arbitrum --amount 100
 ```
 
 The skill includes safety guardrails (balance checks, user confirmation before trades, error handling with retries).

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { assessRisk, preTradeCheck } from "../risk.js";
+import { assessRisk, preTradeCheck, calcLiquidationDistance, getLiquidationDistances, LIQUIDATION_DISTANCE_HARD_CAP } from "../risk.js";
 const defaultLimits = {
     maxDrawdownUsd: 500,
     maxPositionUsd: 5000,
@@ -8,12 +8,13 @@ const defaultLimits = {
     maxPositions: 10,
     maxLeverage: 20,
     maxMarginUtilization: 80,
+    minLiquidationDistance: 30,
 };
 function makeBalance(equity, available, marginUsed, pnl) {
     return { equity: String(equity), available: String(available), marginUsed: String(marginUsed), unrealizedPnl: String(pnl) };
 }
-function makePosition(symbol, side, size, markPrice, leverage, pnl) {
-    return { symbol, side, size: String(size), entryPrice: String(markPrice), markPrice: String(markPrice), liquidationPrice: "0", unrealizedPnl: String(pnl), leverage };
+function makePosition(symbol, side, size, markPrice, leverage, pnl, liquidationPrice = "0") {
+    return { symbol, side, size: String(size), entryPrice: String(markPrice), markPrice: String(markPrice), liquidationPrice, unrealizedPnl: String(pnl), leverage };
 }
 describe("Risk Assessment", () => {
     it("should return low risk when everything is within limits", () => {
@@ -143,3 +144,123 @@ describe("Pre-Trade Check", () => {
         expect(result.reason).toContain("Leverage");
     });
 });
+describe("calcLiquidationDistance", () => {
+    it("should calculate distance for long position (liq below mark)", () => {
+        // Long at $100000, liq at $80000 → 20% distance
+        const dist = calcLiquidationDistance(100000, 80000, "long");
+        expect(dist).toBeCloseTo(20, 1);
+    });
+    it("should calculate distance for short position (liq above mark)", () => {
+        // Short at $100000, liq at $120000 → 20% distance
+        const dist = calcLiquidationDistance(100000, 120000, "short");
+        expect(dist).toBeCloseTo(20, 1);
+    });
+    it("should return Infinity when liquidation price is 0 or N/A", () => {
+        expect(calcLiquidationDistance(100000, 0, "long")).toBe(Infinity);
+        expect(calcLiquidationDistance(0, 80000, "long")).toBe(Infinity);
+    });
+    it("should handle very close liquidation (dangerous)", () => {
+        // Long at $100000, liq at $95000 → 5% distance
+        const dist = calcLiquidationDistance(100000, 95000, "long");
+        expect(dist).toBeCloseTo(5, 1);
+    });
+    it("should handle very safe distance", () => {
+        // Long at $100000, liq at $50000 → 50% distance
+        const dist = calcLiquidationDistance(100000, 50000, "long");
+        expect(dist).toBeCloseTo(50, 1);
+    });
+});
+describe("getLiquidationDistances", () => {
+    it("should return sorted by distance (closest first)", () => {
+        const positions = [
+            { exchange: "hl", position: makePosition("ETH", "long", 1, 3500, 5, 0, "3000") }, // ~14.3%
+            { exchange: "pac", position: makePosition("BTC", "long", 0.01, 100000, 2, 0, "50000") }, // 50%
+            { exchange: "hl", position: makePosition("SOL", "short", 10, 150, 10, 0, "165") }, // 10%
+        ];
+        const distances = getLiquidationDistances(positions, defaultLimits);
+        expect(distances.length).toBe(3);
+        expect(distances[0].symbol).toBe("SOL"); // closest to liq
+        expect(distances[1].symbol).toBe("ETH");
+        expect(distances[2].symbol).toBe("BTC"); // safest
+    });
+    it("should assign correct status based on limits", () => {
+        const limits = { ...defaultLimits, minLiquidationDistance: 30 };
+        const positions = [
+            { exchange: "a", position: makePosition("A", "long", 1, 100, 2, 0, "85") }, // 15% → critical (< 20% hard cap)
+            { exchange: "b", position: makePosition("B", "long", 1, 100, 2, 0, "78") }, // 22% → danger (< 30% user limit)
+            { exchange: "c", position: makePosition("C", "long", 1, 100, 2, 0, "65") }, // 35% → warning (< 30% * 1.5 = 45%)
+            { exchange: "d", position: makePosition("D", "long", 1, 100, 2, 0, "40") }, // 60% → safe
+        ];
+        const distances = getLiquidationDistances(positions, limits);
+        expect(distances.find(d => d.symbol === "A").status).toBe("critical");
+        expect(distances.find(d => d.symbol === "B").status).toBe("danger");
+        expect(distances.find(d => d.symbol === "C").status).toBe("warning");
+        expect(distances.find(d => d.symbol === "D").status).toBe("safe");
+    });
+    it("should skip positions with liquidationPrice 0 or N/A", () => {
+        const positions = [
+            { exchange: "a", position: makePosition("BTC", "long", 1, 100000, 5, 0, "0") },
+            { exchange: "b", position: makePosition("ETH", "long", 1, 3500, 5, 0, "N/A") },
+            { exchange: "c", position: makePosition("SOL", "long", 1, 150, 5, 0, "120") }, // valid
+        ];
+        const distances = getLiquidationDistances(positions, defaultLimits);
+        expect(distances.length).toBe(1);
+        expect(distances[0].symbol).toBe("SOL");
+    });
+});
+describe("Liquidation Distance in assessRisk", () => {
+    it("should add critical violation when position is below hard cap (20%)", () => {
+        const balances = [{ exchange: "test", balance: makeBalance(10000, 8000, 2000, 0) }];
+        // BTC long at $100000, liq at $90000 → 10% distance (below 20% hard cap)
+        const positions = [{ exchange: "test", position: makePosition("BTC", "long", 0.01, 100000, 10, 0, "90000") }];
+        const result = assessRisk(balances, positions, defaultLimits);
+        expect(result.violations.some(v => v.rule === "liquidation_distance_hard_cap")).toBe(true);
+        expect(result.level).toBe("critical");
+        expect(result.canTrade).toBe(false);
+    });
+    it("should add high violation when below user limit but above hard cap", () => {
+        const limits = { ...defaultLimits, minLiquidationDistance: 30 };
+        const balances = [{ exchange: "test", balance: makeBalance(10000, 8000, 2000, 0) }];
+        // BTC long at $100000, liq at $75000 → 25% distance (above 20% hard cap, below 30% user limit)
+        const positions = [{ exchange: "test", position: makePosition("BTC", "long", 0.01, 100000, 4, 0, "75000") }];
+        const result = assessRisk(balances, positions, limits);
+        expect(result.violations.some(v => v.rule === "min_liquidation_distance")).toBe(true);
+        expect(result.violations.some(v => v.rule === "liquidation_distance_hard_cap")).toBe(false);
+    });
+    it("should not add violation when distance is above user limit", () => {
+        const balances = [{ exchange: "test", balance: makeBalance(10000, 8000, 2000, 0) }];
+        // BTC long at $100000, liq at $50000 → 50% distance (safe)
+        const positions = [{ exchange: "test", position: makePosition("BTC", "long", 0.01, 100000, 2, 0, "50000") }];
+        const result = assessRisk(balances, positions, defaultLimits);
+        expect(result.violations.some(v => v.rule === "liquidation_distance_hard_cap")).toBe(false);
+        expect(result.violations.some(v => v.rule === "min_liquidation_distance")).toBe(false);
+    });
+    it("should report minLiquidationDistancePct in metrics", () => {
+        const balances = [{ exchange: "test", balance: makeBalance(10000, 8000, 2000, 0) }];
+        const positions = [
+            { exchange: "a", position: makePosition("BTC", "long", 0.01, 100000, 2, 0, "60000") }, // 40%
+            { exchange: "b", position: makePosition("ETH", "short", 1, 3500, 5, 0, "4200") }, // 20%
+        ];
+        const result = assessRisk(balances, positions, defaultLimits);
+        expect(result.metrics.minLiquidationDistancePct).toBeCloseTo(20, 1);
+    });
+    it("should report -1 for minLiquidationDistancePct when no positions", () => {
+        const result = assessRisk([], [], defaultLimits);
+        expect(result.metrics.minLiquidationDistancePct).toBe(-1);
+    });
+    it("should include liquidationDistances array in assessment", () => {
+        const balances = [{ exchange: "test", balance: makeBalance(10000, 8000, 2000, 0) }];
+        // BTC long at $100000, liq at $30000 → 70% distance (well above 30% * 1.5 = 45% → safe)
+        const positions = [{ exchange: "test", position: makePosition("BTC", "long", 0.01, 100000, 2, 0, "30000") }];
+        const result = assessRisk(balances, positions, defaultLimits);
+        expect(result.liquidationDistances).toHaveLength(1);
+        expect(result.liquidationDistances[0].symbol).toBe("BTC");
+        expect(result.liquidationDistances[0].distancePct).toBeCloseTo(70, 1);
+        expect(result.liquidationDistances[0].status).toBe("safe");
+    });
+});
+describe("LIQUIDATION_DISTANCE_HARD_CAP", () => {
+    it("should be 20", () => {
+        expect(LIQUIDATION_DISTANCE_HARD_CAP).toBe(20);
+    });
+});

package/dist/commands/manage.js

@@ -1,5 +1,6 @@
 import { PacificaAdapter } from "../exchanges/pacifica.js";
 import { printJson, jsonOk } from "../utils.js";
+import { setEnvVar } from "./init.js";
 import chalk from "chalk";
 export function registerManageCommands(program, getAdapter, isJson, getPacificaAdapter) {
     const manage = program.command("manage").description("Account management");
@@ -288,6 +289,9 @@ export function registerManageCommands(program, getAdapter, isJson, getPacificaA
             console.log(chalk.gray("  Generating key pair + registering on-chain...\n"));
         }
         const { privateKey, publicKey } = await adapter.setupApiKey(keyIndex);
+        // Auto-save to .env
+        setEnvVar("LIGHTER_API_KEY", privateKey);
+        setEnvVar("LIGHTER_ACCOUNT_INDEX", String(adapter.accountIndex));
         if (isJson()) {
             return printJson(jsonOk({
                 privateKey,
@@ -295,15 +299,13 @@ export function registerManageCommands(program, getAdapter, isJson, getPacificaA
                 address: adapter.address,
                 accountIndex: adapter.accountIndex,
                 apiKeyIndex: keyIndex,
+                savedToEnv: true,
             }));
         }
-        console.log(chalk.green("  API Key Registered!\n"));
+        console.log(chalk.green("  API Key Registered & saved to ~/.perp/.env\n"));
         console.log(`  ${chalk.bold("Private Key:")} ${privateKey}`);
         console.log(`  ${chalk.bold("Public Key:")}  ${publicKey}`);
-        console.log();
-        console.log(chalk.yellow("  Add to your .env file:"));
-        console.log(chalk.white(`  LIGHTER_API_KEY=${privateKey}`));
-        console.log(chalk.white(`  LIGHTER_ACCOUNT_INDEX=${adapter.accountIndex}`));
+        console.log(`  ${chalk.bold("Account:")}     ${adapter.accountIndex}`);
         console.log();
     });
 }

package/dist/commands/risk.js

@@ -1,6 +1,6 @@
 import chalk from "chalk";
 import { printJson, jsonOk, makeTable, formatUsd, withJsonErrors } from "../utils.js";
-import { loadRiskLimits, saveRiskLimits, assessRisk } from "../risk.js";
+import { loadRiskLimits, saveRiskLimits, assessRisk, getLiquidationDistances, LIQUIDATION_DISTANCE_HARD_CAP } from "../risk.js";
 const EXCHANGES = ["pacifica", "hyperliquid", "lighter"];
 export function registerRiskCommands(program, getAdapterForExchange, isJson) {
     const risk = program.command("risk").description("Risk management and guardrails");
@@ -56,6 +56,14 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
             console.log(`  Positions:            ${assessment.metrics.positionCount}`);
             console.log(`  Largest Position:     $${formatUsd(assessment.metrics.largestPositionUsd)}`);
             console.log(`  Max Leverage Used:    ${assessment.metrics.maxLeverageUsed}x`);
+            if (assessment.metrics.minLiquidationDistancePct >= 0) {
+                const ldColor = assessment.metrics.minLiquidationDistancePct < LIQUIDATION_DISTANCE_HARD_CAP
+                    ? chalk.bgRed.white
+                    : assessment.metrics.minLiquidationDistancePct < assessment.limits.minLiquidationDistance
+                        ? chalk.red
+                        : chalk.green;
+                console.log(`  Min Liq Distance:     ${ldColor(`${assessment.metrics.minLiquidationDistancePct.toFixed(1)}%`)}`);
+            }
             if (assessment.violations.length > 0) {
                 console.log(chalk.red.bold("\n  Violations"));
                 const vRows = assessment.violations.map(v => {
@@ -89,15 +97,18 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
         .option("--max-positions <n>", "Max number of simultaneous positions")
         .option("--max-leverage <n>", "Max leverage per position")
         .option("--max-margin <pct>", "Max margin utilization %")
+        .option("--min-liq-distance <pct>", `Min liquidation distance % (hard cap: >=${LIQUIDATION_DISTANCE_HARD_CAP}%)`)
         .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 || opts.reset;
+            opts.dailyLoss || 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,
             };
         }
         if (opts.maxDrawdown)
@@ -114,6 +125,17 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
             limits.maxLeverage = parseInt(opts.maxLeverage);
         if (opts.maxMargin)
             limits.maxMarginUtilization = parseFloat(opts.maxMargin);
+        if (opts.minLiqDistance) {
+            const val = parseFloat(opts.minLiqDistance);
+            if (val < LIQUIDATION_DISTANCE_HARD_CAP) {
+                const msg = `Cannot set min liquidation distance below ${LIQUIDATION_DISTANCE_HARD_CAP}% (hard cap). Got: ${val}%`;
+                if (isJson())
+                    return printJson(jsonOk({ error: msg, hardCap: LIQUIDATION_DISTANCE_HARD_CAP }));
+                console.log(chalk.red(`\n  ${msg}\n`));
+                return;
+            }
+            limits.minLiquidationDistance = val;
+        }
         if (hasUpdate)
             saveRiskLimits(limits);
         if (isJson())
@@ -125,7 +147,8 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
         console.log(`  Daily Loss Limit:      $${formatUsd(limits.dailyLossLimitUsd)}`);
         console.log(`  Max Positions:         ${limits.maxPositions}`);
         console.log(`  Max Leverage:          ${limits.maxLeverage}x`);
-        console.log(`  Max Margin Util:       ${limits.maxMarginUtilization}%\n`);
+        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(chalk.gray(`  Config file: ~/.perp/risk.json\n`));
     });
     // ── risk check ── (pre-trade check, for agent use)
@@ -166,4 +189,84 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
             }
         });
     });
+    // ── risk liquidation-distance ──
+    risk
+        .command("liquidation-distance")
+        .description("Show % distance from liquidation price for all positions")
+        .alias("liq-dist")
+        .option("--exchange <exchanges>", "Comma-separated exchanges (default: all)")
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            const exchanges = opts.exchange
+                ? opts.exchange.split(",").map(e => e.trim())
+                : [...EXCHANGES];
+            const positions = [];
+            const results = await Promise.allSettled(exchanges.map(async (ex) => {
+                const adapter = await getAdapterForExchange(ex);
+                const pos = await adapter.getPositions();
+                for (const p of pos)
+                    positions.push({ exchange: ex, position: p });
+            }));
+            for (let i = 0; i < results.length; i++) {
+                if (results[i].status === "rejected") {
+                    const err = results[i].reason;
+                    if (!isJson()) {
+                        console.log(chalk.yellow(`  ${exchanges[i]}: ${err instanceof Error ? err.message : String(err)}`));
+                    }
+                }
+            }
+            if (positions.length === 0) {
+                if (isJson())
+                    return printJson(jsonOk({ positions: [], message: "No open positions" }));
+                console.log(chalk.gray("\n  No open positions.\n"));
+                return;
+            }
+            const limits = loadRiskLimits();
+            const distances = getLiquidationDistances(positions, limits);
+            if (isJson()) {
+                return printJson(jsonOk({
+                    positions: distances,
+                    limits: {
+                        minLiquidationDistance: limits.minLiquidationDistance,
+                        hardCap: LIQUIDATION_DISTANCE_HARD_CAP,
+                    },
+                }));
+            }
+            console.log(chalk.cyan.bold("\n  Liquidation Distance Report\n"));
+            console.log(chalk.gray(`  Your limit: ${limits.minLiquidationDistance}%  |  Hard cap: ${LIQUIDATION_DISTANCE_HARD_CAP}%\n`));
+            const rows = distances.map(d => {
+                const statusColor = {
+                    safe: chalk.green,
+                    warning: chalk.yellow,
+                    danger: chalk.red,
+                    critical: chalk.bgRed.white,
+                }[d.status];
+                return [
+                    chalk.white(d.exchange),
+                    chalk.white.bold(d.symbol),
+                    d.side === "long" ? chalk.green("LONG") : chalk.red("SHORT"),
+                    `$${formatUsd(d.markPrice)}`,
+                    `$${formatUsd(d.liquidationPrice)}`,
+                    statusColor(`${d.distancePct.toFixed(1)}%`),
+                    statusColor(d.status.toUpperCase()),
+                ];
+            });
+            console.log(makeTable(["Exchange", "Symbol", "Side", "Mark Price", "Liq Price", "Distance", "Status"], rows));
+            // Summary warnings
+            const critical = distances.filter(d => d.status === "critical");
+            const danger = distances.filter(d => d.status === "danger");
+            if (critical.length > 0) {
+                console.log(chalk.bgRed.white.bold(`  ⚠ ${critical.length} position(s) BELOW HARD CAP (${LIQUIDATION_DISTANCE_HARD_CAP}%) — REDUCE IMMEDIATELY`));
+            }
+            if (danger.length > 0) {
+                console.log(chalk.red.bold(`  ⚠ ${danger.length} position(s) below your limit (${limits.minLiquidationDistance}%) — action recommended`));
+            }
+            if (critical.length === 0 && danger.length === 0) {
+                console.log(chalk.green("  All positions within safe liquidation distance.\n"));
+            }
+            else {
+                console.log();
+            }
+        });
+    });
 }

package/dist/commands/wallet.js

@@ -382,13 +382,41 @@ export function registerWalletCommands(program, isJson) {
             settings.defaultExchange = resolved;
             saveSettings(settings);
         }
+        // Auto-setup Lighter API key if setting lighter PK
+        let lighterApiSetup = {};
+        if (resolved === "lighter") {
+            try {
+                const { LighterAdapter } = await import("../exchanges/lighter.js");
+                const adapter = new LighterAdapter(normalized);
+                await adapter.init();
+                const { privateKey: apiKey } = await adapter.setupApiKey();
+                setEnvVar("LIGHTER_API_KEY", apiKey);
+                setEnvVar("LIGHTER_ACCOUNT_INDEX", String(adapter.accountIndex));
+                lighterApiSetup = { apiKey, accountIndex: adapter.accountIndex };
+            }
+            catch (e) {
+                lighterApiSetup = { error: e instanceof Error ? e.message : String(e) };
+            }
+        }
         if (isJson())
-            return printJson(jsonOk({ exchange: resolved, address, envFile: ENV_FILE, default: !!opts.default }));
+            return printJson(jsonOk({
+                exchange: resolved, address, envFile: ENV_FILE, default: !!opts.default,
+                ...(resolved === "lighter" && { lighterApiKey: lighterApiSetup }),
+            }));
         console.log(chalk.green(`\n  ${resolved} configured.`));
         console.log(`  Address:  ${chalk.green(address)}`);
         console.log(`  Saved to: ${chalk.gray("~/.perp/.env")}`);
         if (opts.default)
             console.log(`  Default:  ${chalk.cyan(resolved)}`);
+        if (resolved === "lighter") {
+            if (lighterApiSetup.apiKey) {
+                console.log(chalk.green(`  API Key:  auto-registered (index: ${lighterApiSetup.accountIndex})`));
+            }
+            else {
+                console.log(chalk.yellow(`  API Key:  setup failed — ${lighterApiSetup.error}`));
+                console.log(chalk.gray(`  You can retry: perp -e lighter manage setup-api-key`));
+            }
+        }
         console.log();
     });
     // ── show (show configured exchanges with public addresses) ──

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.3")
+    .version("0.3.5")
     .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.3\n"));
+                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.5\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.3\n"));
+                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.5\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.3" }, { capabilities: { tools: {}, resources: {} } });
+const server = new McpServer({ name: "perp-cli", version: "0.3.5" }, { capabilities: { tools: {}, resources: {} } });
 // ============================================================
 // Market Data tools (read-only, no private key needed)
 // ============================================================

package/dist/risk.d.ts

@@ -7,7 +7,10 @@ export interface RiskLimits {
     maxPositions: number;
     maxLeverage: number;
     maxMarginUtilization: number;
+    minLiquidationDistance: number;
 }
+/** Hard cap: liquidation distance can NEVER be set below this % */
+export declare const LIQUIDATION_DISTANCE_HARD_CAP = 20;
 export declare function loadRiskLimits(): RiskLimits;
 export declare function saveRiskLimits(limits: RiskLimits): void;
 export type RiskLevel = "low" | "medium" | "high" | "critical";
@@ -18,6 +21,21 @@ export interface RiskViolation {
     current: number;
     limit: number;
 }
+export interface LiquidationDistanceInfo {
+    exchange: string;
+    symbol: string;
+    side: "long" | "short";
+    markPrice: number;
+    liquidationPrice: number;
+    distancePct: number;
+    status: "safe" | "warning" | "danger" | "critical";
+}
+/** Calculate % distance from current price to liquidation price */
+export declare function calcLiquidationDistance(markPrice: number, liquidationPrice: number, side: "long" | "short"): number;
+export declare function getLiquidationDistances(positions: {
+    exchange: string;
+    position: ExchangePosition;
+}[], limits?: RiskLimits): LiquidationDistanceInfo[];
 export interface RiskAssessment {
     level: RiskLevel;
     violations: RiskViolation[];
@@ -30,7 +48,9 @@ export interface RiskAssessment {
         marginUtilization: number;
         largestPositionUsd: number;
         maxLeverageUsed: number;
+        minLiquidationDistancePct: number;
     };
+    liquidationDistances: LiquidationDistanceInfo[];
     limits: RiskLimits;
     canTrade: boolean;
 }

package/dist/risk.js

@@ -8,7 +8,10 @@ const DEFAULT_LIMITS = {
     maxPositions: 10,
     maxLeverage: 20,
     maxMarginUtilization: 80,
+    minLiquidationDistance: 30,
 };
+/** 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");
 const RISK_FILE = resolve(PERP_DIR, "risk.json");
 export function loadRiskLimits() {
@@ -27,6 +30,38 @@ export function saveRiskLimits(limits) {
         mkdirSync(PERP_DIR, { recursive: true, mode: 0o700 });
     writeFileSync(RISK_FILE, JSON.stringify(limits, null, 2), { mode: 0o600 });
 }
+/** Calculate % distance from current price to liquidation price */
+export function calcLiquidationDistance(markPrice, liquidationPrice, side) {
+    if (liquidationPrice <= 0 || markPrice <= 0)
+        return Infinity;
+    if (side === "long") {
+        // Long: liq price is below mark price
+        return ((markPrice - liquidationPrice) / markPrice) * 100;
+    }
+    else {
+        // Short: liq price is above mark price
+        return ((liquidationPrice - markPrice) / markPrice) * 100;
+    }
+}
+export function getLiquidationDistances(positions, limits) {
+    const lim = limits ?? loadRiskLimits();
+    return positions
+        .filter(({ position: p }) => p.liquidationPrice !== "N/A" && Number(p.liquidationPrice) > 0)
+        .map(({ exchange, position: p }) => {
+        const markPrice = Number(p.markPrice);
+        const liquidationPrice = Number(p.liquidationPrice);
+        const distancePct = calcLiquidationDistance(markPrice, liquidationPrice, p.side);
+        let status = "safe";
+        if (distancePct < LIQUIDATION_DISTANCE_HARD_CAP)
+            status = "critical";
+        else if (distancePct < lim.minLiquidationDistance)
+            status = "danger";
+        else if (distancePct < lim.minLiquidationDistance * 1.5)
+            status = "warning";
+        return { exchange, symbol: p.symbol, side: p.side, markPrice, liquidationPrice, distancePct, status };
+    })
+        .sort((a, b) => a.distancePct - b.distancePct);
+}
 export function assessRisk(balances, positions, limits) {
     const lim = limits ?? loadRiskLimits();
     const violations = [];
@@ -107,6 +142,34 @@ export function assessRisk(balances, positions, limits) {
             limit: lim.maxMarginUtilization,
         });
     }
+    // Check liquidation distances
+    const liquidationDistances = getLiquidationDistances(positions, lim);
+    let minLiquidationDistancePct = Infinity;
+    for (const ld of liquidationDistances) {
+        if (ld.distancePct < minLiquidationDistancePct) {
+            minLiquidationDistancePct = ld.distancePct;
+        }
+        if (ld.distancePct < LIQUIDATION_DISTANCE_HARD_CAP) {
+            violations.push({
+                rule: "liquidation_distance_hard_cap",
+                severity: "critical",
+                message: `${ld.exchange}:${ld.symbol} is ${ld.distancePct.toFixed(1)}% from liquidation (hard cap: ${LIQUIDATION_DISTANCE_HARD_CAP}%)`,
+                current: ld.distancePct,
+                limit: LIQUIDATION_DISTANCE_HARD_CAP,
+            });
+        }
+        else if (ld.distancePct < lim.minLiquidationDistance) {
+            violations.push({
+                rule: "min_liquidation_distance",
+                severity: "high",
+                message: `${ld.exchange}:${ld.symbol} is ${ld.distancePct.toFixed(1)}% from liquidation (limit: ${lim.minLiquidationDistance}%)`,
+                current: ld.distancePct,
+                limit: lim.minLiquidationDistance,
+            });
+        }
+    }
+    if (minLiquidationDistancePct === Infinity)
+        minLiquidationDistancePct = -1; // no positions
     // Determine overall risk level
     let level = "low";
     if (violations.some(v => v.severity === "critical"))
@@ -129,7 +192,9 @@ export function assessRisk(balances, positions, limits) {
             marginUtilization,
             largestPositionUsd,
             maxLeverageUsed,
+            minLiquidationDistancePct,
         },
+        liquidationDistances,
         limits: lim,
         canTrade,
     };

package/package.json

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