Hyperliquid 跟单工具箱

这是一个包含了两个独立策略的 Hyperliquid 交易机器人项目。使用这些工具前，您必须具备 Python 基础知识，并完全理解其代码逻辑和潜在的财务风险。

---

🛑 极度重要：风险警告与免责声明 🛑

在进行任何操作之前，请逐字阅读并完全理解以下内容：

1. 这不是投资建议：本仓库提供的所有代码均为技术示例，不构成任何形式的财务或投资建议。
2. 您可能损失全部资金：加密货币交易，尤其是带有杠杆的衍生品交易，具有极高的风险。市场波动、网络延迟、代码错误或策略本身的问题都可能导致您的账户资金在短时间内完全亏损。
3. 您必须审查代码：您有绝对的责任去阅读、理解并审计您计划运行的每一行代码（包括 ds_copier_v2.py, btc_follow_bot_v1.py 以及所有被引用的 example_utils.py 等辅助文件）。不理解代码就运行，无异于将您的资产交给一个完全不透明的黑箱。
4. 您对自己的行为负全责：一旦您运行这些脚本，所有的交易决策、API密钥安全以及最终的财务结果（无论盈利或亏损）均由您本人承担。项目作者不对任何潜在的损失负责。
5. 从隔离的小额账户开始：严禁在您存有大量资金的主账户中运行任何交易机器人。请务必使用一个完全独立的、资金量很小（您完全可以接受损失的数额）的专用账户进行测试和运行。
6. 保证金模式风险：请注意不同脚本的保证金模式。ds_copier_v2.py 会为每个仓位设置逐仓保证金 (Isolated Margin)，这意味着每个仓位的风险是独立的，但单个仓位也可能因保证金不足而被独立清算。其他脚本可能使用您账户的默认设置，通常是全仓模式 (Cross Margin)，在该模式下单仓位的巨额亏损可能会耗尽您的全部账户余额。

继续使用此项目，即代表您已阅读、理解并接受上述所有条款和风险。

---

脚本介绍

1. ds_copier_v2.py - 全仓位比例跟单机器人

这是一个“完全复制”策略的机器人。它会监控目标地址的所有持仓，并按照您设定的名义价值比例，同步在您自己的账户中建立、调整或平掉仓位。

• 核心逻辑：保持您的账户持仓与目标地址的持仓在币种、方向、杠杆上一致，并在仓位大小上维持一个固定的比例 (COPY_NOTIONAL_RATIO)。
• 保证金模式：此脚本会为每个币种强制设置逐仓 (Isolated) 模式，以精确模仿目标交易员的风险隔离策略。
• 适用场景：当您希望完全模拟某位交易员的整个投资组合，而不是仅仅跟随他的某个币种时。

2. btc_follow_bot_v1.py - 单币种定额跟单机器人

这是一个“事件驱动”型的跟单机器人。它只关注特定币种（默认为 BTC），一旦发现目标开仓，它就会以一个固定的初始金额入场，并带有一个简单的止盈目标。

• 核心逻辑：等待目标地址开立特定币种的仓位 -> 以固定美元价值 (MY_INVESTMENT_USD) 跟随开仓 -> 监控仓位价值，达到止盈目标 (TAKE_PROFIT_USD) 后自动平仓并停止运行。
• 适用场景：当您只想跟随某位交易员的特定币种信号，并且希望采用固定金额投入、一次性止盈的简单策略时。

---

使用前准备

1. 环境配置：确保您的计算机上已安装 Python 3.x 环境。

2. 安装依赖：您需要安装 hyperliquid-python-sdk 及其相关依赖。请查阅其官方文档来了解正确的安装方式，通常是：

   pip install hyperliquid-sdk eth-account

3. 账户配置 (config.json)： 脚本通过 example_utils.py 文件来加载您的账户信息。您需要在项目根目录下创建一个名为 config.json 的文件，用于存放您的私钥。

   这是一个 config.json 的示例 (这是最简方式，但风险较高，请务必妥善保管此文件):

   {
     "secret_key": "您的以太坊私钥",
     "account_address": ""
   }

   警告： secret_key 字段需要填写您的钱包私钥。这是一个极其敏感的信息，泄露它将导致您的账户资产被盗。请确保此文件存放在一个绝对安全的环境中。

---

参数配置

在运行任何脚本之前，您必须打开对应的 .py 文件，仔细阅读并修改文件头部的核心配置参数。

ds_copier_v2.py 的关键参数：

• TARGET_USER_ADDRESS: 您要跟单的目标交易员的钱包地址。
• COPY_NOTIONAL_RATIO: 您的仓位与目标仓位的名义价值比例。这是一个核心风险参数，直接决定您的仓位大小。请从一个极小的值开始测试。
• TARGET_COINS: 您希望跟单的币种列表。

btc_follow_bot_v1.py 的关键参数：

• TARGET_USER_ADDRESS: 您要跟单的目标交易员的钱包地址。
• MY_INVESTMENT_USD: 您希望投入的固定金额（美元计价）。
• TAKE_PROFIT_USD: 您的仓位价值达到多少美元时自动止盈平仓。
• COIN: 您希望跟单的唯一币种。

---

如何运行

1. 完成上述的准备和配置步骤。确保您已经完全理解了脚本的逻辑和您所修改的每一个参数的含义。
2. 打开您的终端或命令行工具。
3. 使用 cd 命令进入到存放这些脚本的文件夹目录。
4. 通过您的 Python 解释器来执行您希望运行的脚本文件。

运行 ds_copier_v2.py

此脚本默认以模拟模式 (Dry Run) 运行，不会执行真实交易。

• 模拟运行 (推荐首先执行):

  python ds_copier_v2.py

  观察控制台和 ds_copier.log 文件中的日志，确认脚本行为符合预期。

• 实盘运行 (风险自负!): 要启动实盘交易，您必须明确添加 --live 标志。

  python ds_copier_v2.py --live

运行 btc_follow_bot_v1.py

对于此脚本，您需要直接编辑文件内的 DRY_RUN 变量来切换模式。

记住，持续监控是必要的。 任何自动交易程序都可能因网络、服务器或代码本身的问题而中断。您需要定期检查程序的运行状态和您在交易所的实际持仓情况。