从轮询到推送：面向 Hyperliquid WebSocket 的构建者指南

每个 Hyperliquid 机器人的起点都大同小异：一个循环、一个睡眠计时器，以及每隔几秒触发一次的 REST 调用。这套方案能用，直到它撑不住为止。一旦你开始追踪的资产超过寥寥几个，轮询就会变成你始料未及的瓶颈：耗尽速率限制、两次请求之间数据过时，以及每增加一个资产就线性膨胀的架构。

WebSocket 通过翻转模型解决了这个问题。你的机器人不再每小时向服务器发出数千次"有什么变化吗？"的询问，而是由服务器在任何变化发生的瞬间主动通知你的机器人。一条持久连接取代了数千次独立请求，机器人在市场事件发生时立即做出反应，而不是在事后数秒乃至数分钟才发现。

本指南将介绍如何将 Hyperliquid 原生 WebSocket API 接入交易机器人，如何处理大多数构建者始料未及的重连边缘情况，以及如何叠加 HyperTracker 推送交付的预计算分析数据，让你的机器人同时接收原始市场数据和队列级别的情报。

规模化场景下的轮询困境

REST 轮询对大多数机器人来说是正确的起点：简单、无状态、易于调试。一个每小时检查几次队列仓位和资金费率的波段交易机器人，其整个生命周期都可以安心使用 REST。架构直白，请求量也维持在可控范围内。

问题在于扩展。如果你以一秒为刷新目标追踪十个资产，单小时内就会产生 36,000 次请求。追踪三十个资产时，这个数字超过 100,000。Hyperliquid 公共 API 的共享权重预算为每分钟 1,200，大多数端点的单次 info 查询消耗 2 到 20 个权重单位（部分专用端点最高达 60）。即使取最轻量级的情形，一个每秒轮询十个资产的机器人也会在数分钟内耗尽预算。

另一个问题是延迟。以一秒为间隔轮询时，你的数据随时处于零到一秒的过时状态。大多数时候，你问"有什么变化吗？"得到的是同样的答案。WebSocket 彻底消除了这种带宽浪费，因为服务器只在真正有新内容时才发送数据。

Hyperliquid 的 WebSocket 频道

Hyperliquid 在主网暴露了单一 WebSocket 端点 wss://api.hyperliquid.xyz/ws（测试网镜像为 wss://api.hyperliquid-testnet.xyz/ws）。连接成功后，通过发送 JSON 消息订阅特定数据流。

可用的订阅类型涵盖了交易机器人所需的核心数据：

• AllMids： 所有已上线资产的最新中间价。一次订阅即可获得全资产的持续价格流，无需逐币轮询。
• L2Book： 特定币种的订单簿快照。适用于需要深度数据来确定入场规模或评估流动性的机器人。
• Trades： 实时成交数据。交易所上发生的每笔成交都会在此推送。
• Candle： 从 1 分钟到 1 天各周期的 OHLCV K 线。K 线收盘时服务器实时推送。
• UserEvents： 你自己的成交、资金费结算和强平事件。这个流负责告知机器人其订单是否已成交。

订阅消息格式如下：

{
  "method": "subscribe",
  "subscription": {
    "type": "allMids"
  }
}

订阅特定币种的 L2Book：

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC"
  }
}

服务器会返回订阅确认，并附带当前状态的快照（以 isSnapshot: true 标记），机器人无需额外 REST 调用即可立即初始化本地状态。

保持连接活跃

Hyperliquid 会在 WebSocket 连接沉默 60 秒后断开。你的机器人需要每 20 秒发送一次心跳 ping 以保持连接。消息极为简洁：

{"method": "ping"}

这很容易实现，却出人意料地容易被遗忘。很多构建者写好订阅逻辑，在低流量环境下测试，便认为连接是稳定的。然后机器人在安静的深夜时段陷入沉默，服务器断开连接，机器人因为没有处理重连逻辑而错过亚洲盘开盘。

规划重连机制：它一定会发生

Hyperliquid 的文档明确指出：断线会周期性发生，且不会提前通知。你的机器人必须将重连视为正常运营事件。以下是生产级机器人采用的流程：

1. 检测断线。 通过 ping 超时（在合理时间窗口内未收到 pong）或 WebSocket 错误/关闭事件来判断。
2. 指数退避等待。 从一秒开始，每次重试翻倍。这可以防止机器人在服务故障期间持续冲击服务器，在原有问题之上再触发速率限制。
3. 重连并重新订阅。 建立新的 WebSocket 连接，重新发送所有订阅消息。服务器会回复新的快照。
4. 处理快照。 这些快照以 isSnapshot: true 标记，包含每个订阅流的当前状态。用它们重建本地状态。
5. 与 REST 对账。 若断线持续超过数秒，查询 Info API 以填补空白。可通过 REST 获取成交记录和用户事件，确保断线期间没有遗漏。

关键在于第五步。快照给你的是当前状态，但不会回放你错过的事件。如果一个仓位在断线期间开仓又平仓，快照对此一无所知。重连后的一次 REST 查询可以捕获这类边缘情况。

多资产监控模式

WebSocket 带来的最大架构收益是多资产监控。一个追踪三十个资产的 REST 机器人需要三十个独立的轮询循环（或一个包含三十次顺序请求的循环）。基于 WebSocket 的机器人只需订阅一次 AllMids，便可通过单条连接获取所有资产的更新。

对于更精细的数据，你可以在同一连接上混合多种订阅类型。典型的多资产机器人可能订阅：

• AllMids 获取全市场价格流
• L2Book 获取它主动交易的三四个资产的深度数据（用于确定规模）
• Trades 获取这些资产的实时大额成交信息
• UserEvents 跟踪自身订单成交和资金费结算

总共约十个订阅，处理多策略机器人所需的一切数据。同样的数据若通过 REST 以一秒为间隔轮询，每秒需要发出数十次请求。

最简 Python 连接管理器

以下是使用 Python websockets 库实现的 WebSocket 连接管理器骨架，涵盖心跳、自动重连和消息路由：

import asyncio
import json
import websockets

WS_URL = "wss://api.hyperliquid.xyz/ws"

class HyperliquidWS:
    def __init__(self, subscriptions):
        self.subscriptions = subscriptions
        self.ws = None

    async def connect(self):
        while True:
            try:
                async with websockets.connect(WS_URL) as ws:
                    self.ws = ws
                    await self._subscribe_all()
                    await asyncio.gather(
                        self._heartbeat(),
                        self._listen()
                    )
            except websockets.ConnectionClosed:
                print("Disconnected. Reconnecting...")
                await asyncio.sleep(1)

    async def _subscribe_all(self):
        for sub in self.subscriptions:
            await self.ws.send(json.dumps({
                "method": "subscribe",
                "subscription": sub
            }))

    async def _heartbeat(self):
        while True:
            await self.ws.send('{"method": "ping"}')
            await asyncio.sleep(20)

    async def _listen(self):
        async for msg in self.ws:
            data = json.loads(msg)
            self._route(data)

    def _route(self, data):
        channel = data.get("channel")
        if channel == "allMids":
            self.on_price_update(data["data"])
        elif channel == "l2Book":
            self.on_book_update(data["data"])
        elif channel == "trades":
            self.on_trade(data["data"])

这里做了有意简化。生产版本需要加入指数退避、逐频道状态追踪、重连后的 REST 差距对账，以及针对格式错误消息的错误处理。但核心模式已在此：连接、订阅、心跳、监听、断线重连。

叠加分析层：市场数据加情报

原始市场数据告诉你的机器人正在发生什么：价格移动了、一笔成交发生了、订单簿偏移了。但它不会告诉机器人是谁在推动这次移动。这是鲸鱼在建仓吗？那些持续盈利的交易者是否倾向同一方向？Leviathan 队列（持有 500 万美元或以上永续仓位权益的钱包）是否在零售商抛售时悄悄建仓？

这正是分析推送交付发挥作用的地方。我们的数据将 Hyperliquid 上的每个钱包划分为 16 个行为队列：按账户规模分为八个（Shrimp 到 Leviathan），按历史总盈亏记录分为八个（Giga-Rekt 到 Money Printer）。队列指标每五分钟更新一次，这意味着你的机器人可以将 Hyperliquid 原生 WebSocket 提供的 tick 级市场数据，与 HyperTracker 推送交付的队列仓位情报融合在一起。

架构是这样的：Hyperliquid 的 WebSocket 将价格、成交和订单簿数据直接推送给你的机器人，用于 tick 级反应。HyperTracker 通过 Flow 档（$799/月）和 Stream 档（$1,999/月）的 webhook 交付预计算分析数据（队列仓位、Smart Money 警报、强平风险评分、订单流摘要）。来自 HyperTracker 的原生 WebSocket 推送即将上线，流式基础设施正在积极开发中。你的机器人融合两路数据流，同时基于原始市场数据和行为情报做出决策。

举个例子：你的机器人在 Hyperliquid Trades 流上发现价格突然下跌。原始数据的信息是：价格下跌了。通过 webhook 交付的我们的队列数据则显示：Money Printer 钱包（历史总盈利超过 100 万美元的队列）在下跌期间增加了多头敞口。这与 Giga-Rekt 钱包（历史总亏损最惨烈的队列）在同一时刻买入，是截然不同的信号。

REST 仍是正确答案的场合

WebSocket 引入了额外的复杂性：连接管理、心跳循环、重连逻辑、状态对账。对于很多机器人来说，这种复杂性并不划算。

在以下情况下，REST 轮询是更好的选择：你的机器人不频繁地检查仓位或信号（每小时数次或更少）；你在执行交易（Hyperliquid 的 Exchange API 下单仅支持 REST）；你在构建日报工具或投资组合追踪器；或者你在原型阶段，想要尽可能简单的架构。

大多数生产系统最终都会收敛到混合模式：REST 用于下单和账户管理，WebSocket 用于实时市场数据，HyperTracker 的 REST API 或推送交付用于分析数据（根据你需要队列更新的频率而定）。

| 数据类型 | 最佳交付方式 | 原因 | | --- | --- | --- | | 价格流、成交、订单簿 | WebSocket（Hyperliquid 原生） | tick 级新鲜度，规模化下低开销 | | 下单、撤单 | REST（Hyperliquid Exchange API） | 请求-响应模型符合执行语义 | | 队列仓位、Smart Money 信号 | REST 轮询或推送（HyperTracker） | 分析数据每 5 分钟刷新，推送用于阈值警报 | | 强平风险、排行榜变化 | REST 或 webhook（HyperTracker） | 事件驱动：仅在阈值触发时相关 | | 历史数据、回测 | REST（HyperTracker） | 对数月成交和仓位数据进行批量查询 |

常见错误及规避方法

在实际交付过使用两种模式的机器人之后，有几类失败模式反复出现。

没有重连逻辑

最常见的 WebSocket bug 是你不会察觉的那种。机器人连接、订阅，平稳运行数小时。然后服务器断开连接（例行维护、网络抖动、Hyperliquid 节点轮换），机器人陷入沉默，什么都不处理，而你还以为它仍在运行。务必实现带指数退避的重连机制，并记录每次断线以便事后审计空白期。

忽视快照

重连并重新订阅后，服务器会发送以 isSnapshot: true 标记的当前状态快照。有些机器人丢弃这些快照，只处理增量更新，导致每次重连后本地状态永久过时。应处理快照来重建状态，然后再切换到增量更新处理。

混淆 REST 与 WebSocket 的执行用途

Hyperliquid 的 WebSocket 仅用于交付市场数据。下单必须通过 REST Exchange API 并需要 EIP-712 签名请求。如果你试图通过 WebSocket 发送订单，什么都不会发生。机器人的数据管道和执行管道应该是独立的循环。

以 tick 速度轮询分析数据

队列级分析数据（如 Smart Money 仓位或强平风险）不会随每个 tick 变化。我们的数据每五分钟刷新一次，这是行为队列分析的合理粒度。每秒轮询队列端点既浪费速率限制预算，又得不到更新鲜的数据。请将轮询频率与数据的实际刷新率匹配，或切换到 webhook/推送交付，让服务器在有变化时主动通知你。

同时使用市场数据和队列情报构建

HyperTracker 的 API 为你的机器人提供跨 16 个行为队列的预计算分析数据。从免费档开始 REST 轮询（每日 100 次请求），随着机器人数据需求的增长，再升级到 webhook（Flow，$799/月）或 WebSocket 推送（Stream，$1,999/月）。

探索 API

进阶路径

大多数成功的 Hyperliquid 机器人都遵循可预测的演进轨迹。它们从 REST 轮询起步，因为这样易于理解、便于快速原型验证。一旦机器人跑通、优势得到验证，构建者就会将市场数据层迁移到 WebSocket，因为轮询的请求量变得难以为继。分析层通常沿循相似路径：先每隔数分钟轮询 HyperTracker 的 REST 端点，当机器人需要对队列变化更即时地响应时，再切换到推送交付。

这种演进与哪种协议"更好"无关，而在于让交付方式匹配数据的自然节奏。价格数据每个 tick 都在变化，应走 WebSocket。队列分析每五分钟更新，REST 或推送交付都可行。下单是离散的请求-响应动作，REST 是自然选择。

让每条数据流使用与其节奏相匹配的交付方式，你将得到一个既不会因速率限制而被迫停止、在重连期间不遗漏任何内容、并能同时基于原始市场数据和行为情报做出决策的机器人。这是大多数构建者最终达到的架构。问题只是：你是有意设计到达这里，还是在几次惨痛故障后被迫摸索出来的。