Hyperliquid 大户监控器 V2.5.1

监控 Hyperliquid 交易所大户交易活动，自动生成 HTML 持仓报告

🐛 V2.5.1 Bug修复 (2025-10-21)

🔧 修复SSL连接错误 - 添加指数退避重试机制（最多3次），提高API调用成功率
🔧 修复asyncio警告 - 使用asyncio.run()和get_running_loop()，符合Python 3.10+最佳实践
✨ 账户信息增强 - 交易通知中显示账户总价值、持仓价值、Total PnL
🔥 Fire Emoji等级 - 根据Total PnL显示不同等级的fire/ice emoji（🔥🔥🔥 或 ❄️❄️❄️）

🎯 V2.5.0 新特性 (2025-10-21)

🚀 智能缓存机制 - 5分钟自动更新，避免频繁API请求，提升性能
🚀 账户数据汇总 - 实时显示账户价值、Total PnL、持仓前三、挂单前三
🚀 模块化架构 - HTML生成逻辑独立到 create_html.py，代码更清晰
⭐ 智能交易价值过滤 - 基于交易价值（价格 × 数量）而非数量进行过滤，更加精准
⭐ 统一 USD 阈值 - 不受币种价格差异影响，一个配置适用所有币种
⭐ 增强输出信息 - 通知中显示交易价值，一目了然
✅ 双模式监控 - WebSocket 实时模式 + 轮询模式，灵活选择
✅ 多空持仓统计 - 新增大户多空比分析
✅ HTML 持仓报告 - 自动生成美观的持仓报告

📝 V2.5.0 核心功能

1️⃣ 智能缓存与定期更新

PositionManager 现在带有智能缓存机制：

✅ 每5分钟自动刷新账户数据
✅ 避免频繁API调用，减少延迟
✅ 交易通知时使用缓存数据，响应更快

2️⃣ 丰富的交易通知

当大户交易时，控制台实时显示：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟢  开仓
    (Open Long)
⏰ 时间: 2025-10-21 21:46:17
👤 用户: 0x5d2f4460ac3514ada79f5d9838916e508ab39bb7
💎 币种: BTC
📊 方向: 买入 (Bid)
📈 数量: 0.5000
💵 价格: $67,450.00
💰 交易价值: $33,725.00
📈 仓位: 0.0000 → 0.5000 (变化: +0.5000)

────────────────────────────────────────────────────────────────────────────────
📊 账户汇总信息 🔥🔥🔥  ← Fire Emoji等级（根据Total PnL）
────────────────────────────────────────────────────────────────────────────────
💼 账户总价值: $124,680,000.00
📈 持仓总价值: $124,680,000.00
💰 Total PnL: $3,580,000.00

📊 持仓前三（按价值）:
   1. 🔴 BTC | $124,680,000.00 | PnL: +$3,580,000.00
   2. 🟢 ETH | $2,340,000.00 | PnL: +$120,000.00
   3. 🔴 HYPE | $890,000.00 | PnL: -$45,000.00

📋 挂单前三（按价值）:
   1. 🟢 BTC | 买入 @ $65,000.0000 | 价值: $650,000.00
   2. 🔴 ETH | 卖出 @ $3,500.0000 | 价值: $350,000.00
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔥 Fire Emoji等级说明

根据用户的Total PnL显示不同等级：

Total PnL	Emoji	说明
≥ $10M	🔥🔥🔥🔥🔥	超级大户
≥ $5M	🔥🔥🔥🔥	顶级交易员
≥ $1M	🔥🔥🔥	百万盈利
≥ $500K	🔥🔥	高手
≥ $100K	🔥	盈利
> $0	✨	小盈利
$0	➖	持平
> -$100K	❄️	小亏损
> -$500K	❄️❄️	亏损
> -$1M	❄️❄️❄️	较大亏损
> -$5M	❄️❄️❄️❄️	重大亏损
≤ -$5M	❄️❄️❄️❄️❄️	严重亏损

3️⃣ 增强的HTML报告

每个地址现在显示：

📊 PnL卡片: Total PnL, 24h/48h/7d/30d PnL
🏆 持仓前三: 按价值排序的Top 3持仓
📋 挂单前三: 按价值排序的Top 3挂单
💼 账户统计: 账户价值、持仓价值、持仓数、挂单数

📝 V2.4.1 核心优化

交易价值过滤

旧逻辑问题：

基于数量过滤 (min_position_size)
- 0.1 BTC ($6,000)  → ❌ 被过滤（数量小）
- 1000 DOGE ($80)   → ✅ 通知（数量大但价值低）
→ 错过重要交易，被小额交易干扰

新逻辑优势：

基于交易价值过滤 (min_trade_value)
- 0.1 BTC ($6,000)  → ✅ 通知（价值超过阈值）
- 1000 DOGE ($80)   → ❌ 过滤（价值太小）
→ 精准监控，专注大额交易

配置示例：

{
  "monitor": {
    "min_trade_value": 5000,    // 只通知价值超过 $5,000 的交易
    "min_position_size": 0      // 设置为 0，使用新的价值过滤
  }
}

🚀 快速开始

# 1. 运行监控
python3 monitor_whales.py

# 2. 查看持仓报告
open positions/positions_*.html

# 3. 查看交易日志
tail -f logs/20251018_*.log

📊 HTML 持仓报告

总览统计卡片

统计项	说明	示例
监控地址数	总共监控的地址数量	10
持仓地址数	有持仓的地址数量	8
总持仓数	所有持仓总数	45
🟢 做多持仓	做多数量和价值	20 个 ($5,234,567) 45.2%
🔴 做空持仓	做空数量和价值	25 个 ($6,345,678) 54.8%
📈 多空比	Long/Short比率	0.82

持仓表格字段

字段	说明	示例
代币	币种	HYPE, BTC
方向	Long/Short	🟢 Long, 🔴 Short
杠杆	倍数	10x
价值	美元	$3,571.77
数量	仓位	100.5000
开仓价格	入场价	$35.5450
盈亏(PnL)	未实现盈亏	🟢 +$125.50
资金费	累计资金费（正=盈利，负=亏损）	🟢 +$12.34 或 🔴 -$12.34
爆仓价格	清算价	$32.0000

颜色标识

🟢 绿色 = 做多 / 盈利 / 收到资金费
🔴 红色 = 做空 / 亏损 / 支付资金费
⚪ 灰色 = 中性

📌 资金费说明

重要：资金费显示已修正

Hyperliquid API 返回的 cumFunding 正值表示支付资金费（亏损）
本系统已自动转换：正值显示为盈利（收到），负值显示为亏损（支付）
示例：做空FARTCOIN，API返回+66996.89，实际显示-$66,996.89（支付/亏损）

🏗️ 架构说明

核心模块

position_manager.py - 持仓管理器（带缓存）
- get_account_data_async() - 获取账户数据（5分钟缓存）
- get_top_positions() - 获取持仓前N
- get_top_open_orders() - 获取挂单前N
- update_and_generate_report_async() - 更新数据并生成HTML报告
create_html.py - HTML报告生成
- generate_position_table_html() - 生成单个地址的HTML
- generate_html_report() - 生成完整报告
monitor_whales.py - 监控主程序
- WebSocket实时监控
- 定期数据更新（5分钟）
- 交易通知（包含账户汇总、持仓前三、挂单前三）

数据流

启动 → PositionManager初始化
     → 首次获取所有地址数据 → 生成HTML报告
     → 启动WebSocket监控
     → 启动定期更新任务（5分钟）
     
交易事件 → 解析交易 → 从缓存获取账户数据 → 显示通知
         
定期更新 → 刷新所有地址数据 → 更新HTML报告

📁 项目结构

hyperliquid/
├── monitor_whales.py             # 主程序（WebSocket实时监控）
├── position_manager.py           # 持仓管理器（带缓存）
├── create_html.py                # HTML报告生成模块
├── monitor_utils.py              # 共享工具模块
├── filter_top_traders.py         # 筛选顶级交易员
├── test_position_manager.py      # 测试脚本
├── jsons/
│   ├── config.json              # 配置文件
│   ├── top_traders_addresses.json  # 监控地址
│   └── address_filters.json     # 地址过滤规则
├── positions/
│   └── positions_YYYYMMDD_HHMMSS.html  # HTML 持仓报告（自动生成）
├── logs/
│   └── YYYYMMDD_HHMMSS.log      # 交易日志（自动生成）
└── README.md                     # 本文档

⚙️ 配置

jsons/config.json - 已优化默认配置：

{
  "monitor": {
    "max_addresses": 20,
    "notify_on_open": true,      // 通知开仓
    "notify_on_close": true,     // 通知平仓
    "notify_on_reverse": true,   // 通知反向开仓
    "notify_on_add": true,       // ✅ 通知加仓（V2.3启用）
    "notify_on_reduce": true,    // ✅ 通知减仓（V2.3启用）
    "min_position_size": 0       // 最小通知仓位（0=全部通知）
  },
  "notification": {
    "log_file": "logs/"           // 自动生成时间戳日志
  },
  "debug": true
}

配置说明

交易监听：默认监听所有类型的仓位变动（开仓/平仓/加仓/减仓/反向）
最小仓位：设置 min_position_size > 0 可过滤小额交易
地址数量：建议 ≤ 20 个地址以避免API限制

🧪 测试与验证

快速测试

# 1. 测试持仓管理器
python3 -c "from position_manager import PositionManager; print('✅ 持仓模块正常')"

# 2. 测试配置加载
python3 -c "from monitor_whales import Config; c=Config(); print('✅ 配置加载正常')"

# 3. 检查日志目录
ls -ld logs/ positions/ jsons/

运行监控

# 启动监控（会自动生成持仓报告）
python3 monitor_whales.py

# 预期输出：
# ✅ 成功订阅 [1/10]: 0x...
# 📊 多空持仓统计
# 🟢 做多: X 个持仓, 总价值: $XXX
# 🔴 做空: X 个持仓, 总价值: $XXX
# 📈 多空比: X.XX

🔧 常见问题

Q: 资金费显示不正确？

A: V2.3 已修复。API 返回的 cumFunding 正值表示支付（亏损），系统自动转换为负值显示。

Q: 为什么看不到加仓/减仓通知？

A: V2.3 已默认启用。确认 config.json 中 notify_on_add 和 notify_on_reduce 为 true。

Q: 多空比在哪里查看？

A: 打开 positions/positions_*.html 文件，顶部统计卡片会显示：

做多持仓数量和价值
做空持仓数量和价值
多空比（Long/Short Ratio）

Q: 如何过滤小额交易？

// 在 config.json 中设置
"min_position_size": 1000  // 只通知 ≥ $1000 的交易

Q: 持仓报告在哪里？

# 查看最新的持仓报告
open positions/positions_$(ls -t positions/ | head -1)

📈 功能特性

核心功能

✅ 实时监控 - WebSocket 订阅大户交易活动
✅ 持仓管理 - 自动获取并追踪用户持仓
✅ 交易分类 - 识别开仓/平仓/加仓/减仓/反向操作
✅ 多空分析 - 实时计算多空比和持仓分布

报告功能

✅ HTML 持仓报告 - 美观的持仓可视化（positions/*.html）
✅ 多空统计卡片 - 顶部展示多空力量对比
✅ 资金费修正 - 正确显示资金费盈亏方向
✅ 9 字段完整展示 - 代币/方向/杠杆/价值/数量/价格/盈亏/资金费/爆仓价

技术特性

✅ 模块化设计 - 独立的持仓管理器
✅ 暗色主题 - 舒适的视觉体验
✅ 响应式布局 - 适配各种屏幕
✅ 地址过滤 - 支持黑名单和关键词过滤

⚠️ 注意事项

持仓数据 - 启动时获取快照，每次运行生成新文件（时间戳命名）
资金费理解 - 显示值已反转（正=盈利，负=亏损），与API原始值相反
交易通知 - 默认监听所有操作，可在配置中选择性关闭
API 限制 - 建议监控 ≤ 20 个地址，避免超出速率限制
浏览器兼容 - 使用现代浏览器（Chrome/Firefox/Safari）打开 HTML

🎯 使用流程

# 1. 安装依赖
pip3 install hyperliquid-python-sdk

# 2. 运行监控程序
python3 monitor_whales.py

# 3. 查看持仓报告（在浏览器中打开）
open positions/positions_*.html

# 4. 实时查看交易日志
tail -f logs/*.log

📊 输出示例

控制台输出

================================================================================
📊 多空持仓统计
================================================================================
🟢 做多: 15 个持仓, 总价值: $5,234,567.89 (42.3%)
🔴 做空: 25 个持仓, 总价值: $7,132,456.78 (57.7%)
📈 多空比: 0.73
================================================================================

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟢  开仓  🟢
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏰ 时间: 2025-10-18 23:45:12
👤 用户: 0x856c35038594767646266bc7fd68dc26480e910d
────────────────────────────────────────────────────────────────────────────────
💎 币种: HYPE
📊 方向: 买入 (Bid)
📈 数量: 100.0000
💵 价格: $35.5450
📈 仓位: 0.0000 → 100.0000 (变化: +100.0000)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📞 获取帮助

查看本文档 - 完整的功能说明和配置指南
检查日志 - tail -50 logs/*.log 查看详细运行日志
查看持仓报告 - 打开 positions/*.html 查看可视化报告
参考官方文档 - Hyperliquid API 文档

🔄 版本历史

V2.3 (2025-10-18)

✅ 修复资金费计算方向错误
✅ 新增多空持仓统计和多空比
✅ 默认启用加仓/减仓通知
✅ 优化日志输出和报告展示

V2.2 (2025-10-18)

✅ 修复日志文件生成错误
✅ 独立持仓管理模块
✅ 自动生成 HTML 持仓报告

版本: V2.3
日期: 2025-10-18
状态: ✅ 生产就绪

祝交易监控顺利！ 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
docs		docs
jsons		jsons
.DS_Store		.DS_Store
.gitignore		.gitignore
BUGFIX_V2.5.1.md		BUGFIX_V2.5.1.md
CHANGELOG_V2.5.0.md		CHANGELOG_V2.5.0.md
HOTFIX_V2.5.1.md		HOTFIX_V2.5.1.md
README.md		README.md
SUMMARY_V2.5.1.md		SUMMARY_V2.5.1.md
bugfix.md		bugfix.md
create_html.py		create_html.py
filter_top_traders.py		filter_top_traders.py
get_coinglass_range9.py		get_coinglass_range9.py
monitor_utils.py		monitor_utils.py
monitor_whales.py		monitor_whales.py
position_manager.py		position_manager.py
requirements.txt		requirements.txt
test_position_manager.py		test_position_manager.py
todo.md		todo.md

fanyilun0/hyperliquid

Folders and files

Latest commit

History

Repository files navigation