perp-cli 0.12.14 → 0.12.17

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.
@@ -1,219 +1,336 @@
1
1
  ---
2
2
  name: perp-cli
3
- description: "Multi-DEX perpetual futures trading CLI for Pacifica (Solana), Hyperliquid (EVM), Lighter (Ethereum), and Aster (BNB Chain). Use when user asks to: trade perps, check funding rates, scan arbitrage (perp-perp or spot-perp), delta-neutral strategies, bridge USDC, manage positions/orders, deposit/withdraw, spot+perp hedge, HIP-3 DEX trading, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, Lighter, Aster, HyperEVM, funding arb, U-token (UBTC/UETH/USOL)."
4
- allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
3
+ description: "Multi-DEX perpetual futures trading via the perp-cli command-line tool. Use when user asks to: trade perps, check funding rates, scan/execute arbitrage (perp-perp or spot-perp), run delta-neutral strategies, bridge USDC across chains, manage positions/orders/leverage, deposit/withdraw, hedge spot+perp, trade HIP-3 DEXes, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, Lighter, Aster, HyperEVM, funding arb, or U-tokens (UBTC/UETH/USOL). Covers Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), and Aster (BNB Chain)."
5
4
  license: MIT
5
+ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
6
+ compatibility: "Requires Node.js 20 or newer and the perp-cli npm package (global install or npx). Network access required for exchange APIs and bridge providers. Mutating commands need wallet keys configured via 'perp wallet set EXCHANGE KEY' (Solana base58 / EVM hex / Aster API key). Skill is portable across Claude Code, Claude.ai, Cursor, Codex, and Gemini CLI — no platform-specific features."
6
7
  metadata:
7
8
  author: hypurrquant
8
- version: "0.12.14"
9
+ version: "0.12.17"
9
10
  ---
10
11
 
11
- # perp-cli Agent Guide
12
+ # perp-cli
12
13
 
13
- Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), Aster (BNB Chain).
14
+ Multi-DEX perpetual futures CLI + MCP server for Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), and Aster (BNB Chain).
14
15
 
15
- [![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)
16
+ ## Instructions
16
17
 
17
- ## MCP Server
18
+ ### When to use this skill
18
19
 
19
- 18 tools, 3 resources, 2 prompts. No API keys required for market data — explore prices, orderbooks, funding rates, and arb opportunities without setup.
20
+ Activate whenever the user wants to do anything against perp-cli, including: scanning funding-rate arbitrage, executing perp-perp or spot+perp legs, running long-running strategy bots, moving USDC between chains/exchanges, checking account/portfolio state, configuring wallets, or troubleshooting any of the above.
20
21
 
21
- ```json
22
- {
23
- "mcpServers": {
24
- "perp-cli": {
25
- "command": "npx",
26
- "args": ["-y", "-p", "perp-cli", "perp-mcp"]
27
- }
28
- }
29
- }
30
- ```
22
+ **Do NOT** answer trading questions from memory — always run the actual CLI command and parse its JSON output.
23
+
24
+ ### Reference files (load only when needed)
31
25
 
32
- ## Rules
26
+ This skill uses progressive disclosure. Read these on demand:
33
27
 
34
- 1. **Always use `--json`** on every command.
35
- 2. **Always use `--dry-run`** before any mutating trade (then execute without it after user confirms).
36
- 3. **Always use `--fields`** to reduce output when you only need specific data (saves tokens).
37
- 4. **NEVER use `perp setup`** (alias: `perp init`) — interactive, will hang.
38
- 5. **NEVER trade without user confirmation.**
39
- 6. **NEVER read ~/.perp/.env or key files.**
28
+ - `references/commands.md` — full command tree for every group (market, account, trade, arb, funds, wallet, risk, history, strategy, background, alerts, settings, backtest)
29
+ - `references/agent-operations.md` — non-interactive setup flows, idempotency rules, error codes, common mistakes
30
+ - `references/strategies.md` — funding-arb decision framework + risk-management playbook (read before designing arb strategy)
40
31
 
41
- ## Install
32
+ Also bundled under `scripts/`: `preflight.sh`, `arb-monitor.sh`, `funding-analysis.sh`, `spot-perp-scan.sh`, `validate-arb.sh`. Use these for repeatable multi-step diagnostics.
33
+
34
+ ### Critical rules
35
+
36
+ 1. **Always pass `--json`.** Without it, output is human-formatted and hard to parse.
37
+ 2. **Always run `--dry-run` first** for any mutating trade (open / close / bridge / withdraw). Show the result, get user confirmation, then execute without `--dry-run`.
38
+ 3. **Always use `--fields`** when you only need specific data — saves tokens.
39
+ 4. **NEVER run `perp setup`, `perp init`, or `perp wallet setup`.** All three are interactive and will hang the agent. Use `perp wallet set <exchange> <key>` instead.
40
+ 5. **NEVER trade without explicit user confirmation.** A dry-run is not consent.
41
+ 6. **NEVER read `~/.perp/.env` or other key files.** The CLI reads them — you should not.
42
+ 7. **NEVER manually add `-PERP` suffix** to symbols. Use bare names (`BTC`, `SOL`, `ICP`); the CLI resolves exchange-specific naming.
43
+
44
+ ### Step 1: Verify install + version
42
45
 
43
46
  ```bash
44
- perp --version 2>/dev/null # check if exists (must be >= 0.12.14)
47
+ perp --version 2>/dev/null # must be >= 0.12.17
45
48
  npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
46
49
  ```
47
50
 
48
- Use `perp` if global install works, otherwise `npx -y perp-cli@latest` as prefix.
51
+ If `perp` is not on PATH, prefix every command with `npx -y perp-cli@latest`.
49
52
 
50
- ## Global Flags
53
+ ### Step 2: Verify wallet + balance
51
54
 
52
- `--json` (required) | `-e hl/pac/lt/aster` (exchange) | `--dex <name>` (HIP-3) | `-w <wallet>` | `--dry-run` | `--fields <f1,f2>` | `--ndjson`
55
+ ```bash
56
+ perp --json wallet show # confirms configured exchanges
57
+ perp --json -e <ex> account balance # per-exchange USDC available
58
+ ```
53
59
 
54
- ## Wallet Setup
60
+ If any required exchange is missing, register it (user supplies the key):
55
61
 
56
62
  ```bash
57
- perp --json wallet set pac <SOLANA_KEY> # Pacifica
58
- perp --json wallet set hl <EVM_KEY> # Hyperliquid
59
- perp --json wallet set lt <EVM_KEY> # Lighter (API key auto-generated)
60
- perp --json wallet set aster <API_KEY> # Aster (BNB Chain)
61
- perp --json wallet show # verify
63
+ perp --json wallet set pac <SOLANA_BASE58_KEY> # Pacifica
64
+ perp --json wallet set hl <EVM_HEX_KEY> # Hyperliquid
65
+ perp --json wallet set lt <EVM_HEX_KEY> # Lighter (auto-generates API key, default index 4)
66
+ perp --json wallet set aster <ASTER_API_KEY> # Aster (BNB Chain)
62
67
  ```
63
68
 
64
- ## Core Workflow: Arb
69
+ The same EVM key works for both Hyperliquid and Lighter.
65
70
 
66
- ```
67
- 1. perp --json arb scan # scan opportunities (perp-perp + spot-perp + HIP-3)
68
- 2. perp --json account balance # check balances across all exchanges
69
- 3. perp --json --dry-run arb exec <SYM> <longEx> <shortEx> <$> # dry-run (auto-sizes)
70
- 4. [show result to user, get confirmation]
71
- 5. perp --json arb exec <SYM> <longEx> <shortEx> <$> # execute
72
- 6. perp --json arb status # monitor PnL + funding income
73
- 7. perp --json arb close <SYM> # close both legs
71
+ ### Step 3: Discover (read-only)
72
+
73
+ ```bash
74
+ perp --json arb scan # all modes (perp-perp + spot-perp), default --min 10 (% annual)
75
+ perp --json arb scan --mode perp-perp --top 10
76
+ perp --json arb scan --mode spot-perp --top 10
77
+ perp --json arb scan --rates # raw funding rates
78
+ perp --json arb scan --basis [<symbol>] # cross-exchange basis
79
+ perp --json arb scan --gaps # cross-exchange price gaps
80
+ perp --json arb scan --hip3 # HIP-3 cross-dex spreads
81
+ perp --json arb scan --history <symbol> # historical funding
82
+ perp --json arb scan --compare <symbol> # one symbol across all exchanges
83
+ perp --json arb scan --positions # funding impact on open positions
84
+ perp --json arb scan --live --interval 60 # continuous monitoring
74
85
  ```
75
86
 
76
- ### Scan Modes
87
+ Common knobs: `--min <pct>`, `--top <n>`, `--hold-days <n>`, `--bridge-cost <usd>`, `--size <usd>`.
77
88
 
78
- | Flag | Description |
79
- |------|-------------|
80
- | _(default)_ | All modes combined (perp-perp + spot-perp) |
81
- | `--rates` | Funding rates across exchanges |
82
- | `--basis [symbol]` | Cross-exchange basis/price diff |
83
- | `--gaps` | Price gaps |
84
- | `--hip3` | HIP-3 on-chain dex opportunities |
85
- | `--history [symbol]` | Historical funding data |
86
- | `--compare <symbol>` | Compare symbol across exchanges |
87
- | `--positions` | Existing position exit signals |
88
- | `--live` | Continuous monitoring |
89
+ ### Step 4: Validate before mutating
89
90
 
90
- ### Spot+Perp Arb
91
+ For arb:
92
+
93
+ ```bash
94
+ perp --json -e <longEx> account balance # check available USDC
95
+ perp --json -e <shortEx> account balance # check available USDC
96
+ perp --json --dry-run arb exec <SYM> <longEx> <shortEx> <USD>
97
+ ```
91
98
 
92
- Spot has 0 funding cost. Use `spot:<exch>` prefix for the long leg:
99
+ For a single trade:
93
100
 
94
101
  ```bash
95
- perp --json arb exec ETH spot:hl hl 100 # spot buy(HL) + perp short(HL)
96
- perp --json arb exec BTC spot:lt pac 50 # spot buy(LT) + perp short(PAC)
97
- perp --json arb close ETH # sells spot + buys back perp
102
+ perp --json -e <ex> trade check <SYM> <SIDE> <SIZE> --leverage <N>
103
+ perp --json --dry-run -e <ex> trade buy <SYM> <SIZE> --smart
98
104
  ```
99
105
 
100
- Spot exchanges: HL, LT. Pacifica and Aster are perp-only.
106
+ > `trade check` does NOT read exchange-set leverage. Always pass `--leverage` explicitly.
107
+
108
+ Show the dry-run output to the user. Wait for confirmation.
109
+
110
+ ### Step 5: Execute
101
111
 
102
- ## Strategy Engine (19 bot algorithms + nested scripted plans)
112
+ After explicit user confirmation:
103
113
 
104
114
  ```bash
105
- perp strategy list-strategies # list all 19 strategies
106
- perp strategy run <strategy> [symbol] # run any registered strategy
107
- perp strategy run funding-auto # multi-exchange funding arb
108
- perp strategy apex [symbol] # APEX orchestrator (Radar+Pulse+Guard)
109
- perp strategy reflect # performance analysis (win rate, fees, PnL)
110
- perp strategy preset-list # list strategy presets
111
- perp strategy preset <name> [symbol] # run from preset
112
- perp strategy start <config.yaml> # start from YAML/JSON config
113
- perp strategy quick-grid <symbol> # quick grid bot
114
- perp strategy quick-dca <symbol> <side> <amount> <interval>
115
- perp strategy quick-arb # quick funding arb
115
+ # Perp-perp arb (auto-matches both legs)
116
+ perp --json arb exec <SYM> <longEx> <shortEx> <USD> --smart --reconcile
116
117
 
117
- # Scripted plans (one-shot multi-step execution)
118
- perp strategy plan example # show plan format
119
- perp --json strategy plan validate <file> # validate before run
120
- perp --json strategy plan execute <file> --dry-run # dry-run plan
118
+ # Spot+perp arb (spot has 0 funding cost; spot exchanges: hl, lt)
119
+ perp --json arb exec <SYM> spot:hl hl <USD>
120
+ perp --json arb exec <SYM> spot:lt pac <USD>
121
121
 
122
- # Background process supervisor (tmux)
123
- perp background list # list running jobs
124
- perp background stop <id> # stop a job
125
- perp background logs <id> -f # follow logs
122
+ # Single trade
123
+ perp --json -e <ex> trade buy <SYM> <SIZE> --smart
124
+ perp --json -e <ex> trade sell <SYM> <SIZE> --smart
125
+ perp --json -e <ex> trade split <SYM> buy <USD> --max-slippage 0.5
126
126
  ```
127
127
 
128
- **Strategies:** grid, dca, funding-arb, funding-arb-v2, funding-auto, basis-arb, simple-mm, engine-mm, avellaneda-mm, regime-mm, grid-mm, liquidation-mm, momentum-breakout, mean-reversion, aggressive-taker, hedge-agent, rfq-agent, claude-agent, apex
128
+ HL spot uses U-tokens (`BTC→UBTC`, `ETH→UETH`, `SOL→USOL`) — auto-resolved.
129
129
 
130
- **Flags:** `--dry-run` (simulate without executing), `--headless` (no TUI, log only)
130
+ ### Step 6: Monitor
131
131
 
132
- ## Core Workflow: Single Trade
132
+ ```bash
133
+ perp --json arb status # open arb positions, PnL, funding earned
134
+ perp --json portfolio # cross-exchange equity + risk
135
+ perp --json risk status # canTrade, level, violations
136
+ perp --json risk liquidation-distance # % from liq for ALL positions
137
+ ```
138
+
139
+ If `risk status.canTrade === false`, do NOT open new positions. If liquidation distance falls below the user's `--min-liq-distance`, recommend reducing position size.
140
+
141
+ For continuous monitoring, run `bash scripts/arb-monitor.sh --json`.
142
+
143
+ ### Step 7: Close
133
144
 
134
145
  ```bash
135
- perp --json -e <EX> trade buy <SYM> <SIZE> # market buy (SIZE = token units)
136
- perp --json -e <EX> trade sell <SYM> <SIZE> # market sell
137
- perp --json -e <EX> trade buy <SYM> <SIZE> --smart # IOC limit at best ask
138
- perp --json -e <EX> trade split <SYM> buy <USD> # orderbook-aware split
139
- perp --json -e <EX> trade limit <SYM> buy <PRICE> <SIZE>
140
- perp --json -e <EX> trade tpsl <SYM> buy --tp <P> --sl <P>
141
- perp --json -e <EX> trade close <SYM>
142
- perp --json -e <EX> trade flatten # close ALL + cancel ALL
143
- perp --json -e <EX> trade cancel <SYM> # cancel all orders for symbol
146
+ perp --json arb close <SYM> # perp-perp arb
147
+ perp --json arb close <SYM> --pair <longEx>:<shortEx> # disambiguate
148
+ perp --json arb close <SYM> --spot-exch hl --perp-exch hl # spot+perp
149
+ perp --json arb close <SYM> --smart # IOC limits
150
+
151
+ # Single trade
152
+ perp --json -e <ex> trade close <SYM> # close one symbol
153
+ perp --json -e <ex> trade close-all # close all positions on this exchange
154
+ perp --json -e <ex> trade flatten # close ALL + cancel ALL orders
144
155
  ```
145
156
 
146
- ## Agent Tools
157
+ ### Funds workflow (deposit / withdraw / transfer / bridge / rebalance)
158
+
159
+ All money movement lives under `perp funds`:
147
160
 
148
161
  ```bash
149
- perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> # pre-validate trade
150
- perp --json portfolio # balances + positions + risk level
151
- perp --json --fields totalEquity,positions portfolio # filtered output
162
+ # Exchange in/out
163
+ perp --json funds deposit hyperliquid 100
164
+ perp --json funds deposit pacifica 100
165
+ perp --json funds deposit lighter ethereum 100 # L1 direct
166
+ perp --json funds deposit lighter cctp arbitrum 100 # via CCTP
167
+ perp --json funds withdraw hyperliquid 100
168
+ perp --json funds transfer 100 <ADDRESS> # HL internal (instant)
169
+
170
+ # Cross-chain bridge (auto-cheapest cctp/relay/debridge)
171
+ perp --json funds bridge quote --from solana --to arbitrum --amount 100
172
+ perp --json funds bridge send --from solana --to arbitrum --amount 100
173
+ perp --json funds bridge status <orderId> # poll until success
174
+
175
+ # Inter-exchange rebalance (orchestrated withdraw → bridge → deposit)
176
+ perp --json funds rebalance check
177
+ perp --json funds rebalance plan
178
+ perp --json funds rebalance execute --auto-bridge
152
179
  ```
153
180
 
154
- ## Position Sizing & Safety
181
+ Always run `funds bridge quote` before `funds bridge send` so the user sees fees + ETA.
155
182
 
156
- - Single position < **80%** of that exchange's available balance
157
- - Leverage 1-3x for arb, max 5x
158
- - `arb exec` auto-matches both legs to the same size
159
- - ALWAYS follow `longExch`/`shortExch` from scan — NEVER reverse direction
160
- - NEVER enter if `netSpread <= 0` or `netSpread < estimated round-trip slippage`
161
- - Check `portfolio.risk.canTrade` — if `false`, do NOT trade
183
+ ### Strategy engine (20 algorithms + scripted plans)
162
184
 
163
- ## HIP-3 Support
185
+ ```bash
186
+ perp strategy list-strategies # 20 registered
187
+ perp strategy run <strategy> [symbol] # run any strategy
188
+ perp strategy apex [symbol] # APEX orchestrator
189
+ perp strategy reflect # performance analysis
190
+ perp --json strategy plan validate <FILE> # validate scripted plan
191
+ perp --json strategy plan execute <FILE> --dry-run # dry-run scripted plan
192
+ ```
193
+
194
+ **Strategies:** `grid`, `dca`, `simple-mm`, `engine-mm`, `avellaneda-mm`, `regime-mm`, `grid-mm`, `liquidation-mm`, `momentum-breakout`, `mean-reversion`, `aggressive-taker`, `funding-arb`, `funding-arb-v2`, `funding-auto`, `basis-arb`, `spot-perp-arb`, `hedge-agent`, `rfq-agent`, `claude-agent`, `apex`.
195
+
196
+ Background daemon (tmux):
164
197
 
165
198
  ```bash
166
- perp --json -e hl --dex km market list # dex-specific markets
167
- perp --json market list --hip3 # all HIP-3 markets
168
- perp --json account positions --hip3 # HIP-3 positions
169
- perp --json arb scan --hip3 # HIP-3 arb opportunities
199
+ perp --json arb auto --min-spread 30 --size 100 --background
200
+ perp --json background list
201
+ perp --json background logs <id> -f
202
+ perp --json background stop <id>
170
203
  ```
171
204
 
172
- ## Error Handling
205
+ ### Position sizing & safety
173
206
 
174
- Response format: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
207
+ - Single position notional < **80%** of that exchange's available balance.
208
+ - Leverage 1–3x for arb; never above 5x for arb positions.
209
+ - `arb exec` auto-matches both legs to the same size; pass `--reconcile` to trim mismatches.
210
+ - ALWAYS follow `longExch`/`shortExch` from `arb scan` — NEVER reverse direction.
211
+ - NEVER enter if `netSpread <= 0` or `netSpread < estimated round-trip slippage`.
212
+ - Capital that's mid-bridge is "at risk" and unhedged — factor it in.
175
213
 
176
- | Error | Action |
177
- |-------|--------|
178
- | `RATE_LIMITED` | wait 5s, retry (max 3). Lighter: space 3s+ apart |
179
- | `EXCHANGE_UNREACHABLE` | wait 10s, retry. 3x fail → skip exchange |
180
- | `INSUFFICIENT_BALANCE` | reduce size or bridge funds |
181
- | `SYMBOL_NOT_FOUND` | `market list` to verify symbol |
182
- | `SIZE_TOO_SMALL` | `market info <SYM>` for min size |
183
- | `DUPLICATE_ORDER` | already submitted — check positions |
184
- | Lighter `invalid signature` | `perp wallet agent approve lighter` to regenerate |
214
+ For deeper risk-management framework, read `references/strategies.md`.
185
215
 
186
216
  ## Examples
187
217
 
188
- **"Find arb opportunities"**
218
+ ### Example 1: "Find funding-rate arb opportunities"
219
+
189
220
  ```bash
221
+ # 1. Discover
190
222
  perp --json arb scan --min 10 --top 10
191
- perp --json account balance
192
- # → show results, recommend best, ask confirmation
223
+ # 2. Show top 3 to user; ask which to evaluate
224
+ # 3. Check balances on the two exchanges
225
+ perp --json -e <longEx> account balance
226
+ perp --json -e <shortEx> account balance
227
+ # 4. Recommend size + dry-run
228
+ perp --json --dry-run arb exec BTC <longEx> <shortEx> 100
229
+ # 5. After user confirmation:
230
+ perp --json arb exec BTC <longEx> <shortEx> 100 --smart
231
+ perp --json arb status
193
232
  ```
194
233
 
195
- **"ETH spot-perp arb, $100"**
234
+ ### Example 2: "ETH spot+perp arb, $100"
235
+
196
236
  ```bash
197
237
  perp --json --dry-run arb exec ETH spot:hl hl 100
198
238
  # → show dry-run, ask confirmation
199
239
  perp --json arb exec ETH spot:hl hl 100
200
240
  perp --json arb status
241
+ # Later, to close both legs:
242
+ perp --json arb close ETH --spot-exch hl --perp-exch hl
201
243
  ```
202
244
 
203
- **"Long SOL 0.5 on HL"**
245
+ ### Example 3: "Long SOL 0.5 on Hyperliquid with 2x leverage"
246
+
204
247
  ```bash
205
- perp --json -e hl trade check SOL buy 0.5
248
+ perp --json -e hl wallet manage margin SOL isolated # use isolated margin for new trade
249
+ perp --json -e hl trade leverage SOL 2 --isolated
250
+ perp --json -e hl trade check SOL buy 0.5 --leverage 2
206
251
  perp --json --dry-run -e hl trade buy SOL 0.5 --smart
207
- # → ask confirmation
252
+ # → show dry-run, ask confirmation
208
253
  perp --json -e hl trade buy SOL 0.5 --smart
254
+ perp --json -e hl account positions
255
+ ```
256
+
257
+ ### Example 4: "Move 500 USDC from Pacifica to Hyperliquid"
258
+
259
+ ```bash
260
+ perp --json funds withdraw pacifica 500
261
+ perp --json funds bridge quote --from solana --to arbitrum --amount 500
262
+ # → show fee, ETA, ask confirmation
263
+ perp --json funds bridge send --from solana --to arbitrum --amount 500
264
+ perp --json funds bridge status <orderId> # poll until completed
265
+ perp --json funds deposit hyperliquid 500
209
266
  ```
210
267
 
211
- ## Referrals (Optional)
268
+ Or use the orchestrated path:
269
+
270
+ ```bash
271
+ perp --json funds rebalance plan
272
+ perp --json funds rebalance execute --auto-bridge
273
+ ```
274
+
275
+ ### Example 5: "Run a delta-neutral funding bot in background"
276
+
277
+ ```bash
278
+ perp --json arb auto --min-spread 30 --close-spread 5 --size 100 --max-positions 5 --background
279
+ perp --json background list
280
+ perp --json background logs <id> -f
281
+ # To stop:
282
+ perp --json background stop <id>
283
+ ```
284
+
285
+ ## Troubleshooting
286
+
287
+ Every response is `{ "ok": true, "data": ... }` or `{ "ok": false, "error": { "code": "...", "retryable": true|false } }`. Always check `ok` first.
288
+
289
+ | Error code | Meaning | Action |
290
+ |---|---|---|
291
+ | `RATE_LIMITED` | Exchange throttled the request | Wait 5s, retry up to 3 times. For Lighter, space calls 3s+ apart. |
292
+ | `EXCHANGE_UNREACHABLE` | API down or network issue | Wait 10s, retry. After 3 failures, skip that exchange and continue. |
293
+ | `INSUFFICIENT_BALANCE` | Not enough USDC on that exchange | Reduce size or `funds bridge`/`funds rebalance` first. |
294
+ | `SYMBOL_NOT_FOUND` | Symbol not listed on this exchange | Run `market list` to verify. Don't add `-PERP` suffix manually. |
295
+ | `SIZE_TOO_SMALL` | Below exchange minimum (HL is $10 notional) | Compute `size × price` before submitting; raise size. |
296
+ | `DUPLICATE_ORDER` | Same `--client-id` already submitted | Already executed — check `account positions` instead of retrying. |
297
+ | `INVALID_SIGNATURE` (Lighter) | API key drift / not approved | `perp wallet agent approve lighter --master <wallet>` to regenerate. |
298
+
299
+ ### Common mistakes
300
+
301
+ - **Forgetting `--json`** → output becomes unparseable human text. The very first thing to check when parsing fails.
302
+ - **Using legacy command names** — `arb rates`/`arb prices`/`arb dex`/`arb spot-exec`/`arb spot-close` are removed. Use `arb scan --rates|--gaps|--hip3` and `arb exec spot:<exch>` / `arb close <SYM> --spot-exch <ex>`.
303
+ - **Calling `trade check` without `--leverage`** → cost estimate doesn't match what the exchange applies.
304
+ - **Retrying a non-idempotent trade** without checking `account positions` → opens a duplicate position.
305
+ - **Bridging without quoting first** → user sees no fee/ETA and can't approve cleanly.
306
+ - **Treating `bridge send` as instant** → always `funds bridge status <orderId>` before depositing on the destination.
307
+ - **Manually adding `-PERP` suffix** → CLI auto-resolves; let it.
308
+
309
+ For a full troubleshooting + non-interactive flow guide, read `references/agent-operations.md`.
310
+
311
+ ## Referrals (optional, ask once per setup)
212
312
 
213
313
  ```bash
214
- perp --json settings referrals on # enable (opt-in, no extra fees)
215
- perp --json settings referrals off # disable anytime
314
+ perp --json settings referrals on # opt-in (no extra fees — exchange rebates only)
315
+ perp --json settings referrals off
216
316
  ```
217
317
 
218
- When setting up wallets for the first time, ask:
318
+ When the user first sets up a wallet, ask:
219
319
  > "perp-cli development is supported by optional referrals. Enable? No extra fees — only exchange rebates are used."
320
+
321
+ ## MCP Server
322
+
323
+ The package also ships a 18-tool MCP server (no API keys required for read-only market data):
324
+
325
+ ```json
326
+ {
327
+ "mcpServers": {
328
+ "perp-cli": {
329
+ "command": "npx",
330
+ "args": ["-y", "-p", "perp-cli", "perp-mcp"]
331
+ }
332
+ }
333
+ }
334
+ ```
335
+
336
+ [![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)