perp-cli 0.3.15 → 0.3.17

package/README.md

@@ -1,296 +1,108 @@
 # perp-cli
 
-Multi-DEX perpetual futures CLI for **Pacifica**, **Hyperliquid**, and **Lighter**.
-
-Trade, bridge, arbitrage, and manage positions across 3 exchanges from a single command line.
+Multi-DEX perpetual futures CLI — **Pacifica** (Solana), **Hyperliquid** (HyperEVM), **Lighter** (Ethereum).
 
 ```bash
 npm install -g perp-cli
-perp status --json
+perp --json portfolio
 ```
 
 ## Features
 
-- **3 Exchanges** — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum)
-- **Live Dashboard** — Real-time multi-exchange dashboard with WebSocket feeds
-- **CCTP V2 Bridge** — $0 fee USDC bridging across Solana, Arbitrum, Base (6 routes)
-- **Funding Rate Arb** — Cross-exchange funding rate arbitrage scanner + auto-executor
-- **Grid & DCA Bots** — Automated strategies with background job management
-- **AI Agent Mode** — JSON schema + structured I/O for LLM-powered trading agents
-- **Full JSON Output** — Every command supports `--json` for programmatic access
-
-## Quick Start
-
-```bash
-# Interactive setup (recommended for first-time users)
-perp init
-
-# Or configure exchange keys manually
-export HL_PRIVATE_KEY=<evm-hex-key>           # Hyperliquid
-export PRIVATE_KEY=<solana-base58-key>        # Pacifica
-export LIGHTER_PRIVATE_KEY=<evm-hex-key>      # Lighter
-
-# Or use wallet management
-perp wallet import evm <key>                  # Import & auto-bind to HL + Lighter
-perp wallet import solana <key>               # Import & auto-bind to Pacifica
-
-# Set default exchange (skip -e flag)
-perp settings set default-exchange hyperliquid
-
-# Check status
-perp status
-perp -e pacifica status
-```
-
-## Commands
-
-### Market Data
-
-```bash
-perp market list                    # All available markets
-perp market mid BTC                 # Mid price
-perp market info BTC                # Market details (tick size, max leverage)
-perp market book BTC                # Orderbook
-perp market funding BTC             # Funding rate
-```
-
-### Account
-
-```bash
-perp account info                   # Balance & margin
-perp account positions              # Open positions
-perp account orders                 # Open orders
-perp account history                # Trade history
-perp account margin BTC             # Position-level margin info
-```
-
-### Trading
-
-```bash
-perp trade buy BTC 0.01             # Market buy
-perp trade sell BTC 0.01            # Market sell
-perp trade buy BTC 0.01 -p 60000   # Limit buy @ $60,000
-perp trade close BTC                # Close position
-perp trade cancel <orderId>         # Cancel order
-perp trade tp BTC 65000             # Take-profit
-perp trade sl BTC 58000             # Stop-loss
-```
-
-### Position Management
-
-```bash
-perp manage leverage BTC 10         # Set leverage
-perp manage margin-mode BTC cross   # Cross/isolated margin
-```
+- **3 Exchanges** — trade, bridge, arbitrage across Pacifica, Hyperliquid, Lighter
+- **Funding Rate Arb** — scan spreads + one-command dual-leg execution (`arb exec`)
+- **Portfolio** — single call returns balances, positions, risk level across all exchanges
+- **CCTP V2 Bridge** — $0 fee USDC bridging (Solana, Arbitrum, Base)
+- **Agent-First Design** — `--json`, `--fields`, `--ndjson`, `--dry-run`, runtime schema introspection
+- **Safety** — pre-trade validation, response sanitization, client-id deduplication
 
-### Deposit & Withdraw
+## Setup
 
 ```bash
-perp deposit pacifica 100           # Deposit USDC into Pacifica
-perp deposit hyperliquid 100        # Deposit USDC into Hyperliquid (Arbitrum)
-perp deposit lighter ethereum 100   # Deposit via Ethereum L1
-perp deposit lighter cctp arb 100   # Deposit via CCTP (Arbitrum/Base/Avalanche)
-perp deposit lighter info           # Show all Lighter deposit routes
-perp withdraw pacifica 50           # Withdraw USDC
-perp withdraw hyperliquid 50
-perp deposit info                   # All deposit instructions
-```
-
-### Cross-Chain Bridge (CCTP V2)
+# Set exchange keys
+perp wallet set hl <EVM_KEY>         # Hyperliquid
+perp wallet set pac <SOLANA_KEY>     # Pacifica
+perp wallet set lt <EVM_KEY>         # Lighter (API key auto-generated)
 
-Zero-fee USDC bridging powered by Circle CCTP V2.
-
-```bash
-perp bridge chains                  # Supported chains
-perp bridge quote --from solana --to arbitrum --amount 100
-perp bridge send --from solana --to arbitrum --amount 100
-perp bridge exchange --from pacifica --to hyperliquid --amount 100
-perp bridge status <orderId>
+# Verify
+perp wallet show
 ```
 
-**Supported routes:** Solana ↔ Arbitrum ↔ Base (all 6 directions, $0 CCTP fee)
+Same EVM key works for both Hyperliquid and Lighter.
 
-### Funding Rate Arbitrage
+## Core Commands
 
 ```bash
-perp arb rates                      # Compare rates across exchanges
-perp arb scan --min 10              # Find opportunities (>10 bps spread)
-perp arb auto --min-spread 30      # Auto-execute arb (daemon mode)
-```
-
-### Automated Strategies
-
-```bash
-# Grid trading
-perp run grid BTC --range 5 --grids 10 --size 100
-
-# DCA (Dollar Cost Average)
-perp run dca BTC --interval 1h --size 50 --side buy
+# Portfolio (balances + positions + risk across all exchanges)
+perp --json portfolio
 
-# Funding arb bot
-perp run arb --min-spread 20
-```
+# Market data
+perp --json -e <EX> market list
+perp --json -e <EX> market book <SYM>
+perp --json -e <EX> market funding <SYM>
 
-### Real-Time Streams
+# Trading
+perp --json -e <EX> trade market <SYM> buy <SIZE>
+perp --json -e <EX> trade close <SYM>
+perp --json -e <EX> trade leverage <SYM> <N>
 
-```bash
-perp stream book BTC                # Live orderbook
-perp stream trades BTC              # Live trades
-perp stream funding                 # Live funding rates
-```
+# Funding rate arbitrage
+perp --json arb scan --min 5                                              # find opportunities
+perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage 2 --isolated # execute both legs
 
-### Live Dashboard
+# Risk
+perp --json risk limits --max-leverage 5
+perp --json risk liquidation-distance
 
-```bash
-perp dashboard                      # Real-time multi-exchange dashboard
-perp dashboard --port 3457          # Custom port
-perp dashboard --exchanges hl,pac   # Specific exchanges only
-```
-
-WebSocket-based real-time monitoring: positions, orders, balances, funding rates, arb opportunities across all exchanges. Includes HIP-3 dex position tracking.
-
-### Cross-Exchange Tools
-
-```bash
-perp gap show                       # Price gaps between exchanges
-perp gap watch --min 0.05           # Live gap monitor
-perp portfolio                      # Unified portfolio view
-perp risk overview                  # Cross-exchange risk assessment
-perp analytics pnl                  # P&L analytics
-```
-
-### Background Jobs
-
-```bash
-perp jobs list                      # Running background jobs
-perp jobs start arb                 # Start arb in background (tmux)
-perp jobs stop <id>                 # Stop a job
-perp jobs logs <id>                 # View job logs
-```
-
-### Alerts
-
-```bash
-perp alert add -t price -s BTC --above 100000 --telegram
-perp alert add -t funding -s ETH --spread 30
-perp alert daemon --interval 30
-```
-
-## Claude Code Agent Skill
-
-Install as a Claude Code plugin or via the universal skills CLI:
-
-```bash
-# 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-cli
-```
-
-Once installed, Claude can trade for you via natural language:
-
-```
-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
+# Bridge
 perp --json bridge quote --from solana --to arbitrum --amount 100
+perp --json bridge send --from solana --to arbitrum --amount 100
 ```
 
-The skill includes safety guardrails (balance checks, user confirmation before trades, error handling with retries).
+Exchange flags: `-e hyperliquid`, `-e pacifica`, `-e lighter` (aliases: `hl`, `pac`, `lt`).
 
-## AI Agent Integration
+## AI Agent Skill
 
-Every command supports `--json` for structured output:
+Install as a skill for Claude Code, Cursor, Codex, Gemini CLI, etc.:
 
 ```bash
-# Discover capabilities
-perp api-spec --json                # Full command spec for agent discovery
-perp schema --json                  # CLI schema with error codes
-
-# Machine-readable trading
-perp --json -e hyperliquid market mid BTC
-perp --json trade buy ETH 0.1
-perp --json account positions
-```
-
-All JSON responses follow a consistent envelope:
+# Using npx (recommended)
+npx skills add hypurrquant/perp-cli
 
-```json
-{
-  "ok": true,
-  "data": { ... },
-  "meta": { "timestamp": "2026-03-08T..." }
-}
+# Or via Claude Code slash command
+/install-skill hypurrquant/perp-cli
 ```
 
-Error responses:
-
-```json
-{
-  "ok": false,
-  "error": { "code": "INSUFFICIENT_BALANCE", "message": "...", "retryable": false },
-  "meta": { "timestamp": "..." }
-}
-```
+See [`skills/perp-cli/SKILL.md`](skills/perp-cli/SKILL.md) for the full agent guide.
 
-### Composite Plans
+## Agent-First CLI Design
 
-Multi-step atomic operations for agents:
+Built following [agent-first CLI principles](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/):
 
 ```bash
-perp plan example                   # Example plan JSON
-perp plan validate plan.json        # Validate a plan
-perp plan execute plan.json         # Execute multi-step plan
-```
+# Every command returns structured JSON envelope
+perp --json portfolio
+# → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } }
 
-## Configuration
+# Runtime schema introspection (don't guess commands — query this)
+perp --json agent schema
 
-### Wallet Management (Recommended)
+# Filter output to save tokens
+perp --json --fields totalEquity,risk portfolio
 
-```bash
-perp init                           # Interactive setup wizard
-perp wallet generate evm            # Generate new EVM wallet
-perp wallet import solana <key>     # Import existing key
-perp wallet use <name>              # Auto-bind to exchanges by type
-perp wallet list                    # List all wallets
-perp wallet balance                 # On-chain balances
-```
-
-Wallets are stored in `~/.perp/wallets.json` (file permission 0600).
+# Stream large lists as NDJSON (one JSON per line)
+perp --json --ndjson -e hl market list
 
-### Environment Variables
+# Pre-validate before executing
+perp --json -e hl trade check BTC buy 0.01
+perp --json --dry-run -e hl trade market BTC buy 0.01
 
-```bash
-# Exchange keys (alternative to wallet management)
-PRIVATE_KEY=                        # Default key (Solana base58 or EVM hex)
-PACIFICA_PRIVATE_KEY=               # Pacifica (Solana)
-HL_PRIVATE_KEY=                     # Hyperliquid (EVM)
-LIGHTER_PRIVATE_KEY=                # Lighter (EVM)
-LIGHTER_API_KEY=                    # Lighter API key (40-byte)
+# Idempotent orders with client ID
+perp --json -e hl trade market BTC buy 0.01 --client-id my-unique-id
 ```
 
-Key resolution order: `--private-key` flag → exchange-specific env var → `PRIVATE_KEY` → wallet store → `~/.perp/<exchange>.key`
-
-### Settings
-
-```bash
-perp settings show                  # Current settings
-perp settings set default-exchange hyperliquid  # Set default exchange
-perp settings referrals on          # Enable referral codes
-perp settings set referralCodes.hyperliquid MYCODE
-```
-
-## Tech Stack
-
-- **TypeScript** + Node.js (ESM)
-- **Solana**: `@solana/web3.js`, `tweetnacl`, `bs58`
-- **EVM**: `ethers` v6
-- **Exchanges**: `hyperliquid` SDK, `lighter-ts-sdk` (WASM), `@pacifica/sdk`
-- **Bridge**: Circle CCTP V2 (Solana ↔ EVM), deBridge DLN (fallback)
-- **Testing**: Vitest (860+ tests)
+All responses are auto-sanitized (control chars stripped, prompt injection patterns blocked).
+Errors include `retryable` flag — only retry when `true`.
 
 ## License
 

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/index.js

@@ -56,6 +56,8 @@ program
     .option("-n, --network <network>", "Network: mainnet or testnet", "mainnet")
     .option("-k, --private-key <key>", "Private key")
     .option("--json", "Output raw JSON (for piping)")
+    .option("--fields <fields>", "Comma-separated fields to include in JSON output (e.g. totalEquity,positions)")
+    .option("--ndjson", "Output newline-delimited JSON (one object per line for streaming)")
     .option("--dry-run", "Simulate trades without executing (log as simulated)")
     .option("--dex <name>", "HIP-3 deployed perp dex name (Hyperliquid only)")
     .configureOutput({

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/dist/utils.js

@@ -51,8 +51,78 @@ export function makeTable(head, rows) {
     rows.forEach((r) => table.push(r));
     return table.toString();
 }
+/** Pick only specified keys from an object (shallow). Supports nested paths via dot notation. */
+function pickFields(obj, fields) {
+    if (obj == null || typeof obj !== "object")
+        return obj;
+    const result = {};
+    for (const field of fields) {
+        const parts = field.split(".");
+        let src = obj;
+        for (const p of parts) {
+            if (src == null || typeof src !== "object") {
+                src = undefined;
+                break;
+            }
+            src = src[p];
+        }
+        if (src !== undefined) {
+            result[field] = src;
+        }
+    }
+    return result;
+}
+// ── Response Sanitization ──
+// Strips control characters and potential prompt-injection patterns from all string values.
+// Applied automatically to all JSON output to prevent agent confusion from external data.
+const CONTROL_CHAR_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+const PROMPT_INJECTION_RE = /(?:^|\n)\s*(?:SYSTEM:|ASSISTANT:|HUMAN:|<\/?(?:system|prompt|instruction|tool_use)>|ignore (?:previous|above|all) instructions?)/gi;
+function sanitizeValue(val) {
+    if (typeof val === "string") {
+        let s = val.replace(CONTROL_CHAR_RE, "");
+        if (PROMPT_INJECTION_RE.test(s)) {
+            s = s.replace(PROMPT_INJECTION_RE, "[SANITIZED]");
+        }
+        return s;
+    }
+    if (Array.isArray(val))
+        return val.map(sanitizeValue);
+    if (val && typeof val === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(val)) {
+            out[k] = sanitizeValue(v);
+        }
+        return out;
+    }
+    return val;
+}
+// ── JSON Output ──
+const _isNdjson = () => process.argv.includes("--ndjson");
 export function printJson(data) {
-    console.log(JSON.stringify(data, null, 2));
+    // Sanitize all string values in output
+    let output = sanitizeValue(data);
+    // Apply --fields filter
+    const fieldsArg = process.argv.indexOf("--fields");
+    if (fieldsArg !== -1 && process.argv[fieldsArg + 1] && output && typeof output === "object") {
+        const fields = process.argv[fieldsArg + 1].split(",").map(f => f.trim());
+        const envelope = output;
+        if (envelope.ok && envelope.data && typeof envelope.data === "object") {
+            envelope.data = pickFields(envelope.data, fields);
+        }
+        output = envelope;
+    }
+    // NDJSON mode: if data.data is an array, emit one JSON line per element
+    if (_isNdjson() && output && typeof output === "object") {
+        const envelope = output;
+        if (envelope.ok && Array.isArray(envelope.data)) {
+            const meta = envelope.meta;
+            for (const item of envelope.data) {
+                console.log(JSON.stringify({ ok: true, data: item, meta }));
+            }
+            return;
+        }
+    }
+    console.log(JSON.stringify(output, null, _isNdjson() ? undefined : 2));
 }
 export function errorAndExit(msg) {
     if (process.argv.includes("--json")) {

package/package.json

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

package/skills/perp-cli/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.3.14"
+  version: "0.3.17"
 ---
 
 # perp-cli Agent Guide
@@ -15,10 +15,11 @@ Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), L
 ## Rules
 
 1. **Always use `--json`** on every command.
-2. **NEVER use `perp init`** — interactive, will hang. Use `wallet set` instead.
-3. **NEVER trade without user confirmation.** Show order details and wait for approval.
-4. **NEVER read ~/.perp/.env or key files.** Use `perp --json wallet show`.
-5. **Risk first.** Run `perp --json risk status` before and during any operation.
+2. **Always use `--dry-run`** before any mutating trade (then execute without it after user confirms).
+3. **Always use `--fields`** to reduce output when you only need specific data (saves tokens).
+4. **NEVER use `perp init`** — interactive, will hang.
+5. **NEVER trade without user confirmation.**
+6. **NEVER read ~/.perp/.env or key files.**
 
 ## Install
 
@@ -35,81 +36,115 @@ 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
 ```
-Same EVM key works for both HL and Lighter. Lighter API key is created automatically on first use.
+Same EVM key works for both HL and Lighter.
 
-## Core Commands
+## Key Commands
 
 ```bash
-# Account
-perp --json -e <EX> account info          # balance, equity, margin
-perp --json -e <EX> account positions     # open positions
-perp --json portfolio                     # unified multi-exchange view
-
-# Market
-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
-
-# Trading
-perp --json -e <EX> trade leverage <SYM> <N> --isolated  # set BEFORE trading
+# Status (ONE call = balances, positions, risk level/violations/canTrade)
+perp --json portfolio
+
+# Arb workflow
+perp --json arb scan --min 5                                    # find opportunities
+perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage <N> --isolated  # execute
+
+# Single exchange trading (when not doing arb)
 perp --json -e <EX> trade market <SYM> buy <SIZE>
-perp --json -e <EX> trade market <SYM> sell <SIZE>
 perp --json -e <EX> trade close <SYM>
-perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L>
 
-# Risk
-perp --json risk status                   # risk level + violations
-perp --json risk liquidation-distance     # % from liq for all positions
-perp --json risk check --notional <$> --leverage <L>
+# Risk (only if you need to set limits — portfolio already includes risk)
+perp --json risk limits --max-leverage 5
+```
+
+Exchange aliases: `hl`, `pac`, `lt`. Symbols auto-resolve (`BTC`, `SOL`, `ICP`).
+
+## Agent Tools
+
+```bash
+# Discover all commands and parameters at runtime (don't guess — query this)
+perp --json agent schema
+
+# Pre-validate a trade before execution (checks balance, liquidity, risk limits)
+perp --json -e <EX> trade check <SYM> <SIDE> <SIZE>
+
+# Dry-run: simulate trade without executing
+perp --json --dry-run -e <EX> trade market <SYM> buy <SIZE>
 
-# Arb
-perp --json arb scan --min 5             # find funding arb opportunities
+# Filter output to specific fields (saves tokens)
+perp --json --fields totalEquity,positions portfolio
+
+# Stream large lists as NDJSON (one JSON per line, no buffering)
+perp --json --ndjson -e <EX> market list
+
+# Prevent duplicate orders with client ID
+perp --json -e <EX> trade market <SYM> buy <SIZE> --client-id <UNIQUE_ID>
 ```
 
-Exchange aliases: `hl`/`hyperliquid`, `pac`/`pacifica`, `lt`/`lighter`. Symbols auto-resolve (use bare: `BTC`, `SOL`, `ICP`).
+All string outputs are auto-sanitized (control chars stripped, prompt injection patterns blocked).
 
-## Trade Execution Checklist
+## Arb Workflow
 
 ```
-1. perp --json risk status                → STOP if critical
-2. perp --json -e <EX> account info       → verify balance
-3. perp --json -e <EX> trade leverage <SYM> <N> --isolated
-4. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L>
-5. [Show details to user, get confirmation]
-6. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE>
-7. perp --json -e <EX> account positions  → verify + check liq price
+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
 ```
 
 ## Position Sizing
 
-- Single position notional < **80%** of that exchange's available balance
-- Use ISOLATED margin for arb
-- Leverage 1-3x for arb, never exceed 5x
-- Both arb legs MUST have exact same size
+- 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
+
+## Arb Direction (CRITICAL)
+
+`arb scan` returns `longExch`, `shortExch`, `netSpread`.
+ALWAYS follow exactly. NEVER reverse. NEVER enter if `netSpread <= 0`.
 
-## Funding Arb Direction
+## Slippage Check (CRITICAL)
 
+`arb scan` returns `netSpread` in bps (already fee-adjusted).
+Before executing, compare against estimated slippage:
 ```
-arb scan returns: longExch, shortExch, netSpread
-→ ALWAYS follow longExch/shortExch exactly. NEVER reverse.
-→ NEVER enter if netSpread <= 0
+Slippage ≈ 2-5 bps per leg for top pairs (BTC, ETH, SOL)
+         ≈ 5-15 bps per leg for low-liquidity (altcoins)
+Total round-trip slippage = (entry + exit) × 2 legs
 ```
+**NEVER enter if:** `netSpread < total round-trip slippage`
+Example: netSpread=12 bps, estimated slippage=4 bps/leg × 4 = 16 bps → SKIP.
+
+## Portfolio Response
+
+`portfolio` includes `risk: { level, canTrade, violations[] }` — no need for separate `risk status`.
+Check `canTrade` before any order. If `false`, do NOT trade.
 
 ## Monitoring (while positions open)
 
-Every 15 min: `risk status` + `risk liquidation-distance` + `account positions`
-Every 1 hour: `arb scan --min 5` + `portfolio`
-Exit if: spread < breakeven, risk critical, one leg closed unexpectedly.
+```
+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
 
-All responses: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
+Responses: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
 
-Retryable (wait 5s, retry once): `RATE_LIMITED`, `EXCHANGE_UNREACHABLE`, `TIMEOUT`
-Not retryable: `INSUFFICIENT_BALANCE`, `MARGIN_INSUFFICIENT`, `SYMBOL_NOT_FOUND`
+- **Retryable** (wait 5s, max 3 retries): `RATE_LIMITED`, `EXCHANGE_UNREACHABLE`, `TIMEOUT`
+- **Non-retryable**: `INSUFFICIENT_BALANCE`, `SYMBOL_NOT_FOUND`, `RISK_VIOLATION` — fix the cause, don't retry
+- **Lighter `invalid signature`**: `perp --json -e lighter manage setup-api-key`
+- If `error.retryable` is `false`, do NOT retry. Report to user.
 
 ## References
 
 - `references/commands.md` — full command reference
-- `references/agent-operations.md` — setup flows, deposit/withdraw, idempotency
-- `references/strategies.md` — risk framework, arb strategy, opportunity cost
+- `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-margin 95 \
   --max-position-pct 80 \
   --max-drawdown 500 \
   --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