perp-cli 0.3.8 → 0.3.9

package/dist/exchanges/hyperliquid.d.ts

@@ -20,6 +20,11 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     init(): Promise<void>;
     /** Load asset index map — supports native and HIP-3 dex. */
     private _loadAssetMap;
+    /**
+     * Resolve a symbol to the canonical name in the asset map.
+     * Handles: "ICP" → "ICP-PERP", "BTC-PERP" → "BTC-PERP", "km:GOOGL" → "km:GOOGL"
+     */
+    resolveSymbol(symbol: string): string;
     getAssetIndex(symbol: string): number;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
     getOrderbook(symbol: string): Promise<{

package/dist/exchanges/hyperliquid.js

@@ -93,24 +93,34 @@ export class HyperliquidAdapter {
             // non-critical
         }
     }
-    getAssetIndex(symbol) {
+    /**
+     * Resolve a symbol to the canonical name in the asset map.
+     * Handles: "ICP" → "ICP-PERP", "BTC-PERP" → "BTC-PERP", "km:GOOGL" → "km:GOOGL"
+     */
+    resolveSymbol(symbol) {
         const sym = symbol.toUpperCase();
-        // Try exact match first (handles both "BTC" for native and "km:GOOGL" for dex)
-        let idx = this._assetMap.get(sym);
-        if (idx !== undefined)
-            return idx;
-        // For dex: try lowercase prefix (API returns "km:GOOGL" but input may be "KM:GOOGL")
+        if (this._assetMap.has(sym))
+            return sym;
+        if (this._assetMap.has(`${sym}-PERP`))
+            return `${sym}-PERP`;
+        if (sym.endsWith("-PERP") && this._assetMap.has(sym.replace(/-PERP$/, "")))
+            return sym.replace(/-PERP$/, "");
         if (sym.includes(":")) {
             const [prefix, base] = sym.split(":");
-            idx = this._assetMap.get(`${prefix.toLowerCase()}:${base}`);
-            if (idx !== undefined)
-                return idx;
-            // Try base name only (e.g., "GOOGL")
-            idx = this._assetMap.get(base);
-            if (idx !== undefined)
-                return idx;
+            const lower = `${prefix.toLowerCase()}:${base}`;
+            if (this._assetMap.has(lower))
+                return lower;
+            if (this._assetMap.has(base))
+                return base;
         }
-        throw new Error(`Unknown symbol: ${symbol}`);
+        return sym; // return as-is, let downstream error
+    }
+    getAssetIndex(symbol) {
+        const resolved = this.resolveSymbol(symbol);
+        const idx = this._assetMap.get(resolved);
+        if (idx !== undefined)
+            return idx;
+        throw new Error(`Unknown asset: ${symbol}`);
     }
     async getMarkets() {
         let universe;
@@ -589,14 +599,14 @@ export class HyperliquidAdapter {
      * Uses SDK's built-in updateLeverage method.
      */
     async updateLeverage(symbol, leverage, isCross = true) {
-        return this.sdk.exchange.updateLeverage(symbol, isCross ? "cross" : "isolated", leverage);
+        return this.sdk.exchange.updateLeverage(this.resolveSymbol(symbol), isCross ? "cross" : "isolated", leverage);
     }
     /**
      * Update isolated margin for a position.
      * amount > 0 to add margin, amount < 0 to remove
      */
     async updateIsolatedMargin(symbol, amount) {
-        return this.sdk.exchange.updateIsolatedMargin(symbol, amount > 0, Math.round(Math.abs(amount) * 1e6));
+        return this.sdk.exchange.updateIsolatedMargin(this.resolveSymbol(symbol), amount > 0, Math.round(Math.abs(amount) * 1e6));
     }
     /**
      * Withdraw from Hyperliquid L1 bridge.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "./dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.3.8"
+  version: "0.3.9"
   mcp-server: perp-cli
 ---
 
@@ -66,6 +66,12 @@ perp --json -e lighter ...        # Lighter (Ethereum)
 ```
 If a default exchange is set, `-e` can be omitted.
 
+### Symbol naming
+Symbols are auto-resolved across exchanges. Use bare symbols (e.g., `BTC`, `SOL`, `ICP`) everywhere — the CLI handles exchange-specific naming:
+- **Hyperliquid**: `ICP` → `ICP-PERP` (auto-resolved, `-PERP` suffix added)
+- **Pacifica / Lighter**: bare symbols as-is
+- `arb scan` returns bare symbols — pass them directly to any exchange command.
+
 ### Common operations
 ```bash
 perp --json wallet show                      # check configured wallets
@@ -73,10 +79,19 @@ perp --json -e hl account info               # balance & margin
 perp --json -e hl account positions          # open positions
 perp --json -e hl market list                # available markets
 perp --json -e hl market mid BTC             # BTC mid price
-perp --json arb rates                        # cross-exchange funding rates
+perp --json arb scan --min 5                 # find funding arb opportunities (>5bps spread)
 perp --json portfolio                        # unified multi-exchange view
 ```
 
+### Funding arb direction (CRITICAL — do NOT reverse)
+```
+arb scan returns: longExch, shortExch, netSpread
+→ ALWAYS follow longExch/shortExch exactly. NEVER reverse the direction.
+→ NEVER enter if netSpread ≤ 0 (= loss after fees)
+→ Positive funding = longs pay shorts → be SHORT to receive
+→ Negative funding = shorts pay longs → be LONG to receive
+```
+
 ### Trade execution (MANDATORY checklist)
 ```
 BEFORE ANY TRADE:
@@ -98,6 +113,43 @@ BEFORE ANY TRADE:
 9. perp --json -e <EX> account positions       → verify result + check liquidation price
 ```
 
+### Exchange-specific constraints
+```
+Minimum order values (notional, enforced by exchange):
+  - Hyperliquid: $10 minimum per order
+  - Pacifica: varies by symbol (usually ~$1)
+  - Lighter: varies by symbol
+
+If your calculated size falls below the minimum, increase to meet it or skip the opportunity.
+trade check returns valid: true/false but is ADVISORY — it does NOT block execution.
+The exchange itself will reject orders below its minimum.
+```
+
+### Arb order sizing (CRITICAL — both legs MUST match)
+```
+For funding arb, BOTH legs must have the EXACT SAME SIZE. Size mismatch = directional exposure.
+
+1. Check orderbook depth on BOTH exchanges:
+   perp --json -e <LONG_EX> market book <SYM>    → asks (you're buying)
+   perp --json -e <SHORT_EX> market book <SYM>   → bids (you're selling)
+
+2. Compute ORDER_SIZE:
+   - fillable_long = sum of ask sizes at best 2-3 levels
+   - fillable_short = sum of bid sizes at best 2-3 levels
+   - ORDER_SIZE = min(fillable_long, fillable_short, desired_size)
+   - Must be ≥ BOTH exchanges' minimum order value (e.g. HL requires ≥$10 notional)
+
+3. Execute BOTH legs with the SAME ORDER_SIZE:
+   perp --json -e <LONG_EX> trade market <SYM> buy <ORDER_SIZE>
+   → verify fill via account positions
+   perp --json -e <SHORT_EX> trade market <SYM> sell <ORDER_SIZE>
+   → verify fill via account positions
+
+4. Confirm matched: both positions must show identical size.
+   If mismatch (partial fill), adjust the larger to match the smaller.
+```
+See `references/strategies.md` for detailed execution strategy (chunked orders, limit orders, failure handling).
+
 ### Post-entry monitoring (MANDATORY while positions are open)
 ```
 Every 15 minutes:
@@ -106,7 +158,7 @@ Every 15 minutes:
   perp --json -e <EX> account positions        → check each position P&L
 
 Every 1 hour (at funding settlement):
-  perp --json arb rates                        → is spread still profitable?
+  perp --json arb scan --min 5                  → is spread still profitable?
   perp --json portfolio                        → total equity across exchanges
   Compare both legs' unrealized P&L — they should roughly offset
 

package/skills/perp-cli/references/agent-operations.md

@@ -78,7 +78,7 @@ perp --json bridge send --from solana --to arbitrum --amount 500
 perp --json bridge status <orderId>     # wait for completion
 
 # 5. Verify both sides have balance, then start arb
-perp --json arb rates
+perp --json arb scan --min 5
 ```
 
 ### Lighter API Key Setup
@@ -229,7 +229,7 @@ Error case:
 - `wallet show`, `wallet balance` — read-only
 - `account info`, `account positions`, `account orders` — read-only
 - `market list`, `market mid`, `market book` — read-only
-- `arb rates`, `arb scan` — read-only
+- `arb scan` — read-only (`arb rates` is deprecated)
 - `portfolio`, `risk overview` — read-only
 - `bridge quote` — read-only
 - `bridge status` — read-only
@@ -242,6 +242,29 @@ Error case:
 
 **For non-idempotent commands:** always verify the result before retrying. Check positions or balances to confirm whether the first attempt succeeded.
 
+## Symbol Naming Across Exchanges
+
+Symbols are auto-resolved by the CLI. **Always use bare symbols** (e.g., `BTC`, `SOL`, `ICP`) — the CLI handles exchange-specific naming automatically:
+
+| Input | Hyperliquid | Pacifica | Lighter |
+|-------|-------------|----------|---------|
+| `ICP` | → `ICP-PERP` | → `ICP` | → `ICP` |
+| `BTC` | → `BTC` | → `BTC` | → `BTC` |
+| `SOL` | → `SOL` | → `SOL` | → `SOL` |
+
+- `arb scan` returns bare symbols — pass them directly to trade/leverage commands on any exchange.
+- Do NOT manually add `-PERP` suffix — the CLI resolves this automatically.
+
+## Exchange-Specific Constraints
+
+| Exchange | Min Order (notional) | Notes |
+|----------|---------------------|-------|
+| Hyperliquid | **$10** | Rejects orders below $10 notional |
+| Pacifica | ~$1 (varies by symbol) | Lower minimums |
+| Lighter | Varies by symbol | Check market info |
+
+**`trade check` is advisory only** — it returns `valid: true/false` but does NOT block execution. The exchange itself enforces minimums and will reject with an error if the order is too small.
+
 ## Common Agent Mistakes
 
 1. **Using `perp init`** — interactive, will hang forever. Use `wallet set` instead.
@@ -250,3 +273,5 @@ Error case:
 4. **Retrying a trade without checking** — leads to double positions. Always check `account positions` after a trade, even if it seemed to fail.
 5. **Bridging without quoting** — always run `bridge quote` first to show the user fees and estimated time.
 6. **Assuming deposit is instant** — after `bridge send`, wait for `bridge status` to confirm completion before depositing to the destination exchange.
+7. **Manually adding `-PERP` suffix** — the CLI auto-resolves symbols. Just use bare names like `ICP`, `SOL`, `BTC`.
+8. **Order below exchange minimum** — Hyperliquid requires $10+ notional. Compute `size × price` before submitting.

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

@@ -89,11 +89,11 @@ perp --json bridge status <ORDER_ID>
 
 ## Arbitrage
 ```bash
-perp --json arb rates                       # compare funding rates across exchanges
-perp --json arb scan --min <BPS>            # find opportunities (>N bps spread)
+perp --json arb scan --min <BPS>            # find opportunities (>N bps spread) — PRIMARY command
 perp --json arb funding                     # detailed funding analysis
 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
 ```
 
 ## Wallet Management

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

@@ -9,7 +9,7 @@ You are not expected to follow rigid rules — use this as a decision framework
 - Funding rates settle **every 1 hour** on all supported exchanges
 - Positive rate = longs pay shorts, negative rate = shorts pay longs
 - Rates are annualized in display but applied hourly: `hourly = annual / 8760`
-- Scan rates: `perp --json arb rates`
+- Scan opportunities: `perp --json arb scan --min 5` (shows spread, longExch, shortExch, netSpread)
 
 ### Opportunity Cost Awareness
 
@@ -56,10 +56,29 @@ During transition, you are **unhedged**. Price can move against you. Factor this
 
 ### Discovery Loop
 ```bash
-perp --json arb rates                    # compare rates across exchanges
-perp --json arb scan --min 10            # find spreads > 10 bps
+perp --json arb scan --min 5             # find spreads > 5 bps (shows longExch/shortExch/netSpread)
+# NOTE: 'arb rates' is deprecated — use 'arb scan' instead
 ```
 
+### CRITICAL: Reading arb scan Results
+
+The `arb scan` output tells you EXACTLY what to do:
+
+```
+longExch: "hyperliquid"   → open LONG on this exchange
+shortExch: "pacifica"     → open SHORT on this exchange
+netSpread: 12.87          → profit after fees (bps/hour)
+```
+
+**Rules:**
+1. **ALWAYS follow longExch/shortExch directions exactly.** DO NOT reverse them.
+2. **NEVER enter if netSpread ≤ 0.** Negative netSpread = loss after fees.
+3. The direction logic: go LONG where funding is negative (longs receive), go SHORT where funding is positive (shorts receive).
+
+**Why these directions?**
+- Positive funding (+) = longs pay shorts → you want to be SHORT to receive
+- Negative funding (-) = shorts pay longs → you want to be LONG to receive
+
 ### Decision Framework
 When evaluating an arb opportunity:
 
@@ -118,53 +137,102 @@ Actual hold: 6h | Actual net: ~130 bps
 perp --json portfolio                    # unified multi-exchange view
 perp --json risk overview                # cross-exchange risk assessment
 perp --json -e <EX> account positions    # per-exchange positions
-perp --json arb rates                    # are current rates still favorable?
+perp --json arb scan --min 5             # are current rates still favorable?
+```
+
+### Order Execution: Matched Size, Sequential Legs
+
+**The #1 rule of arb execution: BOTH LEGS MUST HAVE THE EXACT SAME SIZE.** A size mismatch means you have net directional exposure — the whole point of arb is to be delta-neutral.
+
+#### Step 1: Determine Matched Order Size
+
+Before placing ANY order, compute a single `ORDER_SIZE` that BOTH exchanges can fill:
+
+```bash
+# 1. Check orderbook depth on BOTH sides
+perp --json -e <LONG_EX> market book <SYM>     # check asks (you're buying)
+perp --json -e <SHORT_EX> market book <SYM>     # check bids (you're selling)
+
+# 2. Find immediately fillable size at best 2-3 ticks
+#    LONG side: sum ask sizes at best 2-3 ask levels → fillable_long
+#    SHORT side: sum bid sizes at best 2-3 bid levels → fillable_short
+
+# 3. ORDER_SIZE = min(fillable_long, fillable_short, desired_size)
+#    The SMALLER side limits your matched size.
+```
+
+**Example:**
+```
+LONG exchange asks:  $85.00 × 0.5, $85.01 × 0.3 → fillable = 0.8
+SHORT exchange bids: $85.10 × 0.4, $85.09 × 0.2 → fillable = 0.6
+Desired size: 1.0
+
+→ ORDER_SIZE = min(0.8, 0.6, 1.0) = 0.6
+→ Both legs get exactly 0.6
 ```
 
-### Order Execution: Sequential Leg Management
+**CRITICAL: Each exchange has its own minimum order size and step size.**
+```bash
+perp --json -e <EX> market info <SYM>    # check minOrderSize, stepSize
+```
+Round `ORDER_SIZE` to the coarser step size of the two exchanges. If the matched size falls below either exchange's minimum, the arb is NOT executable at this size — reduce target or skip.
+
+#### Step 2: Execute Legs Sequentially with Same Size
+
+Once you have a single `ORDER_SIZE`, execute both legs using THAT EXACT SIZE:
 
-**NEVER close or open both legs of an arb at once with market orders.** You must manage execution carefully.
+```bash
+# Leg 1: Open on exchange A
+perp --json -e <LONG_EX> trade market <SYM> buy <ORDER_SIZE>
+
+# Verify leg 1 filled
+perp --json -e <LONG_EX> account positions
 
-#### Why This Matters
-Orderbooks have limited depth at each price level. A large market order will eat through multiple ticks and suffer heavy slippage. Worse, if you close one leg but fail to close the other (exchange error, rate limit, network issue), you are left with naked directional exposure.
+# Leg 2: Open on exchange B with SAME size
+perp --json -e <SHORT_EX> trade market <SYM> sell <ORDER_SIZE>
 
-#### Pre-Execution: Check Orderbook Depth
-Before executing, verify that the orderbook can absorb your size at acceptable prices on BOTH sides:
+# Verify leg 2 filled
+perp --json -e <SHORT_EX> account positions
+```
+
+**After both legs, verify sizes match:**
 ```bash
-perp --json -e <EX_A> market book <SYM>    # check bids/asks depth
-perp --json -e <EX_B> market book <SYM>    # check bids/asks depth
-```
-
-Look at the size available at the best tick. If your order size exceeds what's available at the best 2-3 ticks, you MUST split the order.
-
-#### Execution Strategy
-1. **Determine executable chunk size** — the largest size both orderbooks can absorb at the best tick without excessive slippage
-2. **Execute in sequential chunks:**
-   ```
-   Chunk 1: close X on Exchange A → immediately open X on Exchange B
-   Chunk 2: close X on Exchange A → immediately open X on Exchange B
-   ... repeat until full size is executed
-   ```
-3. **Verify each chunk** before proceeding to the next:
-   ```bash
-   perp --json -e <EX_A> account positions    # confirm partial close
-   perp --json -e <EX_B> account positions    # confirm partial open
-   ```
-4. **Re-check the orderbook** between chunks — liquidity may have changed
-
-#### Paired Execution Rule
-Each chunk must be a **matched pair**: close on one side, open on the other. Never execute multiple closes without the corresponding opens. If one leg fails:
-- STOP immediately
-- Assess your current exposure
-- Decide whether to retry the failed leg or unwind the completed leg
-- Do NOT continue with remaining chunks
+perp --json -e <LONG_EX> account positions    # size = X
+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
+
+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**:
+
+```
+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
+```
+
+**Rules:**
+1. Re-check orderbook depth between chunks — liquidity changes
+2. Each chunk: same size on both sides, no exceptions
+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
 
 #### Using Limit Orders for Better Execution
-For non-urgent transitions, consider limit orders at the best bid/ask instead of market orders:
+For non-urgent entries, use limit orders at best bid/ask instead of market:
+```bash
+perp --json -e <EX> trade buy <SYM> <ORDER_SIZE> -p <PRICE>    # limit order
+```
+This avoids crossing the spread but risks not getting filled. Set a timeout and fall back to market if unfilled. **Both legs must still use the same `ORDER_SIZE`.**
+
+#### Closing Arb Positions: Same Rules Apply
+When exiting, close BOTH legs with the SAME size:
 ```bash
-perp --json -e <EX> trade sell <SYM> <SIZE> -p <PRICE>    # limit order
+perp --json -e <LONG_EX> trade close <SYM>     # closes full position
+perp --json -e <SHORT_EX> trade close <SYM>     # closes full position
 ```
-This avoids crossing the spread, but you risk not getting filled. Set a reasonable timeout and fall back to market if not filled.
+If positions already have mismatched sizes, close to the smaller size first, then close the remaining delta on the larger side.
 
 ### When to Exit
 - Spread compressed below your breakeven (including fees)
@@ -287,7 +355,7 @@ Check the output:
 #### Every hour (at funding settlement):
 ```bash
 perp --json portfolio                        # total equity across exchanges
-perp --json arb rates                        # are rates still favorable?
+perp --json arb scan --min 5                  # are rates still favorable?
 perp --json -e <EX_A> account positions      # P&L on leg A
 perp --json -e <EX_B> account positions      # P&L on leg B
 ```

package/skills/perp-cli/templates/arb-scan.sh

@@ -11,9 +11,5 @@ echo "=== Funding Rate Arbitrage Scanner ==="
 echo "Minimum spread: ${MIN_SPREAD} bps"
 echo ""
 
-echo "1. Cross-exchange rates:"
-perp --json arb rates
-
-echo ""
-echo "2. Opportunities (>= ${MIN_SPREAD} bps):"
+echo "1. Opportunities (>= ${MIN_SPREAD} bps):"
 perp --json arb scan --min "$MIN_SPREAD"