從 Hyperliquid 拉取歷史數據：API 方法

2026年5月6日

hyperliquid historical data
hyperliquid data api
hyperliquid 歷史數據
hyperliquid K 線數據
hyperliquid 資金費率歷史

量化研究的基礎是數據。無論你想回測交易策略、分析資金費率規律，還是研究市場微觀結構，都需要可靠而完整的歷史數據作為原材料。Hyperliquid 作為鏈上永續合約交易所，透過 REST API 提供多類歷史數據介面，涵蓋 K 線（OHLCV）、資金費率、成交記錄、訂單成交明細及清算事件等。

本文會整理常見歷史數據的拉取方法、主要參數、分頁策略，以及本地儲存做法。至於涉及認證或簽名的私有數據場景，OneKey 硬件錢包可用作安全簽名工具，避免私鑰暴露於腳本或伺服器環境。

Hyperliquid 歷史數據 API 概覽

參考 Hyperliquid 官方文檔，歷史數據主要透過 POST /info 端點存取，並以請求 body 內的 type 欄位區分不同數據類型。

所有時間戳一般使用毫秒級 Unix timestamp，即 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  : 開始時間，毫秒 timestamp
    end_ms    : 結束時間，毫秒 timestamp
    """
    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 線開始時間，毫秒 timestamp
o：開盤價（open）
h：最高價（high）
l：最低價（low）
c：收盤價（close）
v：成交量（volume）
n：成交筆數

分頁策略

單次請求通常會有返回數量上限。若要拉取較長時間範圍的數據，建議按時間分段請求，再合併結果：

import time

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 不完全相同，但 K 線、成交、資金費率等基本概念相通。

常見問題

Q1：K 線數據的最小時間粒度是多少？

答：請參考 Hyperliquid 官方文檔中 candleSnapshot 介面說明。其支援多種時間粒度，包括分鐘級、小時級及日級。具體可用的 interval 值以文檔及實際 API 返回為準；若參數不合法，API 一般會返回錯誤訊息。

Q2：歷史數據可以追溯到幾耐之前？

答：原則上，市場上線後產生的數據才有機會透過 API 查詢。實際可追溯範圍取決於個別市場的上線時間及 API 可用數據範圍。若某段時間沒有數據，API 可能會返回空陣列。

Q3：拉取大量歷史數據大約需要幾耐？

答：這取決於時間範圍、時間粒度、分頁大小及限速策略。以 1 小時 K 線及較長歷史範圍為例，考慮限速後，可能需要數分鐘至數十分鐘不等。建議先落庫，再定期做增量更新，避免每次都重新全量拉取。

Q4：OneKey 錢包在數據獲取入面有咩作用？

答：公開市場數據，例如 K 線、資金費率等，通常不需要認證即可查詢。涉及用戶私有數據的介面，例如歷史成交、訂單記錄等，可能需要簽名驗證。OneKey 硬件錢包可為這類請求提供安全簽名，降低私鑰被腳本、伺服器或惡意程式接觸的風險。

Q5：如何處理數據缺口（gap）？

答：網絡錯誤、API 臨時異常或限速重試失敗，都可能令部分時間段出現缺口。建議在入庫時記錄每次拉取的時間範圍，定期掃描數據庫中的時間連續性，並針對缺口重新補拉。對回測系統而言，數據缺口會扭曲訊號及績效評估，使用前應先做完整性檢查。

結語

Hyperliquid 的歷史數據 API 為量化研究者提供了實用的數據基礎。由 K 線到資金費率，由用戶成交到清算記錄，透過簡潔的 Python 腳本已可搭建一條基本數據採集管道。若涉及需要簽名的私有數據查詢，配合 OneKey 硬件錢包可在保護私鑰的同時完成認證流程。

如果你希望由數據分析延伸到實盤操作，可以下載並試用 OneKey，在熟悉風險及功能後，透過 OneKey Perps 管理加密貨幣永續合約交易流程。OneKey Perps 可作為由研究、觀察到下單執行之間的實用工作流入口，但任何交易決定都應以你自己的風險承受能力及獨立判斷為準。

風險提示：歷史數據只反映過去市場狀況，不代表未來表現。基於歷史數據建立的量化策略可能存在過度擬合風險，實盤結果或會與回測結果有明顯差異。永續合約及槓桿交易具有高風險，可能導致資金損失。本文只供技術學習及研究參考，不構成法律、稅務、投資或財務建議。