perp-cli 0.4.8 → 0.4.9

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

@@ -12,11 +12,12 @@ perp --json market book <SYMBOL>           # orderbook (bids/asks)
 perp --json market trades <SYMBOL>         # recent trades
 perp --json market funding <SYMBOL>        # funding rate history
 perp --json market kline <SYM> <INTERVAL>  # OHLCV candles (1m,5m,15m,1h,4h,1d)
+perp --json market hip3                    # list HIP-3 deployed perp dexes (Hyperliquid only)
 ```
 
 ## Account (read-only, safe)
 ```bash
-perp --json account info                   # balance, equity, margin, PnL
+perp --json account balance                # perp balance + spot holdings + 24h funding (alias: account info)
 perp --json account positions              # open positions
 perp --json account orders                 # open/pending orders
 perp --json account history                # order history
@@ -24,7 +25,6 @@ perp --json account trades                 # trade fill history
 perp --json account funding-history        # funding payments
 perp --json account pnl                    # profit & loss
 perp --json account margin <SYMBOL>        # position margin info
-perp --json status                         # combined: balance + positions + orders
 perp --json portfolio                      # cross-exchange unified view
 ```
 
@@ -60,22 +60,29 @@ perp --json trade leverage <SYMBOL> <N>     # set leverage
 # Advanced orders
 perp --json trade scale-tp <SYMBOL> --levels '<PRICE1>:<PCT>,<PRICE2>:<PCT>'
 perp --json trade scale-in <SYMBOL> <SIDE> --levels '<PRICE1>:<SIZE>,<PRICE2>:<SIZE>'
-perp --json trade trailing-stop <SYMBOL>    # trailing stop with callback %
-perp --json trade twap <SYMBOL> <SIDE> <SIZE> <DURATION>
 perp --json trade pnl-track                 # real-time PnL tracker
+
+# Split execution (orderbook-aware)
+perp --json trade split <SYMBOL> <buy|sell> <USD>   # split large order into depth-based slices
+perp --json trade split <SYM> buy 5000 --max-slippage 0.5 --max-slices 5 --delay 2000 --min-slice 200
+perp --json trade market <SYM> buy <SIZE> --split   # split via market command flag
+perp --json trade market <SYM> buy <SIZE> --split --max-slippage 0.5
 ```
 
-## Deposit & Withdraw
+## Funds (Deposit, Withdraw, Transfer, Bridge)
 ```bash
-perp --json deposit pacifica <AMOUNT>
-perp --json deposit hyperliquid <AMOUNT>
-perp --json deposit lighter ethereum <AMOUNT>         # L1 direct (min 1 USDC)
-perp --json deposit lighter cctp arbitrum <AMOUNT>    # CCTP (min 5 USDC)
-perp --json deposit lighter info                      # all Lighter deposit routes
-perp --json withdraw pacifica <AMOUNT>
-perp --json withdraw hyperliquid <AMOUNT>
-perp --json deposit info                    # deposit instructions
-perp --json withdraw info                   # withdrawal instructions
+perp --json funds deposit pacifica <AMOUNT>
+perp --json funds deposit hyperliquid <AMOUNT>
+perp --json funds deposit lighter ethereum <AMOUNT>         # L1 direct (min 1 USDC)
+perp --json funds deposit lighter cctp arbitrum <AMOUNT>    # CCTP (min 5 USDC)
+perp --json funds deposit lighter info                      # all Lighter deposit routes
+perp --json funds withdraw pacifica <AMOUNT>
+perp --json funds withdraw hyperliquid <AMOUNT>
+perp --json funds withdraw lighter <AMOUNT>
+perp --json funds transfer <AMOUNT> <ADDRESS>     # HL internal transfer (instant)
+perp --json funds bridge --from <CHAIN> --to <CHAIN> --amount <AMT> --recipient <ADDR>  # CCTP bridge
+perp --json funds bridge-status --hash <HASH>     # check CCTP bridge status
+perp --json funds info                            # combined deposit & withdrawal info
 ```
 
 ## Bridge (Cross-chain USDC)
@@ -105,10 +112,10 @@ perp --json arb spot-close <SYM> --spot-exch <hl|lt>   # close spot+perp arb
 # HL spot uses U-tokens: BTC→UBTC, ETH→UETH, SOL→USOL (auto-resolved)
 
 # Other arb tools
-perp --json arb funding                     # detailed funding analysis
+perp --json arb rates                       # funding rates across all DEXs (detailed)
+perp --json arb prices                      # cross-exchange price gaps
 perp --json arb dex                         # HIP-3 cross-dex arb (Hyperliquid)
-perp --json gap show                        # cross-exchange price gaps
-# NOTE: 'arb rates' is deprecated — use 'arb scan' instead
+# Deprecated: 'gap show' → use 'arb prices'; 'funding rates/spread' → use 'arb rates/scan'
 ```
 
 ## Wallet Management
@@ -130,30 +137,30 @@ perp --json risk liquidation-distance       # % distance from liquidation for AL
 perp --json risk limits                     # view current risk limits
 perp --json risk limits --min-liq-distance 30 --max-leverage 5  # set risk limits
 perp --json risk check --notional 1000 --leverage 3  # pre-trade risk check
-perp --json health                          # exchange connectivity & latency
-perp --json analytics summary              # trading performance
-perp --json analytics pnl                   # P&L breakdown
+perp --json agent ping                      # exchange connectivity & latency
+perp --json history summary                 # trading performance
+perp --json history pnl                     # P&L breakdown by exchange
+perp --json history funding                 # funding payment aggregation
+perp --json history report                  # full performance report (summary + pnl + funding)
+perp --json history perf --period daily     # daily PnL breakdown (replaces daily-pnl)
+perp --json history perf --period weekly    # weekly PnL breakdown (replaces weekly-pnl)
+perp --json history perf --period summary   # performance summary stats
 perp --json history list                    # execution audit trail
 ```
 
-## Automated Strategies
+## Automated Strategies (bot)
 ```bash
-perp --json run grid <SYMBOL> --range <PCT> --grids <N> --size <USD>
-perp --json run dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL>
-perp --json run funding-arb                 # auto funding arb
+perp --json bot twap <SYMBOL> <SIDE> <SIZE> <DURATION>    # TWAP execution
+perp --json bot grid <SYMBOL> --range <PCT> --grids <N> --size <USD>
+perp --json bot dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL>
+perp --json bot trailing-stop <SYMBOL>      # trailing stop with callback %
+perp --json bot funding-arb                 # auto funding arb
 perp --json bot quick-grid <SYMBOL>         # quick grid bot
 perp --json bot quick-arb                   # quick arb bot
 perp --json jobs list                       # list running jobs
 perp --json jobs stop <ID>                  # stop a job
 ```
 
-## Alerts
-```bash
-perp --json alert add                       # add price/funding/pnl/liquidation alert
-perp --json alert list                      # list active alerts
-perp --json alert remove <ID>              # remove alert
-```
-
 ## Command Discovery
 ```bash
 perp schema                       # Full CLI schema as JSON

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

@@ -202,19 +202,38 @@ perp --json -e <SHORT_EX> account positions   # size must = X
 ```
 If sizes differ (partial fill, rounding), immediately adjust the larger position to match the smaller one.
 
-#### Step 3: Split Large Orders into Matched Chunks
+#### Step 3: Split Large Orders with `trade split`
 
-If your desired size exceeds what the orderbooks can absorb at best ticks, split into chunks — but **every chunk must be a matched pair with identical size on both sides**:
+For large orders, use the built-in orderbook-aware split execution instead of manual chunking:
 
+```bash
+# Single exchange: split $5000 buy into depth-based slices
+perp --json -e <EX> trade split <SYM> buy 5000
+
+# With options
+perp --json -e <EX> trade split <SYM> buy 5000 --max-slippage 0.5 --max-slices 5 --delay 2000
+
+# Or use --split flag on market command
+perp --json -e <EX> trade market <SYM> buy <SIZE> --split
 ```
-Chunk 1: buy 0.3 on Exchange A → sell 0.3 on Exchange B → verify both
-Chunk 2: buy 0.3 on Exchange A → sell 0.3 on Exchange B → verify both
-... repeat until full size is executed
+
+How it works:
+1. Fetches fresh orderbook before each slice
+2. Walks levels via `computeExecutableSize` to find fillable amount at target slippage
+3. Places IOC limit at worst acceptable price within slippage tolerance
+4. Waits for book to refresh, repeats until target filled or max slices reached
+
+**For arb, both legs must still match.** Use `trade split` on each side independently with the same total USD, then verify sizes match:
+
+```
+Leg A: perp --json -e <LONG_EX> trade split <SYM> buy 5000
+Leg B: perp --json -e <SHORT_EX> trade split <SYM> sell 5000
+→ Verify positions, adjust if sizes differ
 ```
 
 **Rules:**
-1. Re-check orderbook depth between chunks — liquidity changes
-2. Each chunk: same size on both sides, no exceptions
+1. Each chunk re-checks orderbook depth — liquidity changes between slices
+2. For arb: same total USD on both sides, verify matched sizes after execution
 3. If one leg fails → STOP immediately, do NOT continue
 4. Assess exposure: retry the failed leg, or unwind the completed leg
 5. NEVER execute multiple orders on one side without matching the other
@@ -418,15 +437,6 @@ Or use TP/SL together:
 perp --json -e <EX> trade tp-sl <SYM> --tp <PRICE> --sl <PRICE>
 ```
 
-### Monitoring Alerts
-
-Set up alerts so you get notified of dangerous conditions without polling:
-```bash
-perp --json alert add -t margin --margin-pct 70    # alert when margin usage > 70%
-perp --json alert add -t price -s BTC --below 50000 --above 80000   # price boundaries
-perp --json alert add -t funding -s ETH --spread 50  # funding spread alert
-```
-
 ### What to Track Over Time
 As you operate, build awareness of:
 - Which symbols consistently have the best funding spreads

package/skills/perp-cli/scripts/funding-analysis.sh

@@ -62,7 +62,7 @@ EOF
 else
   # All symbols scan
   SCAN=$($PERP --json arb scan --mode all --min 0 2>/dev/null || echo '{"ok":false}')
-  FUNDING_DETAIL=$($PERP --json arb funding 2>/dev/null || echo '{"ok":false}')
+  FUNDING_DETAIL=$($PERP --json arb rates 2>/dev/null || echo '{"ok":false}')
 
   if $JSON_MODE; then
     cat <<EOF
@@ -71,7 +71,7 @@ else
   "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "topN": $TOP,
   "allOpportunities": $SCAN,
-  "fundingDetail": $FUNDING_DETAIL
+  "ratesDetail": $FUNDING_DETAIL
 }
 EOF
   else

package/skills/perp-cli/scripts/preflight.sh

@@ -42,7 +42,7 @@ else
 fi
 
 # 3. Exchange connectivity
-HEALTH_OUT=$($PERP --json health 2>/dev/null || echo '{"ok":false}')
+HEALTH_OUT=$($PERP --json agent ping 2>/dev/null || echo '{"ok":false}')
 if echo "$HEALTH_OUT" | grep -q '"ok":true'; then
   add_check "connectivity" "pass" "Exchanges reachable"
 else

package/skills/perp-cli/scripts/spot-perp-scan.sh

@@ -39,7 +39,7 @@ fi
 SCAN_RESULT=$($PERP --json arb scan --mode "$MODE" --min "$MIN_SPREAD" 2>/dev/null || echo '{"ok":false}')
 
 # 3. Get exchange health for context
-HEALTH=$($PERP --json health 2>/dev/null || echo '{"ok":false}')
+HEALTH=$($PERP --json agent ping 2>/dev/null || echo '{"ok":false}')
 
 if $JSON_MODE; then
   cat <<EOF