perp-cli 0.15.0 → 0.16.0

package/README.zh.md

@@ -0,0 +1,243 @@
+[English](README.md) | [한국어](README.ko.md) | **中文** | [日本語](README.ja.md)
+
+> 以英文版 [README](README.md) 为准；本译文可能滞后于英文版。
+
+# perp-cli
+
+[![npm version](https://img.shields.io/npm/v/perp-cli.svg)](https://www.npmjs.com/package/perp-cli)
+[![npm downloads](https://img.shields.io/npm/dw/perp-cli.svg)](https://www.npmjs.com/package/perp-cli)
+[![license](https://img.shields.io/npm/l/perp-cli.svg)](https://github.com/hypurrquant/perp-cli/blob/main/LICENSE)
+
+一个 CLI 搞定多个 DEX 的永续合约 — 在终端中交易、比较资金费率、调拨资金和运行机器人，或交给 AI agent 使用（JSON 输出、MCP 服务器、agent 技能）。
+
+- **8 个可交易场所：** Hyperliquid（含 HIP-3 dex）、Pacifica、Lighter、Lighter RH、Aster、Ondo Perps、Arcus、QFEX（跨链桥和永续-永续套利覆盖最初的四个：Pacifica、Hyperliquid、Lighter、Aster）
+- **仅市场数据：** RISEx、GRVT、Extended、Variational、TxFlow（非官方 API）— 另有 Derive 期权数据
+
+## 安装
+
+```bash
+npm install -g perp-cli
+perp --version
+
+# Or without a global install
+npx -y perp-cli --json portfolio
+```
+
+本软件包附带三个可执行文件：`perp`（CLI 本体）、`perp-mcp`（[MCP 服务器](docs/mcp.md)，stdio）和 `perp-guardrail`（[签名护栏](docs/guardrail.md)）。
+
+## 快速开始
+
+**1. 先看看 — 无需密钥。**
+
+```bash
+perp -e hl market list                  # markets, prices, funding
+perp -e hl market book BTC              # order book
+perp arb scan --rates                   # funding rates across venues
+```
+
+**2. 添加钱包。** 设置向导会创建或导入一个加密的 [OWS](https://github.com/open-wallet-standard) vault 钱包，选择交易场所并注册 agent 密钥（每次签名前都会先询问，且绝不会移动资金）：
+
+```bash
+perp setup
+perp wallet show
+```
+
+密钥从隐藏输入提示或 stdin 读取 — 绝不从 argv 或 `~/.perp/.env` 读取。一个 EVM 密钥即可覆盖 Hyperliquid、Lighter 和 Aster。其他方式（单行导入密钥、可脚本化的设置、在交易所网站上创建的密钥）请参见 [docs/setup.md](docs/setup.md)。
+
+**3. 查看账户并交易。** 在任意命令后加上 `-n testnet` 即可使用测试网。
+
+```bash
+perp --json portfolio                                 # balances + positions + risk on every venue
+perp --json --dry-run -e hl trade market BTC buy 0.001   # validate only, nothing is sent
+perp --json -e hl trade market BTC buy 0.001          # market order (bounded by the slippage setting)
+perp --json -e hl trade close BTC
+```
+
+## AI Agent Skill
+
+适用于 Claude Code、Cursor、Codex、Gemini CLI 及其他 agent CLI 的即插即用技能（skill）。内含非交互式命令指南、运维手册、策略框架以及可复用的 shell 脚本（预检、套利监控、校验），让你的 agent 在正确的确认节点停下，并且永远不会卡在交互式向导上。
+
+### 安装
+
+```bash
+# Claude Code — slash command
+/install-skill hypurrquant/perp-cli
+
+# Cursor / Codex / generic agent CLIs — via npx
+npx skills add hypurrquant/perp-cli
+
+# Manual install (any agent that reads a Skills directory)
+git clone https://github.com/hypurrquant/perp-cli.git
+cp -R perp-cli/skills/perp-cli ~/.claude/skills/        # or your CLI's skills dir
+```
+
+该技能随 npm 包一同发布（`perp-cli/skills/perp-cli`），因此全局安装后也可在本地使用：
+
+```bash
+npm install -g perp-cli@latest
+ls "$(npm root -g)/perp-cli/skills/perp-cli"
+```
+
+### 技能包含的内容
+
+| 文件 | 用途 |
+|------|---------|
+| `SKILL.md` | 顶层 agent 指南 — 规则、工作流、示例 |
+| `references/commands.md` | 完整的非交互式命令参考（涵盖所有命令组） |
+| `references/agent-operations.md` | 设置流程、幂等性、错误处理、常见错误 |
+| `references/strategies.md` | 资金费率套利决策框架 + 风险管理 |
+| `scripts/preflight.sh` | 安装 + 钱包 + 连通性 + 风险就绪检查 |
+| `scripts/arb-monitor.sh` | 实时监控未平仓的套利持仓 |
+| `scripts/spot-perp-scan.sh` | 结合余额信息扫描现货+永续机会 |
+| `scripts/funding-analysis.sh` | 跨交易所资金费率概览 / 单交易对深入分析 |
+| `scripts/validate-arb.sh` | 执行前校验（价格 / 余额 / 风险 / dry-run） |
+
+完整的 agent 指南请参见 [`skills/perp-cli/SKILL.md`](skills/perp-cli/SKILL.md)。
+
+## 功能特性
+
+- **资金费率套利** — 永续-永续和现货-永续扫描，一条命令完成双腿开仓与平仓
+- **投资组合** — 一次调用即可返回所有交易场所的余额、持仓和风险
+- **资金** — 充值、提现、划转、多提供商跨链桥（CCTP / Relay / deBridge）、交易所间再平衡
+- **机器人** — TWAP、网格、DCA、追踪止损等，支持后台任务管理
+- **Agent 优先设计** — `--json`、`--fields`、`--ndjson`、`--dry-run`、运行时 schema 自省
+- **安全** — 交易前校验、每笔市价单都有滑点上限、client-id 去重、响应净化
+
+## 交易场所
+
+| 交易场所 | `-e` | 交易 | 链 / 抵押品 |
+|---|---|---|---|
+| Hyperliquid | `hyperliquid` (`hl`) | ✅ | HyperEVM，USDC；HIP-3 dex 通过 `--dex` |
+| Pacifica | `pacifica` (`pac`) | ✅ | Solana，USDC |
+| Lighter | `lighter` (`lt`) | ✅ | Ethereum L2，USDC |
+| Lighter RH | `lighter-rh` (`lrh`) | ✅ | Robinhood chain，USDG |
+| Aster | `aster` (`ast`) | ✅ | BNB Chain，USDT / USDC |
+| Ondo Perps | `ondo` | ✅ | 链下，USDC |
+| Arcus | `arcus` | ✅（访问白名单） | Robinhood chain，USDG |
+| QFEX | `qfex` (`qf`) | ✅（仅限手动交易） | 托管；股票、指数、大宗商品 |
+| RISEx | `risex` | 只读 | RISE chain，USDC |
+| GRVT | `grvt` | 仅市场数据 | USDT |
+| Extended | `extended` (`ext`) | 仅市场数据 | Starknet；加密货币 + 股票 / 外汇 |
+| Variational | `variational` (`var`) | 仅市场数据 | RFQ 交易场所 |
+| TxFlow | `txflow` (`txf`) | 仅市场数据 | **非官方** API |
+| Derive | `derive` | 仅期权数据 | — |
+
+- **[支持矩阵及各交易场所说明](docs/venues.md)** — 资金费率、WebSocket、充值 / 提现、按地址查询、限制地区
+- **[主网验证](docs/verification.md)** — 哪些功能已用真实资金运行过
+- **[交易细节](docs/trading.md)** — 订单有效期（TIF）、止盈/止损、止损单、滑点、现货交易、构建者费用
+
+## 常用命令
+
+```bash
+# Market data
+perp --json -e <EX> market list | book <SYM> | funding <SYM> | kline <SYM> 1h
+
+# Trading
+perp --json -e <EX> trade buy <SYM> <SIZE> --tp <PX> --sl <PX>    # entry protected by TP/SL
+perp --json -e <EX> trade limit <SYM> buy <PX> <SIZE>
+perp --json -e <EX> trade close <SYM>                              # or: flatten (every position)
+
+# Account
+perp --json portfolio
+perp --json -e <EX> account positions
+perp --json account balance --address <ADDR>                       # any account, keyless
+
+# Funding arb
+perp --json arb scan --min 5
+perp --json arb exec <SYM> <longEx> <shortEx> <USD>
+
+# Funds
+perp --json funds deposit hyperliquid 100
+perp --json funds bridge send --from solana --to arbitrum --amount 100
+```
+
+包含所有命令组的完整列表：**[docs/commands.md](docs/commands.md)**。全局参数：`--json`、`--fields <f>`、`--ndjson`、`--dry-run`、`-n testnet`、`-e <venue>`、`--dex <name>`（HIP-3）、`-w, --wallet <name>`。
+
+## 命令分组
+
+| 命令组 | 说明 |
+|-------|-------------|
+| `market` | 价格、订单簿、资金费率、K 线、HIP-3 dex |
+| `account` | 余额、持仓、订单、保证金 |
+| `trade` | 市价 / 限价 / 止损单、平仓、分批、拆单执行 |
+| `outcome` | Hyperliquid Outcome（HIP-4）— 二元 / 区间合约，按 outcome 计价（outcomeMeta `quoteToken`，目前为 USDC），无杠杆 |
+| `options` | 期权市场数据，只读（Derive：`-e derive options underlyings / expiries / chain / quote`） |
+| `print` | Pacifica Print — 每个周期赚取权利金的行权价订单：games、quote、positions、history、events、deposit / cancel（`--dry-run`） |
+| `vault` | Pacifica vaults（API 中称 lakes）— list、info、positions、deposit（仅限主钱包）/ withdraw（`--dry-run`） |
+| `arb` | 资金费率套利 — 扫描、执行、平仓、监控（永续-永续 & 现货-永续） |
+| `strategy` | 19 种机器人算法（grid、dca、twap、APEX、REFLECT、预设）+ 嵌套的脚本化计划 |
+| `funds` | 充值、提现、划转、跨链桥（多提供商）、交易所间再平衡 |
+| `risk` | 风险限额、强平距离、护栏 |
+| `wallet` | 多钱包管理、agent 钱包（`wallet agent ...`）、构建者费用（`wallet builder ...`，默认关闭）、保证金模式 / 子账户 / API 密钥（`wallet manage ...`）、链上余额 |
+| `history` | 执行日志、盈亏、绩效拆解 |
+| `portfolio` | 跨交易所统一概览（取代原来的 `account balance` / `status` / `dashboard`；`account balance --address` 可无需密钥读取任意账户的余额） |
+| `health` | 适配器健康检查：ping 每个交易场所的 REST 端点（连通性 + 延迟） |
+| `settings` | CLI 设置（推荐码、默认值、手续费、构建者费用、deBridge affiliate） |
+| `backtest` | 策略回测 |
+| `background` | 后台进程管理器（用于策略、告警等的 tmux 会话） |
+| `alerts` | 资金费率告警（Telegram / Discord），支持后台守护进程 |
+| `setup` | 设置向导：OWS 钱包、交易场所、agent 钱包、滑点、默认交易场所（别名：`init`；脚本中使用 `--non-interactive`） |
+
+## Agent 优先的 CLI 设计
+
+遵循 [agent-first CLI principles](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/) 构建：
+
+```bash
+# Every command returns structured JSON envelope
+perp --json portfolio
+# → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } }
+
+# Filter output to specific fields (saves tokens)
+perp --json --fields totalEquity,risk portfolio
+
+# Stream large lists as NDJSON (one JSON per line)
+perp --json --ndjson -e hl market list
+
+# Pre-validate before executing
+perp --json -e hl trade check BTC buy 0.01
+perp --json --dry-run -e hl trade market BTC buy 0.01
+
+# Idempotent orders with client ID (Hyperliquid: a 128-bit cloid, 0x + 32 hex; --auto-id generates one)
+perp --json -e hl trade market BTC buy 0.01 --client-id 0x1234567890abcdef1234567890abcdef
+perp --json -e hl trade status c:0x1234567890abcdef1234567890abcdef
+```
+
+所有响应都会自动净化（去除控制字符，拦截提示词注入模式）。
+错误中包含 `retryable` 标志 — 仅当其为 `true` 时才重试。
+
+## MCP 服务器
+
+[![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)
+
+`perp-mcp` 为 Claude Desktop、Cursor 及其他 MCP 客户端提供 31 个工具。查询市场数据无需密钥；如需账户和交易工具，请先运行 `perp setup`（服务器读取的是同一个钱包）。切勿在 MCP 配置中放入私钥。
+
+```json
+{
+  "mcpServers": {
+    "perp-cli": {
+      "command": "npx",
+      "args": ["-y", "-p", "perp-cli", "perp-mcp"]
+    }
+  }
+}
+```
+
+测试网、完整工具列表、资源和提示词：**[docs/mcp.md](docs/mcp.md)**。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [设置](docs/setup.md) | 钱包、agent 密钥、在交易所网站上创建的密钥、机密信息的存放位置 |
+| [交易场所](docs/venues.md) | 支持矩阵、交易场所 id、QFEX / RISEx / GRVT / Extended / Variational / TxFlow / Derive 详情 |
+| [交易](docs/trading.md) | 订单有效期（TIF）、止盈/止损、止损单、改单、滑点、现货交易、构建者费用 |
+| [命令](docs/commands.md) | 所有命令组及示例、Telegram 告警 |
+| [主网验证](docs/verification.md) | 各交易场所哪些功能已用真实资金运行过 |
+| [MCP 服务器](docs/mcp.md) | 配置、测试网、工具、资源、提示词 |
+| [签名护栏](docs/guardrail.md) | `perp-guardrail`，用于 agent 密钥的 OWS 策略可执行文件 |
+| [测试](docs/TESTING.md) | 测试套件和交易场所检查清单 |
+| [CHANGELOG](CHANGELOG.md) | 版本发布说明 |
+
+## 许可证
+
+MIT

package/dist/api/public/lighter.d.ts

@@ -17,6 +17,11 @@ export interface LighterFundingEntry {
 }
 export declare function fetchLighterOrderBookDetails(): Promise<LighterMarketDetail[]>;
 export declare function fetchLighterOrderBookDetailsRaw(): Promise<unknown>;
+/**
+ * GET /api/v1/funding-rates (Lighter's own rows): the PREDICTED rate × 8 — a fraction per 8 h, NOT
+ * the venue basis (per 1 h, the settled rate of the market rows). Not read by perp-cli's funding
+ * comparisons (they use fetchVenuesRates); kept for API compatibility. Normalize with 8 h.
+ */
 export declare function fetchLighterFundingRates(): Promise<LighterFundingEntry[]>;
 export declare function fetchLighterFundingRatesRaw(): Promise<unknown>;
 export declare function parseLighterRaw(detailsRaw: unknown, fundingRaw: unknown): {

package/dist/api/public/lighter.js

@@ -37,6 +37,11 @@ export function fetchLighterOrderBookDetailsRaw() {
         return res.json();
     });
 }
+/**
+ * GET /api/v1/funding-rates (Lighter's own rows): the PREDICTED rate × 8 — a fraction per 8 h, NOT
+ * the venue basis (per 1 h, the settled rate of the market rows). Not read by perp-cli's funding
+ * comparisons (they use fetchVenuesRates); kept for API compatibility. Normalize with 8 h.
+ */
 export function fetchLighterFundingRates() {
     // SSOT rule #2: error must propagate.
     // Row-level: rate is required (it's the field the endpoint exists for); a

package/dist/api/public/pacifica.js

@@ -82,7 +82,7 @@ export function fetchPacificaPrices() {
         const out = [];
         for (const p of data) {
             const symbol = String(p.symbol ?? "");
-            const fundingRaw = p.next_funding ?? p.funding;
+            const fundingRaw = p.funding; // last settled hourly rate (the market row / WS `funding`), not next_funding
             const funding = Number(fundingRaw);
             const mark = Number(p.mark);
             if (!symbol || fundingRaw === undefined || !Number.isFinite(funding) || !Number.isFinite(mark) || mark <= 0) {
@@ -113,7 +113,7 @@ export function parsePacificaRaw(raw) {
         if (!sym)
             continue;
         // SSOT rule #2: skip rows missing real funding/mark; never publish 0.
-        const fundingRaw = p.next_funding ?? p.funding;
+        const fundingRaw = p.funding; // last settled hourly rate (the market row / WS `funding`), not next_funding
         const fundingNumber = Number(fundingRaw);
         if (fundingRaw !== undefined && Number.isFinite(fundingNumber)) {
             rates.set(sym, fundingNumber);

package/dist/arb/sizing.js

@@ -5,7 +5,8 @@
  * @returns size string that works for both exchanges, or null if not viable
  */
 export function computeMatchedSize(sizeUsd, price, longExchange, shortExchange, opts) {
-    if (price <= 0)
+    // NaN / Infinity (e.g. a "-" mark parsed as a number) would size to "NaN": no size.
+    if (!Number.isFinite(price) || price <= 0 || !Number.isFinite(sizeUsd))
         return null;
     const rawSize = sizeUsd / price;
     // Use explicitly provided decimals if available, else conservative defaults
@@ -105,7 +106,8 @@ function getMinNotional(exchange) {
  * Uses spot exchange's size decimals for the spot leg.
  */
 export function computeSpotPerpMatchedSize(sizeUsd, price, spotExchange, perpExchange, spotSizeDecimals, perpSizeDecimals) {
-    if (price <= 0)
+    // NaN / Infinity (e.g. a "-" mark parsed as a number) would size to "NaN": no size.
+    if (!Number.isFinite(price) || price <= 0 || !Number.isFinite(sizeUsd))
         return null;
     // If explicit decimals provided, use them; otherwise derive from exchange
     const spotDec = spotSizeDecimals ?? getSizeDecimals(`spot:${spotExchange}`);

package/dist/arb/state.d.ts

@@ -23,6 +23,12 @@ export interface ArbPositionState {
     spotExchange?: string;
     /** Spot symbol, e.g. "ETH/USDC" (for spot-perp mode) */
     spotSymbol?: string;
+    /**
+     * The legs' VENUE symbols when they differ from `symbol` (the canonical key): Hyperliquid
+     * kPEPE ↔ Lighter 1000PEPE. Absent = both legs trade as `symbol`.
+     */
+    longSymbol?: string;
+    shortSymbol?: string;
 }
 export interface ArbDaemonState {
     version: 1;

package/dist/balance-by-address.d.ts

@@ -0,0 +1,39 @@
+import { type Network, type PublicBalanceResult } from "./exchanges/venue.js";
+/**
+ * The JSON shape of one venue's answer: `balance` and `spot` always (null = not published / per
+ * account), the venue-specific keys only on their venue (Lighter `accounts`, Hyperliquid `dexes` +
+ * `accountMode`).
+ */
+export type BalanceData = Pick<PublicBalanceResult, "balance" | "spot"> & Partial<{
+    accounts: NonNullable<PublicBalanceResult["accounts"]>;
+    dexes: NonNullable<PublicBalanceResult["dexes"]>;
+    accountMode: string;
+}>;
+export interface AddressBalance {
+    venue: string;
+    data: BalanceData;
+    /** Sub-reads that failed (Hyperliquid HIP-3 dex), keyed "hip3:<dex>". */
+    errors: Record<string, {
+        code: string;
+        message: string;
+    }>;
+    notes: string[];
+    /** One human line per failed sub-read: its balance is unknown, not zero. */
+    warnings: string[];
+}
+export interface AddressBalanceOptions {
+    accountIndex?: number;
+}
+export declare function readBalanceByAddress(venue: string, net: Network, address: string, opts?: AddressBalanceOptions): Promise<AddressBalance>;
+export interface AddressBalanceFanOut {
+    venues: Record<string, BalanceData>;
+    /** A venue that failed (`<venue>`) or a failed sub-read of a venue (`<venue>:hip3:<dex>`). */
+    errors: Record<string, {
+        code: string;
+        message: string;
+    }>;
+    notes: Record<string, string[]>;
+    warnings: string[];
+}
+/** Every venue that reads balances by address; a venue that fails (address format included) is an `errors` entry. */
+export declare function readBalanceByAddressAll(net: Network, address: string, opts?: AddressBalanceOptions): Promise<AddressBalanceFanOut>;

package/dist/balance-by-address.js

@@ -0,0 +1,44 @@
+/**
+ * `perp account balance --address` and MCP get_balance_by_address: one read path over the
+ * registry (VenuePublicData.fetchBalanceByAddress). Keyless; nothing is signed.
+ */
+import { PerpError } from "./errors.js";
+import { fetchBalanceByAddress, getVenue, listPublicBalanceVenues } from "./exchanges/venue.js";
+function dataOf(r) {
+    return {
+        balance: r.balance,
+        spot: r.spot,
+        ...(r.accounts !== null ? { accounts: r.accounts } : {}),
+        ...(r.dexes !== null ? { dexes: r.dexes } : {}),
+        ...(r.accountMode !== null ? { accountMode: r.accountMode } : {}),
+    };
+}
+function warningsOf(venue, errors) {
+    return Object.entries(errors).map(([src, e]) => `${venue} ${src} unavailable (${e.code}: ${e.message}) — its balance is missing from this answer (unknown, not zero)`);
+}
+export async function readBalanceByAddress(venue, net, address, opts = {}) {
+    const id = getVenue(venue).id;
+    const r = await fetchBalanceByAddress(id, net, address, { accountIndex: opts.accountIndex });
+    return { venue: id, data: dataOf(r), errors: r.errors, notes: r.notes, warnings: warningsOf(id, r.errors) };
+}
+/** Every venue that reads balances by address; a venue that fails (address format included) is an `errors` entry. */
+export async function readBalanceByAddressAll(net, address, opts = {}) {
+    const venues = listPublicBalanceVenues().map(v => v.id);
+    const out = { venues: {}, errors: {}, notes: {}, warnings: [] };
+    const settled = await Promise.allSettled(venues.map(v => readBalanceByAddress(v, net, address, v === "lighter" || v === "lighter-rh" ? opts : {})));
+    settled.forEach((res, i) => {
+        const v = venues[i];
+        if (res.status === "rejected") {
+            const e = res.reason;
+            out.errors[v] = e instanceof PerpError ? { code: e.structured.code, message: e.structured.message } : { code: "EXCHANGE_ERROR", message: e instanceof Error ? e.message : String(e) };
+            return;
+        }
+        out.venues[v] = res.value.data;
+        for (const [src, e] of Object.entries(res.value.errors))
+            out.errors[`${v}:${src}`] = e;
+        if (res.value.notes.length > 0)
+            out.notes[v] = res.value.notes;
+        out.warnings.push(...res.value.warnings);
+    });
+    return out;
+}

package/dist/bot/quote-rules.js

@@ -19,7 +19,7 @@ export async function quoteRulesOf(adapter, symbol) {
     if (network === null) {
         throw new PerpError("EXCHANGE_ERROR", `${adapter.name}: the adapter's network is unknown, so the ${symbol} tick / minimums cannot be read; nothing was sent`, { exchange: adapter.name });
     }
-    const [markets, stepSize] = await Promise.all([getVenue(adapter.name).publicData.fetchMarkets(network), lotStepOf(adapter, symbol)]);
+    const [markets, stepSize] = await Promise.all([getVenue(adapter.name).publicData.fetchMarkets(network, { funding: false }), lotStepOf(adapter, symbol)]);
     const vm = markets.find(m => symbolMatch(m.symbol, symbol));
     return { tickSize: vm?.tickSize ?? null, stepSize, minSize: vm?.minSize ?? null, minNotional: vm?.minNotional ?? null };
 }

package/dist/bot/strategies/funding-arb-strategy.js

@@ -1064,9 +1064,16 @@ export class FundingArbStrategy {
                 return false;
             }
             const perpSymbol = getPerpSymbol(opp.symbol, opp.shortExchange);
-            const priceEstimate = await getPriceEstimate(perpAdapter, perpSymbol, opp.symbol);
-            if (priceEstimate <= 0) {
-                ctx.log(`  [ARB] Skip spot-perp ${opp.symbol}: can't determine price`);
+            let priceEstimate;
+            try {
+                priceEstimate = await getPriceEstimate(perpAdapter, perpSymbol, opp.symbol);
+            }
+            catch (err) {
+                ctx.log(`  [ARB] Skip spot-perp ${opp.symbol}: market read failed: ${err instanceof Error ? err.message : String(err)}`);
+                return false;
+            }
+            if (priceEstimate === null) {
+                ctx.log(`  [ARB] Skip spot-perp ${opp.symbol}: no positive mark price on ${opp.shortExchange}`);
                 return false;
             }
             // Liquidity check

package/dist/bot/strategies/funding-arb-utils.d.ts

@@ -58,8 +58,12 @@ export declare function cappedLeverage(configured: number, legs: {
 }[], logUnknown: (msg: string) => void): number;
 /** Match a symbol against a target, accounting for -PERP suffix variations. */
 export declare function matchSymbol(s: string, target: string): boolean;
-/** Get a price estimate for a symbol from the perp adapter. */
-export declare function getPriceEstimate(perpAdapter: ExchangeAdapter, perpSymbol: string, fallbackSymbol: string): Promise<number>;
+/**
+ * The perp venue's mark price for a symbol. null = the market is not listed or its mark is not a
+ * positive finite number (Pacifica rows carry markPrice "-" when /info/prices has none). A failed
+ * market read throws (never a 0 that callers would size against).
+ */
+export declare function getPriceEstimate(perpAdapter: ExchangeAdapter, perpSymbol: string, fallbackSymbol: string): Promise<number | null>;
 export interface FundingScore {
     symbol: string;
     exchange: string;
@@ -82,6 +86,14 @@ export declare function isPositionGone(e: unknown): boolean;
  * points, or the per-symbol funding basis is unknown). A failed read THROWS — callers must not
  * mistake a 429 / timeout for "history too thin".
  */
+/**
+ * Funding-history rows one request (or the adapter's paging) can serve per venue — a
+ * `history_periods` above it fails every scoring call, so strategies validate it at config time.
+ * Venues without an entry page without a limit. Measured / documented in docs/VENUE_READ_CAPS.md.
+ */
+export declare const FUNDING_HISTORY_CAP: Readonly<Record<string, number>>;
+/** Throws INVALID_PARAMS when `periods` is not a positive integer or exceeds a leg venue's cap. */
+export declare function assertFundingHistoryPeriods(periods: unknown, venues: readonly string[], param?: string): void;
 export declare function scoreFunding(adapter: ExchangeAdapter, symbol: string, exchangeName: string, periods: number, cache?: Map<string, {
     score: FundingScore;
     ts: number;

package/dist/bot/strategies/funding-arb-utils.js

@@ -133,18 +133,20 @@ export function matchSymbol(s, target) {
     const t = target.toUpperCase();
     return u === t || u === t + "-PERP" || u.replace(/-PERP$/, "") === t;
 }
-/** Get a price estimate for a symbol from the perp adapter. */
+/**
+ * The perp venue's mark price for a symbol. null = the market is not listed or its mark is not a
+ * positive finite number (Pacifica rows carry markPrice "-" when /info/prices has none). A failed
+ * market read throws (never a 0 that callers would size against).
+ */
 export async function getPriceEstimate(perpAdapter, perpSymbol, fallbackSymbol) {
-    try {
-        const markets = await perpAdapter.getMarkets();
-        const market = markets.find(m => m.symbol.toUpperCase() === perpSymbol.toUpperCase() ||
-            m.symbol.toUpperCase() === fallbackSymbol.toUpperCase() ||
-            m.symbol.toUpperCase() === `${fallbackSymbol.toUpperCase()}-PERP`);
-        return market ? parseFloat(market.markPrice) : 0;
-    }
-    catch {
-        return 0;
-    }
+    const markets = await perpAdapter.getMarkets();
+    const market = markets.find(m => m.symbol.toUpperCase() === perpSymbol.toUpperCase() ||
+        m.symbol.toUpperCase() === fallbackSymbol.toUpperCase() ||
+        m.symbol.toUpperCase() === `${fallbackSymbol.toUpperCase()}-PERP`);
+    if (market === undefined)
+        return null;
+    const px = Number(market.markPrice);
+    return Number.isFinite(px) && px > 0 ? px : null;
 }
 /**
  * true when a reduce-only close was rejected because there is no position left to reduce.
@@ -187,6 +189,29 @@ async function marketFundingHours(adapter, exchangeName, symbol) {
  * points, or the per-symbol funding basis is unknown). A failed read THROWS — callers must not
  * mistake a 429 / timeout for "history too thin".
  */
+/**
+ * Funding-history rows one request (or the adapter's paging) can serve per venue — a
+ * `history_periods` above it fails every scoring call, so strategies validate it at config time.
+ * Venues without an entry page without a limit. Measured / documented in docs/VENUE_READ_CAPS.md.
+ */
+export const FUNDING_HISTORY_CAP = {
+    // hyperliquid: fundingHistory pages forward, but `-l` above 5000 is refused (HL_FUNDING_HISTORY_MAX_LIMIT).
+    // pacifica: cursor paging, 4000 per page × 10 pages (PACIFICA_FUNDING_PAGE × PACIFICA_MAX_PAGES).
+    hyperliquid: 5000, pacifica: 40_000, lighter: 750, "lighter-rh": 750, arcus: 1000, aster: 1000, grvt: 10_000, extended: 10_000,
+};
+/** Throws INVALID_PARAMS when `periods` is not a positive integer or exceeds a leg venue's cap. */
+export function assertFundingHistoryPeriods(periods, venues, param = "history_periods") {
+    if (typeof periods !== "number" || !Number.isInteger(periods) || periods < 1) {
+        throw new PerpError("INVALID_PARAMS", `${param} must be a positive integer (got ${String(periods)})`, { remediation: `Set ${param} to e.g. 6` });
+    }
+    const over = venues.map(v => v.toLowerCase()).filter(v => FUNDING_HISTORY_CAP[v] !== undefined && periods > FUNDING_HISTORY_CAP[v]);
+    if (over.length > 0) {
+        const caps = over.map(v => `${v} ${FUNDING_HISTORY_CAP[v]}`).join(", ");
+        throw new PerpError("INVALID_PARAMS", `${param} ${periods} exceeds the funding-history cap of ${caps}`, {
+            remediation: `Set ${param} to at most ${Math.min(...over.map(v => FUNDING_HISTORY_CAP[v]))}`,
+        });
+    }
+}
 export async function scoreFunding(adapter, symbol, exchangeName, periods, cache) {
     const key = `${exchangeName}:${symbol}`;
     const cached = cache?.get(key);
@@ -197,15 +222,23 @@ export async function scoreFunding(adapter, symbol, exchangeName, periods, cache
     if (fH === null)
         return null; // per-symbol basis unknown — the hourly rate would be a guess
     const history = await adapter.getFundingHistory(symbol, periods);
-    if (history.length < 2)
+    // A print without a rate is unknown, not 0, and a closed-market window (QFEX outside
+    // market_hours: rate null, marketClosed) carries no funding: both left out of the average.
+    const known = history.filter((h) => h.rate !== null && h.marketClosed !== true);
+    if (known.length < 2)
         return null;
-    const rates = history.map(h => parseFloat(h.rate));
+    const rates = known.map(h => parseFloat(h.rate));
     if (rates.some(r => !Number.isFinite(r))) {
         throw new PerpError("EXCHANGE_ERROR", `${exchangeName} ${symbol}: funding history has a non-numeric rate`, { exchange: exchangeName });
     }
-    const avgRate = rates.reduce((s, r) => s + r, 0) / rates.length;
+    // Every print normalized by its own interval (Lighter /fundings prints are per 1 h while the
+    // venue's quoted rate is per 8 h); intervalHours null → the market basis fH.
+    const hourly = known.map((h, i) => rates[i] / (typeof h.intervalHours === "number" ? h.intervalHours : fH));
+    const avgHourly = hourly.reduce((s, r) => s + r, 0) / hourly.length;
+    /** Average rate per the market's own interval (fH), from interval-normalized prints. */
+    const avgRate = avgHourly * fH;
     const consistency = rates.filter(r => r > 0).length / rates.length;
-    const annualized = annualizeHourlyRate(avgRate / fH);
+    const annualized = annualizeHourlyRate(avgHourly);
     const score = { symbol, exchange: exchangeName, avgRate, consistency, annualized, payments: rates.length };
     cache?.set(key, { score, ts: Date.now() });
     return score;

package/dist/bot/strategies/spot-perp-arb-strategy.d.ts

@@ -1,7 +1,7 @@
 /**
  * Spot-Perp Arbitrage Strategy
  *
- * Focused strategy: buy spot (HL or Lighter) + short perp on the BEST of 4 exchanges.
+ * Focused strategy: buy spot (HL or Lighter) + short perp on the best of the configured perp exchanges (`exchanges`).
  * No perp-perp logic. History-based entry/exit with short rotation.
  *
  * Strategy layer handles ONLY decisions (opportunity scanning, scoring, close/rotation decisions).

package/dist/bot/strategies/spot-perp-arb-strategy.js

@@ -1,7 +1,7 @@
 /**
  * Spot-Perp Arbitrage Strategy
  *
- * Focused strategy: buy spot (HL or Lighter) + short perp on the BEST of 4 exchanges.
+ * Focused strategy: buy spot (HL or Lighter) + short perp on the best of the configured perp exchanges (`exchanges`).
  * No perp-perp logic. History-based entry/exit with short rotation.
  *
  * Strategy layer handles ONLY decisions (opportunity scanning, scoring, close/rotation decisions).
@@ -12,7 +12,7 @@ import { registerStrategy } from "../strategy-registry.js";
 import { getFundingHours } from "../../funding.js";
 import { annualizeHourlyRate } from "../../funding/normalize.js";
 import { pruneExecutionLog } from "../../execution-log.js";
-import { buildAdapterMap, getPerpSymbol, findRate, cappedLeverage, matchSymbol, fetchRates, scoreFunding, botSpotPerpMatches, assertFundingArbLegs, cancelBotSymbols, collectFundingSince } from "./funding-arb-utils.js";
+import { buildAdapterMap, getPerpSymbol, findRate, cappedLeverage, matchSymbol, fetchRates, scoreFunding, assertFundingHistoryPeriods, botSpotPerpMatches, assertFundingArbLegs, cancelBotSymbols, collectFundingSince } from "./funding-arb-utils.js";
 import { SpotPerpExecutor } from "./spot-perp-executor.js";
 import { findSpotQuoteBalance, getBotSpotAdapter, nonQuoteSpotBalances, spotNetworkOf, spotSharesPerpMargin, spotTokenBase } from "../../exchanges/spot-factory.js";
 import { getVenue } from "../../exchanges/venue.js";
@@ -80,6 +80,8 @@ export class SpotPerpArbStrategy {
         catch { /* non-critical */ }
         this._config = ctx.config;
         const p = this.params;
+        // Config-time check: a history_periods above a leg venue's cap would fail every tick.
+        assertFundingHistoryPeriods(p.history_periods, p.exchanges);
         ctx.state.set("arbRunning", true);
         ctx.state.set("spaPositions", []);
         ctx.state.set("arbPositions", 0);

package/dist/bot/strategies/spot-perp-executor.js

@@ -65,8 +65,8 @@ export class SpotPerpExecutor {
             }
             // Price estimate
             const price = await getPriceEstimate(perpAdapter, perpSymbol, symbol);
-            if (price <= 0)
-                return { success: false, error: "price <= 0" };
+            if (price === null)
+                return { success: false, error: `no positive mark price for ${perpSymbol} on ${perpExchange}` };
             // Liquidity check
             const liq = await checkSpotPerpLiquidity(spotAdapter, perpAdapter, symbol, perpSymbol, sizeUsd, 0.5, (msg) => log(`  ${msg}`));
             if (!liq.viable)

package/dist/cli-program.js

@@ -111,7 +111,7 @@ export function buildProgram(opts) {
         .option("-e, --exchange <exchange>", `Exchange: ${listVenues().map(v => v.id).join(", ")} (default: ${defaultExchange})`, defaultExchange)
         .option("-k, --private-key <key>", "REJECTED — a raw key on argv leaks via ps / shell history. Import it instead: perp wallet set <exchange> (stdin)")
         .option("--json", "Output raw JSON (for piping)")
-        .option("--fields <fields>", "Comma-separated fields to include in JSON output (e.g. totalEquity,positions)")
+        .option("--fields <fields>", "Comma-separated fields to include in JSON output (dot paths allowed, e.g. totals.equity,exchanges)")
         .option("--ndjson", "Output newline-delimited JSON (one object per line for streaming)")
         .option("-w, --wallet <name>", "Use a specific wallet by name (from 'perp wallet list')")
         .option("--ows <name>", "Use an OWS (Open Wallet Standard) wallet by name")