perp-cli 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 HypurrQuant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# 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.
+
+```bash
+npm install -g perp-cli
+perp status --json
+```
+
+## 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
+```
+
+### Deposit & Withdraw
+
+```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)
+
+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>
+```
+
+**Supported routes:** Solana ↔ Arbitrum ↔ Base (all 6 directions, $0 CCTP fee)
+
+### Funding Rate Arbitrage
+
+```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
+
+# Funding arb bot
+perp run arb --min-spread 20
+```
+
+### Real-Time Streams
+
+```bash
+perp stream book BTC                # Live orderbook
+perp stream trades BTC              # Live trades
+perp stream funding                 # Live funding rates
+```
+
+### Live Dashboard
+
+```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 to let Claude trade for you:
+
+```bash
+# In Claude Code
+/plugin marketplace add hypurrquant/perp-cli
+/plugin install perp-trading@hypurrquant-perp-cli
+```
+
+Once installed, use `/perp-trading` in Claude Code:
+
+```
+/perp-trading status                          # Check all exchanges
+/perp-trading BTC 0.01 long on hyperliquid    # Natural language trading
+/perp-trading scan arb opportunities          # Find funding rate arb
+/perp-trading bridge 100 USDC solana to arb   # Cross-chain bridge
+```
+
+The skill includes safety guardrails (balance checks, user confirmation before trades, error handling with retries).
+
+## AI Agent Integration
+
+Every command supports `--json` for structured output:
+
+```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:
+
+```json
+{
+  "ok": true,
+  "data": { ... },
+  "meta": { "timestamp": "2026-03-08T..." }
+}
+```
+
+Error responses:
+
+```json
+{
+  "ok": false,
+  "error": { "code": "INSUFFICIENT_BALANCE", "message": "...", "retryable": false },
+  "meta": { "timestamp": "..." }
+}
+```
+
+### Composite Plans
+
+Multi-step atomic operations for 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
+```
+
+## Configuration
+
+### Wallet Management (Recommended)
+
+```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).
+
+### Environment Variables
+
+```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)
+```
+
+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-sdk` (WASM), `@pacifica/sdk`
+- **Bridge**: Circle CCTP V2 (Solana ↔ EVM), deBridge DLN (fallback)
+- **Testing**: Vitest (860+ tests)
+
+## License
+
+MIT

package/dist/__tests__/alert-logic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/alert-logic.test.js

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest";
+/**
+ * Tests for the alert price merging logic (extracted from alert.ts).
+ * Validates the fix for the price map key inconsistency bug.
+ */
+function mergePrices(pacData, hlData) {
+    const map = new Map();
+    if (pacData) {
+        for (const p of pacData) {
+            map.set(`pac:${p.symbol}`, Number(p.mark));
+        }
+    }
+    if (hlData) {
+        for (const [symbol, price] of Object.entries(hlData)) {
+            map.set(`hl:${symbol}`, Number(price));
+        }
+    }
+    // Merge into bare symbol keys: prefer pac price, fallback to hl
+    const allSymbols = new Set();
+    for (const k of map.keys()) {
+        if (k.includes(":"))
+            allSymbols.add(k.split(":")[1]);
+    }
+    for (const sym of allSymbols) {
+        const pacPrice = map.get(`pac:${sym}`);
+        const hlPrice = map.get(`hl:${sym}`);
+        map.set(sym, pacPrice ?? hlPrice ?? 0);
+    }
+    return map;
+}
+describe("Alert price merging", () => {
+    it("prefers Pacifica price when both available", () => {
+        const map = mergePrices([{ symbol: "BTC", mark: "100000" }], { BTC: "99900" });
+        expect(map.get("BTC")).toBe(100000);
+        expect(map.get("pac:BTC")).toBe(100000);
+        expect(map.get("hl:BTC")).toBe(99900);
+    });
+    it("falls back to HL price when pac unavailable", () => {
+        const map = mergePrices(null, { ETH: "3500" });
+        expect(map.get("ETH")).toBe(3500);
+        expect(map.has("pac:ETH")).toBe(false);
+        expect(map.get("hl:ETH")).toBe(3500);
+    });
+    it("handles Pacifica-only symbols", () => {
+        const map = mergePrices([{ symbol: "SOL", mark: "150" }], {});
+        expect(map.get("SOL")).toBe(150);
+    });
+    it("handles empty data", () => {
+        const map = mergePrices(null, null);
+        expect(map.size).toBe(0);
+    });
+    it("handles multiple symbols from both sources", () => {
+        const map = mergePrices([
+            { symbol: "BTC", mark: "100000" },
+            { symbol: "ETH", mark: "3500" },
+        ], {
+            BTC: "99900",
+            ETH: "3490",
+            SOL: "150",
+        });
+        // Pac preferred for BTC and ETH
+        expect(map.get("BTC")).toBe(100000);
+        expect(map.get("ETH")).toBe(3500);
+        // HL-only for SOL
+        expect(map.get("SOL")).toBe(150);
+    });
+    it("bare symbol key is always set (no orphaned prefixed keys)", () => {
+        const map = mergePrices([{ symbol: "DOGE", mark: "0.15" }], { DOGE: "0.14", ARB: "1.20" });
+        // Every symbol with a prefixed key should have a bare key
+        for (const k of map.keys()) {
+            if (k.includes(":")) {
+                const bare = k.split(":")[1];
+                expect(map.has(bare)).toBe(true);
+            }
+        }
+    });
+});
+describe("Alert trigger conditions", () => {
+    it("fires price above alert", () => {
+        const currentPrice = 105000;
+        const threshold = 100000;
+        const condition = "above";
+        expect(condition === "above" && currentPrice >= threshold).toBe(true);
+    });
+    it("does NOT fire price above when below", () => {
+        const currentPrice = 95000;
+        const threshold = 100000;
+        const condition = "above";
+        expect(condition === "above" && currentPrice >= threshold).toBe(false);
+    });
+    it("fires price below alert", () => {
+        const currentPrice = 95000;
+        const threshold = 100000;
+        const condition = "below";
+        expect(condition === "below" && currentPrice <= threshold).toBe(true);
+    });
+    it("fires funding spread alert", () => {
+        const spread = 35; // annual %
+        const alertThreshold = 30;
+        expect(spread >= alertThreshold).toBe(true);
+    });
+    it("does NOT fire funding spread below threshold", () => {
+        const spread = 25;
+        const alertThreshold = 30;
+        expect(spread >= alertThreshold).toBe(false);
+    });
+});

package/dist/__tests__/arb-auto-3dex.test.d.ts

@@ -0,0 +1 @@
+export {};