Hyperliquid WebSocket 订阅：连接生命周期、数据流与重连

直接回答：关于 Hyperliquid WebSocket 你需要了解的内容

Hyperliquid 的 WebSocket API 是接收实时市场数据和用户特定更新的唯一方式。与需要轮询的 REST 端点不同，WebSocket 在数据发生时推送数据，使其成为交易机器人、仪表盘以及任何需要低延迟数据的应用的关键。该 API 支持多个不同的数据流：l2Book、trades、candles、allMids、activeAssetCtxs、activeAssetCtx、userEvents 和 orderUpdates。每个数据流都有特定的订阅消息格式，连接生命周期由心跳机制控制，该机制在大约 30 秒后关闭空闲连接。

要开始使用，你连接到 wss://api.hyperliquid.xyz/ws（主网）或 wss://api.hyperliquid-testnet.xyz/ws（测试网），发送订阅消息，然后监听传入的数据。你还必须响应 ping 帧以保持连接存活。本指南涵盖了从初始连接到意外断开后重连的完整生命周期，并提供了 Python 和 Node.js 的可运行代码示例。

• 实时数据仅通过 WebSocket 可用；REST 端点仅提供快照。
• 连接限制：每个 IP 一个 info 连接和一个 user 连接。
• 心跳：服务器发送 ping 帧；如果在约 30 秒内未收到 pong，则连接关闭。

理解 Hyperliquid 的 WebSocket 架构

Hyperliquid 的 WebSocket API 与其 REST API 是分开的。REST 端点（/info 和 /exchange）用于获取历史数据、下单和查询账户状态。WebSocket 专门用于实时流式传输。这种分离意味着对于实时数据，你必须使用 WebSocket；REST 轮询不能替代。

WebSocket 端点是 wss://api.hyperliquid.xyz/ws。该 API 支持两种类型的连接：用于市场数据的 'info' 连接和用于用户特定事件的 'user' 连接。每个 IP 地址最多只能有一个每种连接。这个限制对于需要同时订阅市场数据和用户事件的应用很重要。

协议使用 JSON 消息。要订阅，你发送一条消息，其中 method 字段设置为 "subscribe"，并且 subscription 对象指定数据流及其参数。例如，要订阅 allMids 数据流，你发送：{"method":"subscribe","subscription":{"type":"allMids"}}。要取消订阅，你发送类似的消息，将 method 设置为 "unsubscribe"。

服务器以 JSON 消息形式发送数据。每条消息都有一个 channel 字段指示数据流类型，以及一个 data 字段包含有效负载。例如，一条交易消息可能看起来像：{"channel":"trades","data":[{"coin":"BTC","px":"50000","sz":"0.1","side":"B","time":1620000000000}]}。

• Info 连接：用于市场数据流（l2Book、trades、candles、allMids、activeAssetCtxs）。
• User 连接：用于 userEvents 和 orderUpdates。
• 订阅消息必须包含确切的通道字符串；否则服务器会忽略它们。

可用的 WebSocket 数据流和订阅格式

Hyperliquid 提供多个数据流，每个都有特定的订阅格式。以下是最常见的：

l2Book：提供特定币种的订单簿。使用 {"type":"l2Book","coin":"BTC"} 订阅。数据包括带档位和数量的买盘和卖盘。

trades：流式传输特定币种的单笔交易。使用 {"type":"trades","coin":"BTC"} 订阅。每笔交易包括价格、数量、方向和时间戳。

candles：提供特定币种和间隔的 K 线数据。使用 {"type":"candles","coin":"BTC","interval":"1m"} 订阅。数据包括 OHLCV 值。

allMids：流式传输所有币种的中间价。使用 {"type":"allMids"} 订阅。数据是币种到中间价的映射。

activeAssetCtxs：提供所有活跃资产的环境信息，包括资金费率、未平仓合约和标记价格。使用 {"type":"activeAssetCtxs"} 订阅。

activeAssetCtx：提供特定资产的环境信息。使用 {"type":"activeAssetCtx","coin":"BTC"} 订阅。

userEvents：流式传输用户特定事件，如成交和资金支付。使用 {"type":"userEvents","user":"0x..."} 订阅。

orderUpdates：流式传输用户的订单状态更新。使用 {"type":"orderUpdates","user":"0x..."} 订阅。

• 所有订阅消息必须包含 type 字段。
• 对于特定币种的数据流，coin 字段是必需的。
• 对于 K 线，interval 字段是必需的（例如，'1m'、'5m'、'1h'）。

心跳和超时约定

Hyperliquid 的 WebSocket 服务器每 30 秒发送一个 ping 帧以保持连接存活。如果客户端在该时间内未响应 pong 帧，服务器将关闭连接。这是标准的 WebSocket 心跳机制，但在客户端代码中正确处理它至关重要。

在大多数 WebSocket 库中，ping/pong 会自动处理。但是，如果你使用低级库，可能需要手动实现。例如，在 Python 的 websockets 库中，ping_interval 和 ping_timeout 参数控制此行为。在 Node.js 的 ws 库中，你可以监听 'ping' 事件并发送 pong。

文档化的超时时间约为 30 秒。如果你的客户端在该窗口内未响应 ping，连接将被终止。这是社区报告中常见的“获取 K 线时连接错误”问题的常见原因。

• 服务器每 30 秒发送一次 ping。
• 客户端必须在 30 秒内响应 pong。
• 否则，服务器将以 1006 异常关闭连接。

连接限制和速率限制

Hyperliquid 强制每个 IP 地址一个 info 连接和一个 user 连接的限制。这意味着你不能从同一 IP 打开多个 WebSocket 连接到同一端点。如果你需要订阅多个数据流，可以在单个连接上通过发送多个订阅消息来实现。

此外，REST API 有速率限制，但 WebSocket 连接不受相同的速率限制。但是，在短时间内发送太多订阅消息可能会触发断开连接。最好在连接后立即订阅所有需要的数据流。

有关速率限制的更多详细信息，请参阅我们的 Hyperliquid 速率限制指南。

• 每个 IP 一个 info 连接。
• 每个 IP 一个 user 连接。
• 超过这些限制会导致连接被拒绝。

可运行的 Python 客户端示例

下面是一个完整的 Python 客户端，它订阅 BTC 的 allMids 和 l2Book，自动处理 ping，并包含一个简单的重连策略。它使用 websockets 库，该库默认自动处理 ping/pong。

客户端连接到 WebSocket，发送订阅消息，然后监听消息。如果连接断开，它会尝试使用指数退避重新连接，并重新订阅相同的数据流。

import asyncio
import json
import websockets

async def subscribe(ws, subscription):
    await ws.send(json.dumps({"method": "subscribe", "subscription": subscription}))

async def main():
    uri = "wss://api.hyperliquid.xyz/ws"
    subscriptions = [
        {"type": "allMids"},
        {"type": "l2Book", "coin": "BTC"}
    ]
    while True:
        try:
            async with websockets.connect(uri, ping_interval=20, ping_timeout=20) as ws:
                for sub in subscriptions:
                    await subscribe(ws, sub)
                print("Subscribed to allMids and l2Book")
                async for message in ws:
                    data = json.loads(message)
                    print(f"Received: {data['channel']} - {data['data']}")
        except websockets.exceptions.ConnectionClosed as e:
            print(f"Connection closed: {e}. Reconnecting in 5 seconds...")
            await asyncio.sleep(5)
        except Exception as e:
            print(f"Error: {e}. Reconnecting in 5 seconds...")
            await asyncio.sleep(5)

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

可运行的 Node.js 客户端示例

这是一个使用 ws 库的等效 Node.js 客户端。它通过监听 'ping' 事件并发送 pong 来手动处理 ping/pong。它还包含一个带有固定延迟的重连策略。

客户端订阅 BTC 的 allMids 和 l2Book，并记录所有传入消息。

const WebSocket = require('ws');

const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');

function subscribe(ws, subscription) {
  ws.send(JSON.stringify({ method: 'subscribe', subscription }));
}

ws.on('open', () => {
  console.log('Connected');
  subscribe(ws, { type: 'allMids' });
  subscribe(ws, { type: 'l2Book', coin: 'BTC' });
});

ws.on('ping', () => {
  ws.pong();
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  console.log(`Received: ${msg.channel} - ${JSON.stringify(msg.data)}`);
});

ws.on('close', () => {
  console.log('Connection closed. Reconnecting in 5 seconds...');
  setTimeout(() => {
    // Reconnect logic: create a new WebSocket and repeat subscriptions
    const newWs = new WebSocket('wss://api.hyperliquid.xyz/ws');
    // ... (repeat the same event handlers)
  }, 5000);
});

ws.on('error', (err) => {
  console.error('WebSocket error:', err);
});

预期结果和如何验证

当你运行 Python 或 Node.js 客户端时，你应该会看到消息流。对于 allMids，你会收到类似 {"channel":"allMids","data":{"BTC":"50000.0","ETH":"3000.0"}} 的消息。对于 l2Book，你会看到带有买盘和卖盘的订单簿更新。

要验证你的订阅是否正常工作，请检查你是否收到每个订阅数据流的消息。你还可以使用 Hyperliquid 的 API 文档 查看示例负载。

如果你没有收到任何消息，请检查你的订阅消息格式，并确保你连接到正确的端点。另外，验证你的客户端是否响应 ping。

• 你应该在几秒钟内收到每个订阅数据流的一条消息。
• 消息中的 channel 字段指示数据流类型。
• 如果你看不到任何消息，请检查你的订阅格式和网络连接。

常见故障和故障排除

一个常见问题是“获取 K 线时连接错误”，通常由 Hummingbot 等交易机器人的用户报告。这通常发生在 WebSocket 连接因错过心跳或网络问题而断开时。要修复它，请确保你的客户端正确处理 ping 并实现重连策略。

另一个问题是超过连接限制。如果你尝试从同一 IP 打开多个 info 连接，服务器将拒绝新连接。确保你的应用程序使用单个连接进行所有市场数据订阅。

如果你使用代理或负载均衡器，请确保 WebSocket 连接不会过早终止。某些代理的空闲超时时间比 Hyperliquid 的 30 秒心跳间隔短。

有关 WebSocket 断开连接的全面修复列表，请参阅我们的 通用 WebSocket RPC 断开连接修复 指南。

• 检查你的客户端是否在 30 秒内响应 ping。
• 验证你没有超过每个 IP 一个连接的限制。
• 确保你的网络允许 WebSocket 连接，并且没有激进的空闲超时。

权衡和限制

Hyperliquid 的 WebSocket API 功能强大，但有一些限制。每个 IP 一个连接的限制对于需要从单个服务器订阅许多数据流的应用可能具有限制性。但是，你可以在一个连接上订阅多个数据流，所以这很少成为问题。

心跳机制要求客户端响应迅速。如果你的应用程序忙于处理数据，它可能会错过 ping 并断开连接。为了缓解这种情况，请使用单独的线程或进程来处理 WebSocket 连接，或者使用自动处理 ping 的库。

另一个限制是 WebSocket API 不提供历史数据。对于历史数据，你必须使用 REST /info 端点。这意味着你需要结合两种 API 才能获得完整的解决方案。

最后，WebSocket API 除了 官方文档 之外没有详细公开文档。某些数据流可能会在没有通知的情况下更改，因此监控官方文档以获取更新非常重要。

• 每个 IP 一个连接用于 info 和 user 数据流。
• WebSocket 不提供历史数据；请使用 REST 获取。
• 心跳需要及时的 pong 响应。

后续步骤和更多资源

既然你了解了 Hyperliquid 的 WebSocket API，你就可以构建实时应用程序。要开始，请尝试修改示例客户端以订阅不同的数据流或处理用户事件。

对于更高级的用例，请考虑使用像 OnFinality 这样的托管基础设施提供商。我们的 Hyperliquid 网络页面 提供可靠的 WebSocket 端点，具有自动重连和负载均衡功能。你还可以使用我们的 RPC 助手 找到最适合你需求的端点。

如果你正在构建交易机器人，你还需要了解用于下单的 REST API。查看我们的 API 服务 以获取托管 API 访问。别忘了查看我们的 定价 以选择适合你使用情况的计划。

有关更多教育内容，请访问我们的 学习中心 获取有关 WebSocket 最佳实践、速率限制等的指南。

• 尝试不同的数据流和订阅格式。
• 使用 OnFinality 的托管 WebSocket 端点以获得生产可靠性。
• 探索我们关于 Hyperliquid 和 WebSocket 最佳实践的其他指南。