Hyperliquid 历史数据与市场数据 API：查询交易、OHLCV、资金费和订单簿历史

直接回答：如何获取 Hyperliquid 历史数据

要检索 Hyperliquid 历史市场数据以进行分析和回测，您需要使用两个互补的接口：原生 Hyperliquid API（HTTP POST 到 /info 和 WebSocket 订阅）用于实时和近期状态，以及单独发布的历史数据档案（交易、资金费和 OHLCV 文件）用于更深层的历史。原生 API 提供近期交易、K线、资金费和订单簿快照，但不提供完整的历史订单簿深度或非常旧的 K线；对于这些，您需要档案或第三方转售商。本指南将逐一介绍每个接口，展示具体的请求/响应示例，并提供决策清单。

本指南的主要来源是官方 Hyperliquid 文档：hyperliquid.gitbook.io。所有端点主机、请求字段和响应结构都在那里有文档说明；对于未记录的特定限制或保留窗口，文档说明它们会变化，因此本指南避免编造数字。

• 原生 API：POST /info 获取交易、K线、资金费和订单簿快照；WebSocket 用于实时订阅。
• 历史档案：公开的交易、资金费和 OHLCV 文件，定期更新，覆盖更长历史。
• 第三方转售商：如 HypeRPC 和 QuickNode 等服务提供扩展数据 API 和 SQL 访问，但它们是独立参考，并非官方。

理解 Hyperliquid 数据 API 接口

Hyperliquid 的 API 分为两大类：直接与验证器通信的原生 API，以及单独生成和托管的历史数据档案。原生 API 进一步分为 HTTP 端点（POST /info）用于查询当前状态和近期历史，以及 WebSocket 端点（ws2 等）用于实时订阅。档案是包含历史交易、资金费率和 OHLCV 数据的文件（通常是压缩的），并按计划更新。

原生 API 非常适合需要最新状态或过去几小时或几天数据的应用程序。例如，您可以获取某个币的最后 500 笔交易、当前资金费率或订单簿最优买卖盘。然而，原生 API 不提供完整的历史订单簿深度（所有层级随时间变化）或早于特定时期的 K线（具体保留时间未记录；会变化）。对于深度回测，您需要档案。

档案由 Hyperliquid 发布，可供下载。它们涵盖所有永续合约和现货对的交易、资金费和 OHLCV。具体覆盖范围（开始日期、更新频率）在 Hyperliquid 文档页面 中有记录；建议查看该页面以获取最新详情。第三方转售商如 HypeRPC 和 QuickNode 也提供历史数据 API，但它们是独立的，可能具有不同的覆盖范围和定价。

• 原生 API：POST /info（HTTP）和 WebSocket（ws2）用于实时和近期数据。
• 档案：公开的交易、资金费、OHLCV 文件，定期更新。
• 第三方：HypeRPC、QuickNode 等提供扩展 API，但并非官方。

使用原生 /info API 获取近期市场数据

/info 端点是一个 HTTP POST 端点，接受 JSON 请求对象。请求类型在 'type' 字段中指定。对于历史市场数据，最相关的请求类型是 'trades'、'candleSnapshot' 和 'fundingHistory'。响应是对象数组。

例如，要获取 BTC 的近期交易，您发送一个类型为 'trades' 且包含币种符号的请求。响应包含 'time'、'px'、'sz'、'side' 和 'tid' 等字段。对于 OHLCV，您使用 'candleSnapshot'，参数包括 'req'（间隔）、'coin'、'startTime' 和 'endTime'。响应包含 't'、'o'、'h'、'l'、'c'、'v' 和 'n'（交易数量）。

确切的请求和响应结构在 Hyperliquid API 文档 中有记录。以下是交易和 K线的具体示例。

// 示例：获取 BTC 的近期交易（使用 Node.js fetch）
const response = await fetch('https://api.hyperliquid.xyz/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ type: 'trades', coin: 'BTC' })
});
const trades = await response.json();
console.log(trades);
// 预期输出：交易对象数组，例如：
// [{"time":1730000000000,"px":"65000.0","sz":"0.1","side":"B","tid":123456,"coin":"BTC"}]

// 示例：获取 BTC 在特定时间范围内的 1 小时 K线
const candlesResponse = await fetch('https://api.hyperliquid.xyz/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'candleSnapshot',
    req: { coin: 'BTC', interval: '1h', startTime: 1730000000000, endTime: 1730003600000 }
  })
});
const candles = await candlesResponse.json();
console.log(candles);
// 预期输出：K线对象数组，例如：
// [{"t":1730000000000,"o":"65000.0","h":"65100.0","l":"64900.0","c":"65050.0","v":"100.0","n":123}]

WebSocket 订阅实时和近期数据

对于实时市场数据，Hyperliquid 提供 WebSocket 端点。主要端点是 wss://api.hyperliquid.xyz/ws，您可以订阅 'trades'、'candle'、'l2Book' 和 'userFills' 等频道。这些订阅会在发生时推送更新，适用于实时监控，但不适用于历史回测。

然而，WebSocket 订阅也可用于随时间累积数据。例如，您可以订阅 'candle' 频道来构建自己的 OHLCV 历史。订阅消息格式在 Hyperliquid WebSocket 文档 中有记录。以下是一个使用 'ws' 包的简单 Node.js 示例。

// Node.js WebSocket 示例（需要 'ws' 包：npm install ws）
const WebSocket = require('ws');
const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');

ws.on('open', () => {
  // 订阅 BTC 的交易
  ws.send(JSON.stringify({ method: 'subscribe', subscription: { type: 'trades', coin: 'BTC' } }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.channel === 'trades') {
    console.log('交易:', msg.data);
    // 每笔交易包含 time、px、sz、side、tid 等字段
  }
});

ws.on('error', (err) => console.error('WebSocket 错误:', err));

访问历史档案以获取深层历史

当您需要比原生 API 提供的数据更旧的数据，或需要完整的订单簿深度时，您必须使用历史档案。Hyperliquid 在公共 URL 上发布这些档案（在 Hyperliquid 文档 中有记录）。档案通常是压缩文件（例如 .csv.gz），您可以下载并在本地处理。

档案包括交易数据、资金费率和 OHLCV 数据。确切的文件命名和更新计划在 Hyperliquid 文档页面有记录。例如，交易档案可能按日期和币种组织。要使用它们，您需要下载相关文件并解析。

第三方转售商如 HypeRPC 和 QuickNode 也提供历史数据 API，可能通过 SQL 或 REST 提供更便捷的访问。这些是独立服务，可能具有不同的覆盖范围和定价；请务必查看其文档。

• 查看官方 Hyperliquid 文档以获取档案 URL 和格式。
• 下载并解析文件以进行本地回测。
• 考虑第三方转售商以方便使用，但验证其数据质量。

决策清单：根据数据需求选择接口

要选择合适的 API 接口，请考虑您需要的数据类型和年龄。下表将常见数据需求映射到推荐的接口。

对于近期交易（最近几分钟），使用原生 API 或 WebSocket。对于 K线，原生 API 提供近期 K线，但对于更旧的 K线，请使用档案。资金费历史可通过原生 API 获取近期数据，但对于长期资金费分析，请使用档案。订单簿最优买卖盘可通过原生 API 获取，但完整深度历史不可用；如果可用，请使用档案或转售商。

• 近期交易（最近几分钟）：原生 API（类型 'trades'）或 WebSocket。
• 历史交易（数天/数周）：档案。
• 近期 OHLCV K线：原生 API（类型 'candleSnapshot'）。
• 历史 OHLCV：档案。
• 资金费历史：原生 API（类型 'fundingHistory'）获取近期；档案获取长期。
• 订单簿最优买卖盘：原生 API（类型 'l2Book'）或 WebSocket。
• 完整订单簿深度历史：原生 API 不可用；检查档案或第三方。

常见故障与故障排除

在使用 Hyperliquid 数据 API 时，您可能会遇到速率限制、请求格式错误或数据缺失等问题。以下是常见故障及解决方法。

速率限制：Hyperliquid API 具有速率限制，因端点和订阅类型而异。如果您收到 HTTP 429 或 WebSocket 断开，您可能超出了限制。请参阅 Hyperliquid API 速率限制指南 了解详情和最佳实践。

无效请求：确保您的请求 JSON 符合文档中的模式。例如，'candleSnapshot' 请求需要 'req' 对象，包含 'coin'、'interval'，以及可选的 'startTime' 和 'endTime'。缺少字段或类型错误将导致错误。

未找到数据：如果您请求不存在的币种或没有数据的时间范围的交易，API 可能返回空数组。请检查币种符号和时间范围。

WebSocket 连接问题：如果您的 WebSocket 连接断开，请实现具有指数退避的重连逻辑。此外，确保发送正确的订阅消息格式。

• HTTP 429：放慢请求速度并遵守速率限制。
• 无效 JSON：根据文档验证您的请求。
• 空响应：检查币种符号和时间范围。
• WebSocket 断开：实现重连逻辑。

权衡与限制

原生 API 快速且易于使用，但有其局限性：它仅提供有限数量的历史数据（具体保留时间未记录），并且不提供完整的订单簿深度历史。档案提供深层历史，但需要下载和处理大型文件，这可能耗时且需要大量存储。

第三方转售商可能提供更便捷的访问，但它们是独立的，可能具有不同的数据质量、覆盖范围和定价。尽可能验证官方来源的数据。

对于生产应用程序，请考虑组合使用：使用原生 API 获取实时数据，使用档案进行历史回测。对于高频数据需求，您可能需要使用 WebSocket 订阅构建自己的数据收集系统。

后续步骤与进一步阅读

既然您了解了 Hyperliquid 数据 API 接口，您可以开始构建自己的数据管道。有关 Hyperliquid 基础设施的更多背景，请参阅 Hyperliquid 网络概述。如果您对 RPC 端点感兴趣，请查看 Hyperliquid RPC 端点（RPC Assistant）。相关指南请参阅 Hyperliquid WebSocket 订阅、Hyperliquid RPC 延迟 和 Hyperliquid API 速率限制。

有关一般 API 服务信息，请访问 API 服务页面 和 RPC 定价。浏览 OnFinality Learn 中心 获取更多教程和指南。

• 探索官方 Hyperliquid 文档以获取最新 API 详情。
• 查看第三方转售商如 HypeRPC 和 QuickNode 以获取扩展数据服务。
• 加入 Hyperliquid 社区以获取支持和讨论。