Hyperliquid 資金費率歷史 API 完整指南
資金費率（Funding Rate）是永續合約市場的核心定價機制，會直接影響好倉同淡倉雙方的持倉成本。對量化策略研究員、套利交易者以至風險管理團隊來講，能夠快速、批量取得歷史資金費率數據，是一項基本能力。Hyperliquid 提供開放資訊查詢接口，無需 API Key 都可以存取大量公開市場數據。本文會系統地介紹如何調用 Hyperliquid 官方 API 取得資金費率歷史，並提供 Python 範例，幫你快速上手。
為何資金費率歷史數據如此重要
資金費率歷史數據有以下幾種常見用途：
- 識別市場長期偏向好倉或淡倉的結構，輔助趨勢判斷
- 計算資金費率套利（Funding Arbitrage）的歷史期望收益
- 建立資金費率因子，用於量化揀幣或倉位管理模型
- 回測現貨－永續合約對沖策略在不同費率環境下的表現
Hyperliquid 的架構建基於鏈上訂單簿，所有交易及結算數據均可在鏈上驗證，令歷史數據具備較高可信度。
Hyperliquid API 基礎架構
Hyperliquid 提供兩類接口：
- Info Endpoint（只讀）：用於查詢市場數據、帳戶狀態、歷史紀錄，無需簽名
- Exchange Endpoint：用於落盤、撤單等寫入操作，需要錢包簽名
資金費率歷史查詢屬於只讀操作，使用 Info Endpoint，地址為：
POST https://api.hyperliquid.xyz/info
所有請求均為 POST，Body 為 JSON，Content-Type 為 application/json。
查詢資金費率歷史的請求結構
如要取得指定幣種的資金費率歷史，可使用 fundingHistory 類型：
{
"type": "fundingHistory",
"coin": "BTC",
"startTime": 1700000000000,
"endTime": 1700086400000
}
字段說明：
type：固定為fundingHistorycoin：幣種代號，例如BTC、ETH、SOLstartTime：開始時間，毫秒級 Unix 時間戳endTime：結束時間，毫秒級 Unix 時間戳
時間戳必須為毫秒級 Unix 時間戳。如果不傳入 endTime，接口會返回由 startTime 至今的數據，但會受單次返回條數上限影響。
響應數據格式
接口會返回一個陣列，每條紀錄包含：
[
{
"coin": "BTC",
"fundingRate": "0.0001",
"premium": "0.00012",
"time": 1700000000000
}
]
Hyperliquid 的資金費率每小時結算一次，具體機制可參考官方文件的 Perpetuals 章節。
Python 完整範例
以下程式碼示範如何拉取 BTC 最近 30 日的資金費率歷史，並計算簡單年化數值：
import requests
import time
import pandas as pd
ENDPOINT = "https://api.hyperliquid.xyz/info"
def get_funding_history(coin: str, days: int = 30) -> pd.DataFrame:
end_ms = int(time.time() * 1000)
start_ms = end_ms - days * 24 * 3600 * 1000
payload = {
"type": "fundingHistory",
"coin": coin,
"startTime": start_ms,
"endTime": end_ms,
}
resp = requests.post(ENDPOINT, json=payload, timeout=15)
resp.raise_for_status()
data = resp.json()
df = pd.DataFrame(data)
df["time"] = pd.to_datetime(df["time"], unit="ms", utc=True)
df["fundingRate"] = df["fundingRate"].astype(float)
df["annualized"] = df["fundingRate"] * 24 * 365 # 每小時結算
return df.sort_values("time")
if __name__ == "__main__":
df = get_funding_history("BTC", days=30)
print(df.tail(10).to_string(index=False))
print(f"\n30 日平均年化資金費率: {df['annualized'].mean():.2%}")
注意：以上年化計算只屬簡單線性外推，實際收益會受複利、滑點、借幣成本、交易費及市場流動性等因素影響。
批量拉取多個幣種
如果需要同時取得多個幣種的資金費率，可以並發調用：
import concurrent.futures
import pandas as pd
COINS = ["BTC", "ETH", "SOL", "ARB", "DOGE"]
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
futures = {executor.submit(get_funding_history, c, 7): c for c in COINS}
results = {}
for future in concurrent.futures.as_completed(futures):
coin = futures[future]
results[coin] = future.result()
# 合併成一個 DataFrame
combined = pd.concat(results.values(), ignore_index=True)
pivot = combined.pivot_table(
index="time",
columns="coin",
values="fundingRate",
aggfunc="mean"
)
實際應用時，建議加入錯誤處理、重試機制，以及對空數據或格式變化的檢查，避免單一請求失敗影響整個數據流程。
數據儲存建議
對於高頻使用場景，建議將歷史數據快取到本地資料庫，例如 SQLite 或 TimescaleDB，避免重複請求 API：
import sqlite3
conn = sqlite3.connect("funding_rates.db")
df.to_sql("funding_history", conn, if_exists="append", index=False)
conn.close()
如果你需要同時處理交易操作，Hyperliquid 官方 GitHub 亦提供 Python SDK，封裝了認證及簽名流程，較適合需要下單、撤單等功能的開發者使用。
在 OneKey 錢包管理 Hyperliquid 資產
數據分析只是第一步，真正進行資金管理時，仍然需要安全可靠的錢包工具。OneKey 硬件錢包支援連接 Hyperliquid，私鑰始終保存在離線設備中，有助減低因 API Key 外洩、釣魚網站或惡意授權而導致資產損失的風險。
當你透過數據分析發現潛在套利機會，需要在 Hyperliquid 上執行資金費率套利、現貨對沖或其他永續合約策略時，可以使用 OneKey Perps 作為實際操作入口，在硬件級私鑰保護下完成更順暢的永續合約交互。
你可以下載並試用 OneKey，連接錢包後進入 OneKey Perps，按自己的研究結果及風險承受能力管理加密貨幣倉位。
常見問題
Q1：Hyperliquid 資金費率 API 需要註冊帳戶嗎？
不需要。Info Endpoint 完全公開，無需 API Key 或帳戶，任何人都可以直接調用以取得歷史資金費率數據。
Q2：單次請求最多可以取得多少條紀錄？
Hyperliquid 官方文件未有明確列出單次上限。實際測試中，較長時間範圍的請求可能會被截斷。建議分段查詢，例如每次 7 日，並在程式中處理分頁或分段拼接邏輯。
Q3：資金費率是正數還是負數，哪種情況較常見？
當資金費率為正數時，好倉向淡倉支付費用；當資金費率為負數時，淡倉向好倉支付費用。在牛市或高風險偏好市場中，正資金費率較常見，通常反映市場整體存在好倉溢價。
Q4：如何用資金費率歷史評估套利機會？
可以計算歷史資金費率的平均值、標準差及百分位。當當前費率明顯高於歷史平均值時，例如超過 1 個標準差，做淡永續合約同時做好友現貨的對沖策略，理論上可能具備正期望。不過，這並不構成財務或投資建議，實際結果會受滑點、槓桿、借幣成本、交易費及強平風險等因素影響。
Q5：API 返回的 premium 字段和 fundingRate 有甚麼分別？
premium 是標記價格與現貨指數價格之間的即時溢價，是計算下一期資金費率的基礎輸入；fundingRate 則是已結算的當期費率，會受 premium 均值及利率基準（Interest Rate）共同影響。
風險提示
本文僅供技術學習及研究參考，不構成任何投資、法律或財務建議。加密貨幣及永續合約交易存在高風險，使用槓桿可能放大虧損；資金費率歷史表現亦不代表未來收益。請在充分了解相關風險後，審慎作出決策。
