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.
Files changed (13) hide show
  1. package/README.md +31 -4
  2. package/dist/commands/account.js +14 -2
  3. package/dist/index.js +25 -8
  4. package/dist/landing.d.ts +9 -0
  5. package/dist/landing.js +20 -0
  6. package/package.json +1 -1
  7. package/skills/perp-cli/SKILL.md +250 -133
  8. package/skills/perp-cli/references/agent-operations.md +95 -60
  9. package/skills/perp-cli/references/commands.md +267 -119
  10. package/skills/perp-cli/references/strategies.md +10 -7
  11. package/skills/perp-cli/scripts/arb-monitor.sh +15 -15
  12. package/skills/perp-cli/scripts/funding-analysis.sh +11 -6
  13. package/skills/perp-cli/scripts/validate-arb.sh +2 -1
package/skills/perp-cli/references/commands.md CHANGED
@@ -2,74 +2,94 @@
2
2
 
3
3
  All commands support `--json` for structured output. Always use `--json` when calling from an agent.
4
4
 
5
+ ## Global Flags
6
+
7
+ `--json` (required for agents) | `-e <pac|hl|lt|aster>` (exchange) | `--dex <name>` (HIP-3) | `-w, --wallet <name>` | `--dry-run` | `--fields <f1,f2>` | `--ndjson`
8
+
5
9
  ## Market Data (read-only, safe)
6
10
  ```bash
7
- perp --json market list # all markets with prices, funding, volume
8
- perp --json market prices # cross-exchange price comparison
9
- perp --json market mid <SYMBOL> # mid price (fast)
10
- perp --json market info <SYMBOL> # mark/index price, funding, volume, OI, max leverage
11
- perp --json market book <SYMBOL> # orderbook (bids/asks)
12
- perp --json market trades <SYMBOL> # recent trades
13
- perp --json market funding <SYMBOL> # funding rate history
14
- perp --json market kline <SYM> <INTERVAL> # OHLCV candles (1m,5m,15m,1h,4h,1d)
15
- perp --json market hip3 # list HIP-3 deployed perp dexes (Hyperliquid only)
11
+ perp --json -e <EX> market list # all markets with prices, funding, volume
12
+ perp --json market prices # cross-exchange price comparison
13
+ perp --json -e <EX> market mid <SYMBOL> # mid price (fast)
14
+ perp --json -e <EX> market info <SYMBOL> # mark/index price, funding, volume, OI, max leverage
15
+ perp --json -e <EX> market book <SYMBOL> # orderbook (bids/asks)
16
+ perp --json -e <EX> market trades <SYMBOL> # recent trades
17
+ perp --json -e <EX> market funding <SYMBOL> # funding rate history
18
+ perp --json -e <EX> market kline <SYM> <INT> # OHLCV candles (1m,5m,15m,1h,4h,1d)
19
+ perp --json market hip3 # list HIP-3 deployed perp dexes (Hyperliquid)
16
20
  ```
17
21
 
18
22
  ## Account (read-only, safe)
19
23
  ```bash
20
- perp --json account balance # perp balance + spot holdings + 24h funding (alias: account balance)
21
- perp --json account positions # open positions
22
- perp --json account orders # open/pending orders
23
- perp --json account history # order history
24
- perp --json account trades # trade fill history
25
- perp --json account funding-history # funding payments
26
- perp --json account pnl # profit & loss
27
- perp --json account margin <SYMBOL> # position margin info
28
- perp --json portfolio # cross-exchange unified view
24
+ perp --json -e <EX> account balance # perp balance + spot holdings + 24h funding
25
+ perp --json -e <EX> account positions # open positions
26
+ perp --json -e <EX> account orders # open/pending orders
27
+ perp --json -e <EX> account history # order history
28
+ perp --json -e <EX> account trades # trade fill history
29
+ perp --json -e <EX> account funding-history # funding payments
30
+ perp --json -e <EX> account settings # per-market leverage & margin mode
31
+ perp --json -e <EX> account margin <SYMBOL> # position margin info
32
+ perp --json -e <EX> account pnl # realized + unrealized + funding
33
+ perp --json -e <EX> account twap-orders # active TWAP orders
34
+ perp --json portfolio # cross-exchange unified view
35
+ perp --json portfolio --arb # full dashboard with arb top 5
29
36
  ```
30
37
 
31
38
  ## Trading (requires user confirmation)
32
39
  ```bash
33
40
  # Market orders
34
- perp --json trade market <SYMBOL> <buy|sell> <SIZE>
35
- perp --json trade buy <SYMBOL> <SIZE> # shorthand market buy
36
- perp --json trade sell <SYMBOL> <SIZE> # shorthand market sell
41
+ perp --json -e <EX> trade market <SYMBOL> <buy|sell> <SIZE>
42
+ perp --json -e <EX> trade buy <SYMBOL> <SIZE> # shorthand market buy
43
+ perp --json -e <EX> trade sell <SYMBOL> <SIZE> # shorthand market sell
44
+ perp --json -e <EX> trade buy <SYM> <SIZE> --smart # IOC limit at best ask (less slippage)
37
45
 
38
- # Limit orders
39
- perp --json trade limit <SYMBOL> <buy|sell> <PRICE> <SIZE>
46
+ # Split execution (orderbook-aware, for large orders)
47
+ perp --json -e <EX> trade split <SYMBOL> <buy|sell> <USD>
48
+ perp --json -e <EX> trade split <SYM> buy 5000 --max-slippage 0.5 --max-slices 5 --delay 2000 --min-slice 200
49
+ perp --json -e <EX> trade market <SYM> buy <SIZE> --split # split via flag
40
50
 
41
- # Stop orders
42
- perp --json trade stop <SYMBOL> <SIDE> <STOP_PRICE> <SIZE>
43
- perp --json trade tpsl <SYMBOL> <SIDE> --tp <PRICE> --sl <PRICE>
51
+ # Limit / stop / TPSL
52
+ perp --json -e <EX> trade limit <SYMBOL> <buy|sell> <PRICE> <SIZE>
53
+ perp --json -e <EX> trade stop <SYMBOL> <SIDE> <SIZE> <STOP_PRICE>
54
+ perp --json -e <EX> trade tpsl <SYMBOL> <SIDE> --tp <P> --sl <P>
44
55
 
45
56
  # Order management
46
- perp --json trade edit <SYMBOL> <ORDER_ID> <PRICE> <SIZE>
47
- perp --json trade cancel <SYMBOL> <ORDER_ID>
48
- perp --json trade cancel-all
49
- perp --json trade check <SYMBOL> <SIDE> <SIZE> # pre-flight validation (no execution)
50
- perp --json trade check <SYM> <SIDE> <SIZE> --leverage 3 # check with specific leverage
57
+ perp --json -e <EX> trade edit <SYMBOL> <ORDER_ID> <PRICE> <SIZE>
58
+ perp --json -e <EX> trade cancel <SYMBOL_OR_ORDER_ID> [orderId]
59
+ perp --json -e <EX> trade cancel-all
60
+ perp --json -e <EX> trade cancel-stop <SYMBOL> <STOP_ORDER_ID>
61
+ perp --json -e <EX> trade cancel-twap <SYMBOL> <TWAP_ORDER_ID>
62
+ perp --json -e <EX> trade status <ORDER_ID> # check order state
63
+ perp --json -e <EX> trade fills [SYMBOL] # recent fills
64
+
65
+ # Pre-flight validation
66
+ perp --json -e <EX> trade check <SYMBOL> <SIDE> <SIZE>
67
+ perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage 3
51
68
  # NOTE: trade check does NOT read exchange-set leverage. Always pass --leverage explicitly.
52
69
 
53
70
  # Position management
54
- perp --json trade close <SYMBOL> # close single position
55
- perp --json trade close-all # close all positions
56
- perp --json trade flatten # cancel all orders + close all positions
57
- perp --json trade reduce <SYMBOL> <PCT> # reduce position by percentage
58
- perp --json trade leverage <SYMBOL> <N> # set leverage
71
+ perp --json -e <EX> trade close <SYMBOL> # close single position
72
+ perp --json -e <EX> trade close-all # close all positions
73
+ perp --json -e <EX> trade flatten # cancel all orders + close all positions
74
+ perp --json -e <EX> trade reduce <SYMBOL> <PCT> # reduce by percentage
75
+ perp --json -e <EX> trade leverage <SYMBOL> <N> [--isolated]
59
76
 
60
77
  # Advanced orders
61
- perp --json trade scale-tp <SYMBOL> --levels '<PRICE1>:<PCT>,<PRICE2>:<PCT>'
62
- perp --json trade scale-in <SYMBOL> <SIDE> --levels '<PRICE1>:<SIZE>,<PRICE2>:<SIZE>'
63
- perp --json trade pnl-track # real-time PnL tracker
78
+ perp --json -e <EX> trade scale-tp <SYMBOL> --levels '<P1>:<PCT>,<P2>:<PCT>'
79
+ perp --json -e <EX> trade scale-in <SYMBOL> <SIDE> --levels '<P1>:<SIZE>,<P2>:<SIZE>'
80
+ perp --json -e <EX> trade pnl-track # real-time PnL tracker
81
+ perp --json trade twap <SYMBOL> <SIDE> <SIZE> <DURATION> # native TWAP order
82
+
83
+ # Spot helpers (Hyperliquid / Lighter)
84
+ perp --json -e <EX> trade spot-buy <SYMBOL> <SIZE>
85
+ perp --json -e <EX> trade spot-sell <SYMBOL> <SIZE>
86
+ perp --json -e <EX> trade spot-balance
64
87
 
65
- # Split execution (orderbook-aware)
66
- perp --json trade split <SYMBOL> <buy|sell> <USD> # split large order into depth-based slices
67
- perp --json trade split <SYM> buy 5000 --max-slippage 0.5 --max-slices 5 --delay 2000 --min-slice 200
68
- perp --json trade market <SYM> buy <SIZE> --split # split via market command flag
69
- perp --json trade market <SYM> buy <SIZE> --split --max-slippage 0.5
88
+ # Multi-leg atomic execution
89
+ perp --json trade multi <legs...>
70
90
  ```
71
91
 
72
- ## Funds (Deposit, Withdraw, Transfer, Bridge, Rebalance)
92
+ ## Funds (deposit, withdraw, transfer, bridge, rebalance)
73
93
 
74
94
  All fund movement lives under `perp funds`.
75
95
 
@@ -89,11 +109,11 @@ perp --json funds info # combined routes &
89
109
 
90
110
  ### Cross-chain bridge (multi-provider router: cctp / relay / debridge — auto-cheapest)
91
111
  ```bash
92
- perp --json funds bridge chains # supported chains
112
+ perp --json funds bridge chains # supported chains
93
113
  perp --json funds bridge quote --from <CHAIN> --to <CHAIN> --amount <AMT>
94
- perp --json funds bridge send --from <CHAIN> --to <CHAIN> --amount <AMT> # auto-cheapest
114
+ perp --json funds bridge send --from <CHAIN> --to <CHAIN> --amount <AMT>
95
115
  perp --json funds bridge send --from <CHAIN> --to <CHAIN> --amount <AMT> --provider cctp
96
- perp --json funds bridge exchange --from <EX> --to <EX> --amount <AMT> # between exchanges
116
+ perp --json funds bridge exchange --from <EX> --to <EX> --amount <AMT> # between exchanges
97
117
  perp --json funds bridge status <ORDER_ID>
98
118
  ```
99
119
 
@@ -106,100 +126,228 @@ perp --json funds rebalance execute --withdraw-only # only withdraw, ma
106
126
  ```
107
127
 
108
128
  ## Arbitrage
129
+
130
+ All scan modes are routed through `arb scan`. Legacy aliases (`arb rates`, `arb prices`, `arb dex`, `arb spot-exec`, `arb spot-close`) are removed.
131
+
109
132
  ```bash
110
- # Perp-Perp arb
111
- perp --json arb scan --min <BPS> # find opportunities (>N bps spread) — PRIMARY command
112
- perp --json arb exec <SYM> <longEx> <shortEx> <$> # execute perp-perp arb
113
- perp --json arb close <SYM> # close perp-perp arb
114
- perp --json arb status # monitor open arb positions
115
- perp --json arb funding-earned # actual funding payments
133
+ # Scan (read-only, safe)
134
+ perp --json arb scan # default --mode all (perp-perp + spot-perp)
135
+ perp --json arb scan --mode perp-perp --min 10 # perp-only with min annual %
136
+ perp --json arb scan --mode spot-perp --min 10 # spot+perp only
137
+ perp --json arb scan --rates # funding rates across exchanges
138
+ perp --json arb scan --basis [SYMBOL] # cross-exchange basis
139
+ perp --json arb scan --gaps # cross-exchange price gaps
140
+ perp --json arb scan --hip3 # HIP-3 cross-dex spreads
141
+ perp --json arb scan --history [SYMBOL] # historical funding
142
+ perp --json arb scan --compare <SYMBOL> # compare a symbol across exchanges
143
+ perp --json arb scan --positions # position funding impact
144
+ perp --json arb scan --live --interval 60 # continuous monitoring
145
+ perp --json arb scan --top 10 --hold-days 7 --bridge-cost 0 --size 100 # cost-aware filtering
146
+
147
+ # Execute (perp-perp or spot+perp via spot:<exch> prefix)
148
+ perp --json arb exec <SYM> <longEx> <shortEx> <USD> # perp-perp dual-leg entry
149
+ perp --json arb exec <SYM> spot:hl hl <USD> # spot+perp via HL spot
150
+ perp --json arb exec <SYM> spot:lt pac <USD> # spot+perp via LT spot
151
+ perp --json arb exec <SYM> <longEx> <shortEx> <USD> \
152
+ --leverage 2 --isolated --smart --reconcile --max-slippage 0.5
153
+
154
+ # Close
155
+ perp --json arb close <SYM> # close perp-perp arb
156
+ perp --json arb close <SYM> --pair <longEx>:<shortEx> # disambiguate by pair
157
+ perp --json arb close <SYM> --spot-exch hl --perp-exch hl # close spot+perp legs
158
+ perp --json arb close <SYM> --smart # IOC limits at best price
116
159
 
117
- # Spot+Perp arb (spot funding = 0, spread = |perp funding|)
118
- perp --json arb scan --mode spot-perp # scan spot+perp opportunities
119
- perp --json arb scan --mode all # both perp-perp + spot-perp
120
- perp --json arb spot-exec <SYM> <spotEx> <perpEx> <$> # execute spot+perp arb
121
- perp --json arb spot-close <SYM> --spot-exch <hl|lt> # close spot+perp arb
122
- # spotEx: hl (Hyperliquid) or lt (Lighter). perpEx: hl, lt, pac.
123
- # HL spot uses U-tokens: BTC→UBTC, ETH→UETH, SOL→USOL (auto-resolved)
160
+ # Status / history / config / rebalance
161
+ perp --json arb status # open arb positions + PnL + funding earned
162
+ perp --json arb status --period 7 --symbol BTC # filter funding lookback / symbol
163
+ perp --json arb history # alias: arb log
164
+ perp --json arb history --period 30 # past arb trade performance
165
+ perp --json arb config # show arb defaults
166
+ perp --json arb rebalance --check # cross-exchange balance distribution
167
+ perp --json arb rebalance --target 50:50 --amount 1000 --dry-run
124
168
 
125
- # Other arb tools
126
- perp --json arb rates # funding rates across all DEXs (detailed)
127
- perp --json arb prices # cross-exchange price gaps
128
- perp --json arb dex # HIP-3 cross-dex arb (Hyperliquid)
129
- # Deprecated: 'gap show' → use 'arb prices'; 'funding rates/spread' → use 'arb rates/scan'
169
+ # Auto-execute daemon
170
+ perp --json arb auto --min-spread 30 --close-spread 5 --size 100 --max-positions 5
171
+ perp --json arb auto --background # tmux session
172
+ perp --json arb auto --hip3 --min-oi 50000 --min-grade C # HIP-3 mode
173
+ perp --json arb auto --dry-run # simulate
130
174
  ```
131
175
 
132
176
  ## Wallet Management
133
177
  ```bash
134
- perp --json wallet set hl <KEY> # set Hyperliquid key
135
- perp --json wallet set pac <KEY> # set Pacifica key
136
- perp --json wallet set lt <KEY> # set Lighter key
137
- perp --json wallet set hl <KEY> --default # set key + make default exchange
138
- perp --json wallet show # show configured wallets (public addresses)
139
- perp --json wallet generate evm # generate new EVM wallet
140
- perp --json wallet generate solana # generate new Solana wallet
141
- perp --json wallet balance # on-chain balance
178
+ perp --json wallet generate evm # generate EVM wallet
179
+ perp --json wallet generate solana # generate Solana wallet
180
+ perp --json wallet import [privateKey] # import an existing key
181
+ perp --json wallet set hl <KEY> # set Hyperliquid key
182
+ perp --json wallet set pac <KEY> # set Pacifica key
183
+ perp --json wallet set lt <KEY> # set Lighter key (auto-generates API key)
184
+ perp --json wallet set aster <API_KEY> # set Aster API key
185
+ perp --json wallet set hl <KEY> --default # set + make default exchange
186
+ perp --json wallet show # public addresses for active wallet
187
+ perp --json wallet list # all named wallets
188
+ perp --json wallet use <name> # set active wallet
189
+ perp --json wallet rename <old> <new>
190
+ perp --json wallet remove <name>
191
+ perp --json wallet balance # on-chain USDC balances
192
+ perp --json wallet solana <address> # check arbitrary Solana address
193
+ perp --json wallet arbitrum <address> # check arbitrary Arbitrum address
194
+ perp --json wallet migrate # migrate legacy ~/.perp/.env config
195
+ perp --json wallet rotate # rotate keys + transfer assets
196
+ perp --json wallet backup # encrypted backup
197
+ perp --json wallet restore <file> # restore from backup
198
+ perp --json wallet deposit <walletName> # deposit prompt for a stored wallet
199
+ perp --json wallet setup # **interactive — DO NOT use from agent**
200
+ ```
201
+
202
+ ### Agent wallet (DEX-side delegation)
203
+ ```bash
204
+ perp --json wallet agent approve <exchange> [--master <name>] [--api-key-index <n>]
205
+ perp --json wallet agent list [exchange]
206
+ perp --json wallet agent revoke <exchange> <agentName>
207
+ perp --json wallet agent rotate <exchange> [oldAgentName]
208
+ perp --json wallet agent verify [exchange] [agentName]
209
+ ```
210
+
211
+ ### Exchange settings (`wallet manage`)
212
+ ```bash
213
+ perp --json wallet manage margin <SYMBOL> <cross|isolated>
214
+ perp --json wallet manage withdraw <amount> <address> # generic on-exchange withdraw
215
+ perp --json wallet manage account-mode [standard|big-blocks] # Hyperliquid only
216
+ perp --json wallet manage sub create <name>
217
+ perp --json wallet manage sub list
218
+ perp --json wallet manage sub transfer <from> <to> <amount>
219
+ perp --json wallet manage lake create <symbol> <amount>
220
+ perp --json wallet manage lake deposit <lakeId> <amount>
221
+ perp --json wallet manage lake withdraw <lakeId> <amount>
222
+ perp --json wallet manage builder approve <code> <maxFeeRate>
223
+ perp --json wallet manage builder revoke <code>
224
+ perp --json wallet manage builder list
225
+ perp --json wallet manage builder overview
226
+ perp --json wallet manage builder trades <code>
227
+ perp --json wallet manage builder leaderboard <code>
228
+ perp --json wallet manage builder update-fee <code> <feeRate>
229
+ perp --json wallet manage referral claim <code> # Pacifica
230
+ perp --json wallet manage apikey create <name> <maxFeeRate>
231
+ perp --json wallet manage apikey list
232
+ perp --json wallet manage apikey revoke <key>
233
+ ```
234
+
235
+ ### OWS (Open Wallet Standard) API key + policy — optional, scoped agent tokens
236
+ ```bash
237
+ perp --json wallet key create
238
+ perp --json wallet key list
239
+ perp --json wallet key revoke <id>
240
+ perp --json wallet policy create
241
+ perp --json wallet policy list
242
+ perp --json wallet policy show <id>
243
+ perp --json wallet policy delete <id>
142
244
  ```
143
245
 
144
246
  ## Risk & Analytics
145
247
  ```bash
146
- perp --json risk status # portfolio risk overview (level, violations, canTrade)
147
- perp --json risk liquidation-distance # % distance from liquidation for ALL positions
148
- perp --json risk limits # view current risk limits
248
+ perp --json risk status # portfolio risk overview (level, violations, canTrade)
249
+ perp --json risk health # health-check summary
250
+ perp --json risk liquidation-distance # % distance from liquidation for ALL positions
251
+ perp --json risk limits # view current risk limits
149
252
  perp --json risk limits --min-liq-distance 30 --max-leverage 5 # set risk limits
150
- perp --json risk check --notional 1000 --leverage 3 # pre-trade risk check
151
- perp --json history summary # trading performance
152
- perp --json history pnl # P&L breakdown by exchange
153
- perp --json history funding # funding payment aggregation
154
- perp --json history report # full performance report (summary + pnl + funding)
155
- perp --json history perf --period daily # daily PnL breakdown (replaces daily-pnl)
156
- perp --json history perf --period weekly # weekly PnL breakdown (replaces weekly-pnl)
157
- perp --json history perf --period summary # performance summary stats
158
- perp --json history list # execution audit trail
253
+ perp --json risk check --notional 1000 --leverage 3 # pre-trade risk check
254
+ ```
255
+
256
+ ## History (execution log + analytics)
257
+ ```bash
258
+ perp --json history list # execution audit trail
259
+ perp --json history stats # aggregated execution stats
260
+ perp --json history positions # position lifetime tracking
261
+ perp --json history prune # purge old entries
262
+ perp --json history summary # trading performance summary
263
+ perp --json history pnl # P&L breakdown by exchange
264
+ perp --json history funding # funding payment aggregation
265
+ perp --json history report # full performance report (summary + pnl + funding)
266
+ perp --json history compare # compare strategies / accounts
267
+ perp --json history snapshot # equity snapshot
268
+ perp --json history track # PnL tracking helper
269
+ perp --json history perf --period daily # daily PnL breakdown
270
+ perp --json history perf --period weekly # weekly PnL breakdown
271
+ perp --json history perf --period summary # performance summary stats
159
272
  ```
160
273
 
161
- ## Automated Strategies (strategy — 19 algorithms + nested scripted plans)
274
+ ## Strategies (`perp strategy` — 20 algorithms + nested scripted plans)
162
275
  ```bash
163
- perp --json strategy list-strategies # list all 19 strategies
276
+ perp --json strategy list-strategies # list all 20 strategies
164
277
  perp --json strategy run <STRATEGY> [SYMBOL] # run any registered strategy
165
- perp --json strategy run funding-auto # multi-exchange funding arb (no symbol needed)
166
- perp --json strategy apex [SYMBOL] # APEX autonomous orchestrator (Radar+Pulse+Guard)
167
- perp --json strategy reflect # trading performance analysis (win rate, fees, PnL)
168
- perp --json strategy preset-list # list strategy presets
169
- perp --json strategy preset <NAME> [SYMBOL] # run from preset
170
- perp --json strategy twap <SYMBOL> <SIDE> <SIZE> <DURATION> # TWAP execution
278
+ perp --json strategy run funding-auto # multi-exchange funding arb
279
+ perp --json strategy apex [SYMBOL] # APEX orchestrator
280
+ perp --json strategy reflect # performance analysis
281
+ perp --json strategy preset-list
282
+ perp --json strategy preset <NAME> [SYMBOL]
283
+ perp --json strategy start <CONFIG.yaml> # YAML/JSON config-driven
284
+ perp --json strategy quick-grid <SYMBOL>
285
+ perp --json strategy quick-dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL>
286
+ perp --json strategy quick-arb
287
+ perp --json strategy delta-neutral
288
+ perp --json strategy twap <SYMBOL> <SIDE> <SIZE> <DURATION>
171
289
  perp --json strategy grid <SYMBOL> --range <PCT> --grids <N> --size <USD>
172
290
  perp --json strategy dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL>
173
- perp --json strategy trailing-stop <SYMBOL> # trailing stop with callback %
174
- perp --json strategy funding-arb # auto funding arb
175
- perp --json strategy quick-grid <SYMBOL> # quick grid bot
176
- perp --json strategy quick-arb # quick arb bot
291
+ perp --json strategy trailing-stop <SYMBOL>
292
+ perp --json strategy funding-arb # legacy alias for run funding-arb
177
293
 
178
294
  # Scripted execution plans (one-shot multi-step)
179
- perp --json strategy plan example # show plan format
180
- perp --json strategy plan validate <FILE> # validate plan
181
- perp --json strategy plan execute <FILE> --dry-run # dry-run plan
295
+ perp --json strategy plan example
296
+ perp --json strategy plan validate <FILE>
297
+ perp --json strategy plan execute <FILE> --dry-run
298
+ ```
299
+
300
+ ### Available Strategies (20)
301
+ - **Market Making:** `simple-mm`, `engine-mm`, `avellaneda-mm`, `regime-mm`, `grid-mm`, `liquidation-mm`
302
+ - **Signal/Directional:** `momentum-breakout`, `mean-reversion`, `aggressive-taker`
303
+ - **Arbitrage:** `funding-arb`, `funding-arb-v2`, `funding-auto`, `basis-arb`, `spot-perp-arb`
304
+ - **Infrastructure:** `hedge-agent`, `rfq-agent`, `claude-agent`
305
+ - **Classic:** `grid`, `dca`, `apex`
306
+
307
+ ## Background Process Supervisor (tmux)
308
+ ```bash
309
+ perp --json background list # list running jobs (default subcommand)
310
+ perp --json background stop <ID> # stop a job
311
+ perp --json background logs <ID> # view logs (use -f to follow)
312
+ perp --json background remove <ID> # remove a job entry
313
+ perp --json background clean # purge all stopped/done jobs
314
+ ```
315
+
316
+ ## Backtest
317
+ ```bash
318
+ perp --json backtest funding-arb # backtest funding arb on historical data
319
+ perp --json backtest grid # backtest grid strategy
320
+ ```
182
321
 
183
- # Background process supervisor (tmux)
184
- perp --json background list # list running jobs
185
- perp --json background stop <ID> # stop a job
186
- perp --json background logs <ID> # view job logs
187
- perp --json background remove <ID> # remove a job entry
188
- perp --json background clean # remove all stopped/done jobs
322
+ ## Alerts (Telegram / Discord)
323
+ ```bash
324
+ perp alerts setup # interactive setup wizard
325
+ perp --json alerts test # send test message
326
+ perp --json alerts add <SYMBOL> <PCT> # add alert rule
327
+ perp --json alerts add --all <PCT> # alert for any symbol > N%
328
+ perp --json alerts list # list active rules
329
+ perp --json alerts remove <ID> # remove a rule
330
+ perp alerts start [--background] # run daemon (tmux for background)
331
+ perp alerts stop # stop background daemon
189
332
  ```
190
333
 
191
- ### Available Strategies
192
- Market Making: `simple-mm`, `engine-mm`, `avellaneda-mm`, `regime-mm`, `grid-mm`, `liquidation-mm`
193
- Signal/Directional: `momentum-breakout`, `mean-reversion`, `aggressive-taker`
194
- Arbitrage: `funding-arb`, `funding-auto`, `basis-arb`
195
- Infrastructure: `hedge-agent`, `rfq-agent`, `claude-agent`
196
- Classic: `grid`, `dca`, `twap`, `apex`
334
+ ## Settings
335
+ ```bash
336
+ perp --json settings show # show current CLI settings
337
+ perp --json settings set <key> <value> # set a CLI default
338
+ perp --json settings referrals on|off # toggle referral codes
339
+ perp --json settings fees show # cached exchange fee table
340
+ perp --json settings fees sync # refresh fee cache
341
+ perp --json settings env show # show ~/.perp/.env values
342
+ perp --json settings env set <name> <value>
343
+ perp --json settings env remove <name>
344
+ perp --json settings env path # config file path
345
+ ```
197
346
 
198
- ## Agent Wallet Management
347
+ ## Init / Setup
199
348
  ```bash
200
- perp wallet agent approve <exchange> [--master <name>] # Register an agent wallet
201
- perp wallet agent list [exchange] # List registered agents
202
- perp wallet agent revoke <exchange> <agentName> # Revoke an agent
203
- perp wallet agent rotate <exchange> [agentName] # Revoke + re-approve same name
204
- perp wallet agent verify [exchange] [agentName] # Verify via DEX query API
349
+ perp init # interactive — DO NOT use from agent
350
+ perp setup # alias for init — DO NOT use from agent
205
351
  ```
352
+
353
+ Use `perp wallet set <ex> <key>` instead — non-interactive and agent-safe.
package/skills/perp-cli/references/strategies.md CHANGED
@@ -26,9 +26,9 @@ Switch Cost =
26
26
 
27
27
  Query each component:
28
28
  ```bash
29
- perp --json -e <FROM> trade check <SYM> <SIDE> <SIZE> # close cost estimate
30
- perp --json bridge quote --from <CHAIN> --to <CHAIN> --amount <AMT> # bridge cost
31
- perp --json -e <TO> trade check <SYM> <SIDE> <SIZE> # open cost estimate
29
+ perp --json -e <FROM> trade check <SYM> <SIDE> <SIZE> --leverage <L> # close cost estimate
30
+ perp --json funds bridge quote --from <CHAIN> --to <CHAIN> --amount <AMT> # bridge cost
31
+ perp --json -e <TO> trade check <SYM> <SIDE> <SIZE> --leverage <L> # open cost estimate
32
32
  ```
33
33
 
34
34
  **Only switch if:**
@@ -56,8 +56,10 @@ During transition, you are **unhedged**. Price can move against you. Factor this
56
56
 
57
57
  ### Discovery Loop
58
58
  ```bash
59
- perp --json arb scan --min 5 # find spreads > 5 bps (shows longExch/shortExch/netSpread)
60
- # NOTE: 'arb rates' is deprecated — use 'arb scan' instead
59
+ perp --json arb scan --min 5 # find spreads > 5% annual (shows longExch/shortExch/netSpread)
60
+ perp --json arb scan --rates # raw funding rates across all exchanges
61
+ perp --json arb scan --history <SYMBOL> # historical funding for a symbol
62
+ # NOTE: legacy 'arb rates'/'arb prices'/'arb dex' are removed — all routes go through 'arb scan'
61
63
  ```
62
64
 
63
65
  ### CRITICAL: Reading arb scan Results
@@ -135,7 +137,7 @@ Actual hold: 6h | Actual net: ~130 bps
135
137
  ### Monitoring Active Positions
136
138
  ```bash
137
139
  perp --json portfolio # unified multi-exchange view
138
- perp --json risk overview # cross-exchange risk assessment
140
+ perp --json risk status # cross-exchange risk assessment (level, violations, canTrade)
139
141
  perp --json -e <EX> account positions # per-exchange positions
140
142
  perp --json arb scan --min 5 # are current rates still favorable?
141
143
  ```
@@ -453,7 +455,8 @@ This is YOUR operational knowledge. Use it to make better decisions over time.
453
455
  ### Cross-Exchange Capital Allocation
454
456
  Your capital is split across exchanges. Rebalancing has real costs:
455
457
  ```bash
456
- perp --json bridge quote --from solana --to arbitrum --amount 1000
458
+ perp --json funds bridge quote --from solana --to arbitrum --amount 1000
459
+ perp --json funds rebalance plan # auto-compute optimal moves across exchanges
457
460
  ```
458
461
 
459
462
  Before rebalancing, ask:
package/skills/perp-cli/scripts/arb-monitor.sh CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/bin/bash
2
2
  # Monitor open arb positions and evaluate exit conditions
3
3
  # Usage: ./arb-monitor.sh [--json] [--min-spread 5]
4
- # Checks: current spread vs entry, funding earned, PnL, liquidation distance
4
+ # Checks: current spread vs entry, funding earned (from arb status), PnL, liquidation distance
5
5
  # Returns JSON with position health + actionable recommendations
6
6
 
7
7
  set -euo pipefail
@@ -23,7 +23,7 @@ while [[ $# -gt 0 ]]; do
23
23
  esac
24
24
  done
25
25
 
26
- # 1. Get current arb status
26
+ # 1. Get current arb status (already includes funding earned per period)
27
27
  ARB_STATUS=$($PERP --json arb status 2>/dev/null || echo '{"ok":false}')
28
28
  if ! echo "$ARB_STATUS" | grep -q '"ok":true'; then
29
29
  if $JSON_MODE; then
@@ -34,15 +34,15 @@ if ! echo "$ARB_STATUS" | grep -q '"ok":true'; then
34
34
  exit 0
35
35
  fi
36
36
 
37
- # 2. Get current spreads
38
- ARB_SCAN=$($PERP --json arb scan --min 0 2>/dev/null || echo '{"ok":false,"data":{"opportunities":[]}}')
37
+ # 2. Get current spreads (all modes)
38
+ ARB_SCAN=$($PERP --json arb scan --mode all --min 0 2>/dev/null || echo '{"ok":false,"data":{"opportunities":[]}}')
39
39
 
40
- # 3. Get funding earned
41
- FUNDING=$($PERP --json arb funding-earned 2>/dev/null || echo '{"ok":false}')
42
-
43
- # 4. Get liquidation distances
40
+ # 3. Get liquidation distances
44
41
  LIQ_DIST=$($PERP --json risk liquidation-distance 2>/dev/null || echo '{"ok":false}')
45
42
 
43
+ # 4. Get risk overview
44
+ RISK_STATUS=$($PERP --json risk status 2>/dev/null || echo '{"ok":false}')
45
+
46
46
  # 5. Output combined analysis
47
47
  if $JSON_MODE; then
48
48
  cat <<EOF
@@ -51,8 +51,8 @@ if $JSON_MODE; then
51
51
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
52
52
  "positions": $ARB_STATUS,
53
53
  "currentSpreads": $ARB_SCAN,
54
- "fundingEarned": $FUNDING,
55
54
  "liquidationDistance": $LIQ_DIST,
55
+ "riskStatus": $RISK_STATUS,
56
56
  "minSpreadThreshold": $MIN_SPREAD
57
57
  }
58
58
  EOF
@@ -60,15 +60,15 @@ else
60
60
  echo "=== Arb Position Monitor ==="
61
61
  echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
62
62
  echo ""
63
- echo "--- Positions ---"
63
+ echo "--- Positions (with funding earned) ---"
64
64
  echo "$ARB_STATUS" | jq -r '.data // empty'
65
65
  echo ""
66
- echo "--- Funding Earned ---"
67
- echo "$FUNDING" | jq -r '.data // empty'
68
- echo ""
69
66
  echo "--- Liquidation Distance ---"
70
67
  echo "$LIQ_DIST" | jq -r '.data // empty'
71
68
  echo ""
72
- echo "Min spread threshold: ${MIN_SPREAD} bps"
73
- echo "Recommendation: Check if current spreads exceed ${MIN_SPREAD} bps to continue holding."
69
+ echo "--- Risk Status ---"
70
+ echo "$RISK_STATUS" | jq -r '.data // empty'
71
+ echo ""
72
+ echo "Min spread threshold: ${MIN_SPREAD}% annual"
73
+ echo "Recommendation: Check if current spreads exceed ${MIN_SPREAD}% to continue holding."
74
74
  fi
package/skills/perp-cli/scripts/funding-analysis.sh CHANGED
@@ -26,8 +26,9 @@ done
26
26
 
27
27
  if [[ -n "$SYMBOL" ]]; then
28
28
  # Single symbol detailed analysis
29
- FUNDING=$($PERP --json market funding "$SYMBOL" 2>/dev/null || echo '{"ok":false}')
30
- SCAN=$($PERP --json arb scan --min 0 2>/dev/null || echo '{"ok":false}')
29
+ FUNDING=$($PERP --json arb scan --history "$SYMBOL" 2>/dev/null || echo '{"ok":false}')
30
+ COMPARE=$($PERP --json arb scan --compare "$SYMBOL" 2>/dev/null || echo '{"ok":false}')
31
+ SCAN=$($PERP --json arb scan --mode perp-perp --min 0 2>/dev/null || echo '{"ok":false}')
31
32
  SPOT_SCAN=$($PERP --json arb scan --mode spot-perp --min 0 2>/dev/null || echo '{"ok":false}')
32
33
 
33
34
  if $JSON_MODE; then
@@ -36,7 +37,8 @@ if [[ -n "$SYMBOL" ]]; then
36
37
  "ok": true,
37
38
  "symbol": "$SYMBOL",
38
39
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
39
- "funding": $FUNDING,
40
+ "fundingHistory": $FUNDING,
41
+ "compare": $COMPARE,
40
42
  "perpPerpArb": $SCAN,
41
43
  "spotPerpArb": $SPOT_SCAN
42
44
  }
@@ -44,13 +46,16 @@ EOF
44
46
  else
45
47
  echo "=== Funding Analysis: $SYMBOL ==="
46
48
  echo ""
47
- echo "--- Current Funding Rates ---"
49
+ echo "--- Cross-Exchange Compare ---"
50
+ echo "$COMPARE" | jq -r '.data // empty' 2>/dev/null || echo "(unavailable)"
51
+ echo ""
52
+ echo "--- Funding History ---"
48
53
  echo "$FUNDING" | jq -r '.data // empty' 2>/dev/null || echo "(unavailable)"
49
54
  echo ""
50
55
  echo "--- Perp-Perp Arb ---"
51
56
  echo "$SCAN" | jq -r '
52
57
  .data // [] | map(select(.symbol == "'"$SYMBOL"'")) | .[] |
53
- " \(.longExch // .longExchange)→\(.shortExch // .shortExchange): \(.netSpread // .spread)bps"
58
+ " \(.longExch // .longExchange)→\(.shortExch // .shortExchange): \(.netSpread // .spread)% annual"
54
59
  ' 2>/dev/null || echo " (no opportunity)"
55
60
  echo ""
56
61
  echo "--- Spot+Perp Arb ---"
@@ -62,7 +67,7 @@ EOF
62
67
  else
63
68
  # All symbols scan
64
69
  SCAN=$($PERP --json arb scan --mode all --min 0 2>/dev/null || echo '{"ok":false}')
65
- FUNDING_DETAIL=$($PERP --json arb rates 2>/dev/null || echo '{"ok":false}')
70
+ FUNDING_DETAIL=$($PERP --json arb scan --rates 2>/dev/null || echo '{"ok":false}')
66
71
 
67
72
  if $JSON_MODE; then
68
73
  cat <<EOF