Hyperliquid orderUpdates WebSocket：订单生命周期追踪

orderUpdates 频道的范围与用途

Hyperliquid orderUpdates 频道是一个用户级 WebSocket 订阅。它仅传递订阅请求中指定账户的订单状态转换。公共市场数据源无法替代它，因为订单更新对已认证用户是私有的。根据 Hyperliquid WebSocket 订阅文档，订阅消息包含一个 type 和一个 subscription 对象，后者指定频道名称，对于用户级频道还需指定用户地址。

该频道对于需要实时了解订单生命周期事件的应用程序至关重要，例如交易仪表盘、订单管理系统和自动化策略。它通过提供基于推送的更新，补充了只读的 Hyperliquid info API 订单状态，但并不能替代历史查询。有关 Hyperliquid 连接的更广泛概述，请参阅 Hyperliquid 网络页面。

• 用户级：仅传递已订阅账户的订单。
• 需要包含用户地址的有效订阅消息。
• 补充 info API 的历史数据，但不能替代它。

订阅消息格式与频道识别

要接收订单更新，客户端需在已建立的 WebSocket 连接上发送 JSON-RPC 2.0 订阅请求。请求必须包含一个 subscription 对象，其中包含频道名称和用户地址。确切的字段名称和任何附加参数均有文档说明，并可能因 API 版本而异，因此请始终根据当前负载进行验证。JSON-RPC 2.0 规范定义了请求/响应语义，而 以太坊 JSON-RPC 规范为类似的订阅模式提供了参考，不过 Hyperliquid 有自己的实现。

典型的订阅消息如下方代码示例所示。请注意，用户地址必须按 API 要求使用小写或校验和格式。订阅后，服务器将开始为该用户发送 orderUpdates 消息。

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

ws.on('open', () => {
  const subscribeMsg = {
    method: 'subscribe',
    subscription: {
      type: 'orderUpdates',
      user: '0xYourAddressHere'
    }
  };
  ws.send(JSON.stringify(subscribeMsg));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.channel === 'orderUpdates') {
    console.log('Order update:', msg.data);
  }
});

订单对象字段与快照语义

每条 orderUpdates 消息都包含订单的完整快照，而非增量。负载包含 coin、oid（订单 ID）、cloid（客户端订单 ID）、side、订单类型、price、size、original size、status 和时间戳等字段。确切的字段名称和附加字段均有文档说明，并可能因 API 版本而异，因此请始终检查实时负载。由于消息是快照，客户端的正确行为是按订单标识符（oid 或 cloid）进行 upsert，而不是应用增量。将消息视为增量的客户端会重复计算部分成交。

例如，如果订单部分成交，size 字段反映剩余数量，status 表示当前状态。original size 保持不变。这种设计简化了状态管理：你始终拥有当前订单状态，无需重放历史。然而，这也意味着如果你错过一条消息，本地状态会变得陈旧，直到下一次更新或对账。

• 快照而非增量：每次更新时替换整个订单记录。
• 按 oid 或 cloid 作为键进行正确 upsert。
• size 和 status 等字段反映当前状态。

订单状态词汇与状态转换

订单状态字段编码了生命周期阶段。订单创建时状态为 'open'。随着成交发生，它可能转换为 'partially filled'，并最终以 'filled'、'cancelled' 或 'rejected' 终止。确切的状态字符串均有文档说明，并可能因 API 版本而异，因此请根据当前文档进行验证。客户端必须根据 status 字段来驱动其状态机，而不是根据消息到达顺序，因为 WebSocket 消息可能乱序到达或延迟。

理解这些转换对于构建可靠的订单追踪器至关重要。例如，订单可能从 open 变为 partially filled 再变为 filled，或者从 open 变为 cancelled。被拒绝的订单可能永远不会以 open 出现。Hyperliquid 订单拒绝处理指南涵盖了被拒绝订单的错误解码。始终将 status 视为订单当前状态的权威指示。

• open：订单活跃且未成交。
• partially filled：部分数量已执行。
• filled：完全执行。
• cancelled：被用户或系统取消。
• rejected：未被交易所接受。

将实时流与 info API 对账

WebSocket 订阅仅传递 socket 打开期间观察到的事件。任何重连或进程重启都会丢失断开期间发生的状态转换。因此，重建订单历史的唯一正确方法是与 info API 读取路径进行对账。Hyperliquid info 端点文档描述了 historicalOrders、frontendOpenOrders 和 userFills 等端点。这些提供了权威的订单集合。

重连时，重新发送订阅，然后从 info API 拉取权威订单集合并与本地快照进行差异比较。将 info API 结果视为事实来源。这确保任何遗漏的更新都得到纠正。有关 info API 订单表面的更深入探讨，请参阅 Hyperliquid info API 订单状态。

• WebSocket 仅提供实时数据；历史数据需要 info API。
• 重连时，重新订阅并获取权威订单。
• 将本地状态与 info API 进行差异比较并应用修正。

在 Node.js 中构建可恢复的订单追踪器

要使流可恢复，请在本地存储中记录每个 oid 最后观察到的订单状态。重连时，重新发送订阅，然后从 info API 获取权威订单集合并与本地快照进行差异比较。下方代码示例展示了使用 Node.js 和 ws 库的最小实现。它维护一个以 oid 为键的订单 Map，在每条 orderUpdates 消息时更新它，并在重连时从 info API 获取未结订单以进行对账。

此模式确保即使 WebSocket 连接断开，本地状态也能保持一致。请注意，info API 调用是向 /info 端点发送 POST 请求，JSON 正文指定 type 和 user。确切的请求格式均有文档说明，并可能因 API 版本而异。

const WebSocket = require('ws');
const fetch = require('node-fetch');

const user = '0xYourAddressHere';
const orders = new Map(); // oid -> order snapshot

async function fetchOpenOrders() {
  const res = await fetch('https://api.hyperliquid.xyz/info', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ type: 'frontendOpenOrders', user })
  });
  return res.json();
}

async function reconcile() {
  const openOrders = await fetchOpenOrders();
  for (const order of openOrders) {
    orders.set(order.oid, order);
  }
  console.log('Reconciled', orders.size, 'orders');
}

function connect() {
  const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');
  ws.on('open', () => {
    ws.send(JSON.stringify({
      method: 'subscribe',
      subscription: { type: 'orderUpdates', user }
    }));
    reconcile();
  });
  ws.on('message', (data) => {
    const msg = JSON.parse(data);
    if (msg.channel === 'orderUpdates') {
      for (const update of msg.data) {
        orders.set(update.oid, update);
      }
    }
  });
  ws.on('close', () => {
    setTimeout(connect, 1000);
  });
}

connect();

测量方法与结果表

要针对你自己的端点验证 orderUpdates 频道的行为，你可以对客户端进行插桩，记录测试订单的状态序列。下一笔小订单，然后记录每条 orderUpdates 消息及其时间戳、oid、status 和 size。订单达到终态后，将观察到的序列与预期生命周期进行比较。此方法可复现，且不依赖虚构的基准测试。

使用下表记录你的观察结果。填入测试中的实际值。这有助于确认你的客户端正确处理快照和状态转换。

• Timestamp：收到消息的时间。
• oid：订单标识符。
• Status：报告的状态字符串。
• Size：剩余数量。
• Expected next state：基于生命周期。

orderUpdates 频道的局限性与权衡

orderUpdates 频道并非完整历史。它仅在 socket 打开期间传递事件，因此任何断开都会产生缺口。它也不直接提供成交；如需成交级别的详细信息，请使用 Hyperliquid trades 和 userFills 频道。此外，该频道是用户级的，因此不能用于全市场订单簿监控。有关活性检测，请参阅 Hyperliquid WebSocket 心跳检测。

另一个权衡是快照消息可能比增量更大，从而增加带宽。然而，按 oid 进行 upsert 的简单性通常超过这一成本。最后，确切的字段名称和状态字符串均有文档说明，并可能因 API 版本而异，因此客户端必须准备好适应变化。

• 无历史：断开时出现缺口。
• 用户级：不适用于公共市场数据。
• 快照大小可能大于增量。
• 字段名称可能因 API 版本而异。

常见问题故障排查

如果你没有收到 orderUpdates 消息，首先验证订阅消息格式是否正确，以及用户地址是否与账户匹配。检查 WebSocket 连接是否打开，以及是否被限流。有关速率限制和端点健康状况，请参阅 Hyperliquid RPC 端点（RPC Assistant）。如果消息到达但本地状态不正确，请确保你按 oid 进行 upsert，而不是应用增量。

如果你看到重复或乱序消息，请依赖 status 字段和时间戳来解决冲突。重连后始终与 info API 进行对账。有关错误处理，请参阅 Hyperliquid 订单拒绝处理。

• 验证订阅格式和用户地址。
• 检查 WebSocket 连接和速率限制。
• 按 oid 进行 upsert；不要应用增量。
• 重连时与 info API 对账。

后续步骤与更多资源

要加深理解，请探索 OnFinality Learn 中心，获取更多关于 Hyperliquid 和 WebSocket 机制的指南。如果你的应用程序需要可靠的 RPC 端点，请考虑 API 服务并查看 RPC 定价以了解选项。有关 Hyperliquid 端点的完整列表，请参阅 Hyperliquid RPC 端点（RPC Assistant）。

你还可以查看官方 Hyperliquid WebSocket 订阅文档和 info 端点文档以获取最新详细信息。始终针对实时 API 测试你的实现，以确保兼容性。

• 在 OnFinality Learn 上探索更多指南。
• 考虑使用 OnFinality API 服务获取可靠端点。
• 查看官方 Hyperliquid 文档以获取更新。