perp-cli 0.3.3 → 0.3.5

package/skills/perp-cli/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: perp-cli
 description: "Multi-DEX perpetual futures trading CLI for Pacifica (Solana), Hyperliquid (EVM), and Lighter (Ethereum). Use when user asks to trade perps, check funding rates, bridge USDC, manage positions, scan arbitrage opportunities, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, or Lighter exchanges. Also use when user says 'set up perp trading', 'check my positions', 'buy BTC perps', 'funding rate arb', 'bridge USDC', or 'deposit to exchange'."
+allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.3.3"
+  version: "0.3.5"
   mcp-server: perp-cli
 ---
 
@@ -14,10 +15,14 @@ Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), L
 
 ## Critical Rules
 
-1. **NEVER use interactive commands.** Do NOT run `perp init`. Always use non-interactive commands with `--json`.
-2. **Always use `--json`** on every command for structured output.
-3. **NEVER trade without user confirmation.** Show order details and wait for explicit approval.
-4. **Verify wallet before any operation.** Run `perp --json wallet show` first.
+1. **RISK MANAGEMENT IS YOUR #1 PRIORITY.** A single liquidation wipes out months of profit. Always check `perp --json risk status` before and during any operation. See `references/strategies.md` for the full risk framework.
+2. **NEVER use interactive commands.** Do NOT run `perp init`. Always use non-interactive commands with `--json`.
+3. **Always use `--json`** on every command for structured output.
+4. **NEVER trade without user confirmation.** Show order details and wait for explicit approval.
+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
 
@@ -74,15 +79,19 @@ perp --json portfolio                        # unified multi-exchange view
 
 ### Trade execution (MANDATORY checklist)
 ```
-1. perp --json -e <EX> account info           → verify balance
-2. perp --json -e <EX> market mid <SYM>       → current price
-3. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> → pre-flight validation
-4. [Show order details to user, get explicit confirmation]
-5. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE> → execute
-6. perp --json -e <EX> account positions      → verify result
+1. perp --json risk status                     → check risk level (STOP if critical)
+2. perp --json -e <EX> account info            → verify 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
+6. [Show order details + risk assessment to user, get explicit confirmation]
+7. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE>  → execute
+8. perp --json -e <EX> account positions       → verify result + check liquidation price
 ```
 
 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`.
 
 ## Response Format
 

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

@@ -0,0 +1,260 @@
+# Agent Operations Guide
+
+Complete reference for non-interactive CLI operations. Every command here is safe for agents — no prompts, no hangs.
+
+## Interactive vs Non-Interactive Commands
+
+### NEVER use these (interactive, will hang):
+```
+perp init                    # interactive wizard — asks questions via stdin
+perp wallet setup            # removed, but may appear in old docs
+```
+
+### ALWAYS use these (non-interactive, agent-safe):
+```bash
+perp --json wallet set <exchange> <key>     # set private key
+perp --json wallet generate evm             # generate EVM wallet
+perp --json wallet generate solana          # generate Solana wallet
+perp --json wallet show                     # check configured wallets
+perp --json wallet balance                  # on-chain USDC balances
+perp --json -e <EX> account info            # exchange account info
+perp --json -e <EX> account positions       # open positions
+perp --json -e <EX> market list             # available markets
+perp --json -e <EX> trade market ...        # execute trade
+perp --json -e <EX> trade buy ...           # alias for market buy
+perp --json -e <EX> trade sell ...          # alias for market sell
+perp --json risk status                     # risk assessment
+perp --json risk liquidation-distance       # % from liquidation for all positions
+perp --json risk limits                     # view/set risk limits
+perp --json risk check --notional <$> --leverage <L>  # pre-trade risk check
+```
+
+**Rule: every command MUST include `--json`.** Without it, output is human-formatted and harder to parse.
+
+## Zero to Trading: Complete Setup Flow
+
+### Single Exchange Setup
+```bash
+# 1. Install
+npm install -g perp-cli
+
+# 2. Register wallet (user provides key)
+perp --json wallet set hl 0xUSER_PRIVATE_KEY
+
+# 3. Verify
+perp --json wallet show
+# → check "ok": true and address appears
+
+# 4. Check balance
+perp --json -e hl account info
+# → if balance is 0, tell user to deposit USDC
+
+# 5. Ready to trade
+perp --json -e hl market list
+```
+
+### Multi-Exchange Setup (for Funding Rate Arb)
+To run arb, you need wallets on AT LEAST 2 exchanges. Each exchange needs:
+- A configured wallet with a private key
+- USDC balance deposited on-exchange
+
+```bash
+# 1. Register both wallets
+perp --json wallet set hl 0xEVM_KEY
+perp --json wallet set pac SOLANA_BASE58_KEY
+
+# 2. Verify both
+perp --json wallet show
+# → should show both exchanges with addresses
+
+# 3. Check balances on both
+perp --json -e hl account info
+perp --json -e pac account info
+
+# 4. If one side needs funding, bridge USDC
+perp --json bridge quote --from solana --to arbitrum --amount 500
+# → show quote to user, get confirmation
+perp --json bridge send --from solana --to arbitrum --amount 500
+perp --json bridge status <orderId>     # wait for completion
+
+# 5. Verify both sides have balance, then start arb
+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
+perp --json wallet set hl 0xKEY
+perp --json wallet set lt 0xKEY        # same key, different exchange binding
+```
+
+## Wallet Key Types
+
+| Exchange | Chain | Key Format | Example |
+|----------|-------|-----------|---------|
+| Hyperliquid | EVM | Hex with 0x prefix, 66 chars | `0x4c0883a69102937d...` |
+| Lighter | EVM | Hex with 0x prefix, 66 chars | `0x4c0883a69102937d...` |
+| Pacifica | Solana | Base58 string | `5KQwrPbwdL6PhXu...` |
+
+Aliases for exchange names:
+- `hl` or `hyperliquid`
+- `pac` or `pacifica`
+- `lt` or `lighter`
+
+## Deposit & Withdraw Flows
+
+### Check On-Chain vs Exchange Balance
+```bash
+perp --json wallet balance               # on-chain USDC in your wallet
+perp --json -e hl account info           # USDC deposited on exchange
+```
+
+**On-chain balance ≠ exchange balance.** USDC in your wallet must be deposited to the exchange before trading.
+
+### Deposit to Exchange
+```bash
+# Hyperliquid (from Arbitrum wallet)
+perp --json deposit hyperliquid 100
+
+# Pacifica (from Solana wallet)
+perp --json deposit pacifica 100
+
+# Lighter (multiple routes)
+perp --json deposit lighter info         # show all available routes
+perp --json deposit lighter cctp arb 100 # via CCTP from Arbitrum
+```
+
+### Withdraw from Exchange
+```bash
+perp --json withdraw hyperliquid 100
+perp --json withdraw pacifica 100
+```
+
+### Bridge Between Chains
+When you need to move USDC between exchanges on different chains:
+```bash
+# 1. Withdraw from source exchange
+perp --json withdraw pacifica 500
+
+# 2. Quote the bridge
+perp --json bridge quote --from solana --to arbitrum --amount 500
+
+# 3. Send (after user confirmation)
+perp --json bridge send --from solana --to arbitrum --amount 500
+
+# 4. Wait for completion
+perp --json bridge status <orderId>
+
+# 5. Deposit to destination exchange
+perp --json deposit hyperliquid 500
+```
+
+## Order Types & Execution
+
+### Market Orders (immediate execution)
+```bash
+perp --json -e hl trade market BTC buy 0.01       # market buy
+perp --json -e hl trade market BTC sell 0.01      # market sell
+perp --json -e hl trade buy BTC 0.01              # shorthand
+perp --json -e hl trade sell BTC 0.01             # shorthand
+```
+
+### Limit Orders (execute at specific price)
+```bash
+perp --json -e hl trade buy BTC 0.01 -p 60000    # buy at $60,000
+perp --json -e hl trade sell BTC 0.01 -p 70000   # sell at $70,000
+```
+
+### Close Position
+```bash
+perp --json -e hl trade close BTC                 # close entire position
+```
+
+### Stop Loss / Take Profit
+```bash
+perp --json -e hl trade sl BTC 58000              # stop loss at $58k
+perp --json -e hl trade tp BTC 65000              # take profit at $65k
+```
+
+### Cancel Orders
+```bash
+perp --json -e hl account orders                  # list open orders
+perp --json -e hl trade cancel <orderId>          # cancel specific order
+```
+
+### Pre-Flight Validation
+ALWAYS run before executing a trade:
+```bash
+perp --json -e hl trade check BTC buy 0.01
+```
+This returns estimated fees, slippage, and whether the trade can execute.
+
+## Parsing JSON Output
+
+Every command returns this envelope:
+```json
+{
+  "ok": true,
+  "data": { ... },
+  "meta": { "timestamp": "2026-03-11T..." }
+}
+```
+
+Error case:
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "INSUFFICIENT_BALANCE",
+    "message": "Not enough USDC",
+    "retryable": false
+  }
+}
+```
+
+**Always check `ok` field first.** If `ok` is `false`, read `error.code` to decide next action. If `error.retryable` is `true`, wait 5 seconds and retry once.
+
+## Idempotency & Safety
+
+### Safe to retry (idempotent):
+- `wallet show`, `wallet balance` — read-only
+- `account info`, `account positions`, `account orders` — read-only
+- `market list`, `market mid`, `market book` — read-only
+- `arb rates`, `arb scan` — read-only
+- `portfolio`, `risk overview` — read-only
+- `bridge quote` — read-only
+- `bridge status` — read-only
+
+### NOT safe to retry blindly:
+- `trade market`, `trade buy`, `trade sell` — will open duplicate positions
+- `trade close` — may error if already closed, but harmless
+- `bridge send` — will send duplicate transfers
+- `deposit`, `withdraw` — will move funds twice
+
+**For non-idempotent commands:** always verify the result before retrying. Check positions or balances to confirm whether the first attempt succeeded.
+
+## Common Agent Mistakes
+
+1. **Using `perp init`** — interactive, will hang forever. Use `wallet set` instead.
+2. **Forgetting `--json`** — output becomes unparseable human text.
+3. **Trading with zero balance** — check `account info` first, tell user to deposit.
+4. **Retrying a trade without checking** — leads to double positions. Always check `account positions` after a trade, even if it seemed to fail.
+5. **Bridging without quoting** — always run `bridge quote` first to show the user fees and estimated time.
+6. **Assuming deposit is instant** — after `bridge send`, wait for `bridge status` to confirm completion before depositing to the destination exchange.

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

@@ -108,8 +108,11 @@ perp --json wallet balance                  # on-chain balance
 
 ## Risk & Analytics
 ```bash
-perp --json risk status                     # portfolio risk overview
-perp --json risk limits                     # position limits
+perp --json risk status                     # portfolio risk overview (level, violations, canTrade)
+perp --json risk liquidation-distance       # % distance from liquidation for ALL positions
+perp --json risk limits                     # view current risk limits
+perp --json risk limits --min-liq-distance 30 --max-leverage 5  # set risk limits
+perp --json risk check --notional 1000 --leverage 3  # pre-trade risk check
 perp --json health                          # exchange connectivity & latency
 perp --json analytics summary              # trading performance
 perp --json analytics pnl                   # P&L breakdown