perp-cli 0.3.14 → 0.3.16

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { assessRisk, preTradeCheck, calcLiquidationDistance, getLiquidationDistances, effectiveLimit, LIQUIDATION_DISTANCE_HARD_CAP } from "../risk.js";
+import { assessRisk, preTradeCheck, calcLiquidationDistance, getLiquidationDistances, effectiveLimit } from "../risk.js";
 const defaultLimits = {
     maxDrawdownUsd: 500,
     maxPositionUsd: 5000,
@@ -186,13 +186,13 @@ describe("getLiquidationDistances", () => {
     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: "a", position: makePosition("A", "long", 1, 100, 2, 0, "85") }, // 15% → danger (< 30% user limit)
             { 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 === "A").status).toBe("danger");
         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");
@@ -209,30 +209,18 @@ describe("getLiquidationDistances", () => {
     });
 });
 describe("Liquidation Distance in assessRisk", () => {
-    it("should add critical violation when position is below hard cap (20%)", () => {
+    it("should add violation when position is below user limit", () => {
         const balances = [{ exchange: "test", balance: makeBalance(10000, 8000, 2000, 0) }];
-        // BTC long at $100000, liq at $90000 → 10% distance (below 20% hard cap)
+        // BTC long at $100000, liq at $90000 → 10% distance (below 30% user limit)
         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", () => {
@@ -259,11 +247,6 @@ describe("Liquidation Distance in assessRisk", () => {
         expect(result.liquidationDistances[0].status).toBe("safe");
     });
 });
-describe("LIQUIDATION_DISTANCE_HARD_CAP", () => {
-    it("should be 20", () => {
-        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

package/dist/commands/arb-auto.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import { formatUsd, printJson, jsonOk } from "../utils.js";
+import { computeExecutableSize } from "../liquidity.js";
 import { computeAnnualSpread, toHourlyRate } from "../funding.js";
 import { fetchPacificaPricesRaw, parsePacificaRaw, fetchHyperliquidMetaRaw, parseHyperliquidMetaRaw, fetchLighterOrderBookDetailsRaw, fetchLighterFundingRatesRaw, parseLighterRaw, } from "../shared-api.js";
 import { scanDexArb } from "../dex-asset-map.js";
@@ -729,6 +730,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         .command("scan")
         .description("Scan current funding rate spreads")
         .option("--min <pct>", "Min annual spread to show", "10")
+        .option("--top <n>", "Return only top N results (for JSON output)")
         .option("--hold-days <days>", "Expected hold period for cost calc", "7")
         .option("--bridge-cost <usd>", "One-way bridge cost in USD", "0.5")
         .option("--size <usd>", "Position size per leg ($) for cost calc", "100")
@@ -742,12 +744,14 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         const spreads = await fetchFundingSpreads();
         const filtered = spreads.filter(s => Math.abs(s.spread) >= minSpread);
         if (isJson()) {
-            const enriched = filtered.map(s => {
+            let enriched = filtered.map(s => {
                 const grossSpread = Math.abs(s.spread);
                 const rtCost = computeRoundTripCostPct(s.longExch, s.shortExch);
                 const net = computeNetSpread(grossSpread, holdDays, rtCost, bridgeCostUsd, sizeUsd);
-                return { ...s, grossSpread, netSpread: net, estFeesPct: rtCost };
-            });
+                return { symbol: s.symbol, longExch: s.longExch, shortExch: s.shortExch, markPrice: s.markPrice, grossSpread, netSpread: net, estFeesPct: rtCost };
+            }).sort((a, b) => b.netSpread - a.netSpread);
+            if (opts.top)
+                enriched = enriched.slice(0, parseInt(opts.top));
             return printJson(jsonOk(enriched));
         }
         if (filtered.length === 0) {
@@ -783,6 +787,221 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         console.log(chalk.gray(`  * Spreads are estimates based on current rates — actual may vary`));
         console.log(chalk.gray(`  Use 'perp arb auto --min-spread ${minSpread}' to auto-trade\n`));
     });
+    // ── arb exec ── (validate orderbook + simultaneous dual-leg entry)
+    arb
+        .command("exec")
+        .description("Execute arb: validate orderbook depth on both exchanges, then enter both legs simultaneously")
+        .argument("<symbol>", "Symbol (e.g. BTC, ETH, ICP)")
+        .argument("<longExch>", "Exchange to go LONG on (hl, pac, lighter)")
+        .argument("<shortExch>", "Exchange to go SHORT on (hl, pac, lighter)")
+        .argument("<sizeUsd>", "Position size per leg in USD")
+        .option("--max-slippage <pct>", "Max slippage % per leg", "0.5")
+        .option("--leverage <n>", "Set leverage before entry (both exchanges)")
+        .option("--isolated", "Use isolated margin mode")
+        .action(async (symbol, longExch, shortExch, sizeUsdStr, opts) => {
+        const sym = symbol.toUpperCase();
+        const sizeUsd = parseFloat(sizeUsdStr);
+        const maxSlippage = parseFloat(opts.maxSlippage);
+        // Resolve exchange aliases
+        const aliasMap = { hl: "hyperliquid", pac: "pacifica", lt: "lighter" };
+        longExch = aliasMap[longExch.toLowerCase()] || longExch.toLowerCase();
+        shortExch = aliasMap[shortExch.toLowerCase()] || shortExch.toLowerCase();
+        if (longExch === shortExch) {
+            if (isJson())
+                return printJson(jsonOk({ error: "longExch and shortExch must be different" }));
+            console.log(chalk.red("  Long and short exchange must be different."));
+            return;
+        }
+        const longAdapter = await getAdapterForExchange(longExch);
+        const shortAdapter = await getAdapterForExchange(shortExch);
+        // 1. Set leverage if requested
+        if (opts.leverage) {
+            const lev = parseInt(opts.leverage);
+            const mode = opts.isolated ? "isolated" : "cross";
+            if (!isJson())
+                console.log(chalk.gray(`  Setting leverage ${lev}x ${mode} on both exchanges...`));
+            const [longLev, shortLev] = await Promise.allSettled([
+                longAdapter.setLeverage(sym, lev, mode),
+                shortAdapter.setLeverage(sym, lev, mode),
+            ]);
+            if (longLev.status === "rejected") {
+                const msg = `Failed to set leverage on ${longExch}: ${longLev.reason instanceof Error ? longLev.reason.message : longLev.reason}`;
+                if (isJson())
+                    return printJson(jsonOk({ error: msg }));
+                console.log(chalk.red(`  ${msg}`));
+                return;
+            }
+            if (shortLev.status === "rejected") {
+                const msg = `Failed to set leverage on ${shortExch}: ${shortLev.reason instanceof Error ? shortLev.reason.message : shortLev.reason}`;
+                if (isJson())
+                    return printJson(jsonOk({ error: msg }));
+                console.log(chalk.red(`  ${msg}`));
+                return;
+            }
+        }
+        // 2. Fetch orderbooks simultaneously
+        if (!isJson())
+            console.log(chalk.gray(`  Checking orderbook depth on both exchanges...`));
+        const [longBook, shortBook] = await Promise.all([
+            longAdapter.getOrderbook(sym),
+            shortAdapter.getOrderbook(sym),
+        ]);
+        // 3. Validate: long side buys from asks, short side sells into bids
+        const longCheck = computeExecutableSize(longBook.asks, sizeUsd, maxSlippage);
+        const shortCheck = computeExecutableSize(shortBook.bids, sizeUsd, maxSlippage);
+        const validation = {
+            long: { exchange: longExch, side: "buy", depthUsd: longCheck.depthUsd, canFill: longCheck.canFillFull, slippagePct: longCheck.slippagePct, maxSizeBase: longCheck.maxSize },
+            short: { exchange: shortExch, side: "sell", depthUsd: shortCheck.depthUsd, canFill: shortCheck.canFillFull, slippagePct: shortCheck.slippagePct, maxSizeBase: shortCheck.maxSize },
+        };
+        if (!longCheck.canFillFull || !shortCheck.canFillFull) {
+            // Use the smaller fillable amount
+            const fillableUsd = Math.min(longCheck.maxSize * longCheck.avgFillPrice, shortCheck.maxSize * shortCheck.avgFillPrice);
+            const result = {
+                error: "Insufficient orderbook depth",
+                requestedUsd: sizeUsd,
+                fillableUsd: Math.round(fillableUsd * 100) / 100,
+                validation,
+            };
+            if (isJson())
+                return printJson(jsonOk(result));
+            console.log(chalk.red(`\n  Insufficient depth for $${sizeUsd}:`));
+            console.log(chalk.gray(`    ${longExch} asks: $${longCheck.depthUsd.toFixed(0)} depth, ${longCheck.canFillFull ? "OK" : "NOT ENOUGH"}`));
+            console.log(chalk.gray(`    ${shortExch} bids: $${shortCheck.depthUsd.toFixed(0)} depth, ${shortCheck.canFillFull ? "OK" : "NOT ENOUGH"}`));
+            console.log(chalk.yellow(`  Max fillable: $${fillableUsd.toFixed(2)}\n`));
+            return;
+        }
+        // 4. Compute matched size in base asset (use the smaller side)
+        // Round down to each exchange's lot size (inferred from orderbook)
+        const inferDecimals = (levels) => {
+            for (const [, s] of levels) {
+                const dot = s.indexOf(".");
+                if (dot >= 0)
+                    return s.length - dot - 1;
+            }
+            return 0;
+        };
+        const longDecimals = inferDecimals(longBook.asks);
+        const shortDecimals = inferDecimals(shortBook.bids);
+        const decimals = Math.min(longDecimals, shortDecimals);
+        const matchedBase = Math.min(longCheck.recommendedSize, shortCheck.recommendedSize);
+        const matchedSize = (Math.floor(matchedBase * 10 ** decimals) / 10 ** decimals).toFixed(decimals);
+        const avgPrice = (longCheck.avgFillPrice + shortCheck.avgFillPrice) / 2;
+        const matchedUsd = matchedBase * avgPrice;
+        if (!isJson()) {
+            console.log(chalk.cyan(`\n  Arb Exec: ${sym}`));
+            console.log(chalk.gray(`    LONG  ${longExch}: buy  ${matchedSize} (~$${(matchedBase * longCheck.avgFillPrice).toFixed(2)}, slippage ${longCheck.slippagePct.toFixed(3)}%)`));
+            console.log(chalk.gray(`    SHORT ${shortExch}: sell ${matchedSize} (~$${(matchedBase * shortCheck.avgFillPrice).toFixed(2)}, slippage ${shortCheck.slippagePct.toFixed(3)}%)`));
+            console.log(chalk.gray(`    Executing both legs simultaneously...\n`));
+        }
+        // 5. Execute both legs simultaneously
+        const [longResult, shortResult] = await Promise.allSettled([
+            longAdapter.marketOrder(sym, "buy", matchedSize),
+            shortAdapter.marketOrder(sym, "sell", matchedSize),
+        ]);
+        const longOk = longResult.status === "fulfilled";
+        const shortOk = shortResult.status === "fulfilled";
+        if (longOk && shortOk) {
+            // 6. Verify both positions actually exist (some exchanges return success but silently reject)
+            const [longPositions, shortPositions] = await Promise.all([
+                longAdapter.getPositions().catch(() => []),
+                shortAdapter.getPositions().catch(() => []),
+            ]);
+            const longPos = longPositions.find(p => p.symbol.toUpperCase().startsWith(sym));
+            const shortPos = shortPositions.find(p => p.symbol.toUpperCase().startsWith(sym));
+            if (!longPos && !shortPos) {
+                // Both silently rejected
+                const result = { status: "both_rejected", symbol: sym, size: matchedSize, message: "Both exchanges accepted order but no positions opened. Check min order size." };
+                if (isJson())
+                    return printJson(jsonOk(result));
+                console.log(chalk.red(`  Both orders accepted but no positions opened. Min order size not met?\n`));
+                return;
+            }
+            if (!longPos || !shortPos) {
+                // One side silently rejected — close the other
+                const openSide = longPos ? "long" : "short";
+                const openAdapter = longPos ? longAdapter : shortAdapter;
+                if (!isJson())
+                    console.log(chalk.yellow(`  ${openSide} opened but other side silently rejected — closing ${openSide}...`));
+                try {
+                    await openAdapter.marketOrder(sym, longPos ? "sell" : "buy", matchedSize);
+                }
+                catch { /* best effort */ }
+                const result = { status: "silent_reject", symbol: sym, openedSide: openSide, closedSide: longPos ? "short" : "long", message: "One leg silently rejected (likely min order size). Rolled back." };
+                if (isJson())
+                    return printJson(jsonOk(result));
+                console.log(chalk.yellow(`  Rolled back ${openSide} leg. Check exchange min order sizes.\n`));
+                return;
+            }
+            logExecution({
+                type: "arb_entry", exchange: `${longExch}+${shortExch}`,
+                symbol: sym, side: "entry", size: matchedSize,
+                status: "success", dryRun: false,
+                meta: { longExch, shortExch, matchedUsd, longSlippage: longCheck.slippagePct, shortSlippage: shortCheck.slippagePct },
+            });
+            const result = {
+                status: "filled", symbol: sym, size: matchedSize, notionalUsd: Math.round(matchedUsd * 100) / 100,
+                long: { exchange: longExch, side: "buy", size: longPos.size, slippagePct: longCheck.slippagePct },
+                short: { exchange: shortExch, side: "sell", size: shortPos.size, slippagePct: shortCheck.slippagePct },
+            };
+            if (isJson())
+                return printJson(jsonOk(result));
+            console.log(chalk.green(`  FILLED: ${sym} ${matchedSize} units (~$${matchedUsd.toFixed(2)})`));
+            console.log(chalk.green(`    LONG  ${longExch} ✓ (${longPos.size})`));
+            console.log(chalk.green(`    SHORT ${shortExch} ✓ (${shortPos.size})\n`));
+        }
+        else if (longOk !== shortOk) {
+            // One leg failed — rollback
+            const filledSide = longOk ? "long" : "short";
+            const failedSide = longOk ? "short" : "long";
+            const filledAdapter = longOk ? longAdapter : shortAdapter;
+            const rollbackAction = longOk ? "sell" : "buy";
+            const failedErr = longOk
+                ? shortResult.reason
+                : longResult.reason;
+            if (!isJson())
+                console.log(chalk.yellow(`  PARTIAL: ${filledSide} OK, ${failedSide} FAILED — rolling back...`));
+            let rollbackOk = false;
+            for (let attempt = 1; attempt <= 2; attempt++) {
+                try {
+                    await filledAdapter.marketOrder(sym, rollbackAction, matchedSize);
+                    rollbackOk = true;
+                    break;
+                }
+                catch { /* retry */ }
+            }
+            logExecution({
+                type: "arb_entry", exchange: `${longExch}+${shortExch}`,
+                symbol: sym, side: "entry", size: matchedSize,
+                status: "failed", dryRun: false,
+                error: `Partial: ${failedSide} failed (${failedErr instanceof Error ? failedErr.message : String(failedErr)}). Rollback: ${rollbackOk ? "ok" : "FAILED"}`,
+            });
+            const result = {
+                status: "partial_fill", symbol: sym, filledSide, failedSide,
+                failedError: failedErr instanceof Error ? failedErr.message : String(failedErr),
+                rollback: rollbackOk ? "success" : "FAILED — MANUAL CLOSE REQUIRED",
+            };
+            if (isJson())
+                return printJson(jsonOk(result));
+            console.log(rollbackOk
+                ? chalk.yellow(`  Rollback OK — no open exposure.\n`)
+                : chalk.red.bold(`  ROLLBACK FAILED — ${filledSide} leg still open. Close manually!\n`));
+        }
+        else {
+            // Both failed
+            const longErr = longResult.reason;
+            const shortErr = shortResult.reason;
+            const result = {
+                status: "both_failed", symbol: sym,
+                longError: longErr instanceof Error ? longErr.message : String(longErr),
+                shortError: shortErr instanceof Error ? shortErr.message : String(shortErr),
+            };
+            if (isJson())
+                return printJson(jsonOk(result));
+            console.log(chalk.red(`  Both legs failed:`));
+            console.log(chalk.red(`    LONG:  ${result.longError}`));
+            console.log(chalk.red(`    SHORT: ${result.shortError}\n`));
+        }
+    });
     // ── arb pnl ── (check arb position PnL)
     arb
         .command("pnl")

package/dist/commands/portfolio.js

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import { printJson, jsonOk, makeTable, formatUsd, formatPnl, withJsonErrors } from "../utils.js";
+import { assessRisk } from "../risk.js";
 const EXCHANGES = ["pacifica", "hyperliquid", "lighter"];
 async function fetchExchangeSnapshot(name, getAdapter) {
     try {
@@ -65,6 +66,12 @@ function buildSummary(snapshots) {
         pct: totalEquity > 0 ? (Number(s.balance.equity) / totalEquity) * 100 : 0,
     }))
         .sort((a, b) => b.pct - a.pct);
+    // Full risk assessment (reuses same data, no extra API calls)
+    const riskBalances = snapshots
+        .filter(s => s.balance)
+        .map(s => ({ exchange: s.exchange, balance: s.balance }));
+    const riskPositions = allPositions.map(p => ({ exchange: p.exchange, position: p }));
+    const assessment = assessRisk(riskBalances, riskPositions);
     return {
         totalEquity,
         totalAvailable,
@@ -79,6 +86,11 @@ function buildSummary(snapshots) {
             largestPosition,
             exchangeConcentration,
         },
+        risk: {
+            level: assessment.level,
+            canTrade: assessment.canTrade,
+            violations: assessment.violations,
+        },
     };
 }
 export function registerPortfolioCommands(program, getAdapterForExchange, isJson) {
@@ -149,6 +161,14 @@ export function registerPortfolioCommands(program, getAdapterForExchange, isJson
             }
             // ── Risk Metrics ──
             console.log(chalk.white.bold("\n  Risk Metrics"));
+            const levelColor = {
+                low: chalk.green,
+                medium: chalk.yellow,
+                high: chalk.red,
+                critical: chalk.bgRed.white,
+            }[summary.risk.level];
+            console.log(`  Risk Level:         ${levelColor(summary.risk.level.toUpperCase())}`);
+            console.log(`  Can Trade:          ${summary.risk.canTrade ? chalk.green("YES") : chalk.red("NO")}`);
             const mu = summary.riskMetrics.marginUtilization;
             const muColor = mu < 30 ? chalk.green : mu < 60 ? chalk.yellow : chalk.red;
             console.log(`  Margin Utilization: ${muColor(`${mu.toFixed(1)}%`)}`);
@@ -163,6 +183,13 @@ export function registerPortfolioCommands(program, getAdapterForExchange, isJson
                     console.log(`    ${ec.exchange.padEnd(12)} ${bar} ${ec.pct.toFixed(1)}%`);
                 }
             }
+            if (summary.risk.violations.length > 0) {
+                console.log(chalk.red.bold("\n  Risk Violations"));
+                for (const v of summary.risk.violations) {
+                    const sevColor = { low: chalk.green, medium: chalk.yellow, high: chalk.red, critical: chalk.bgRed.white }[v.severity];
+                    console.log(`    ${sevColor(v.severity.toUpperCase().padEnd(8))} ${v.message}`);
+                }
+            }
             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, getLiquidationDistances, LIQUIDATION_DISTANCE_HARD_CAP } from "../risk.js";
+import { loadRiskLimits, saveRiskLimits, assessRisk, getLiquidationDistances } from "../risk.js";
 const EXCHANGES = ["pacifica", "hyperliquid", "lighter"];
 export function registerRiskCommands(program, getAdapterForExchange, isJson) {
     const risk = program.command("risk").description("Risk management and guardrails");
@@ -57,11 +57,9 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
             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;
+                const ldColor = 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) {
@@ -101,7 +99,7 @@ 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("--min-liq-distance <pct>", "Min liquidation distance %")
         .option("--reset", "Reset all limits to defaults")
         .action(async (opts) => {
         let limits = loadRiskLimits();
@@ -111,9 +109,9 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
             opts.minLiqDistance || opts.reset;
         if (opts.reset) {
             limits = {
-                maxDrawdownUsd: 500, maxPositionUsd: 5000, maxTotalExposureUsd: 20000,
-                dailyLossLimitUsd: 200, maxPositions: 10, maxLeverage: 20, maxMarginUtilization: 80,
-                minLiquidationDistance: 30, maxDrawdownPct: 10, maxPositionPct: 25,
+                maxDrawdownUsd: 100000, maxPositionUsd: 100000, maxTotalExposureUsd: 500000,
+                dailyLossLimitUsd: 50000, maxPositions: 50, maxLeverage: 50, maxMarginUtilization: 95,
+                minLiquidationDistance: 5,
             };
         }
         if (opts.maxDrawdown)
@@ -139,15 +137,7 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
         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;
+            limits.minLiquidationDistance = parseFloat(opts.minLiqDistance);
         }
         if (hasUpdate)
             saveRiskLimits(limits);
@@ -167,7 +157,7 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
         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}%)`)}`);
+        console.log(`  Min Liq Distance:      ${limits.minLiquidationDistance}%`);
         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`));
     });
@@ -248,12 +238,11 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
                     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`));
+            console.log(chalk.gray(`  Your limit: ${limits.minLiquidationDistance}%\n`));
             const rows = distances.map(d => {
                 const statusColor = {
                     safe: chalk.green,
@@ -276,7 +265,7 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
             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`));
+                console.log(chalk.bgRed.white.bold(`  ⚠ ${critical.length} position(s) critically close to liquidation — REDUCE IMMEDIATELY`));
             }
             if (danger.length > 0) {
                 console.log(chalk.red.bold(`  ⚠ ${danger.length} position(s) below your limit (${limits.minLiquidationDistance}%) — action recommended`));

package/dist/risk.d.ts

@@ -15,8 +15,6 @@ export interface RiskLimits {
 }
 /** 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;
 export declare function saveRiskLimits(limits: RiskLimits): void;
 export type RiskLevel = "low" | "medium" | "high" | "critical";

package/dist/risk.js

@@ -1,16 +1,16 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { resolve } from "path";
 const DEFAULT_LIMITS = {
-    maxDrawdownUsd: 500,
-    maxPositionUsd: 5000,
-    maxTotalExposureUsd: 20000,
-    dailyLossLimitUsd: 200,
-    maxPositions: 10,
-    maxLeverage: 20,
-    maxMarginUtilization: 80,
-    minLiquidationDistance: 30,
-    maxDrawdownPct: 10,
-    maxPositionPct: 25,
+    maxDrawdownUsd: 100000,
+    maxPositionUsd: 100000,
+    maxTotalExposureUsd: 500000,
+    dailyLossLimitUsd: 50000,
+    maxPositions: 50,
+    maxLeverage: 50,
+    maxMarginUtilization: 95,
+    minLiquidationDistance: 5,
+    maxDrawdownPct: undefined,
+    maxPositionPct: undefined,
 };
 /** Resolve effective USD limit: min of fixed USD and pct-of-equity (if both set) */
 export function effectiveLimit(usdLimit, pctLimit, totalEquity) {
@@ -19,8 +19,6 @@ export function effectiveLimit(usdLimit, pctLimit, totalEquity) {
     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");
 const RISK_FILE = resolve(PERP_DIR, "risk.json");
 export function loadRiskLimits() {
@@ -61,9 +59,7 @@ export function getLiquidationDistances(positions, limits) {
         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)
+        if (distancePct < lim.minLiquidationDistance)
             status = "danger";
         else if (distancePct < lim.minLiquidationDistance * 1.5)
             status = "warning";
@@ -162,16 +158,7 @@ export function assessRisk(balances, positions, limits) {
         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) {
+        if (ld.distancePct < lim.minLiquidationDistance) {
             violations.push({
                 rule: "min_liquidation_distance",
                 severity: "high",

package/package.json

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

package/skills/perp-cli/SKILL.md

@@ -1,307 +1,110 @@
 ---
 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'."
+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."
 allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.3.12"
-  mcp-server: perp-cli
+  version: "0.3.16"
 ---
 
 # perp-cli Agent Guide
 
 Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum).
 
-## Critical Rules
+## Rules
 
-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.
-8. **NEVER read ~/.perp/.env or any key files directly.** Private keys are managed by the CLI internally. Use `perp --json wallet show` to check wallet status. Never attempt to read, cat, or access key files — this is a security violation.
+1. **Always use `--json`** on every command.
+2. **NEVER use `perp init`** — interactive, will hang.
+3. **NEVER trade without user confirmation.**
+4. **NEVER read ~/.perp/.env or key files.**
 
-## Step 1: Install
+## Install
 
 ```bash
 npm install -g perp-cli
 ```
+No sudo: `npm install -g perp-cli --prefix ~/.npm-global && export PATH="$HOME/.npm-global/bin:$PATH"`
 
-**No sudo / Docker / restricted environments:**
-```bash
-npm config set prefix ~/.npm-global
-npm install -g perp-cli --prefix ~/.npm-global
-export PATH="$HOME/.npm-global/bin:$PATH"
-```
-
-## Step 2: Configure Wallet
-
-CRITICAL: Do NOT use `perp init` — it is interactive and will hang.
-
-**If user needs a new wallet:**
-```bash
-perp --json wallet generate evm              # creates EVM wallet for Hyperliquid + Lighter
-perp --json wallet generate solana           # creates Solana wallet for Pacifica
-# IMPORTANT: Tell user the generated address so they can fund it with USDC!
-```
+## Wallet Setup
 
-### Hyperliquid setup
 ```bash
-perp --json wallet set hl <EVM_PRIVATE_KEY>        # register EVM key → ready to trade immediately
-perp --json wallet show                            # verify
-perp --json -e hl account info                     # check balance
+perp --json wallet set hl <EVM_KEY>       # Hyperliquid
+perp --json wallet set pac <SOLANA_KEY>   # Pacifica
+perp --json wallet set lt <EVM_KEY>       # Lighter (API key auto-generated)
+perp --json wallet show                   # verify
 ```
-No extra steps. Key is saved as `HL_PRIVATE_KEY` in .env.
+Same EVM key works for both HL and Lighter.
 
-### Pacifica setup
-```bash
-perp --json wallet set pac <SOLANA_PRIVATE_KEY>    # register Solana key → ready to trade immediately
-perp --json wallet show                            # verify
-perp --json -e pac account info                    # check balance
-```
-No extra steps. Key is saved as `PACIFICA_PRIVATE_KEY` in .env.
-
-### Lighter setup (API key auto-generated on registration)
-```bash
-perp --json wallet set lt <EVM_PRIVATE_KEY>        # register EVM key
-#    → AUTOMATICALLY generates Lighter API key via on-chain tx
-#    → Saves to .env: LIGHTER_PRIVATE_KEY, LIGHTER_API_KEY, LIGHTER_ACCOUNT_INDEX, LIGHTER_API_KEY_INDEX
-#    → No manual API key creation needed. Do NOT ask the user to visit the Lighter website.
-perp --json wallet show                            # verify
-perp --json -e lighter account info                # check balance
-```
-Same EVM key can be used for both Hyperliquid and Lighter:
-```bash
-perp --json wallet set hl <KEY>                    # same key
-perp --json wallet set lt <KEY>                    # same key, different exchange binding
-```
-If API key auto-setup fails (rare, e.g. no ETH for gas on Lighter chain):
-```bash
-perp --json -e lighter manage setup-api-key        # manual retry
-```
+## Key Commands
 
-**Verify setup (ALWAYS do this after any wallet command):**
 ```bash
-perp --json wallet show
-# Success: { "ok": true, "data": { "exchanges": [{ "exchange": "hyperliquid", "address": "0x..." }] } }
-# Empty:   { "ok": true, "data": { "exchanges": [] } }  ← wallet not configured yet
-```
+# Status (ONE call = balances, positions, risk level/violations/canTrade)
+perp --json portfolio
 
-## Step 3: Use
-
-### Exchange selection
-```bash
-perp --json -e hyperliquid ...    # Hyperliquid (EVM)
-perp --json -e pacifica ...       # Pacifica (Solana)
-perp --json -e lighter ...        # Lighter (Ethereum)
-```
-If a default exchange is set, `-e` can be omitted.
+# Arb workflow
+perp --json arb scan --min 5                                    # find opportunities
+perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage <N> --isolated  # execute
 
-### Symbol naming
-Symbols are auto-resolved across exchanges. Use bare symbols (e.g., `BTC`, `SOL`, `ICP`) everywhere — the CLI handles exchange-specific naming:
-- **Hyperliquid**: `ICP` → `ICP-PERP` (auto-resolved, `-PERP` suffix added)
-- **Pacifica / Lighter**: bare symbols as-is
-- `arb scan` returns bare symbols — pass them directly to any exchange command.
+# Single exchange trading (when not doing arb)
+perp --json -e <EX> trade market <SYM> buy <SIZE>
+perp --json -e <EX> trade close <SYM>
 
-### Common operations
-```bash
-perp --json wallet show                      # check configured wallets
-perp --json portfolio                        # unified multi-exchange view
-perp --json arb scan --min 5                 # find funding arb opportunities (>5bps spread)
+# Risk (only if you need to set limits — portfolio already includes risk)
+perp --json risk limits --max-leverage 5
 ```
 
-### Per-exchange commands (ALL 3 exchanges use the SAME commands)
-Every command below works on ALL exchanges. Just change `-e`:
-```bash
-# Account
-perp --json -e hl account info               # Hyperliquid balance & margin
-perp --json -e pac account info              # Pacifica balance & margin
-perp --json -e lighter account info          # Lighter balance & margin
-perp --json -e <EX> account positions        # open positions
-
-# Market data
-perp --json -e <EX> market list              # available markets
-perp --json -e <EX> market mid <SYM>         # mid price
-perp --json -e <EX> market book <SYM>        # orderbook depth
+Exchange aliases: `hl`, `pac`, `lt`. Symbols auto-resolve (`BTC`, `SOL`, `ICP`).
 
-# Trading (same syntax on ALL exchanges)
-perp --json -e <EX> trade leverage <SYM> <N> --isolated   # set leverage
-perp --json -e <EX> trade market <SYM> buy <SIZE>         # market buy
-perp --json -e <EX> trade market <SYM> sell <SIZE>        # market sell
-perp --json -e <EX> trade close <SYM>                     # close position
-perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L>  # pre-flight
+## Arb Workflow
 
-# Deposit / Withdraw
-perp --json deposit hyperliquid <AMOUNT>     # deposit to HL
-perp --json deposit pacifica <AMOUNT>        # deposit to Pacifica
-perp --json deposit lighter info             # show Lighter deposit routes
-perp --json deposit lighter cctp arb <AMOUNT>  # deposit to Lighter via CCTP
-perp --json withdraw <EX> <AMOUNT>           # withdraw from exchange
 ```
-**All 3 exchanges are fully operational.** Do NOT say any exchange "requires additional setup" or "is not available" — if `wallet show` shows it configured, it's ready to trade.
-
-### Funding arb direction (CRITICAL — do NOT reverse)
-```
-arb scan returns: longExch, shortExch, netSpread
-→ ALWAYS follow longExch/shortExch exactly. NEVER reverse the direction.
-→ NEVER enter if netSpread ≤ 0 (= loss after fees)
-→ Positive funding = longs pay shorts → be SHORT to receive
-→ Negative funding = shorts pay longs → be LONG to receive
+1. perp --json portfolio                    → check balances across all exchanges
+2. perp --json arb scan --min 5             → find opportunity (longExch, shortExch, netSpread)
+3. [Show opportunity to user, get confirmation]
+4. perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage 2 --isolated
+   → validates orderbook depth on both sides
+   → rounds size to each exchange's lot size
+   → executes BOTH legs simultaneously
+   → verifies positions exist after execution
+   → auto-rollback if one leg fails
+5. perp --json portfolio                    → verify positions
 ```
 
-### 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.
+## Position Sizing
 
-1. perp --json risk status                     → check risk level (STOP if critical)
-2. perp --json -e <EX> account info            → verify EXCHANGE-SPECIFIC balance
-3. perp --json -e <EX> market mid <SYM>        → current price
-4. perp --json -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
-```
+- Single position < **80%** of that exchange's available balance
+- Leverage 1-3x for arb, max 5x
+- `arb exec` auto-matches both legs to the same size
 
-### Exchange-specific constraints
-```
-Minimum order values (notional, enforced by exchange):
-  - Hyperliquid: $10 minimum per order
-  - Pacifica: varies by symbol (usually ~$1)
-  - Lighter: varies by symbol
+## Arb Direction (CRITICAL)
 
-If your calculated size falls below the minimum, increase to meet it or skip the opportunity.
-trade check returns valid: true/false but is ADVISORY — it does NOT block execution.
-The exchange itself will reject orders below its minimum.
-```
+`arb scan` returns `longExch`, `shortExch`, `netSpread`.
+ALWAYS follow exactly. NEVER reverse. NEVER enter if `netSpread <= 0`.
 
-### Arb order sizing (CRITICAL — both legs MUST match)
-```
-For funding arb, BOTH legs must have the EXACT SAME SIZE. Size mismatch = directional exposure.
+## Portfolio Response
 
-1. Check orderbook depth on BOTH exchanges:
-   perp --json -e <LONG_EX> market book <SYM>    → asks (you're buying)
-   perp --json -e <SHORT_EX> market book <SYM>   → bids (you're selling)
+`portfolio` includes `risk: { level, canTrade, violations[] }` — no need for separate `risk status`.
+Check `canTrade` before any order. If `false`, do NOT trade.
 
-2. Compute ORDER_SIZE:
-   - fillable_long = sum of ask sizes at best 2-3 levels
-   - fillable_short = sum of bid sizes at best 2-3 levels
-   - ORDER_SIZE = min(fillable_long, fillable_short, desired_size)
-   - Must be ≥ BOTH exchanges' minimum order value (e.g. HL requires ≥$10 notional)
+## Monitoring (while positions open)
 
-3. Execute BOTH legs with the SAME ORDER_SIZE:
-   perp --json -e <LONG_EX> trade market <SYM> buy <ORDER_SIZE>
-   → verify fill via account positions
-   perp --json -e <SHORT_EX> trade market <SYM> sell <ORDER_SIZE>
-   → verify fill via account positions
-
-4. Confirm matched: both positions must show identical size.
-   If mismatch (partial fill), adjust the larger to match the smaller.
 ```
-See `references/strategies.md` for detailed execution strategy (chunked orders, limit orders, failure handling).
-
-### Post-entry monitoring (MANDATORY while positions are open)
-```
-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 scan --min 5                  → 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`.
-For autonomous strategies (funding rate arb, risk management, opportunity cost), see `references/strategies.md`.
-
-## Response Format
-
-All JSON responses follow this envelope:
-```json
-{ "ok": true,  "data": { ... }, "meta": { "timestamp": "..." } }
-{ "ok": false, "error": { "code": "ERROR_CODE", "message": "...", "retryable": true } }
+Every 15 min: perp --json portfolio
+Every 1 hour: perp --json arb scan --min 5
+Exit if: spread < breakeven or one leg closed unexpectedly.
+Close both: perp --json -e <EX1> trade close <SYM> & perp --json -e <EX2> trade close <SYM>
 ```
 
 ## Error Handling
 
-| Code | Retryable | Action |
-|------|-----------|--------|
-| INSUFFICIENT_BALANCE | No | Report, suggest deposit |
-| MARGIN_INSUFFICIENT | No | Suggest lower leverage or smaller size |
-| SYMBOL_NOT_FOUND | No | Run `market list` for valid symbols |
-| SIGNATURE_FAILED | No | Run `wallet show` to check key configuration |
-| RATE_LIMITED | Yes | Wait 5s, retry once |
-| EXCHANGE_UNREACHABLE | Yes | Wait 5s, retry up to 3 times |
-| TIMEOUT | Yes | Retry, check network |
-
-## Safety Guardrails
-
-- NEVER execute trades without user confirmation
-- Warn if single trade exceeds 50% of available balance
-- Warn if leverage exceeds 10x
-- Double-confirm bridge transfers over $1000
-
-## Troubleshooting
+Responses: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
 
-### "No private key configured for <exchange>"
-The wallet is not set up. Fix:
-```bash
-perp --json wallet set <exchange> <key>      # if user has a key
-perp --json wallet generate evm              # if user needs a new EVM wallet
-perp --json wallet generate solana           # if user needs a new Solana wallet
-perp --json wallet show                      # verify it worked
-```
-
-### Command hangs or waits for input
-You used an interactive command. NEVER use `perp init` or any command without `--json`. Cancel and retry with `--json`.
+Retryable (wait 5s): `RATE_LIMITED`, `EXCHANGE_UNREACHABLE`, `TIMEOUT`
+**Lighter `invalid signature`**: `perp --json -e lighter manage setup-api-key`
 
-### Generated wallet has zero balance
-New wallets start empty. Show the address to the user and ask them to fund it with USDC before trading.
-
-## MCP Server (Advisor Mode)
-
-For read-only access without CLI execution:
-```json
-{
-  "mcpServers": {
-    "perp-cli": {
-      "command": "npx",
-      "args": ["-y", "perp-cli", "mcp"],
-      "env": {
-        "HL_PRIVATE_KEY": "<evm-hex>",
-        "PACIFICA_PRIVATE_KEY": "<solana-base58>"
-      }
-    }
-  }
-}
-```
+## References
 
-**MCP Tools:** get_markets, get_orderbook, get_funding_rates, get_prices, get_balance, get_positions, get_open_orders, portfolio, arb_scan, health_check, suggest_command, explain_command
+- `references/commands.md` — full command reference
+- `references/agent-operations.md` — setup flows, deposit/withdraw
+- `references/strategies.md` — risk framework, arb strategy

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

@@ -257,17 +257,14 @@ perp --json -e <EX> account margin <SYM>     # detailed: liquidationPrice, margi
 
 **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%)"
+# Ask user: "What minimum liquidation distance do you want? (default: 5%)"
 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
 
@@ -309,14 +306,13 @@ Limits can be set in **USD or % of equity** (when both are set, the stricter one
 ```bash
 perp --json risk limits \
   --max-leverage 5 \
-  --max-margin 60 \
-  --max-drawdown-pct 10 \
-  --max-position-pct 25 \
+  --max-margin 95 \
+  --max-position-pct 80 \
   --max-drawdown 500 \
-  --max-position 5000 \
-  --max-exposure 20000 \
+  --max-position 50000 \
+  --max-exposure 100000 \
   --daily-loss 200 \
-  --min-liq-distance 30
+  --min-liq-distance 5
 ```
 
 **Use % limits for small portfolios.** A $65 portfolio with `--max-drawdown 500` is meaningless.
@@ -325,7 +321,7 @@ 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)
-- "How close to liquidation are you willing to get?" (default: 30%, minimum: 20%)
+- "How close to liquidation are you willing to get?" (default: 5%)
 
 These limits are enforced by `perp risk check`. Always run it before trades:
 ```bash
@@ -380,8 +376,8 @@ perp --json portfolio                        # totalEquity, marginUtilization, c
 ```
 
 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
+- **Single position notional < 80% of that exchange's available balance**
+- **Total margin used < 80% 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