hyperliquid-reader

Hyperliquid 读取器（只读）

如果你的宿主尚未执行下面的 Shell 探测（例如，在 Codex 中），请先使用其 Shell 工具运行 ! 包裹的命令，再选择设置路径。请使用实际输出；如果无法访问 Shell，请说明这一限制。

通过 opencli 以及本仓库 opencli-plugins/hyperliquid 目录中的 hyperliquid 插件，读取 Hyperliquid（链上永续合约/现货 DEX）的市场数据。该插件与 opencli 内置适配器分开，通过 opencli 的 monorepo 子路径语法安装。

此技能仅供只读访问市场数据。 它会读取 Hyperliquid 完全公开的 info API，用于分析市场表、资金费率、订单簿和 K 线。它不会读取个人账户、下达/修改/取消订单，也不会转移资金。该插件不包含交易功能——下单需要在独立端点上执行钱包签名操作，而此适配器绝不会调用该端点。

工作原理：每条命令都会向 https://api.hyperliquid.xyz/info 发送一个 { "type": "..." } 请求体的 POST 请求，并对响应进行规范化。无需 API key、钱包、登录或运行应用——info API 是公开的。

---

第 1 步：确认已安装并准备好 opencli + 插件

当前环境状态：

!`(command -v opencli && opencli hyperliquid markets --coin BTC -f json 2>&1 | head -3 && echo "READY" || echo "SETUP_NEEDED") 2>/dev/null || echo "NOT_INSTALLED"`

如果上方状态显示 READY，请跳到第 2 步。否则：

NOT_INSTALLED — 安装 opencli

npm install -g @jackwener/opencli

需要 Node.js >= 24——hyperliquid 插件声明了 engines.node >= 24。

SETUP_NEEDED — 安装 Hyperliquid 插件

Hyperliquid 适配器并未内置于 opencli 中——它是一个独立插件：

opencli plugin install github:himself65/finance-skills/hyperliquid

以上就是全部设置步骤——无需身份验证，也无需启动。使用 opencli hyperliquid markets --coin BTC 验证。

常见设置问题

症状	解决方法
opencli: command not found	npm install -g @jackwener/opencli（Node ≥ 24）
Unknown command: hyperliquid	opencli plugin install github:himself65/finance-skills/hyperliquid
hyperliquid info 429	请求受限——等待几秒后重试

---

第 2 步：确定用户的需求

用户请求	命令	关键标志
永续合约市场概览 / 按成交量排名	opencli hyperliquid markets	--sort、--limit、--coin
某个永续合约的价格 + 资金费率 + OI	opencli hyperliquid markets --coin BTC	—
现货交易对概览	opencli hyperliquid spot-markets	--sort、--limit、--pair、--canonical-only
所有当前中间价	opencli hyperliquid mids	--coin <substring>
某个币种的订单簿	opencli hyperliquid book --coin ETH	--depth、--n-sig-figs
OHLCV K 线	opencli hyperliquid candles --coin BTC --interval 1h	--limit
某个币种的历史资金费率	opencli hyperliquid funding-history --coin BTC	--hours、--limit
资金费率套利：HL 与 Binance 和 Bybit 对比	opencli hyperliquid funding-compare	--coin、--sort、--limit

---

第 3 步：执行命令

通用模式

# Use -f json or -f yaml for structured output
opencli hyperliquid markets --sort fundingAprPct --limit 15 -f json
opencli hyperliquid funding-compare --sort hlVsBinancePct --limit 20 -f md
opencli hyperliquid candles --coin BTC --interval 4h --limit 50 -f csv
opencli hyperliquid book --coin ETH --depth 5 -f json

核心规则

1. 币种符号是裸永续合约名称 — BTC、ETH、SOL、HYPE（不带交易所前缀）。现货交易对为 BASE/USDC（例如 PURR/USDC）；对于 book/candles，可以传入永续合约币种或现货交易对。
2. 查询“X／市场表现如何”时，默认使用 markets — 每个永续合约占一行，包含标记／预言机／中间价、24 小时涨跌幅、每小时资金费率和 APR、未平仓合约量（币数和名义金额）以及 24 小时成交量。使用 --coin 筛选单个资产。
3. 资金费率有两种报告方式 — fundingHrPct 是以百分比表示的原始每小时费率；fundingAprPct 将其年化（hourly × 24 × 365）。比较不同资产的持仓收益时，优先看 APR；了解“下一小时要支付多少”时，则看每小时费率。
4. funding-compare 是资金费率套利对比界面 — 它按各交易场所自身的间隔进行年化（HL 为每小时，Binance／Bybit 通常为每 4 小时），并报告 hlVsBinancePct / hlVsBybitPct 价差。默认排序按 HL 与 Binance 价差的绝对值排列（偏离最大者优先）。hlVsBinancePct 为正，表示 HL 多头支付的资金费率高于 Binance 多头。
5. book 默认显示每侧 10 个档位 — 增大 --depth（最大 20）可查看更多档位；也可以使用 --n-sig-figs 2..5 聚合价格档位。根据最优买价和卖价计算价差／中间价。
6. candles 获取最近的 --limit 根 --interval 周期蜡烛图（默认 1h，100 根）。有效周期：1m 3m 5m 15m 30m 1h 2h 4h 8h 12h 1d 3d 1w 1M。最多 5000 根。
7. 使用 -f json 进行程序化处理／传递给其他技能；使用 -f md 或 -f table 获取便于阅读的输出。
8. 仅提供只读市场数据。 不读取账户信息、不下单、不修改或取消订单，也不进行转账 — 该插件有意不提供任何写入端点，因此不要尝试寻找变通方法。

输出格式标志（-f）

格式	标志	最适用于
表格	-f table（默认）	便于阅读的终端输出
JSON	-f json	程序化处理、大模型上下文
YAML	-f yaml	结构化且易读
Markdown	-f md	报告
CSV	-f csv	导出到电子表格

输出列

• markets — coin、markPx、midPx、oraclePx、change24hPct、fundingHrPct、fundingAprPct、openInterest、oiNotional、dayNtlVlm、premiumPct、maxLeverage
• spot-markets — pair、base、markPx、midPx、change24hPct、dayNtlVlm、circulatingSupply、marketCap、canonical
• mids — coin、mid
• book — side、level、px、sz、orders
• candles — time、open、high、low、close、volume、trades
• funding-history — coin、fundingRatePct、fundingAprPct、premiumPct、time
• funding-compare — coin、hlAprPct、binanceAprPct、bybitAprPct、hlVsBinancePct、hlVsBybitPct、nextHlFunding

---

步骤 4：呈现结果

1. 先给出关键数字，再展示表格。 对于 markets --coin BTC：先用文字说明标记价格、24 小时涨跌幅、资金费率年化收益率和未平仓合约量。对于完整的 markets 数据：先给出总数以及涨跌幅最大的市场／资金费率最高的市场名称。
2. 用套利收益的角度说明资金费率——例如：“BTC 永续合约的资金费率为 +10.9% 年化（多头向空头支付）。”正资金费率 ⇒ 多头向空头支付；负资金费率 ⇒ 空头向多头支付。
3. 对于 funding-compare，优先展示差异最大的项目——指出币种、两个平台各自的年化收益率以及利差，并记住该利差是按年化计算的；实际套利还需承担交易所／提现成本，因此应将其作为筛选结果呈现，而非保证收益。
4. 对于 book，报告价差——先给出（或仅给出）最佳买价、最佳卖价、中间价和以基点表示的价差。除非用户要求，否则不要贴出 20 档盘口。
5. 对于 candles，描述价格走势——给出首尾收盘价、最高价／最低价和走势方向；只有在用户需要完整序列时，才展示完整的 OHLCV 表格。
6. 展示前积极筛选——markets 有约 180 个永续合约，mids 有约 700 个市场；除非用户要求完整列表，否则按相关排序最多展示前 15–20 个。
7. 交叉参考以辅助交易决策——Hyperliquid 是链上平台；涉及股票／期权时，应搭配 tradingview-reader 技能。对于资金费率／基差交易，核心视图是 funding-compare 加上 markets（溢价、未平仓合约量）。

---

步骤 5：诊断

opencli hyperliquid markets --coin BTC

如果成功返回 BTC 行，则表示 opencli、插件和公共 API 均可访问。如果出现 Unknown command: hyperliquid 错误，请重新安装插件（步骤 1）。hyperliquid info 4xx/5xx 表示上游 API 问题——稍等片刻后重试。

---

错误参考

错误	原因	修复方法
Unknown command: hyperliquid	未安装插件	opencli plugin install github:himself65/finance-skills/hyperliquid
hyperliquid info 429	请求频率受限	等待几秒后重试
hyperliquid info 422/500	请求体格式错误或上游问题	重新检查币种／时间间隔；稍等片刻后重试
No perp market for coin "X"	符号错误或未上市	运行 opencli hyperliquid markets（或 mids）以查找准确符号

---

参考文件

• references/commands.md — 每条命令及其所有标志、输出架构和分析工作流（资金费率套利收益、基差／套利、现货快照）