从 Hyperliquid 拉历史数据：API 方法
-
hyperliquid historical data
-
hyperliquid data api
-
hyperliquid 历史数据
-
hyperliquid k线数据
-
hyperliquid 资金费率历史
locale: zh-CN
量化研究的基石是数据。无论是回测交易策略、分析资金费率规律，还是研究市场微观结构，都需要可靠、完整的历史数据作为原材料。Hyperliquid 作为链上永续合约交易所，通过其 REST API 提供了丰富的历史数据接口，涵盖 K 线（OHLCV）、资金费率、成交记录、订单成交明细和清算事件等。本文将系统梳理各类历史数据的获取方法、参数说明、分页策略，以及本地存储的最佳实践。需要认证接口的场景，OneKey 硬件钱包可以提供安全的签名支持。
Hyperliquid 历史数据 API 概览
参考 Hyperliquid 官方文档，历史数据接口主要通过 POST /info 端点访问，通过请求体中的 type 字段区分不同数据类型。以下是核心数据类型汇总：
所有时间戳均使用毫秒级 Unix 时间戳格式（13 位整数）。
K 线数据（OHLCV）获取
请求格式
import requests
BASE_URL = "https://api.hyperliquid.xyz"
def fetch_candles(coin, interval, start_ms, end_ms):
"""
coin : 交易对，如 "BTC"
interval : 时间粒度，如 "1m", "5m", "1h", "1d"
start_ms : 开始时间（毫秒时间戳）
end_ms : 结束时间（毫秒时间戳）
"""
payload = {
"type": "candleSnapshot",
"req": {
"coin": coin,
"interval": interval,
"startTime": start_ms,
"endTime": end_ms
}
}
resp = requests.post(f"{BASE_URL}/info", json=payload)
resp.raise_for_status()
return resp.json()
示例：获取 BTC 近 7 天的 1 小时 K 线
import time
end_ms = int(time.time() * 1000)
start_ms = end_ms - 7 * 24 * 3600 * 1000
candles = fetch_candles("BTC", "1h", start_ms, end_ms)
返回字段说明
每根 K 线包含以下字段（字段名以官方文档为准）：
t：K 线开始时间（毫秒时间戳）
o：开盘价（open）
h：最高价（high）
l：最低价（low）
c：收盘价（close）
v：成交量（volume）
n：成交笔数
分页策略
单次请求通常有返回条数上限。对于长时间范围的数据，需要分页拉取：
def fetch_candles_paginated(coin, interval, start_ms, end_ms, page_size_ms):
"""
将时间范围切分为多段，逐段拉取并合并。
page_size_ms：每段时间跨度（毫秒），根据 interval 调整。
"""
all_candles = []
cursor = start_ms
while cursor < end_ms:
batch_end = min(cursor + page_size_ms, end_ms)
batch = fetch_candles(coin, interval, cursor, batch_end)
all_candles.extend(batch)
if not batch:
break
下一页从最后一根 K 线的时间戳 + 1 开始
cursor = batch[-1]["t"] + 1
time.sleep(0.2) # 避免触发限速
return all_candles
资金费率历史
资金费率是永续合约的核心机制，历史资金费率数据对于研究市场情绪、设计套利策略都很有价值：
def fetch_funding_history(coin, start_ms, end_ms):
payload = {
"type": "fundingHistory",
"req": {
"coin": coin,
"startTime": start_ms,
"endTime": end_ms
}
}
resp = requests.post(f"{BASE_URL}/info", json=payload)
resp.raise_for_status()
return resp.json()
返回数据包含每个结算周期的资金费率值和对应时间戳。资金费率历史可以用于：分析多空比变化趋势、识别极端情绪信号、计算持仓成本。
用户成交记录与订单历史
涉及用户私有数据的接口需要提供钱包地址，部分接口还需要签名认证。OneKey 硬件钱包可以安全地为这类认证请求提供签名，私钥始终存储在硬件安全元件中，不会暴露给查询脚本。
def fetch_user_fills(address, start_ms, end_ms):
payload = {
"type": "userFills",
"req": {
"user": address,
"startTime": start_ms,
"endTime": end_ms
}
}
resp = requests.post(f"{BASE_URL}/info", json=payload)
resp.raise_for_status()
return resp.json()
成交记录包含订单 ID、方向、成交价、成交量、手续费等字段，是计算实际盈亏、评估策略执行质量的基础数据。
清算记录
市场级别的清算数据有助于研究市场结构和极端行情特征：
def fetch_liquidations(start_ms, end_ms):
payload = {
"type": "liquidations",
"req": {
"startTime": start_ms,
"endTime": end_ms
}
}
resp = requests.post(f"{BASE_URL}/info", json=payload)
resp.raise_for_status()
return resp.json()
数据存储：CSV 与数据库
存储为 CSV
快速原型阶段，CSV 是最简便的存储方式：
import csv
def save_candles_to_csv(candles, filepath):
if not candles:
return
fieldnames = ["t", "o", "h", "l", "c", "v", "n"]
with open(filepath, "w", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fieldnames)
writer.writeheader()
for candle in candles:
writer.writerow({k: candle.get(k, "") for k in fieldnames})
存储到数据库
对于大规模数据或需要高效查询的场景，建议使用 SQLite（单机）或 PostgreSQL（生产环境）：
import sqlite3
def init_db(db_path):
conn = sqlite3.connect(db_path)
conn.execute("""
CREATE TABLE IF NOT EXISTS candles (
coin TEXT,
interval TEXT,
t INTEGER,
o REAL,
h REAL,
l REAL,
c REAL,
v REAL,
n INTEGER,
PRIMARY KEY (coin, interval, t)
)
""")
conn.commit()
return conn
def insert_candles(conn, coin, interval, candles):
rows = [(coin, interval, c["t"], c["o"], c["h"], c["l"], c["c"], c["v"], c["n"]) for c in candles]
conn.executemany(
"INSERT OR IGNORE INTO candles VALUES (?,?,?,?,?,?,?,?,?)",
rows
)
conn.commit()
PRIMARY KEY (coin, interval, t) 确保重复拉取不会导致数据重复插入，便于增量更新。
限速与注意事项
Hyperliquid API 对请求频率有限制，截至本文请以 官方文档 为准。实践建议：
在循环请求之间加入适当延迟（建议 200ms–500ms）
实现指数退避重试机制，遇到 HTTP 429 时自动等待后重试
优先在非高峰时段批量拉取历史数据，减少对实时交易 API 的竞争
本地缓存已拉取的数据，避免重复请求相同时间段
与其他数据源对比
Hyperliquid 原生 API 的优势是数据最权威、延迟最低；对于需要跨交易所数据的研究项目，可以结合其他来源。dYdX 文档 和 GMX 文档 也提供了各自的历史数据接口，接口设计风格与 Hyperliquid 有所差异，但基本概念相通。
常见问题
Q1：K 线数据的最小时间粒度是多少？
答：参考 Hyperliquid 官方文档 中的 candleSnapshot 接口说明，截至本文支持多种时间粒度，包括分钟级、小时级和日级。具体支持的 interval 值以文档为准，API 会在参数不合法时返回错误信息。
Q2：历史数据能追溯多远？
答：Hyperliquid 上线以来的数据原则上均可通过 API 获取，实际可追溯范围取决于各市场的上线时间。截至本文请以实际请求结果为准，若某个时间段无数据，API 会返回空数组。
Q3：拉取大量历史数据大约需要多长时间？
答：这取决于时间范围、时间粒度和分页策略。以 1 小时 K 线、全量历史为例，考虑限速约束，合理估计需要数分钟到数十分钟不等。建议将数据落库后增量更新，避免每次重新全量拉取。
Q4：OneKey 钱包在数据获取中起什么作用？
答：公开的行情数据（K 线、资金费率等）无需认证即可访问。涉及用户私有数据的接口（如历史成交、订单记录）可能需要签名验证。OneKey 硬件钱包 可以为这类请求提供安全签名，确保私钥不被数据采集脚本所在的服务器获取。
Q5：如何处理数据缺口（gap）？
答：网络错误或 API 故障可能导致部分时间段数据缺失。建议在入库时记录每次拉取的时间范围，定期扫描数据库中的时间缺口，并针对缺口重新补拉。对于回测系统，数据缺口会导致信号失真，务必在使用前做完整性检验。
结语
Hyperliquid 的历史数据 API 为量化研究者提供了坚实的数据基础。从 K 线到资金费率，从用户成交到清算记录，只需几十行 Python 代码就能构建起完整的数据采集管道。结合 OneKey 硬件钱包 的安全签名能力，你可以在保护账户安全的同时，充分利用 Hyperliquid 的数据资源。
如果你希望在丰富的数据分析基础上直接参与交易，OneKey Perps 是连接数据洞察与实盘操作的最便捷通道。访问 Hyperliquid App 开始你的链上交易研究之旅。
风险提示：历史数据仅反映过去的市场状况，不代表未来表现。基于历史数据的量化策略存在过度拟合风险，实盘表现可能与回测结果显著不同。永续合约交易具有高风险特性，可能导致资金损失。本文内容仅供技术学习参考，不构成任何形式的投资建议。
