HL Copy Trader 是一款面向 Hyperliquid 的自动跟单工具,核心用途是让用户以自己设定的资金规模自动复制指定交易员的持仓与订单。所有资金始终保留在用户自己的钱包中。
【用途】 将任意 Hyperliquid 交易员的持仓与挂单,按用户资金与目标账户价值的比例等比缩放后同步到用户账户,实现跟单交易,并可配置风控与报告。
【前置条件:钱包策略】 在执行任何交易前,必须先激活钱包策略。需加载 wallet-policy 技能,并提议标准通配策略(禁止导出密钥 + 允许 *)。该策略是 HL 充值、下单签名与撤单的必要条件。
【主要参数】
- target_address(字符串,必填):目标交易员的 HL 钱包地址。
- my_capital(数字,必填):你的资金,以 USDC 计。
- risk_stop_pct(数字,默认 40):止损百分比。当账户价值低于 my_capital × (1 - risk_stop_pct/100) 时全部平仓。
- sync_interval(数字,默认 5):同步频率,单位为分钟,可选 1 / 3 / 5 / 15。
- max_leverage(数字,默认 10):杠杆上限,目标使用更高杠杆时按此封顶。
- copy_assets(字符串,默认 "all"):要跟单的币种,"all" 或逗号分隔,例如 "BTC,ETH"。
- min_order_size(数字,默认 10):缩放后名义价值低于此 USDC 金额的订单将被跳过。
- risk_action(字符串,默认 "liquidate"):熔断触发时的动作。"liquidate" 表示平掉全部仓位并停止(默认);"pause" 表示仅停止同步,通知用户自行处理,不动任何仓位。
【初始化流程】 运行 scripts/setup.py 进行初始化,流程为:读取目标当前 HL 账户价值;计算 scale_ratio = my_capital / target_account_value;向用户展示确认摘要;用户确认后按需充值、设置杠杆、镜像当前持仓与订单;注册同步监控定时任务(每 sync_interval 分钟执行一次)。
启动前展示给用户的确认摘要包含:目标交易员地址(截断显示)、目标资金、你的资金、缩放比例、止损线(含 −risk_stop_pct%)、同步频率、资产范围、最大杠杆,并询问是否确认(yes/no)。
【同步循环逻辑】 每次定时触发运行 scripts/sync.py,顺序为:
- 先做风险检查:若 account_value < stop_value,当 risk_action 为 "liquidate" 时,平掉所有技能管理的仓位、撤销所有技能管理的订单、暂停任务并通知用户;当 risk_action 为 "pause" 时,立即暂停任务且不动任何仓位,并通知用户止损已触发、同步已暂停、仓位未受影响,请自行决定是否手动平仓。
- 获取目标状态:通过 HL info API 读取持仓与未成交订单。
- 获取自身状态:持仓、未成交订单与账户价值。
- 缩放比例漂移检查:将当前目标账户价值与 state.json 中的 target_account_value_at_setup 比较,若漂移超过 20%,立即暂停同步并通知用户目标账户价值从 $X 变为 $Y(>20%),缩放比例将从 1:A 变为 1:B,请确认以新比例恢复,或回复 'keep ratio' 继续按原比例执行;等待用户确认后再更新 state 中的 scale_ratio 并恢复。
- 同步持仓:对每个目标持仓按比例缩放数量、限制杠杆、按需开仓/调整/平仓。仅平掉 state.json 中 skill_positions 记录的技能管理仓位,绝不触碰不在该集合中的仓位。
- 同步订单:仅撤销 state.json 中 paul_orders 记录的技能管理订单;挂出目标新增的订单;若缩放后名义价值小于 min_order_size 或资产不在 copy_assets 中则跳过;绝不撤销不在映射中的订单。
- 通知:仅在有变化时通知,无操作运行保持静默。
【状态存储】 状态保存在 tasks/{job_id}/state.json,字段包括:paused、target_address、my_capital、scale_ratio、stop_value、sync_interval、max_leverage、copy_assets、min_order_size、paul_orders(目标订单号到自身订单号的映射)、skill_positions、target_account_value_at_setup、risk_action、lang。
【通知与报告】 语言规则:从用户的初始化命令中检测语言,存入 state.json 的 lang 字段("zh" 或 "en")。所有通知与报告遵循该语言。用户可随时通过“report in English”或“以后用中文汇报”等方式切换。
- 实时(仅在有变化时):中文格式为“[时间] 同步完成:新增 X 笔,取消 X 笔,调整 X 笔仓位”;英文格式为“[time] Synced: +X orders, −X cancelled, X positions adjusted”。
- 每日(UTC 00:00):账户价值与起始资金对比、当前持仓摘要(币种、方向、数量、未实现盈亏)、距止损线的距离、目标交易员当日表现。
- 每周(周日 UTC 00:00):总盈亏(金额与百分比)、目标交易员当周盈亏、跟单偏差分析(为何你的百分比 ≠ 目标百分比)、操作统计、参数调优建议。
【风险提示】(初始化时始终显示)
- 跟单存在风险,历史表现不代表未来结果。
- 5 分钟同步延迟意味着你的成交价与目标不同。
- 缩放后的小额订单可能因低于 min_order_size 被跳过。
- 建议先用小额资金验证,再逐步扩大。
- 可随时停止,资金始终留在你自己的 HL 账户中。
【关键实现说明】
- 所有 HL 调用使用 skills/hyperliquid/client.py 中的 HyperliquidClient。
- 每个币种的最小下单量:下单前通过 HL meta API(POST /info,参数 {"type":"meta"})获取该币种的 szDecimals,计算 min_size = 10 ** (-szDecimals),始终使用 max(scaled_size, min_size)。不要硬编码各币种数值,以 meta 响应为准。
- 开仓后通过 get_account_state 验证成交再确认。
- 去重:首次同步前对自身订单执行一次清理,避免重复下单。
- 缩放比例漂移(>20%)始终触发用户确认暂停,绝不静默更新比例。初始化时将 target_account_value_at_setup 存入 state。
- 用户手动下的订单/持仓(不在 skill_positions / paul_orders 中)绝不会被同步循环触碰。
- 每周报告比较已实现盈亏时,依据成交记录而非市值计价。
【文件构成】
- scripts/setup.py:一次性初始化、确认、充值、初始镜像。
- scripts/sync.py:同步循环,由定时任务每 N 分钟调用。
- references/api.md:HL API 说明与客户端方法参考。