perp-cli 0.14.0 → 0.14.2

package/dist/strategies/funding-arb.js

@@ -4,7 +4,7 @@ import { symbolMatch, logSettledRejections } from "../utils.js";
 import { logExecution } from "../execution-log.js";
 import { updateJobState } from "../jobs.js";
 import { invalidateCache } from "../cache.js";
-import { fetchAllBalances, computeRebalancePlan, hasEnoughBalance, marketLeverageOf, requiredArbMargin } from "../rebalance.js";
+import { fetchBalancesWithFailures, computeRebalancePlan, hasEnoughBalance, marketLeverageOf, requiredArbMargin } from "../rebalance.js";
 import { checkArbLiquidity } from "../liquidity.js";
 import { computeAnnualSpread } from "../funding.js";
 import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates, } from "../shared-api.js";
@@ -15,6 +15,11 @@ import { isQuarantined, quarantineSymbol } from "../bot/quarantine.js";
 import { isPositionGone, matchSymbol } from "../bot/strategies/funding-arb-utils.js";
 /** Quarantine source for `perp strategy funding-arb` (src/bot/quarantine.ts). */
 const SOURCE = "funding-arb-cli";
+/** The market's published size decimals on `adapter` (null = not published / market not listed). */
+async function sizeDecimalsOf(adapter, symbol) {
+    const m = (await adapter.getMarkets()).find((x) => symbolMatch(x.symbol, symbol));
+    return m === undefined ? null : m.sizeDecimals;
+}
 async function fetchAllRates() {
     // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
     // alive when one DEX errors out, while rejection reasons get logged to
@@ -147,9 +152,17 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                 // ── Phase 2: Max drawdown check ──
                 if (params.maxDrawdown && params.autoExecute && positions.length > 0) {
                     try {
-                        const snapshots = await fetchAllBalances(adapters);
+                        const { snapshots, failed } = await fetchBalancesWithFailures(adapters);
                         const totalPnl = snapshots.reduce((s, e) => s + e.unrealizedPnl, 0);
-                        if (totalPnl < -params.maxDrawdown) {
+                        // Only a failed venue that holds one of the bot's legs makes the uPnL sum unknown; a venue
+                        // without credentials (notConfigured) cannot hold one.
+                        const legVenues = new Set(positions.flatMap(p => [p.longExchange, p.shortExchange]));
+                        const failedLegs = failed.filter(f => legVenues.has(f.exchange));
+                        if (failedLegs.length > 0) {
+                            // A partial uPnL sum is not the bot's drawdown: never close everything on it.
+                            log(`[ARB] Drawdown check skipped — balance unavailable on ${failedLegs.map(f => `${f.exchange} (${f.error})`).join(", ")}`);
+                        }
+                        else if (totalPnl < -params.maxDrawdown) {
                             log(`[ARB] MAX DRAWDOWN hit: uPnL $${totalPnl.toFixed(2)} < -$${params.maxDrawdown}`);
                             log(`[ARB] Closing all ${positions.length} positions...`);
                             const stillOpen = await closeAllPositions(positions, adapters, log);
@@ -166,7 +179,11 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                 const shouldCheckBalance = params.autoRebalance && (Date.now() - lastRebalanceCheck > 300_000); // every 5 min
                 if (shouldCheckBalance || (params.autoExecute && positions.length < maxPos)) {
                     try {
-                        balanceSnapshots = await fetchAllBalances(adapters);
+                        const read = await fetchBalancesWithFailures(adapters);
+                        balanceSnapshots = read.snapshots;
+                        // A venue missing from the snapshots has no balance for entry checks (no entry there).
+                        for (const f of read.failed)
+                            log(`[ARB] ${f.exchange} balance unavailable — no entries / rebalance on it this cycle: ${f.error}`);
                         lastRebalanceCheck = Date.now();
                         if (params.autoRebalance) {
                             const threshold = params.rebalanceThreshold ?? 100;
@@ -229,8 +246,22 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                 const liq = await checkArbLiquidity(longAdapter, shortAdapter, symbol, requestedUsd, 0.5, log);
                                 if (!liq.viable)
                                     continue;
-                                // Compute matched size (same for both legs)
-                                let matched = computeMatchedSize(liq.adjustedSizeUsd, highest.markPrice, longEx, shortEx);
+                                // Compute matched size (same for both legs) at each venue's published size precision —
+                                // the per-venue defaults (HL 2 decimals) would reject small BTC legs or over-round.
+                                let longDec;
+                                let shortDec;
+                                try {
+                                    [longDec, shortDec] = await Promise.all([sizeDecimalsOf(longAdapter, symbol), sizeDecimalsOf(shortAdapter, symbol)]);
+                                }
+                                catch (e) {
+                                    log(`[ARB] Skip ${symbol}: could not read the market size precision (${e instanceof Error ? e.message : String(e)})`);
+                                    continue;
+                                }
+                                if (longDec === null || shortDec === null) {
+                                    log(`[ARB] Skip ${symbol}: size precision not published on ${longDec === null ? longEx : shortEx}`);
+                                    continue;
+                                }
+                                let matched = computeMatchedSize(liq.adjustedSizeUsd, highest.markPrice, longEx, shortEx, { longSizeDecimals: longDec, shortSizeDecimals: shortDec });
                                 if (!matched) {
                                     log(`[ARB] Skip ${symbol}: can't compute matched size (min notional or precision issue)`);
                                     continue;
@@ -266,7 +297,7 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                     // The LONG was definitely rejected for lot size (nothing placed): recompute once.
                                     const lotSize = res.lotSize;
                                     log(`[ARB] Lot size ${lotSize} on ${longEx} — recalculating (nothing was placed)`);
-                                    matched = computeMatchedSize(liq.adjustedSizeUsd, highest.markPrice, longEx, shortEx, { lotSize });
+                                    matched = computeMatchedSize(liq.adjustedSizeUsd, highest.markPrice, longEx, shortEx, { lotSize, longSizeDecimals: longDec, shortSizeDecimals: shortDec });
                                     if (!matched) {
                                         log(`[ARB] Skip ${symbol}: can't meet lot size ${lotSize}`);
                                         continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus",
   "bin": {
     "perp": "dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: "Bash(perp:*), Bash(npx -y perp-cli:*), Bash(bash scripts/preflig
 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 a wallet key imported into the OWS vault via 'perp wallet set EXCHANGE' (key on stdin or hidden prompt — never argv). Skill is portable across Claude Code, Claude.ai, Cursor, Codex, and Gemini CLI — no platform-specific features."
 metadata:
   author: hypurrquant
-  version: "0.14.0"
+  version: "0.14.2"
 ---
 
 # perp-cli
@@ -46,7 +46,7 @@ Also bundled under `scripts/`: `preflight.sh`, `arb-monitor.sh`, `funding-analys
 ### Step 1: Verify install + version
 
 ```bash
-perp --version 2>/dev/null || npx -y perp-cli@latest --version   # must be >= 0.14.0
+perp --version 2>/dev/null || npx -y perp-cli@latest --version   # must be >= 0.14.2
 ```
 
 If it is missing or older, ask the user before installing/upgrading (`npm install -g perp-cli@latest`) — never install on your own. If `perp` is not on PATH, prefix every command with `npx -y perp-cli@latest`.
@@ -94,7 +94,7 @@ Imported keys trade; `funds deposit|withdraw|transfer|bridge`, `wallet manage re
 - Limit GTC / ALO returns `status: accepted, finality: pending` after the ACK; `open` only via `perp --json trade status c:<id> --symbol <S> -e qfex`.
 - `ORDER_PENDING` = outcome unknown: NEVER resubmit; check with the `c:<id>` in the remediation.
 - Funding rates on QFEX are unverified: excluded everywhere unless `perp --json arb scan --rates --include-unverified` (display only).
-- Withdrawals need `settings.withdraw.qfex` (allowlist + limits), which only the user can set in an interactive terminal — an agent cannot set or change it. `perp --json --dry-run funds withdraw qfex <amt> --to <addr>` shows the gate verdict.
+- Withdrawals are disabled in perp-cli for now: `funds withdraw qfex` → `CAPABILITY_UNSUPPORTED` (also under `--dry-run`). Withdraw in the QFEX web app. Ondo Perps has no API withdrawals either.
 
 Venue rules for these: `trade limit` defaults to `--tif GTC` on every venue (arcus maps it to GTT; ondo offers GTC|IOC|ALO; FOK is never emulated → `CAPABILITY_UNSUPPORTED` where not offered); market orders on every venue are bounded by `--slippage-bps <n>` → `settings.slippageBps.<venue>` → `settings.defaultSlippageBps` (shipped default 50). Ondo (US, PA) and Arcus (US, CA, GB) print a one-time restricted-region notice on stderr when used with credentials (warn only, never blocks).
 
@@ -116,6 +116,23 @@ perp --json arb scan --live --interval 60         # continuous monitoring
 
 Common knobs: `--min <pct>`, `--top <n>`, `--hold-days <n>`, `--bridge-cost <usd>`, `--size <usd>`.
 
+#### HIP-3 dexes (part of Hyperliquid, not a separate venue)
+
+HIP-3 dexes are selected on the Hyperliquid venue with the root `--dex <name>` flag; every market / account / trade command works the same way. Same account and wallet as native Hyperliquid perps.
+
+```bash
+perp --json -e hyperliquid market hip3                               # list deployed dexes (name, markets)
+perp --json -e hyperliquid --dex xyz market list                     # markets on dex "xyz"
+perp --json -e hyperliquid --dex xyz market info GOLD                # symbols WITHOUT the "xyz:" prefix
+perp --json -e hyperliquid --dex xyz account positions               # positions on that dex only
+perp --json -e hyperliquid --dex xyz --dry-run trade market GOLD buy 0.01
+```
+
+- `--dex` with any other `-e` venue → `INVALID_PARAMS` (never ignored).
+- A dex symbol without `--dex` (e.g. `-e hyperliquid market mid xyz:GOLD`) → `SYMBOL_NOT_FOUND` with remediation `--dex xyz`; it is never read from the native dex.
+- `portfolio --dexes xyz,…` adds HIP-3 dex balances; builder fees are never attached on HIP-3.
+- MCP tools cover native Hyperliquid perps only — use the CLI for HIP-3.
+
 ### Step 4: Validate before mutating
 
 For arb:

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

@@ -42,7 +42,7 @@ perp --json wallet generate evm             # generate EVM wallet
 perp --json wallet generate solana          # generate Solana wallet
 perp --json wallet show                     # check configured wallets
 perp --json wallet list                     # list named wallets
-perp --json wallet balance                  # on-chain USDC balances
+perp --json wallet balance   # gas token + USDC/USDT per chain (Arbitrum, Ethereum, Base, BNB, Robinhood USDG, Solana); failed reads → balance null + error
 perp --json portfolio -e <EX>               # per-exchange balance + positions (account balance was renamed in v0.12)
 perp --json -e <EX> account positions       # open positions
 perp --json -e <EX> market list             # available markets
@@ -148,7 +148,7 @@ Default `-e` = `settings.defaultExchange`, else `pacifica` — always pass `-e`.
 
 ### Check On-Chain vs Exchange Balance
 ```bash
-perp --json wallet balance               # on-chain USDC in your wallet
+perp --json wallet balance   # gas token + USDC/USDT per chain (Arbitrum, Ethereum, Base, BNB, Robinhood USDG, Solana); failed reads → balance null + error
 perp --json portfolio -e hyperliquid     # USDC deposited on exchange
 ```
 

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

@@ -19,12 +19,14 @@ perp --json -e <EX> market book <SYMBOL>       # orderbook (bids/asks)
 perp --json -e <EX> market trades <SYMBOL>     # recent trades
 perp --json -e <EX> market funding <SYMBOL>    # funding rate history
 perp --json -e <EX> market kline <SYM> <INT>   # OHLCV candles (1m,5m,15m,1h,4h,1d)
-perp --json market hip3                        # list HIP-3 deployed perp dexes (Hyperliquid)
+perp --json -e hyperliquid market hip3         # list HIP-3 deployed perp dexes (needs -e hyperliquid; other -e → INVALID_PARAMS)
+perp --json -e hyperliquid --dex <DEX> market list           # one HIP-3 dex's markets (e.g. --dex xyz)
+perp --json -e hyperliquid --dex <DEX> market book <SYMBOL>  # any market/account/trade command takes --dex the same way
 ```
 
 ## Account (read-only, safe)
 ```bash
-perp --json portfolio -e <VENUE_ID>            # perp balance + spot holdings + 24h funding; full venue id only (hl → INVALID_PARAMS)
+perp --json portfolio -e <VENUE_ID>            # perp balance + spot holdings + 24h funding; venue id or alias (hl, lt, …)
 perp --json -e <EX> account positions          # open positions
 perp --json -e <EX> account orders             # open/pending orders
 perp --json -e <EX> account history            # order history
@@ -35,6 +37,7 @@ perp --json -e <EX> account margin <SYMBOL>    # position margin info
 perp --json -e <EX> account pnl                # realized + unrealized + funding
 perp --json -e <EX> account twap-orders        # active TWAP orders
 perp --json portfolio                          # cross-exchange unified view
+# funding24h is null (with fundingError) when a venue's funding history is unreadable; totals.fundingIncomplete = true then
 perp --json portfolio --arb                    # full dashboard with arb top 5
 ```
 
@@ -195,15 +198,14 @@ perp --json funds withdraw hyperliquid <AMOUNT> [--chain arbitrum|ethereum|base]
 #   --to another address only if it is on settings withdraw.hyperliquid (else POLICY_DENIED).
 perp --json funds withdraw lighter <AMOUNT>                 # -e lighter: USDC → Ethereum; -e lighter-rh: USDG → Robinhood Chain
 perp --json funds deposit lighter-rh <AMOUNT>               # USDG on Robinhood Chain (min 1, mainnet only)
-perp --json funds withdraw ondo <AMOUNT> --to <ADDRESS>     # USDC → Ethereum (address-book destination)
+# Ondo Perps: NO API withdrawals — `funds withdraw ondo` → CAPABILITY_UNSUPPORTED; withdraw in the Ondo web app
 perp --json funds withdraw arcus <AMOUNT>                   # USDG → the account owner (min 1)
 perp --json funds deposit qfex                              # prints the USDC / Arbitrum One deposit address (sends nothing)
-perp --json --dry-run funds withdraw qfex <AMOUNT> --to <0x>  # plan + local gate verdict (settings withdraw.qfex; user-only, terminal)
+# QFEX: withdrawals disabled in perp-cli for now — `funds withdraw qfex` → CAPABILITY_UNSUPPORTED; withdraw in the QFEX web app
 perp --json -e qfex funds transfer <AMOUNT> primary --from <account-uuid>   # between your QFEX accounts
 perp --json funds deposit aster <AMOUNT> [--chain bsc|arbitrum] [--asset USDT|USDC]   # vault approve + deposit (mainnet; default BNB Chain USDT)
 perp --json funds withdraw aster <AMOUNT> [--chain bsc|arbitrum] [--asset USDT|USDC]   # → the account's own address (default USDT; mainnet; agent approved with --can-withdraw --ip-whitelist)
 perp --json funds deposit ondo <AMOUNT> [--chain arbitrum|ethereum] [--probe <AMT>]   # USDC transfer to the account's funding address (mainnet)
-perp --json funds address-book add ondo <MASTER_ADDRESS>    # SIWE challenge → Ondo withdrawal address book (own address only)
 perp --json funds transfer <AMOUNT> <ADDRESS>               # HL internal transfer (instant); destination must be on settings withdraw.hyperliquid
 # settings withdraw.<venue> (allowlist + limits) is set ONLY by the user in an interactive terminal
 # (--json / piped → POLICY_DENIED). Agents never set or change it.
@@ -254,7 +256,7 @@ perp --json arb scan --gaps                                 # cross-exchange pri
 perp --json arb scan --hip3                                 # HIP-3 cross-dex spreads
 perp --json arb scan --history [SYMBOL]                     # historical funding
 perp --json arb scan --compare <SYMBOL>                     # compare a symbol across exchanges
-perp --json arb scan --positions                            # position funding impact
+perp --json arb scan --positions                            # position funding impact; actual24h null + fundingHistoryErrors when a venue's history is unreadable
 perp --json arb scan --live --interval 60                   # continuous monitoring
 perp --json arb scan --top 10 --hold-days 7 --bridge-cost 0 --size 100  # cost-aware filtering
 perp --json arb scan --rates --include-unverified           # also show QFEX (unverified funding; display only, never ranked)
@@ -280,6 +282,7 @@ perp --json arb close <SYM> --state-only --yes              # drop a stale state
 
 # Status / history / config / rebalance
 perp --json arb status                                      # open arb positions + PnL + funding; check unconfirmedPairs, staleStateEntries
+# spot-perp entries: fundingSource actual | partial | estimate | recorded (+ fundingError) — only "actual" is complete settled funding
 perp --json arb status --period 7 --symbol BTC              # filter funding lookback / symbol
 perp --json arb history                                     # alias: arb log
 perp --json arb history --period 30                         # past arb trade performance
@@ -307,7 +310,7 @@ perp --json wallet list                        # all named wallets
 perp --json wallet use <name>                  # set active wallet
 perp --json wallet rename <old> <new>
 perp --json wallet remove <name>
-perp --json wallet balance                     # on-chain USDC balances
+perp --json wallet balance   # gas token + USDC/USDT per chain (Arbitrum, Ethereum, Base, BNB, Robinhood USDG, Solana); failed reads → balance null + error
 perp --json wallet solana <address>            # check arbitrary Solana address
 perp --json wallet arbitrum <address>          # check arbitrary Arbitrum address
 perp --json wallet migrate                     # migrate legacy ~/.perp/.env config
@@ -423,9 +426,9 @@ perp --json history list                       # execution audit trail
 perp --json history positions                  # position lifetime tracking
 perp --json history prune                      # purge old entries
 perp --json history summary                    # trading performance summary (replaces former 'stats')
-perp --json history pnl                        # P&L breakdown by exchange
+perp --json history pnl                        # P&L breakdown by exchange; errors + partial name venues whose reads failed (left out, not 0)
 perp --json history funding                    # funding payment aggregation
-perp --json history report                     # full performance report (summary + pnl + funding)
+perp --json history report                     # full performance report (summary + pnl + funding); errors + partial + venuesRead
 perp --json history compare                    # compare strategies / accounts
 perp --json history snapshot                   # equity snapshot
 perp --json history track                      # PnL tracking helper