perp-cli 0.3.3 → 0.3.4

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/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/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.4")
     .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.4\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.4\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.4" }, { 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.4",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "./dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: perp-cli
 description: "Multi-DEX perpetual futures trading CLI for Pacifica (Solana), Hyperliquid (EVM), and Lighter (Ethereum). Use when user asks to trade perps, check funding rates, bridge USDC, manage positions, scan arbitrage opportunities, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, or Lighter exchanges. Also use when user says 'set up perp trading', 'check my positions', 'buy BTC perps', 'funding rate arb', 'bridge USDC', or 'deposit to exchange'."
+allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.3.3"
+  version: "0.3.4"
   mcp-server: perp-cli
 ---
 
@@ -14,10 +15,13 @@ Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), L
 
 ## Critical Rules
 
-1. **NEVER use interactive commands.** Do NOT run `perp init`. Always use non-interactive commands with `--json`.
-2. **Always use `--json`** on every command for structured output.
-3. **NEVER trade without user confirmation.** Show order details and wait for explicit approval.
-4. **Verify wallet before any operation.** Run `perp --json wallet show` first.
+1. **RISK MANAGEMENT IS YOUR #1 PRIORITY.** A single liquidation wipes out months of profit. Always check `perp --json risk status` before and during any operation. See `references/strategies.md` for the full risk framework.
+2. **NEVER use interactive commands.** Do NOT run `perp init`. Always use non-interactive commands with `--json`.
+3. **Always use `--json`** on every command for structured output.
+4. **NEVER trade without user confirmation.** Show order details and wait for explicit approval.
+5. **Verify wallet before any operation.** Run `perp --json wallet show` first.
+6. **Use ISOLATED margin for arb.** Set `perp --json manage margin <SYM> isolated` before opening positions. Cross margin can cascade liquidations.
+7. **Monitor positions continuously.** Run `perp --json risk status` and `perp --json -e <EX> account positions` every 15 minutes while positions are open.
 
 ## Step 1: Install
 
@@ -74,15 +78,19 @@ perp --json portfolio                        # unified multi-exchange view
 
 ### Trade execution (MANDATORY checklist)
 ```
-1. perp --json -e <EX> account info           → verify balance
-2. perp --json -e <EX> market mid <SYM>       → current price
-3. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> → pre-flight validation
-4. [Show order details to user, get explicit confirmation]
-5. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE> → execute
-6. perp --json -e <EX> account positions      → verify result
+1. perp --json risk status                     → check risk level (STOP if critical)
+2. perp --json -e <EX> account info            → verify 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
 ```
 
 For full command reference, see `references/commands.md`.
+For agent-specific operations (setup flows, deposit/withdraw, order types, idempotency), see `references/agent-operations.md`.
+For autonomous strategies (funding rate arb, risk management, opportunity cost), see `references/strategies.md`.
 
 ## Response Format
 

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

@@ -0,0 +1,243 @@
+# Agent Operations Guide
+
+Complete reference for non-interactive CLI operations. Every command here is safe for agents — no prompts, no hangs.
+
+## Interactive vs Non-Interactive Commands
+
+### NEVER use these (interactive, will hang):
+```
+perp init                    # interactive wizard — asks questions via stdin
+perp wallet setup            # removed, but may appear in old docs
+```
+
+### ALWAYS use these (non-interactive, agent-safe):
+```bash
+perp --json wallet set <exchange> <key>     # set private key
+perp --json wallet generate evm             # generate EVM wallet
+perp --json wallet generate solana          # generate Solana wallet
+perp --json wallet show                     # check configured wallets
+perp --json wallet balance                  # on-chain USDC balances
+perp --json -e <EX> account info            # exchange account info
+perp --json -e <EX> account positions       # open positions
+perp --json -e <EX> market list             # available markets
+perp --json -e <EX> trade market ...        # execute trade
+perp --json -e <EX> trade buy ...           # alias for market buy
+perp --json -e <EX> trade sell ...          # alias for market sell
+perp --json risk status                     # risk assessment
+perp --json risk liquidation-distance       # % from liquidation for all positions
+perp --json risk limits                     # view/set risk limits
+perp --json risk check --notional <$> --leverage <L>  # pre-trade risk check
+```
+
+**Rule: every command MUST include `--json`.** Without it, output is human-formatted and harder to parse.
+
+## Zero to Trading: Complete Setup Flow
+
+### Single Exchange Setup
+```bash
+# 1. Install
+npm install -g perp-cli
+
+# 2. Register wallet (user provides key)
+perp --json wallet set hl 0xUSER_PRIVATE_KEY
+
+# 3. Verify
+perp --json wallet show
+# → check "ok": true and address appears
+
+# 4. Check balance
+perp --json -e hl account info
+# → if balance is 0, tell user to deposit USDC
+
+# 5. Ready to trade
+perp --json -e hl market list
+```
+
+### Multi-Exchange Setup (for Funding Rate Arb)
+To run arb, you need wallets on AT LEAST 2 exchanges. Each exchange needs:
+- A configured wallet with a private key
+- USDC balance deposited on-exchange
+
+```bash
+# 1. Register both wallets
+perp --json wallet set hl 0xEVM_KEY
+perp --json wallet set pac SOLANA_BASE58_KEY
+
+# 2. Verify both
+perp --json wallet show
+# → should show both exchanges with addresses
+
+# 3. Check balances on both
+perp --json -e hl account info
+perp --json -e pac account info
+
+# 4. If one side needs funding, bridge USDC
+perp --json bridge quote --from solana --to arbitrum --amount 500
+# → show quote to user, get confirmation
+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
+```
+
+### Using the Same EVM Key for Multiple Exchanges
+One EVM private key works for both Hyperliquid and Lighter:
+```bash
+perp --json wallet set hl 0xKEY
+perp --json wallet set lt 0xKEY        # same key, different exchange binding
+```
+
+## Wallet Key Types
+
+| Exchange | Chain | Key Format | Example |
+|----------|-------|-----------|---------|
+| Hyperliquid | EVM | Hex with 0x prefix, 66 chars | `0x4c0883a69102937d...` |
+| Lighter | EVM | Hex with 0x prefix, 66 chars | `0x4c0883a69102937d...` |
+| Pacifica | Solana | Base58 string | `5KQwrPbwdL6PhXu...` |
+
+Aliases for exchange names:
+- `hl` or `hyperliquid`
+- `pac` or `pacifica`
+- `lt` or `lighter`
+
+## Deposit & Withdraw Flows
+
+### Check On-Chain vs Exchange Balance
+```bash
+perp --json wallet balance               # on-chain USDC in your wallet
+perp --json -e hl account info           # USDC deposited on exchange
+```
+
+**On-chain balance ≠ exchange balance.** USDC in your wallet must be deposited to the exchange before trading.
+
+### Deposit to Exchange
+```bash
+# Hyperliquid (from Arbitrum wallet)
+perp --json deposit hyperliquid 100
+
+# Pacifica (from Solana wallet)
+perp --json deposit pacifica 100
+
+# Lighter (multiple routes)
+perp --json deposit lighter info         # show all available routes
+perp --json deposit lighter cctp arb 100 # via CCTP from Arbitrum
+```
+
+### Withdraw from Exchange
+```bash
+perp --json withdraw hyperliquid 100
+perp --json withdraw pacifica 100
+```
+
+### Bridge Between Chains
+When you need to move USDC between exchanges on different chains:
+```bash
+# 1. Withdraw from source exchange
+perp --json withdraw pacifica 500
+
+# 2. Quote the bridge
+perp --json bridge quote --from solana --to arbitrum --amount 500
+
+# 3. Send (after user confirmation)
+perp --json bridge send --from solana --to arbitrum --amount 500
+
+# 4. Wait for completion
+perp --json bridge status <orderId>
+
+# 5. Deposit to destination exchange
+perp --json deposit hyperliquid 500
+```
+
+## Order Types & Execution
+
+### Market Orders (immediate execution)
+```bash
+perp --json -e hl trade market BTC buy 0.01       # market buy
+perp --json -e hl trade market BTC sell 0.01      # market sell
+perp --json -e hl trade buy BTC 0.01              # shorthand
+perp --json -e hl trade sell BTC 0.01             # shorthand
+```
+
+### Limit Orders (execute at specific price)
+```bash
+perp --json -e hl trade buy BTC 0.01 -p 60000    # buy at $60,000
+perp --json -e hl trade sell BTC 0.01 -p 70000   # sell at $70,000
+```
+
+### Close Position
+```bash
+perp --json -e hl trade close BTC                 # close entire position
+```
+
+### Stop Loss / Take Profit
+```bash
+perp --json -e hl trade sl BTC 58000              # stop loss at $58k
+perp --json -e hl trade tp BTC 65000              # take profit at $65k
+```
+
+### Cancel Orders
+```bash
+perp --json -e hl account orders                  # list open orders
+perp --json -e hl trade cancel <orderId>          # cancel specific order
+```
+
+### Pre-Flight Validation
+ALWAYS run before executing a trade:
+```bash
+perp --json -e hl trade check BTC buy 0.01
+```
+This returns estimated fees, slippage, and whether the trade can execute.
+
+## Parsing JSON Output
+
+Every command returns this envelope:
+```json
+{
+  "ok": true,
+  "data": { ... },
+  "meta": { "timestamp": "2026-03-11T..." }
+}
+```
+
+Error case:
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "INSUFFICIENT_BALANCE",
+    "message": "Not enough USDC",
+    "retryable": false
+  }
+}
+```
+
+**Always check `ok` field first.** If `ok` is `false`, read `error.code` to decide next action. If `error.retryable` is `true`, wait 5 seconds and retry once.
+
+## Idempotency & Safety
+
+### Safe to retry (idempotent):
+- `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
+- `portfolio`, `risk overview` — read-only
+- `bridge quote` — read-only
+- `bridge status` — read-only
+
+### NOT safe to retry blindly:
+- `trade market`, `trade buy`, `trade sell` — will open duplicate positions
+- `trade close` — may error if already closed, but harmless
+- `bridge send` — will send duplicate transfers
+- `deposit`, `withdraw` — will move funds twice
+
+**For non-idempotent commands:** always verify the result before retrying. Check positions or balances to confirm whether the first attempt succeeded.
+
+## Common Agent Mistakes
+
+1. **Using `perp init`** — interactive, will hang forever. Use `wallet set` instead.
+2. **Forgetting `--json`** — output becomes unparseable human text.
+3. **Trading with zero balance** — check `account info` first, tell user to deposit.
+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.

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

@@ -108,8 +108,11 @@ perp --json wallet balance                  # on-chain balance
 
 ## Risk & Analytics
 ```bash
-perp --json risk status                     # portfolio risk overview
-perp --json risk limits                     # position limits
+perp --json risk status                     # portfolio risk overview (level, violations, canTrade)
+perp --json risk liquidation-distance       # % distance from liquidation for ALL positions
+perp --json risk limits                     # view current risk limits
+perp --json risk limits --min-liq-distance 30 --max-leverage 5  # set risk limits
+perp --json risk check --notional 1000 --leverage 3  # pre-trade risk check
 perp --json health                          # exchange connectivity & latency
 perp --json analytics summary              # trading performance
 perp --json analytics pnl                   # P&L breakdown

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

@@ -0,0 +1,343 @@
+# Autonomous Strategy Framework
+
+This guide helps agents make informed decisions about perpetual futures trading across exchanges.
+You are not expected to follow rigid rules — use this as a decision framework and develop your own judgment over time.
+
+## Core Concepts
+
+### Funding Rate Mechanics
+- 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`
+
+### Opportunity Cost Awareness
+
+**This is critical.** Before switching any position, calculate the FULL cost of the switch:
+
+```
+Switch Cost =
+  + close current position (trading fee + slippage)
+  + withdraw from exchange (gas fee + time)
+  + bridge to target chain (bridge fee + gas + time)
+  + deposit to new exchange (gas fee + time)
+  + open new position (trading fee + slippage)
+```
+
+Query each component:
+```bash
+perp --json -e <FROM> trade check <SYM> <SIDE> <SIZE>   # close cost estimate
+perp --json bridge quote --from <CHAIN> --to <CHAIN> --amount <AMT>  # bridge cost
+perp --json -e <TO> trade check <SYM> <SIDE> <SIZE>     # open cost estimate
+```
+
+**Only switch if:**
+```
+expected_hourly_gain × expected_hours_held > total_switch_cost × safety_margin
+```
+
+Where `safety_margin` should be at least 2x — rates can change before you finish switching.
+
+### Time Cost
+Switching is not instant. Estimate total transition time:
+- Exchange withdrawal: 1-30 minutes
+- Bridge transfer: 1-20 minutes (CCTP ~2-5 min, deBridge ~5-15 min)
+- Exchange deposit confirmation: 1-10 minutes
+
+During transition, you are **unhedged**. Price can move against you. Factor this risk in.
+
+## Funding Rate Arbitrage
+
+### How It Works
+1. Find a symbol where Exchange A pays significantly more funding than Exchange B
+2. Go short on Exchange A (receive funding) and long on Exchange B (pay less funding)
+3. Net = funding received - funding paid - fees
+4. The position is market-neutral (delta-hedged) — you profit from the rate spread
+
+### Discovery Loop
+```bash
+perp --json arb rates                    # compare rates across exchanges
+perp --json arb scan --min 10            # find spreads > 10 bps
+```
+
+### Decision Framework
+When evaluating an arb opportunity:
+
+1. **Is the spread real?** Check if rates are stable or spiking temporarily
+   - Query rates multiple times over 15-30 minutes
+   - A spike that reverts in 1 hour is not worth switching for
+
+2. **What's my current position earning?**
+   - If already in a profitable arb, switching has opportunity cost
+   - Calculate: `current_hourly_income vs new_hourly_income - switch_cost`
+
+3. **How long will the spread persist?**
+   - Historical funding tends to mean-revert
+   - Higher confidence in moderate, stable spreads (20-50 bps) than extreme spikes (>100 bps)
+
+4. **Can I execute both legs atomically?**
+   - Both positions should open near-simultaneously to minimize directional exposure
+   - If capital needs to bridge first, you're exposed during transit
+
+### Monitoring Active Positions
+```bash
+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?
+```
+
+### Order Execution: Sequential Leg Management
+
+**NEVER close or open both legs of an arb at once with market orders.** You must manage execution carefully.
+
+#### 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.
+
+#### 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
+
+#### Using Limit Orders for Better Execution
+For non-urgent transitions, consider limit orders at the best bid/ask instead of market orders:
+```bash
+perp --json -e <EX> trade sell <SYM> <SIZE> -p <PRICE>    # limit order
+```
+This avoids crossing the spread, but you risk not getting filled. Set a reasonable timeout and fall back to market if not filled.
+
+### When to Exit
+- Spread compressed below your breakeven (including fees)
+- One side's funding flipped direction
+- Better opportunity found (after accounting for switch cost!)
+- Risk limits breached
+
+## Risk Management — THE MOST IMPORTANT SECTION
+
+**Risk management is more important than profit.** A single liquidation can wipe out months of funding rate income. Every decision you make should be filtered through risk first, profit second.
+
+### Understanding Liquidation
+
+When your margin drops below the maintenance requirement, the exchange force-closes your position at a loss. This is **liquidation** — it is catastrophic and must be avoided at all costs.
+
+**Check liquidation distance for every open position:**
+```bash
+perp --json risk liquidation-distance        # shows % distance from liq price for ALL positions
+perp --json -e <EX> account positions        # shows liquidationPrice per position
+perp --json -e <EX> account margin <SYM>     # detailed: liquidationPrice, marginRequired, marginPctOfEquity
+```
+
+**Liquidation distance is configurable by the user.** You MUST ask the user what risk tolerance they want:
+```bash
+# Ask user: "What minimum liquidation distance do you want? (default: 30%, hard minimum: 20%)"
+perp --json risk limits --min-liq-distance <USER_CHOICE>
+```
+
+**Hard cap: 20%.** No matter what the user says, the system will NEVER allow a position to get within 20% of liquidation. This is non-negotiable and enforced at the system level. If a user tries to set it below 20%, the command will reject it.
+
+**Action rules based on `risk liquidation-distance` output:**
+- `status: "safe"` → no action needed
+- `status: "warning"` → monitor more frequently (every 5 minutes)
+- `status: "danger"` → alert user, recommend reducing position size
+- `status: "critical"` (below 20% hard cap) → REDUCE IMMEDIATELY, `canTrade` becomes `false`
+
+### Leverage and Margin Mode
+
+#### Leverage
+Higher leverage = closer liquidation price = higher risk. For funding rate arb:
+- **Recommended: 1x-3x leverage.** Arb profits are small but consistent — no need to amplify risk.
+- **NEVER exceed 5x for arb positions.** The goal is to collect funding, not to speculate.
+- For directional trades (non-arb), leverage should be set according to user's risk tolerance, but always confirm with user.
+
+**Set leverage BEFORE opening a position:**
+```bash
+perp --json -e <EX> trade leverage <SYM> <LEVERAGE>
+# Example: perp --json -e hl trade leverage BTC 2
+```
+
+#### Cross vs Isolated Margin
+
+| Mode | Behavior | Use When |
+|------|----------|----------|
+| **Cross** | All positions share the same margin pool. One position's loss can liquidate everything. | Single position per exchange, or highly correlated positions |
+| **Isolated** | Each position has its own margin. Liquidation of one doesn't affect others. | Multiple independent positions, recommended for arb |
+
+**For funding rate arb, use ISOLATED margin.** Each leg should be independent — if one side gets liquidated, the other side survives.
+
+```bash
+perp --json manage margin <SYM> isolated     # set isolated margin
+perp --json -e <EX> trade leverage <SYM> <LEV> --isolated   # set leverage + isolated at once
+```
+
+**Check current settings:**
+```bash
+perp --json -e <EX> account settings         # shows leverage and margin_mode per symbol
+```
+
+### Risk Limits — Configure Before Trading
+
+Set your risk limits FIRST, before any trading activity:
+```bash
+perp --json risk limits \
+  --max-leverage 5 \
+  --max-margin 60 \
+  --max-position 5000 \
+  --max-exposure 20000 \
+  --max-drawdown 500 \
+  --daily-loss 200 \
+  --min-liq-distance 30
+```
+
+**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)
+- "How close to liquidation are you willing to get?" (default: 30%, minimum: 20%)
+
+These limits are enforced by `perp risk check`. Always run it before trades:
+```bash
+perp --json risk check --notional 1000 --leverage 3
+# Returns: { "allowed": true/false, "reason": "...", "riskLevel": "low/medium/high/critical" }
+```
+
+**If `allowed: false`, do NOT proceed.** Report to user why.
+
+### The Risk Monitoring Loop
+
+**This is your primary responsibility.** While positions are open, run this loop continuously:
+
+#### Every 15 minutes:
+```bash
+perp --json risk status                      # overall risk level + violations
+perp --json risk liquidation-distance        # % distance from liq price for ALL positions
+perp --json -e <EX> account positions        # check each position's P&L
+```
+
+Check the output:
+- `risk status` returns `level` (low/medium/high/critical) and `canTrade` (boolean)
+- If `level` is "high" or "critical" → take action immediately
+- If `canTrade` is false → do NOT open new positions
+- Check `violations[]` for specific issues
+
+#### Every hour (at funding settlement):
+```bash
+perp --json portfolio                        # total equity across exchanges
+perp --json arb rates                        # 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
+```
+
+Compare each position's unrealized P&L. In a perfect arb, they should roughly offset. If one side is losing significantly more than the other is gaining, investigate — the hedge may not be balanced.
+
+#### Immediate action triggers:
+| Condition | Action |
+|-----------|--------|
+| `risk status` level = "critical" | Reduce positions immediately |
+| Liquidation price within 10% of current price | Reduce that position's size |
+| `canTrade` = false | Stop all new trades, focus on reducing risk |
+| One arb leg closed unexpectedly | Close the other leg IMMEDIATELY (naked exposure) |
+| Unrealized loss > max-drawdown limit | Close losing positions |
+| Margin utilization > 80% | Do not open new positions |
+
+### Position Sizing
+
+Think in terms of total capital across all exchanges:
+```bash
+perp --json portfolio                        # totalEquity, marginUtilization, concentration
+```
+
+Rules of thumb:
+- **Single position notional < 25% of total equity** across all exchanges
+- **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
+
+### Stop Loss for Arb Positions
+
+Even "market-neutral" arb can lose money if:
+- One exchange goes down and you can't manage that leg
+- Extreme funding spike in the wrong direction
+- Slippage on entry/exit far exceeds estimates
+
+**Always set stop losses on both legs:**
+```bash
+perp --json -e <EX_A> trade sl <SYM> <PRICE>    # stop loss on leg A
+perp --json -e <EX_B> trade sl <SYM> <PRICE>    # stop loss on leg B
+```
+
+Or use TP/SL together:
+```bash
+perp --json -e <EX> trade tp-sl <SYM> --tp <PRICE> --sl <PRICE>
+```
+
+### Monitoring Alerts
+
+Set up alerts so you get notified of dangerous conditions without polling:
+```bash
+perp --json alert add -t margin --margin-pct 70    # alert when margin usage > 70%
+perp --json alert add -t price -s BTC --below 50000 --above 80000   # price boundaries
+perp --json alert add -t funding -s ETH --spread 50  # funding spread alert
+```
+
+### What to Track Over Time
+As you operate, build awareness of:
+- Which symbols consistently have the best funding spreads
+- Which exchange pairs have the lowest switching cost
+- Typical bridge times for each route
+- How quickly funding rate spikes mean-revert
+- Your own execution quality (slippage vs estimates)
+- **How close your positions have come to liquidation** — learn from near-misses
+
+This is YOUR operational knowledge. Use it to make better decisions over time.
+
+## Capital Efficiency
+
+### Cross-Exchange Capital Allocation
+Your capital is split across exchanges. Rebalancing has real costs:
+```bash
+perp --json bridge quote --from solana --to arbitrum --amount 1000
+```
+
+Before rebalancing, ask:
+- Is the capital earning anything where it currently sits?
+- Is the destination opportunity worth the bridge fee + downtime?
+- Can I use the capital more efficiently without moving it?
+
+### Idle Capital
+Capital sitting in an exchange wallet but not in a position is earning 0%.
+Options:
+- Open a low-risk funding collection position
+- Bridge to where it's more useful
+- Sometimes idle cash IS the right position (dry powder for opportunities)
+
+## Summary
+
+Your job is not to blindly follow rules — it's to develop judgment:
+- Every switch has a cost. Calculate it before acting.
+- Rates change hourly. What's profitable now may not be in 2 hours.
+- Build pattern recognition over time.
+- The best arb is one you're already in, not one you're chasing.

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

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Scan funding rate arbitrage opportunities
+# Usage: ./arb-scan.sh [min-spread-bps]
+# Example: ./arb-scan.sh 20
+
+set -e
+
+MIN_SPREAD="${1:-10}"
+
+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):"
+perp --json arb scan --min "$MIN_SPREAD"

package/skills/perp-cli/templates/open-position.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Open a perp position with pre-flight checks
+# Usage: ./open-position.sh <exchange> <symbol> <side> <size>
+# Example: ./open-position.sh hl BTC buy 0.01
+
+set -e
+
+EX="${1:?Usage: open-position.sh <exchange> <symbol> <side> <size>}"
+SYM="${2:?Usage: open-position.sh <exchange> <symbol> <side> <size>}"
+SIDE="${3:?Usage: open-position.sh <exchange> <symbol> <side> <size>}"
+SIZE="${4:?Usage: open-position.sh <exchange> <symbol> <side> <size>}"
+
+echo "=== Pre-flight checks ==="
+echo "1. Account info:"
+perp --json -e "$EX" account info
+
+echo "2. Current price:"
+perp --json -e "$EX" market mid "$SYM"
+
+echo "3. Trade validation:"
+perp --json -e "$EX" trade check "$SYM" "$SIDE" "$SIZE"
+
+echo ""
+echo "=== Ready to execute ==="
+echo "  Exchange: $EX"
+echo "  Symbol:   $SYM"
+echo "  Side:     $SIDE"
+echo "  Size:     $SIZE"
+echo ""
+read -p "Confirm? (y/N): " CONFIRM
+
+if [ "$CONFIRM" = "y" ] || [ "$CONFIRM" = "Y" ]; then
+  perp --json -e "$EX" trade market "$SYM" "$SIDE" "$SIZE"
+  echo "=== Position verification ==="
+  perp --json -e "$EX" account positions
+else
+  echo "Cancelled."
+fi

package/skills/perp-cli/templates/wallet-setup.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Wallet setup for perp-cli
+# Usage: ./wallet-setup.sh <exchange> <private-key>
+# Exchanges: hl (Hyperliquid), pac (Pacifica), lt (Lighter)
+
+set -e
+
+EXCHANGE="${1:?Usage: wallet-setup.sh <exchange> <private-key>}"
+KEY="${2:?Usage: wallet-setup.sh <exchange> <private-key>}"
+
+echo "Setting up wallet for $EXCHANGE..."
+perp --json wallet set "$EXCHANGE" "$KEY"
+
+echo "Verifying..."
+perp --json wallet show
+
+echo "Done. Wallet configured for $EXCHANGE."