perp-cli 0.3.5 → 0.3.7

package/dist/exchanges/lighter.js

@@ -62,6 +62,23 @@ export class LighterAdapter {
                 ? this._accountIndexInit
                 : json.accounts[0].account_index;
         }
+        // Auto-generate API key if we have PK but no API key and account exists
+        if (!this._apiKey && this._accountIndex >= 0) {
+            try {
+                const { privateKey: apiKey } = await this.setupApiKey();
+                this._apiKey = apiKey;
+                // Save to .env for future use
+                try {
+                    const { setEnvVar } = await import("../commands/init.js");
+                    setEnvVar("LIGHTER_API_KEY", apiKey);
+                    setEnvVar("LIGHTER_ACCOUNT_INDEX", String(this._accountIndex));
+                }
+                catch { /* non-critical — env save may fail in some contexts */ }
+            }
+            catch {
+                // Auto-setup failed (no gas, network issue, etc.) — continue in read-only mode
+            }
+        }
         // Initialize signer for trading if we have an API key
         if (this._apiKey) {
             const { LighterSignerClient } = require("lighter-sdk");

package/dist/index.js

@@ -48,7 +48,7 @@ const _defaultExchange = _settings.defaultExchange || "pacifica";
 program
     .name("perp")
     .description("Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter)")
-    .version("0.3.5")
+    .version("0.3.7")
     .option("-e, --exchange <exchange>", `Exchange: pacifica, hyperliquid, lighter (default: ${_defaultExchange})`, _defaultExchange)
     .option("-n, --network <network>", "Network: mainnet or testnet", "mainnet")
     .option("-k, --private-key <key>", "Private key")
@@ -383,7 +383,7 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                 process.env.LIGHTER_PRIVATE_KEY);
             if (!status.hasWallets && !hasEnvKey && !settings.defaultExchange) {
                 // Fresh install — onboarding
-                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.5\n"));
+                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.7\n"));
                 console.log("  Multi-DEX perpetual futures CLI for Pacifica, Hyperliquid, and Lighter.\n");
                 console.log(`  Get started:  ${chalk.cyan("perp init")}`);
                 console.log(chalk.gray(`\n  Or explore without a wallet:`));
@@ -396,7 +396,7 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                 // Configured — show status overview
                 const defaultEx = settings.defaultExchange || "pacifica";
                 const activeEntries = Object.entries(status.active);
-                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.5\n"));
+                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.7\n"));
                 console.log(`  Default exchange: ${chalk.cyan(defaultEx)}`);
                 if (activeEntries.length > 0) {
                     console.log(chalk.white.bold("\n  Wallets:"));

package/dist/mcp-server.js

@@ -56,7 +56,7 @@ function err(error, meta) {
     return JSON.stringify({ ok: false, error, meta }, null, 2);
 }
 // ── MCP Server ──
-const server = new McpServer({ name: "perp-cli", version: "0.3.5" }, { capabilities: { tools: {}, resources: {} } });
+const server = new McpServer({ name: "perp-cli", version: "0.3.7" }, { capabilities: { tools: {}, resources: {} } });
 // ============================================================
 // Market Data tools (read-only, no private key needed)
 // ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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.5"
+  version: "0.3.7"
   mcp-server: perp-cli
 ---
 
@@ -79,8 +79,15 @@ perp --json portfolio                        # unified multi-exchange view
 
 ### Trade execution (MANDATORY checklist)
 ```
+BEFORE ANY TRADE:
+0. perp --json portfolio                       → check TOTAL equity + per-exchange balances
+   - Single position notional < 25% of TOTAL equity
+   - Each exchange MUST have sufficient balance for its leg
+   - Notional ≠ margin required. Check available balance on EACH exchange.
+   - If balance is insufficient, bridge first or reduce size.
+
 1. perp --json risk status                     → check risk level (STOP if critical)
-2. perp --json -e <EX> account info            → verify balance
+2. perp --json -e <EX> account info            → verify EXCHANGE-SPECIFIC balance
 3. perp --json -e <EX> market mid <SYM>        → current price
 4. perp --json risk check --notional <$> --leverage <L> → risk pre-check
 5. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE>  → trade validation
@@ -89,6 +96,34 @@ perp --json portfolio                        # unified multi-exchange view
 8. perp --json -e <EX> account positions       → verify result + check liquidation price
 ```
 
+### Post-entry monitoring (MANDATORY while positions are open)
+```
+Every 15 minutes:
+  perp --json risk status                      → overall risk level + violations
+  perp --json risk liquidation-distance        → % from liq price for ALL positions
+  perp --json -e <EX> account positions        → check each position P&L
+
+Every 1 hour (at funding settlement):
+  perp --json arb rates                        → is spread still profitable?
+  perp --json portfolio                        → total equity across exchanges
+  Compare both legs' unrealized P&L — they should roughly offset
+
+Exit triggers:
+  - Spread below breakeven (including fees) → show exit plan, get user approval
+  - risk status level = "critical" or canTrade = false → reduce immediately
+  - One leg closed unexpectedly → close the other leg IMMEDIATELY
+  - Target hold duration reached → re-evaluate or exit
+```
+
+### Knowing your capital (CHECK BEFORE ANY DECISION)
+```
+perp --json wallet show                        → configured wallets + addresses
+perp --json wallet balance                     → on-chain USDC (in wallet, NOT on exchange)
+perp --json -e <EX> account info               → exchange balance (available for trading)
+perp --json portfolio                          → unified view: equity, margin, P&L per exchange
+```
+**On-chain balance ≠ exchange balance.** Always check both. Capital must be deposited to exchange before trading.
+
 For full command reference, see `references/commands.md`.
 For agent-specific operations (setup flows, deposit/withdraw, order types, idempotency), see `references/agent-operations.md`.
 For autonomous strategies (funding rate arb, risk management, opportunity cost), see `references/strategies.md`.

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

@@ -82,22 +82,14 @@ perp --json arb rates
 ```
 
 ### Lighter API Key Setup
-Lighter requires a separate API key in addition to the EVM private key. **`wallet set` handles this automatically:**
+Lighter uses a separate API key for trading, but **this is handled automatically**.
+When `LIGHTER_PRIVATE_KEY` is set (env var or `wallet set`), the CLI auto-generates and saves the API key on first use.
 
-```bash
-# wallet set automatically generates & registers API key + saves to .env
-perp --json wallet set lt 0xEVM_KEY
-# → saves LIGHTER_PRIVATE_KEY, LIGHTER_API_KEY, LIGHTER_ACCOUNT_INDEX to ~/.perp/.env
-```
-
-If auto-setup failed (e.g. no ETH for gas), retry manually:
+If auto-setup fails (e.g. no ETH for gas on Lighter chain), retry manually:
 ```bash
 perp --json -e lighter manage setup-api-key
-# → generates API key, registers on-chain, auto-saves to ~/.perp/.env
 ```
 
-**Note:** On-chain registration requires a small amount of ETH on the Lighter chain for gas.
-
 ### Using the Same EVM Key for Multiple Exchanges
 One EVM private key works for both Hyperliquid and Lighter:
 ```bash

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

@@ -310,6 +310,26 @@ Rules of thumb:
 - **Total margin used < 60% of total equity** — leave buffer for adverse moves
 - **Capital in transit (bridging) counts as "at risk"** — it's not available for margin
 
+### Per-Exchange Balance Constraints
+
+**CRITICAL: You can only trade with the balance available ON THAT EXCHANGE.**
+
+Each exchange holds its own separate balance. Before entering any arb:
+```bash
+perp --json -e <EX_A> account info           # check available balance on exchange A
+perp --json -e <EX_B> account info           # check available balance on exchange B
+```
+
+**Size each leg to fit the available balance on that exchange:**
+```
+Wrong:  total portfolio = $65 → 25% = $16 per leg → but Exchange A only has $10
+Right:  Exchange A has $10, Exchange B has $15 → max leg size = $10 (limited by smaller side)
+```
+
+If one exchange has insufficient balance:
+- Reduce position size to fit the smaller balance, OR
+- Bridge capital first (but account for bridge fees + time + unhedged risk during transit)
+
 ### Stop Loss for Arb Positions
 
 Even "market-neutral" arb can lose money if: