Hyperliquid WebSocket API 指南 2026：订阅、心跳与 Post 请求

一句话：连接 wss://api.hyperliquid.xyz/ws，为每个数据流发送 {"method":"subscribe","subscription":{...}}，并按 channel 字段分发消息。如果某个数据流可能长时间没有消息，请发送 {"method":"ping"}，因为服务器会关闭 60 秒内没有向其发送过消息的连接。userFills 等用户数据流会先推送一条带 isSnapshot: true 的快照。你还可以用 {"method":"post"} 在同一个连接上发送 info 请求和签名操作。

如果只是每分钟刷新一次的面板，REST 轮询就够了。但如果你需要实时订单簿、逐笔成交或某个钱包的成交流，Hyperliquid WebSocket API 才是正确的工具：一个连接、多个数据流，而且没有按请求计算的权重。本文介绍消息格式、最常用的订阅、我们在 2026 年 10 月 20 日对主网的实测结果，以及一个可以直接运行的 Python 脚本。如果你只是想查看某个钱包的 PnL 和持仓，其实不需要这些：Hyperfolio 已经以只读方式做好了。

端点与消息格式

• 主网：wss://api.hyperliquid.xyz/ws
• 测试网：wss://api.hyperliquid-testnet.xyz/ws（参见我们的 Hyperliquid 测试网指南）

所有消息都是 JSON 文本帧。客户端有四种方法：

方法	示例	服务器响应
subscribe	{"method":"subscribe","subscription":{"type":"trades","coin":"BTC"}}	channel: "subscriptionResponse"，随后在 channel: "trades" 推送数据
unsubscribe	与原订阅相同的对象	停止推送
ping	{"method":"ping"}	{"channel":"pong"}
post	{"method":"post","id":1,"request":{"type":"info","payload":{...}}}	channel: "post"，带相同的 id

订阅确认会回显你的订阅并补全默认值。我们订阅 BTC 的 l2Book 时，确认消息为 {"type":"l2Book","coin":"BTC","nSigFigs":null,"mantissa":null,"fast":false}。可以用它确认服务器准确理解了你的请求。

值得了解的订阅类型

官方文档列出了 20 多种数据流。下面这些覆盖了大部分交易、分析和追踪需求：

数据流	订阅	返回内容
allMids	{"type":"allMids"}（可选 dex）	所有市场的中间价。现货中间价只随第一个永续 dex 返回。
trades	{"type":"trades","coin":"BTC"}	成交数组，含价格、数量、方向、时间、tid 和 users: [买方, 卖方]
l2Book	{"type":"l2Book","coin":"BTC"}（可选 nSigFigs、mantissa、fast）	订单簿快照：每边 20 档，fast: true 时为 5 档
bbo	{"type":"bbo","coin":"BTC"}	最优买卖价，仅在某个区块发生变化时推送
candle	{"type":"candle","coin":"BTC","interval":"1m"}	当前 K 线，周期从 1m 到 1M
activeAssetCtx	{"type":"activeAssetCtx","coin":"BTC"}	资金费率、持仓量、标记价、预言机价、中间价、24 小时成交量
userFills	{"type":"userFills","user":"0x…"}（可选 aggregateByTime）	先推送近期成交快照，之后逐笔推送新成交
orderUpdates	{"type":"orderUpdates","user":"0x…"}	该账户的订单状态变化
userEvents	{"type":"userEvents","user":"0x…"}	成交、资金费、强平和非用户撤单，消息在 channel: "user" 上到达
userFundings	{"type":"userFundings","user":"0x…"}	每小时的资金费支付
clearinghouseState	{"type":"clearinghouseState","user":"0x…"}	保证金汇总与持仓

有两个细节经常让人踩坑。第一，userEvents 的消息在 channel: "user" 上，而不是 "userEvents"，按订阅类型做路由的代码会漏掉它们。第二，用户数据流必须使用真实的账户地址（主账户或子账户）。文档提醒，如果传入 API 钱包（agent wallet）的地址，会得到空结果。

主网实测结果

我们于 2026 年 10 月 20 日约 07:10 UTC 在主网运行了下面的脚本。以下是 15 到 30 秒短窗口内的观察，并非保证，推送频率取决于市场活跃度。

数据流	观察结果
l2Book BTC（默认）	每边 20 档，约每 4.5 至 5 秒推送一次
l2Book BTC，fast: true	每边 5 档，约每 0.55 秒推送一次
bbo BTC	30 秒内 204 条消息（约每秒 7 条）
trades BTC	约每 0.85 秒一批，20 秒内 75 笔成交
activeAssetCtx BTC	约每秒更新一次。样本：标记价 81,800，预言机价 81,820，资金费率每小时 0.0000125，持仓量 39,965 BTC
allMids	约每 5 秒一次，共 1,355 个键，其中 472 个现货交易对以 @索引 表示
userFills	首条消息 isSnapshot: true，含 30 笔成交；之后的流式消息不含 isSnapshot 字段

结论：如果需要快速获取盘口最优价，请使用 bbo 或带 fast: true 的 l2Book。默认的 20 档订单簿适合画深度图，但对延迟敏感的场景太慢。另外，流式成交消息会直接省略 isSnapshot，所以应检查 data.get("isSnapshot")，而不是与 false 比较。

快照、重连与丢失的数据

Hyperliquid 明确表示断线可能会定期发生且不会提前通知，所有自动化客户端都应自动重连。好消息是，你很少会真正丢失数据：

1. 重新订阅时，userFills、userFundings 等时间序列数据流会先发送快照（isSnapshot: true）。请与已保存的数据去重，例如成交用 (coin, tid)。
2. 对于成交，文档说明 tid 是买卖双方订单 ID 的 50 位哈希。若需要全局唯一的成交 ID，请使用 (block_time, coin, tid)。
3. 如果快照覆盖的时间不够长，可以用对应的 REST info 请求补齐，例如 userFillsByTime。我们的 Hyperliquid 历史数据指南介绍了分页限制。

一个简单可靠的模式是：用指数退避（1 秒、2 秒、4 秒，最多约 30 秒）循环重连，从列表中重新订阅所有数据流，并把每次重连后的第一条快照当作合并而不是替换。

心跳：60 秒规则

如果服务器 60 秒内没有向你发送任何消息，就会关闭连接。像 bbo 这样繁忙的数据流不会触发，但只订阅了一个不活跃钱包 userFills 的连接就会。请大约每 50 秒发送一次 {"method":"ping"}，并等待 {"channel":"pong"}。我们在主网上确认收到了 pong。文档规定的是这条 JSON 消息，所以请发送它，而不要依赖库自带的协议层 ping。

通过 WebSocket 发送 Post 请求

你可以通过 WebSocket 发送与 REST API 相同的请求体，格式如下：

{"method": "post", "id": 1,
 "request": {"type": "info",
             "payload": {"type": "clearinghouseState", "user": "0x..."}}}

响应在 channel: "post" 上返回，带相同的 id，response.type 为 info、action 或 error。签名操作使用 "type": "action"，并带上常规的 action、nonce 和 signature。id 为必填项，请为每个请求使用唯一的 id 以便匹配响应。不支持 explorer 请求。在我们的测试中，对 HLP 金库地址发送的 clearinghouseState 请求返回账户价值约 3,900 万美元，而同一个连接同时在接收行情数据。

需要注意的限制

WebSocket 有独立于 REST 权重的上限：10 个连接、每分钟 30 个新连接、1,000 个订阅、用户类数据流最多 10 个不同用户、每分钟发送 2,000 条消息、同时 100 个未完成的 post 请求。对钱包追踪来说最关键的是 10 个用户的上限：一个 IP 无法同时接收 50 个钱包的成交流。完整说明和轮询示例见我们的 Hyperliquid 限流指南。

Python 示例：同时接收行情和钱包成交

只需 pip install websockets，无需任何密钥，因为这些数据都是公开的。把 WALLET 换成你想关注的地址即可。

import asyncio, json, time, collections
import websockets  # pip install websockets

WS_URL = "wss://api.hyperliquid.xyz/ws"
WALLET = "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"  # any public address (here: the HLP vault)

SUBS = [
    {"type": "allMids"},
    {"type": "trades", "coin": "BTC"},
    {"type": "bbo", "coin": "BTC"},
    {"type": "l2Book", "coin": "BTC"},
    {"type": "candle", "coin": "BTC", "interval": "1m"},
    {"type": "userFills", "user": WALLET, "aggregateByTime": True},
]

async def heartbeat(ws):
    while True:                      # server drops sockets silent for 60 s
        await asyncio.sleep(50)
        await ws.send(json.dumps({"method": "ping"}))

async def run(seconds=30):
    counts = collections.Counter()
    async with websockets.connect(WS_URL, max_size=None) as ws:
        for s in SUBS:
            await ws.send(json.dumps({"method": "subscribe", "subscription": s}))
        # one-off info request over the same socket
        await ws.send(json.dumps({"method": "post", "id": 1,
            "request": {"type": "info", "payload": {"type": "clearinghouseState", "user": WALLET}}}))
        hb = asyncio.create_task(heartbeat(ws))
        end = time.time() + seconds
        while time.time() < end:
            msg = json.loads(await asyncio.wait_for(ws.recv(), timeout=60))
            ch, data = msg["channel"], msg.get("data")
            counts[ch] += 1
            if ch == "userFills" and data.get("isSnapshot"):
                print("userFills snapshot:", len(data["fills"]), "fills")
            elif ch == "bbo" and counts[ch] == 1:
                bid, ask = data["bbo"]
                print("BTC bbo:", bid["px"], "/", ask["px"])
            elif ch == "post":
                st = data["response"]["payload"]["data"]
                print("account value:", st["marginSummary"]["accountValue"])
        hb.cancel()
    print(dict(counts))

if __name__ == "__main__":
    asyncio.run(run())

在我们的运行中，它打印了 BTC 最优买卖价（81,803 / 81,805）、成交快照、post 请求返回的账户价值，以及每个 channel 的消息数。用于生产环境时，请把 run() 放进带退避的重连循环，并把消息写入队列而不是直接打印。

什么时候根本不需要 WebSocket

自己搭建数据流适合交易机器人、做市和研究。如果你只是想知道某个钱包表现如何，这需要大量底层工作：重连、去重、10 个用户上限，以及资金费和手续费的核算。Hyperfolio 是一款免费、只读的 PWA（可安装的网页应用），可追踪 Hyperliquid 钱包的 PnL、持仓、资金费，并提供 Smart Money 和 Markets 视图，无需 API 密钥或签名。了解无需 API 密钥的追踪如何工作，以及如何同时追踪多个钱包。

常见问题

Hyperliquid 的 WebSocket 地址是什么？

主网为 wss://api.hyperliquid.xyz/ws，测试网为 wss://api.hyperliquid-testnet.xyz/ws。

使用 Hyperliquid WebSocket 需要 API 密钥吗？

不需要。行情和用户数据流都是公开的，无需认证。只有通过 post 请求发送操作（下单、撤单）时才需要签名。

为什么我的 Hyperliquid WebSocket 一分钟后就断开？

服务器会关闭 60 秒内没有向其发送消息的连接。在不活跃的订阅上请定期发送 {"method":"ping"}。

为什么收不到 userEvents 消息？

它们在 channel: "user" 上到达。另请确认使用的是账户地址，而不是 agent wallet 的地址。

Hyperliquid 的 l2Book 推送有多快？

在我们的测试中，默认的 BTC 20 档订单簿约每 4.5 至 5 秒更新一次，而 fast: true（5 档）约每 0.55 秒更新一次。若只需最优价，bbo 约每秒 7 条消息。

可以通过 WebSocket 下单吗？

可以。把签名操作放在 {"method":"post","request":{"type":"action",...}} 中发送，响应与 REST 的 exchange 端点一致。

只想要结果，不想折腾底层？把钱包地址粘贴到 Hyperfolio，无需 API 密钥即可查看实时 PnL 和持仓。在 Hyperliquid 交易？使用邀请码 HYPERFOLIO 可享 4% 手续费折扣（邀请码如何使用）。