perp-cli 0.3.4 → 0.3.5

package/dist/commands/manage.js

@@ -1,5 +1,6 @@
 import { PacificaAdapter } from "../exchanges/pacifica.js";
 import { printJson, jsonOk } from "../utils.js";
+import { setEnvVar } from "./init.js";
 import chalk from "chalk";
 export function registerManageCommands(program, getAdapter, isJson, getPacificaAdapter) {
     const manage = program.command("manage").description("Account management");
@@ -288,6 +289,9 @@ export function registerManageCommands(program, getAdapter, isJson, getPacificaA
             console.log(chalk.gray("  Generating key pair + registering on-chain...\n"));
         }
         const { privateKey, publicKey } = await adapter.setupApiKey(keyIndex);
+        // Auto-save to .env
+        setEnvVar("LIGHTER_API_KEY", privateKey);
+        setEnvVar("LIGHTER_ACCOUNT_INDEX", String(adapter.accountIndex));
         if (isJson()) {
             return printJson(jsonOk({
                 privateKey,
@@ -295,15 +299,13 @@ export function registerManageCommands(program, getAdapter, isJson, getPacificaA
                 address: adapter.address,
                 accountIndex: adapter.accountIndex,
                 apiKeyIndex: keyIndex,
+                savedToEnv: true,
             }));
         }
-        console.log(chalk.green("  API Key Registered!\n"));
+        console.log(chalk.green("  API Key Registered & saved to ~/.perp/.env\n"));
         console.log(`  ${chalk.bold("Private Key:")} ${privateKey}`);
         console.log(`  ${chalk.bold("Public Key:")}  ${publicKey}`);
-        console.log();
-        console.log(chalk.yellow("  Add to your .env file:"));
-        console.log(chalk.white(`  LIGHTER_API_KEY=${privateKey}`));
-        console.log(chalk.white(`  LIGHTER_ACCOUNT_INDEX=${adapter.accountIndex}`));
+        console.log(`  ${chalk.bold("Account:")}     ${adapter.accountIndex}`);
         console.log();
     });
 }

package/dist/commands/wallet.js

@@ -382,13 +382,41 @@ export function registerWalletCommands(program, isJson) {
             settings.defaultExchange = resolved;
             saveSettings(settings);
         }
+        // Auto-setup Lighter API key if setting lighter PK
+        let lighterApiSetup = {};
+        if (resolved === "lighter") {
+            try {
+                const { LighterAdapter } = await import("../exchanges/lighter.js");
+                const adapter = new LighterAdapter(normalized);
+                await adapter.init();
+                const { privateKey: apiKey } = await adapter.setupApiKey();
+                setEnvVar("LIGHTER_API_KEY", apiKey);
+                setEnvVar("LIGHTER_ACCOUNT_INDEX", String(adapter.accountIndex));
+                lighterApiSetup = { apiKey, accountIndex: adapter.accountIndex };
+            }
+            catch (e) {
+                lighterApiSetup = { error: e instanceof Error ? e.message : String(e) };
+            }
+        }
         if (isJson())
-            return printJson(jsonOk({ exchange: resolved, address, envFile: ENV_FILE, default: !!opts.default }));
+            return printJson(jsonOk({
+                exchange: resolved, address, envFile: ENV_FILE, default: !!opts.default,
+                ...(resolved === "lighter" && { lighterApiKey: lighterApiSetup }),
+            }));
         console.log(chalk.green(`\n  ${resolved} configured.`));
         console.log(`  Address:  ${chalk.green(address)}`);
         console.log(`  Saved to: ${chalk.gray("~/.perp/.env")}`);
         if (opts.default)
             console.log(`  Default:  ${chalk.cyan(resolved)}`);
+        if (resolved === "lighter") {
+            if (lighterApiSetup.apiKey) {
+                console.log(chalk.green(`  API Key:  auto-registered (index: ${lighterApiSetup.accountIndex})`));
+            }
+            else {
+                console.log(chalk.yellow(`  API Key:  setup failed — ${lighterApiSetup.error}`));
+                console.log(chalk.gray(`  You can retry: perp -e lighter manage setup-api-key`));
+            }
+        }
         console.log();
     });
     // ── show (show configured exchanges with public addresses) ──

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.4")
+    .version("0.3.5")
     .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.4\n"));
+                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.5\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.4\n"));
+                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.5\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.4" }, { capabilities: { tools: {}, resources: {} } });
+const server = new McpServer({ name: "perp-cli", version: "0.3.5" }, { 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.4",
+  "version": "0.3.5",
   "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.4"
+  version: "0.3.5"
   mcp-server: perp-cli
 ---
 
@@ -22,6 +22,7 @@ Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), L
 5. **Verify wallet before any operation.** Run `perp --json wallet show` first.
 6. **Use ISOLATED margin for arb.** Set `perp --json manage margin <SYM> isolated` before opening positions. Cross margin can cascade liquidations.
 7. **Monitor positions continuously.** Run `perp --json risk status` and `perp --json -e <EX> account positions` every 15 minutes while positions are open.
+8. **NEVER read ~/.perp/.env or any key files directly.** Private keys are managed by the CLI internally. Use `perp --json wallet show` to check wallet status. Never attempt to read, cat, or access key files — this is a security violation.
 
 ## Step 1: Install
 

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

@@ -81,6 +81,23 @@ perp --json bridge status <orderId>     # wait for completion
 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:**
+
+```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:
+```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

@@ -79,6 +79,40 @@ When evaluating an arb opportunity:
    - Both positions should open near-simultaneously to minimize directional exposure
    - If capital needs to bridge first, you're exposed during transit
 
+### Hold Duration Target
+
+**Before entering any arb position, set a target hold duration.** This is critical for calculating whether the position is worth entering.
+
+```
+Expected Profit = hourly_spread × target_hours
+Entry/Exit Cost = open_fees + close_fees + slippage (both legs)
+Net Profit = Expected Profit - Entry/Exit Cost
+```
+
+**Only enter if Net Profit > 0 with a comfortable margin.**
+
+Guidelines for hold duration:
+- **Stable spreads (20-50 bps):** target 8-24 hours. These are reliable but low-yield — you need time for the funding to accumulate past your entry/exit costs.
+- **Elevated spreads (50-100 bps):** target 4-8 hours. Higher yield, but likely to compress. Take profit earlier.
+- **Spike spreads (>100 bps):** target 1-4 hours. These revert quickly. Must cover entry/exit costs within a few funding cycles.
+
+**Re-evaluate at each funding settlement (every hour):**
+1. Is the spread still above breakeven for the remaining target hours?
+2. If spread compressed, should I exit early or extend the hold?
+3. Has a better opportunity appeared? (Remember: switching has its own cost)
+
+**Track your actual hold durations vs targets over time.** This builds intuition for how long spreads persist on each exchange pair.
+
+Example entry decision log:
+```
+Entry: BTC HL↔PAC | Spread: 35 bps | Target hold: 12h
+Expected: 35 bps × 12h = 420 bps gross
+Entry/exit cost: ~80 bps (fees + slippage both legs)
+Net expected: ~340 bps → ENTER
+Hour 6 check: spread compressed to 15 bps → below breakeven for remaining 6h → EXIT
+Actual hold: 6h | Actual net: ~130 bps
+```
+
 ### Monitoring Active Positions
 ```bash
 perp --json portfolio                    # unified multi-exchange view