sonicmountain/Trade-Bot-Hyperliquid · 上手攻略

  • 仓库：sonicmountain/Trade-Bot-Hyperliquid
  • 链接：https://github.com/sonicmountain/Trade-Bot-Hyperliquid
  • 分类：加密货币 · 交易分析
  • 作者：Jay
  • 更新：2026-10-10

一、是什么

Hyperliquid Trade Bot 是一个只读的终端诊断工具（Read-only TUI），通过 Hyperliquid 公开 API 独立重新计算任意交易员的 ROI、胜率、PnL、最大回撤和风险调整后收益，并检测马丁格尔/网格补仓策略和虚假交易信号。它不下单、不需要 API Key，所有数据来自链上公开接口。

核心功能：ROI 真实性核查、马丁格尔检测、生存偏差警告、资金费率调整后PnL重算、统计显著性检验。

二、解决什么问题

Hyperliquid 排行榜上的 ROI 数字具有欺骗性：可能隐藏了马丁格尔仓位放大、幸运单笔拉盘、刷量交易（wash-trading）、忽略手续费/资金费率、以及被现货/永续互换掩盖的回撤。普通跟单者看到高 ROI 就跟，结果实际最大回撤远超预期。

这个工具从公开的链上 fill 数据重新构建权益曲线，告诉你排行榜数字背后的真实风险，再决定是否跟单。

三、快速安装

系统要求

  • Python 3.11+（实测推荐 3.11–3.13，具体以 requirements.txt 为准）
  • 操作系统：Linux / macOS / Windows
  • 网络：能访问 api.hyperliquid.xyz（部分地区可能需要代理）

安装步骤

# 克隆仓库
git clone https://github.com/sonicmountain/trade-bot-hyperliquid.git
cd trade-bot-hyperliquid

# 安装依赖（建议用 venv 或 uv）
python -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\activate     # Windows

pip install -r requirements.txt

# 启动 TUI
python main.py

一键启动脚本（无需系统 Python）

# Linux / macOS
chmod +x run.sh && ./run.sh

# Windows
run.bat

注：run.sh / run.bat 会解压自带的独立 Python 运行时，首次运行稍慢，无需预装系统 Python。

离线预览

python main.py --demo

四、核心用法

4.1 主界面导航（键盘操作）

按键 功能
1–6 切换标签页（Dashboard / Traders / Verify / Positions / Log / Settings）
/ 过滤/搜索当前表格
r 重新验证选中的交易员
c 打开交易配置
v 打开详细验证报告
t 切换主题（dark / light / hyperliquid）
q 退出
? 帮助

4.2 验证一个交易员

# 在 TUI 中切换到 [3]Verify 标签
# 输入要审计的交易员地址（0x 开头）
# 按 Enter 开始从公开 API 拉取 fill 历史重算

验证报告会显示： - Headline ROI vs Verified ROI（含费用和资金费率调整） - 胜率（Fee-adjusted win rate） - 最大回撤（Max drawdown） - 马丁格尔得分（0–1，越高越危险） - 异常值依赖度（Top-N 交易对总 PnL 的贡献比例） - 统计显著性 p 值（p < 0.05 表示业绩不太可能纯靠运气）

4.3 信任评级

每个交易员被打上颜色标签：

  • 🟢 TRUSTED：通过所有规则
  • 🟠 REVIEW：存在可疑点，需要人工审查
  • 🔴 REJECT：违反至少一条硬规则

规则文件在 ~/.hl-verify/rules.toml，可自行修改阈值：

[trust_rubric]
max_drawdown    = -0.35    # 回撤超过 -35% → REJECT
min_profit_factor = 1.6     # 利润因子低于 1.6 → REJECT
max_martingale  = 0.4       # 马丁格尔得分超过 0.4 → REVIEW
max_outlier_dep = 0.30      # 异常值依赖超过 30% → REVIEW

4.4 交易配置（paper-trail）

在 Settings 里配置后，每次验证会记录"如果你跟单会怎么执行"到本地审计日志（不会实际下单）：

[trade]
size_mode = "fixed_fraction"  # 固定比例
fixed_fraction = 0.02         # 每笔用账户 2% 的资金
leverage_cap = 5.0            # 最大 5× 杠杆

⚠️ 这些配置只产生 paper-trail，不会触发任何真实下单。工具永远是只读的。

4.5 实时监控（需 read-only wallet）

# 在 TUI [4]Positions 标签
# 连接一个 read-only（无提款权限）的 Hyperliquid 钱包
# 监控目标交易员的实时持仓变化

4.6 风险模拟器

# 在 [3]Verify 标签输入交易员后
# 按 c 打开 trade config，输入自定义仓位放大倍数和止损线
# 模拟不同跟单策略下的预期结果

五、典型适用场景

  1. 跟单前尽职调查：在复制一个 Hyperliquid 排行榜交易员之前，先用此工具验证其真实业绩
  2. 识别马丁格尔策略：看到"稳定高收益"先怀疑是否为马丁格尔——重仓抗亏损、补仓摊成本，高 ROI 背后是极高风险
  3. 生存偏差评估：排行榜只显示"存活账户"，已爆仓者被剔除。此工具可结合其他链上数据评估该偏差
  4. 自己账户的历史回测：用自己的 read-only API 审计自己历史交易，识别自己的策略缺陷
  5. 批量监控多个交易员：TUI 支持多标签页，可同时观察多个候选人的实时持仓和风险指标

六、坑与注意（§八 工程节）

  1. Verified ROI 必然低于 Leaderboard ROI：手续费（fees）和资金费率（funding）是主要扣除项。Verified ROI 比 Headline ROI 低是正常现象，不是工具算错了。如果出现 Verified ROI 高于 Headline ROI，才需要特别关注。

  2. Read-only 钱包仍然可以被关联身份：工具明确说不需要私钥，但 read-only 钱包地址本身是公开的，任何人都可以通过链上分析工具将你的监控行为和钱包地址关联起来。如果隐私是强需求，考虑使用新的独立地址。

  3. 显著性检验的 p 值阈值可调（默认 0.05）：~/.hl-verify/rules.toml 中 significance_p = 0.05 可修改，但学术上 0.05 仅为惯例，并非绝对标准。牛市环境下很多策略的 p 值会被放大。

  4. 刷量交易检测是启发式的：wash-trade 和 self-trade 标记是heuristics，不是确定性判断。真实联盟/做市商的正常双边交易也可能触发此标记。

  5. WebSocket 实时数据可能有延迟：TUI 实时监控依赖 Hyperliquid WebSocket feed，在网络波动或 API 限流时数据可能延迟。工具默认尊重 API 限流规则，不主动绕过。

  6. 生存偏差（Survivorship Bias）无法被该工具单独解决：排行榜只包含当前活跃账户，历史上已爆仓/退出的不在统计范围内。该工具的统计显著性检验部分缓解此问题，但不能完全消除。审计历史数据时请注意此局限。

  7. 历史 fill 数据窗口有限：Hyperliquid 公开 API 提供的历史数据窗口有长度限制，长期（如 >2 年）业绩验证可能数据不完整。

  8. 不要用此工具的输出作为投资建议：工具免责声明明确"Educational purpose only"。加密货币永续合约高杠杆交易有极高风险，过去业绩不代表未来。

  9. --headless 模式专为 CI 批量扫描设计：如需在自动化流程中批量验证多个交易员，可配合 cron 任务做日/周度扫描，结果可导出 CSV/Parquet（功能 roadmap，参见 README）。

  10. Windows 上 run.bat 兼容性：部分 Windows 环境下路径含空格可能导致解压路径问题，建议优先使用 WSL2 或 Git Bash 运行。

七、与同类对比

工具 类型 Hyperliquid API 只读 马丁格尔检测 TUI License
Trade-Bot-Hyperliquid 验证/TUI 官方公开 API ✅ ✅ ✅（Textual） 社区项目
Dwellir Hyperliquid Bot 跟单 Bot Dwellir 端点 ❌（需 API Key） ❌ ❌ Apache 2.0
Chainstack Trading Bot 网格 Bot 官方 SDK ❌（需 Key） ❌ ❌ Apache 2.0
Hyperliquid 官方 App 官方前端 — — ❌ ❌ —

核心差异：这个工具不做跟单，它是"审计"和"尽调"工具，帮你决定要不要跟单。其他 Bot 是实际执行跟单的。这是安全边界上的刻意分离——审核和执行分离。

八、一句话推荐结论

在复制任何 Hyperliquid 排行榜交易员之前，先跑一遍这个只读 TUI：几分鐘的尽调，可能省下被高ROI隐藏的高风险策略坑掉的大笔本金。