perp-cli 0.3.16 → 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/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/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.16",
+  "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.16"
+  version: "0.3.17"
 ---
 
 # perp-cli Agent Guide
@@ -15,9 +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.
-3. **NEVER trade without user confirmation.**
-4. **NEVER read ~/.perp/.env or key files.**
+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
 
@@ -56,6 +58,30 @@ 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>
+
+# 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>
+```
+
+All string outputs are auto-sanitized (control chars stripped, prompt injection patterns blocked).
+
 ## Arb Workflow
 
 ```
@@ -82,6 +108,18 @@ Exchange aliases: `hl`, `pac`, `lt`. Symbols auto-resolve (`BTC`, `SOL`, `ICP`).
 `arb scan` returns `longExch`, `shortExch`, `netSpread`.
 ALWAYS follow exactly. NEVER reverse. NEVER enter if `netSpread <= 0`.
 
+## Slippage Check (CRITICAL)
+
+`arb scan` returns `netSpread` in bps (already fee-adjusted).
+Before executing, compare against estimated slippage:
+```
+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`.
@@ -100,8 +138,10 @@ Close both: perp --json -e <EX1> trade close <SYM> & perp --json -e <EX2> trade
 
 Responses: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
 
-Retryable (wait 5s): `RATE_LIMITED`, `EXCHANGE_UNREACHABLE`, `TIMEOUT`
-**Lighter `invalid signature`**: `perp --json -e lighter manage setup-api-key`
+- **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