perp-cli 0.14.1 → 0.14.3

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/dist/trade-validator.d.ts

@@ -19,7 +19,7 @@ export interface TradeValidation {
         symbol: string;
         markPrice: number;
         fundingRate: number;
-        maxLeverage: number;
+        maxLeverage: number | null;
     };
     timestamp: string;
 }

package/dist/trade-validator.js

@@ -69,7 +69,12 @@ export async function validateTrade(adapter, params) {
     // reject an order sized past a threshold even though the flat value allows it,
     // so resolve the cap AT THIS ORDER'S NOTIONAL.
     const effectiveMax = maxLeverageForNotional(market, notional);
-    const leverage = params.leverage ?? effectiveMax;
+    // A venue that publishes no max leverage (Aster's public exchangeInfo): the margin estimate
+    // uses 1x — the most conservative requirement — and says so; the venue enforces its own cap.
+    if (effectiveMax === null && params.leverage === undefined) {
+        warnings.push(`Max leverage for ${sym} is not published by ${adapter.name} — margin estimated at 1x; pass --leverage for a tighter estimate`);
+    }
+    const leverage = params.leverage ?? effectiveMax ?? 1;
     if (!Number.isFinite(leverage) || leverage <= 0) {
         throw new Error(`No usable leverage for ${sym} (resolved=${leverage}); supply params.leverage explicitly.`);
     }
@@ -197,7 +202,7 @@ export async function validateTrade(adapter, params) {
     const fee = notional * DEFAULT_TAKER_FEE;
     const estimatedSlippage = params.type === "limit" ? 0 : notional * 0.001;
     const valid = checks.every(c => c.passed);
-    if (leverage > effectiveMax) {
+    if (effectiveMax !== null && market.maxLeverage !== null && leverage > effectiveMax) {
         // Compare against the tier that applies at this notional, not the headline
         // cap — otherwise the check is tautological whenever leverage defaulted FROM
         // maxLeverage, and it never fires for the tiered case it exists to catch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "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.1"
+  version: "0.14.3"
 ---
 
 # 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.1
+perp --version 2>/dev/null || npx -y perp-cli@latest --version   # must be >= 0.14.3
 ```
 
 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`.

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

@@ -37,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
 ```
 
@@ -255,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)
@@ -281,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
@@ -424,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