perp-cli 0.3.14 → 0.3.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/package.json +1 -1
  2. package/skills/perp-cli/SKILL.md +65 -257
  3. package/skills/perp-cli/references/strategies.md +5 -5
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "perp-cli",
3
- "version": "0.3.14",
3
+ "version": "0.3.15",
4
4
  "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
5
5
  "bin": {
6
6
  "perp": "dist/index.js",
package/skills/perp-cli/SKILL.md CHANGED
@@ -1,307 +1,115 @@
1
1
  ---
2
2
  name: perp-cli
3
- 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'."
3
+ 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."
4
4
  allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
5
5
  license: MIT
6
6
  metadata:
7
7
  author: hypurrquant
8
- version: "0.3.12"
9
- mcp-server: perp-cli
8
+ version: "0.3.14"
10
9
  ---
11
10
 
12
11
  # perp-cli Agent Guide
13
12
 
14
13
  Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum).
15
14
 
16
- ## Critical Rules
15
+ ## Rules
17
16
 
18
- 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.
19
- 2. **NEVER use interactive commands.** Do NOT run `perp init`. Always use non-interactive commands with `--json`.
20
- 3. **Always use `--json`** on every command for structured output.
21
- 4. **NEVER trade without user confirmation.** Show order details and wait for explicit approval.
22
- 5. **Verify wallet before any operation.** Run `perp --json wallet show` first.
23
- 6. **Use ISOLATED margin for arb.** Set `perp --json manage margin <SYM> isolated` before opening positions. Cross margin can cascade liquidations.
24
- 7. **Monitor positions continuously.** Run `perp --json risk status` and `perp --json -e <EX> account positions` every 15 minutes while positions are open.
25
- 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.
17
+ 1. **Always use `--json`** on every command.
18
+ 2. **NEVER use `perp init`** — interactive, will hang. Use `wallet set` instead.
19
+ 3. **NEVER trade without user confirmation.** Show order details and wait for approval.
20
+ 4. **NEVER read ~/.perp/.env or key files.** Use `perp --json wallet show`.
21
+ 5. **Risk first.** Run `perp --json risk status` before and during any operation.
26
22
 
27
- ## Step 1: Install
23
+ ## Install
28
24
 
29
25
  ```bash
30
26
  npm install -g perp-cli
31
27
  ```
28
+ No sudo: `npm install -g perp-cli --prefix ~/.npm-global && export PATH="$HOME/.npm-global/bin:$PATH"`
32
29
 
33
- **No sudo / Docker / restricted environments:**
34
- ```bash
35
- npm config set prefix ~/.npm-global
36
- npm install -g perp-cli --prefix ~/.npm-global
37
- export PATH="$HOME/.npm-global/bin:$PATH"
38
- ```
39
-
40
- ## Step 2: Configure Wallet
41
-
42
- CRITICAL: Do NOT use `perp init` — it is interactive and will hang.
43
-
44
- **If user needs a new wallet:**
45
- ```bash
46
- perp --json wallet generate evm # creates EVM wallet for Hyperliquid + Lighter
47
- perp --json wallet generate solana # creates Solana wallet for Pacifica
48
- # IMPORTANT: Tell user the generated address so they can fund it with USDC!
49
- ```
30
+ ## Wallet Setup
50
31
 
51
- ### Hyperliquid setup
52
32
  ```bash
53
- perp --json wallet set hl <EVM_PRIVATE_KEY> # register EVM key → ready to trade immediately
54
- perp --json wallet show # verify
55
- perp --json -e hl account info # check balance
33
+ perp --json wallet set hl <EVM_KEY> # Hyperliquid
34
+ perp --json wallet set pac <SOLANA_KEY> # Pacifica
35
+ perp --json wallet set lt <EVM_KEY> # Lighter (API key auto-generated)
36
+ perp --json wallet show # verify
56
37
  ```
57
- No extra steps. Key is saved as `HL_PRIVATE_KEY` in .env.
38
+ Same EVM key works for both HL and Lighter. Lighter API key is created automatically on first use.
58
39
 
59
- ### Pacifica setup
60
- ```bash
61
- perp --json wallet set pac <SOLANA_PRIVATE_KEY> # register Solana key → ready to trade immediately
62
- perp --json wallet show # verify
63
- perp --json -e pac account info # check balance
64
- ```
65
- No extra steps. Key is saved as `PACIFICA_PRIVATE_KEY` in .env.
66
-
67
- ### Lighter setup (API key auto-generated on registration)
68
- ```bash
69
- perp --json wallet set lt <EVM_PRIVATE_KEY> # register EVM key
70
- # → AUTOMATICALLY generates Lighter API key via on-chain tx
71
- # → Saves to .env: LIGHTER_PRIVATE_KEY, LIGHTER_API_KEY, LIGHTER_ACCOUNT_INDEX, LIGHTER_API_KEY_INDEX
72
- # → No manual API key creation needed. Do NOT ask the user to visit the Lighter website.
73
- perp --json wallet show # verify
74
- perp --json -e lighter account info # check balance
75
- ```
76
- Same EVM key can be used for both Hyperliquid and Lighter:
77
- ```bash
78
- perp --json wallet set hl <KEY> # same key
79
- perp --json wallet set lt <KEY> # same key, different exchange binding
80
- ```
81
- If API key auto-setup fails (rare, e.g. no ETH for gas on Lighter chain):
82
- ```bash
83
- perp --json -e lighter manage setup-api-key # manual retry
84
- ```
85
-
86
- **Verify setup (ALWAYS do this after any wallet command):**
87
- ```bash
88
- perp --json wallet show
89
- # Success: { "ok": true, "data": { "exchanges": [{ "exchange": "hyperliquid", "address": "0x..." }] } }
90
- # Empty: { "ok": true, "data": { "exchanges": [] } } ← wallet not configured yet
91
- ```
92
-
93
- ## Step 3: Use
94
-
95
- ### Exchange selection
96
- ```bash
97
- perp --json -e hyperliquid ... # Hyperliquid (EVM)
98
- perp --json -e pacifica ... # Pacifica (Solana)
99
- perp --json -e lighter ... # Lighter (Ethereum)
100
- ```
101
- If a default exchange is set, `-e` can be omitted.
102
-
103
- ### Symbol naming
104
- Symbols are auto-resolved across exchanges. Use bare symbols (e.g., `BTC`, `SOL`, `ICP`) everywhere — the CLI handles exchange-specific naming:
105
- - **Hyperliquid**: `ICP` → `ICP-PERP` (auto-resolved, `-PERP` suffix added)
106
- - **Pacifica / Lighter**: bare symbols as-is
107
- - `arb scan` returns bare symbols — pass them directly to any exchange command.
108
-
109
- ### Common operations
110
- ```bash
111
- perp --json wallet show # check configured wallets
112
- perp --json portfolio # unified multi-exchange view
113
- perp --json arb scan --min 5 # find funding arb opportunities (>5bps spread)
114
- ```
40
+ ## Core Commands
115
41
 
116
- ### Per-exchange commands (ALL 3 exchanges use the SAME commands)
117
- Every command below works on ALL exchanges. Just change `-e`:
118
42
  ```bash
119
43
  # Account
120
- perp --json -e hl account info # Hyperliquid balance & margin
121
- perp --json -e pac account info # Pacifica balance & margin
122
- perp --json -e lighter account info # Lighter balance & margin
123
- perp --json -e <EX> account positions # open positions
44
+ perp --json -e <EX> account info # balance, equity, margin
45
+ perp --json -e <EX> account positions # open positions
46
+ perp --json portfolio # unified multi-exchange view
124
47
 
125
- # Market data
126
- perp --json -e <EX> market list # available markets
127
- perp --json -e <EX> market mid <SYM> # mid price
128
- perp --json -e <EX> market book <SYM> # orderbook depth
48
+ # Market
49
+ perp --json -e <EX> market list # available markets
50
+ perp --json -e <EX> market mid <SYM> # mid price
51
+ perp --json -e <EX> market book <SYM> # orderbook
129
52
 
130
- # Trading (same syntax on ALL exchanges)
131
- perp --json -e <EX> trade leverage <SYM> <N> --isolated # set leverage
132
- perp --json -e <EX> trade market <SYM> buy <SIZE> # market buy
133
- perp --json -e <EX> trade market <SYM> sell <SIZE> # market sell
134
- perp --json -e <EX> trade close <SYM> # close position
135
- perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L> # pre-flight
53
+ # Trading
54
+ perp --json -e <EX> trade leverage <SYM> <N> --isolated # set BEFORE trading
55
+ perp --json -e <EX> trade market <SYM> buy <SIZE>
56
+ perp --json -e <EX> trade market <SYM> sell <SIZE>
57
+ perp --json -e <EX> trade close <SYM>
58
+ perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L>
136
59
 
137
- # Deposit / Withdraw
138
- perp --json deposit hyperliquid <AMOUNT> # deposit to HL
139
- perp --json deposit pacifica <AMOUNT> # deposit to Pacifica
140
- perp --json deposit lighter info # show Lighter deposit routes
141
- perp --json deposit lighter cctp arb <AMOUNT> # deposit to Lighter via CCTP
142
- perp --json withdraw <EX> <AMOUNT> # withdraw from exchange
143
- ```
144
- **All 3 exchanges are fully operational.** Do NOT say any exchange "requires additional setup" or "is not available" — if `wallet show` shows it configured, it's ready to trade.
60
+ # Risk
61
+ perp --json risk status # risk level + violations
62
+ perp --json risk liquidation-distance # % from liq for all positions
63
+ perp --json risk check --notional <$> --leverage <L>
145
64
 
146
- ### Funding arb direction (CRITICAL — do NOT reverse)
147
- ```
148
- arb scan returns: longExch, shortExch, netSpread
149
- → ALWAYS follow longExch/shortExch exactly. NEVER reverse the direction.
150
- → NEVER enter if netSpread ≤ 0 (= loss after fees)
151
- → Positive funding = longs pay shorts → be SHORT to receive
152
- → Negative funding = shorts pay longs → be LONG to receive
65
+ # Arb
66
+ perp --json arb scan --min 5 # find funding arb opportunities
153
67
  ```
154
68
 
155
- ### Trade execution (MANDATORY checklist)
156
- ```
157
- BEFORE ANY TRADE:
158
- 0. perp --json portfolio → check TOTAL equity + per-exchange balances
159
- - Single position notional < 25% of TOTAL equity
160
- - Each exchange MUST have sufficient balance for its leg
161
- - Notional ≠ margin required. Check available balance on EACH exchange.
162
- - If balance is insufficient, bridge first or reduce size.
69
+ Exchange aliases: `hl`/`hyperliquid`, `pac`/`pacifica`, `lt`/`lighter`. Symbols auto-resolve (use bare: `BTC`, `SOL`, `ICP`).
163
70
 
164
- 1. perp --json risk status → check risk level (STOP if critical)
165
- 2. perp --json -e <EX> account info → verify EXCHANGE-SPECIFIC balance
166
- 3. perp --json -e <EX> market mid <SYM> → current price
167
- 4. perp --json -e <EX> trade leverage <SYM> <N> --isolated → set leverage + isolated margin FIRST
168
- 5. perp --json risk check --notional <$> --leverage <L> → risk pre-check
169
- 6. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L> → trade validation
170
- ⚠ trade check does NOT read exchange-set leverage. ALWAYS pass --leverage explicitly.
171
- 7. [Show order details + risk assessment to user, get explicit confirmation]
172
- 8. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE> → execute
173
- 9. perp --json -e <EX> account positions → verify result + check liquidation price
174
- ```
175
-
176
- ### Exchange-specific constraints
177
- ```
178
- Minimum order values (notional, enforced by exchange):
179
- - Hyperliquid: $10 minimum per order
180
- - Pacifica: varies by symbol (usually ~$1)
181
- - Lighter: varies by symbol
71
+ ## Trade Execution Checklist
182
72
 
183
- If your calculated size falls below the minimum, increase to meet it or skip the opportunity.
184
- trade check returns valid: true/false but is ADVISORY — it does NOT block execution.
185
- The exchange itself will reject orders below its minimum.
186
73
  ```
187
-
188
- ### Arb order sizing (CRITICAL — both legs MUST match)
74
+ 1. perp --json risk status → STOP if critical
75
+ 2. perp --json -e <EX> account info → verify balance
76
+ 3. perp --json -e <EX> trade leverage <SYM> <N> --isolated
77
+ 4. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L>
78
+ 5. [Show details to user, get confirmation]
79
+ 6. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE>
80
+ 7. perp --json -e <EX> account positions → verify + check liq price
189
81
  ```
190
- For funding arb, BOTH legs must have the EXACT SAME SIZE. Size mismatch = directional exposure.
191
-
192
- 1. Check orderbook depth on BOTH exchanges:
193
- perp --json -e <LONG_EX> market book <SYM> → asks (you're buying)
194
- perp --json -e <SHORT_EX> market book <SYM> → bids (you're selling)
195
82
 
196
- 2. Compute ORDER_SIZE:
197
- - fillable_long = sum of ask sizes at best 2-3 levels
198
- - fillable_short = sum of bid sizes at best 2-3 levels
199
- - ORDER_SIZE = min(fillable_long, fillable_short, desired_size)
200
- - Must be ≥ BOTH exchanges' minimum order value (e.g. HL requires ≥$10 notional)
83
+ ## Position Sizing
201
84
 
202
- 3. Execute BOTH legs with the SAME ORDER_SIZE:
203
- perp --json -e <LONG_EX> trade market <SYM> buy <ORDER_SIZE>
204
- → verify fill via account positions
205
- perp --json -e <SHORT_EX> trade market <SYM> sell <ORDER_SIZE>
206
- → verify fill via account positions
85
+ - Single position notional < **80%** of that exchange's available balance
86
+ - Use ISOLATED margin for arb
87
+ - Leverage 1-3x for arb, never exceed 5x
88
+ - Both arb legs MUST have exact same size
207
89
 
208
- 4. Confirm matched: both positions must show identical size.
209
- If mismatch (partial fill), adjust the larger to match the smaller.
210
- ```
211
- See `references/strategies.md` for detailed execution strategy (chunked orders, limit orders, failure handling).
90
+ ## Funding Arb Direction
212
91
 
213
- ### Post-entry monitoring (MANDATORY while positions are open)
214
92
  ```
215
- Every 15 minutes:
216
- perp --json risk status → overall risk level + violations
217
- perp --json risk liquidation-distance → % from liq price for ALL positions
218
- perp --json -e <EX> account positions → check each position P&L
219
-
220
- Every 1 hour (at funding settlement):
221
- perp --json arb scan --min 5 → is spread still profitable?
222
- perp --json portfolio → total equity across exchanges
223
- Compare both legs' unrealized P&L — they should roughly offset
224
-
225
- Exit triggers:
226
- - Spread below breakeven (including fees) → show exit plan, get user approval
227
- - risk status level = "critical" or canTrade = false → reduce immediately
228
- - One leg closed unexpectedly → close the other leg IMMEDIATELY
229
- - Target hold duration reached → re-evaluate or exit
230
- ```
231
-
232
- ### Knowing your capital (CHECK BEFORE ANY DECISION)
233
- ```
234
- perp --json wallet show → configured wallets + addresses
235
- perp --json wallet balance → on-chain USDC (in wallet, NOT on exchange)
236
- perp --json -e <EX> account info → exchange balance (available for trading)
237
- perp --json portfolio → unified view: equity, margin, P&L per exchange
93
+ arb scan returns: longExch, shortExch, netSpread
94
+ → ALWAYS follow longExch/shortExch exactly. NEVER reverse.
95
+ → NEVER enter if netSpread <= 0
238
96
  ```
239
- **On-chain balance ≠ exchange balance.** Always check both. Capital must be deposited to exchange before trading.
240
97
 
241
- For full command reference, see `references/commands.md`.
242
- For agent-specific operations (setup flows, deposit/withdraw, order types, idempotency), see `references/agent-operations.md`.
243
- For autonomous strategies (funding rate arb, risk management, opportunity cost), see `references/strategies.md`.
98
+ ## Monitoring (while positions open)
244
99
 
245
- ## Response Format
246
-
247
- All JSON responses follow this envelope:
248
- ```json
249
- { "ok": true, "data": { ... }, "meta": { "timestamp": "..." } }
250
- { "ok": false, "error": { "code": "ERROR_CODE", "message": "...", "retryable": true } }
251
- ```
100
+ Every 15 min: `risk status` + `risk liquidation-distance` + `account positions`
101
+ Every 1 hour: `arb scan --min 5` + `portfolio`
102
+ Exit if: spread < breakeven, risk critical, one leg closed unexpectedly.
252
103
 
253
104
  ## Error Handling
254
105
 
255
- | Code | Retryable | Action |
256
- |------|-----------|--------|
257
- | INSUFFICIENT_BALANCE | No | Report, suggest deposit |
258
- | MARGIN_INSUFFICIENT | No | Suggest lower leverage or smaller size |
259
- | SYMBOL_NOT_FOUND | No | Run `market list` for valid symbols |
260
- | SIGNATURE_FAILED | No | Run `wallet show` to check key configuration |
261
- | RATE_LIMITED | Yes | Wait 5s, retry once |
262
- | EXCHANGE_UNREACHABLE | Yes | Wait 5s, retry up to 3 times |
263
- | TIMEOUT | Yes | Retry, check network |
106
+ All responses: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
264
107
 
265
- ## Safety Guardrails
108
+ Retryable (wait 5s, retry once): `RATE_LIMITED`, `EXCHANGE_UNREACHABLE`, `TIMEOUT`
109
+ Not retryable: `INSUFFICIENT_BALANCE`, `MARGIN_INSUFFICIENT`, `SYMBOL_NOT_FOUND`
266
110
 
267
- - NEVER execute trades without user confirmation
268
- - Warn if single trade exceeds 50% of available balance
269
- - Warn if leverage exceeds 10x
270
- - Double-confirm bridge transfers over $1000
271
-
272
- ## Troubleshooting
273
-
274
- ### "No private key configured for <exchange>"
275
- The wallet is not set up. Fix:
276
- ```bash
277
- perp --json wallet set <exchange> <key> # if user has a key
278
- perp --json wallet generate evm # if user needs a new EVM wallet
279
- perp --json wallet generate solana # if user needs a new Solana wallet
280
- perp --json wallet show # verify it worked
281
- ```
282
-
283
- ### Command hangs or waits for input
284
- You used an interactive command. NEVER use `perp init` or any command without `--json`. Cancel and retry with `--json`.
285
-
286
- ### Generated wallet has zero balance
287
- New wallets start empty. Show the address to the user and ask them to fund it with USDC before trading.
288
-
289
- ## MCP Server (Advisor Mode)
290
-
291
- For read-only access without CLI execution:
292
- ```json
293
- {
294
- "mcpServers": {
295
- "perp-cli": {
296
- "command": "npx",
297
- "args": ["-y", "perp-cli", "mcp"],
298
- "env": {
299
- "HL_PRIVATE_KEY": "<evm-hex>",
300
- "PACIFICA_PRIVATE_KEY": "<solana-base58>"
301
- }
302
- }
303
- }
304
- }
305
- ```
111
+ ## References
306
112
 
307
- **MCP Tools:** get_markets, get_orderbook, get_funding_rates, get_prices, get_balance, get_positions, get_open_orders, portfolio, arb_scan, health_check, suggest_command, explain_command
113
+ - `references/commands.md` — full command reference
114
+ - `references/agent-operations.md` — setup flows, deposit/withdraw, idempotency
115
+ - `references/strategies.md` — risk framework, arb strategy, opportunity cost
package/skills/perp-cli/references/strategies.md CHANGED
@@ -311,10 +311,10 @@ perp --json risk limits \
311
311
  --max-leverage 5 \
312
312
  --max-margin 60 \
313
313
  --max-drawdown-pct 10 \
314
- --max-position-pct 25 \
314
+ --max-position-pct 80 \
315
315
  --max-drawdown 500 \
316
- --max-position 5000 \
317
- --max-exposure 20000 \
316
+ --max-position 50000 \
317
+ --max-exposure 100000 \
318
318
  --daily-loss 200 \
319
319
  --min-liq-distance 30
320
320
  ```
@@ -380,8 +380,8 @@ perp --json portfolio # totalEquity, marginUtilization, c
380
380
  ```
381
381
 
382
382
  Rules of thumb:
383
- - **Single position notional < 25% of total equity** across all exchanges
384
- - **Total margin used < 60% of total equity** — leave buffer for adverse moves
383
+ - **Single position notional < 80% of that exchange's available balance**
384
+ - **Total margin used < 80% of total equity** — leave buffer for adverse moves
385
385
  - **Capital in transit (bridging) counts as "at risk"** — it's not available for margin
386
386
 
387
387
  ### Per-Exchange Balance Constraints