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.
- package/README.md +31 -4
- package/dist/commands/account.js +14 -2
- package/dist/index.js +25 -8
- package/dist/landing.d.ts +9 -0
- package/dist/landing.js +20 -0
- package/package.json +1 -1
- package/skills/perp-cli/SKILL.md +250 -133
- package/skills/perp-cli/references/agent-operations.md +95 -60
- package/skills/perp-cli/references/commands.md +267 -119
- package/skills/perp-cli/references/strategies.md +10 -7
- package/skills/perp-cli/scripts/arb-monitor.sh +15 -15
- package/skills/perp-cli/scripts/funding-analysis.sh +11 -6
- package/skills/perp-cli/scripts/validate-arb.sh +2 -1
package/skills/perp-cli/SKILL.md
CHANGED
|
@@ -1,219 +1,336 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: perp-cli
|
|
3
|
-
description: "Multi-DEX perpetual futures trading
|
|
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.
|
|
9
|
+
version: "0.12.17"
|
|
9
10
|
---
|
|
10
11
|
|
|
11
|
-
# perp-cli
|
|
12
|
+
# perp-cli
|
|
12
13
|
|
|
13
|
-
Multi-DEX perpetual futures CLI + MCP server
|
|
14
|
+
Multi-DEX perpetual futures CLI + MCP server for Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), and Aster (BNB Chain).
|
|
14
15
|
|
|
15
|
-
|
|
16
|
+
## Instructions
|
|
16
17
|
|
|
17
|
-
|
|
18
|
+
### When to use this skill
|
|
18
19
|
|
|
19
|
-
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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
|
-
|
|
26
|
+
This skill uses progressive disclosure. Read these on demand:
|
|
33
27
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
|
|
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 #
|
|
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
|
-
|
|
51
|
+
If `perp` is not on PATH, prefix every command with `npx -y perp-cli@latest`.
|
|
49
52
|
|
|
50
|
-
|
|
53
|
+
### Step 2: Verify wallet + balance
|
|
51
54
|
|
|
52
|
-
|
|
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
|
-
|
|
60
|
+
If any required exchange is missing, register it (user supplies the key):
|
|
55
61
|
|
|
56
62
|
```bash
|
|
57
|
-
perp --json wallet set pac
|
|
58
|
-
perp --json wallet set hl
|
|
59
|
-
perp --json wallet set lt
|
|
60
|
-
perp --json wallet set aster <
|
|
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
|
-
|
|
69
|
+
The same EVM key works for both Hyperliquid and Lighter.
|
|
65
70
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
87
|
+
Common knobs: `--min <pct>`, `--top <n>`, `--hold-days <n>`, `--bridge-cost <usd>`, `--size <usd>`.
|
|
77
88
|
|
|
78
|
-
|
|
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
|
-
|
|
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
|
-
|
|
99
|
+
For a single trade:
|
|
93
100
|
|
|
94
101
|
```bash
|
|
95
|
-
perp --json
|
|
96
|
-
perp --json
|
|
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
|
-
|
|
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
|
-
|
|
112
|
+
After explicit user confirmation:
|
|
103
113
|
|
|
104
114
|
```bash
|
|
105
|
-
perp
|
|
106
|
-
perp
|
|
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
|
-
#
|
|
118
|
-
perp
|
|
119
|
-
perp --json
|
|
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
|
-
#
|
|
123
|
-
perp
|
|
124
|
-
perp
|
|
125
|
-
perp
|
|
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
|
-
|
|
128
|
+
HL spot uses U-tokens (`BTC→UBTC`, `ETH→UETH`, `SOL→USOL`) — auto-resolved.
|
|
129
129
|
|
|
130
|
-
|
|
130
|
+
### Step 6: Monitor
|
|
131
131
|
|
|
132
|
-
|
|
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
|
|
136
|
-
perp --json
|
|
137
|
-
perp --json
|
|
138
|
-
perp --json
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
perp --json -e <
|
|
142
|
-
perp --json -e <
|
|
143
|
-
perp --json -e <
|
|
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
|
-
|
|
157
|
+
### Funds workflow (deposit / withdraw / transfer / bridge / rebalance)
|
|
158
|
+
|
|
159
|
+
All money movement lives under `perp funds`:
|
|
147
160
|
|
|
148
161
|
```bash
|
|
149
|
-
|
|
150
|
-
perp --json
|
|
151
|
-
perp --json
|
|
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
|
-
|
|
181
|
+
Always run `funds bridge quote` before `funds bridge send` so the user sees fees + ETA.
|
|
155
182
|
|
|
156
|
-
|
|
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
|
-
|
|
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
|
|
167
|
-
perp --json
|
|
168
|
-
perp --json
|
|
169
|
-
perp --json
|
|
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
|
-
|
|
205
|
+
### Position sizing & safety
|
|
173
206
|
|
|
174
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
192
|
-
#
|
|
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
|
-
|
|
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
|
-
|
|
245
|
+
### Example 3: "Long SOL 0.5 on Hyperliquid with 2x leverage"
|
|
246
|
+
|
|
204
247
|
```bash
|
|
205
|
-
perp --json -e hl
|
|
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
|
-
|
|
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 #
|
|
215
|
-
perp --json settings referrals off
|
|
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
|
|
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
|
+
[](https://glama.ai/mcp/servers/hypurrquant/perp-cli)
|