Hyperliquid 펀딩비 히스토리 API 완전 가이드
펀딩비(Funding Rate)는 무기한 선물(Perpetual) 시장의 핵심 가격 조정 메커니즘입니다. 롱과 숏 포지션을 보유하는 비용에 직접적인 영향을 주기 때문에, 퀀트 리서처, 펀딩비 차익거래 트레이더, 리스크 관리팀에게 과거 펀딩비 데이터를 빠르고 대량으로 가져오는 능력은 매우 중요합니다.
Hyperliquid는 공개 시장 데이터를 조회할 수 있는 오픈 API를 제공하며, 상당수 정보는 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: 요청 타입입니다. 펀딩비 히스토리는fundingHistory를 사용합니다.coin: 조회할 코인 심볼입니다. 예:BTC,ETH,SOLstartTime: 조회 시작 시각입니다. 밀리초 단위 Unix 타임스탬프여야 합니다.endTime: 조회 종료 시각입니다. 생략하면startTime부터 현재까지의 데이터를 반환하지만, 단일 요청 반환 개수 제한의 영향을 받을 수 있습니다.
응답 데이터 형식
API는 배열을 반환하며, 각 항목은 대략 다음과 같은 구조입니다.
[
{
"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 # hourly settlement
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
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",
)
이렇게 하면 여러 종목의 펀딩비 흐름을 같은 시간축에서 비교할 수 있습니다. 예를 들어 특정 코인의 펀딩비가 다른 종목 대비 지속적으로 높거나 낮은지 확인하는 데 유용합니다.
데이터 저장 팁
펀딩비 데이터를 자주 사용한다면 매번 API를 호출하기보다 로컬 데이터베이스에 캐싱하는 것이 좋습니다. SQLite나 TimescaleDB 같은 저장소를 사용할 수 있습니다.
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 유출이나 피싱 공격으로 인한 자산 손실 위험을 줄이는 데 도움을 줍니다.
펀딩비 데이터를 분석해 차익거래 또는 현물-무기한 선물 헤지 기회를 검토한 뒤 실제 포지션을 실행해야 한다면, OneKey Perps를 통해 Hyperliquid 무기한 선물에 접근할 수 있습니다. 하드웨어 지갑 기반의 개인키 보호와 함께 보다 매끄러운 Perps 거래 흐름을 사용할 수 있다는 점이 실무적으로 유용합니다.
OneKey를 다운로드해 지갑을 설정하고, OneKey Perps에서 Hyperliquid 기반 무기한 선물 거래 워크플로를 직접 확인해 보세요. 단, 모든 거래 결정은 본인의 리스크 판단에 따라 신중하게 진행해야 합니다.
자주 묻는 질문
Q1. Hyperliquid 펀딩비 API를 사용하려면 계정 가입이 필요한가요?
아니요. Info Endpoint는 공개되어 있으며 API Key나 계정 없이도 호출할 수 있습니다. 과거 펀딩비 데이터도 직접 조회할 수 있습니다.
Q2. 한 번의 요청으로 최대 몇 개의 데이터를 가져올 수 있나요?
Hyperliquid 공식 문서에서 단일 요청의 최대 반환 개수를 명확히 설명하지는 않습니다. 실제로 긴 기간을 한 번에 요청하면 데이터가 잘릴 수 있으므로, 7일 단위처럼 기간을 나누어 조회하고 코드에서 페이지네이션 또는 반복 조회 로직을 처리하는 방식을 권장합니다.
Q3. 펀딩비가 양수일 때와 음수일 때는 무엇이 다른가요?
펀딩비가 양수이면 롱 포지션 보유자가 숏 포지션 보유자에게 비용을 지급합니다. 반대로 펀딩비가 음수이면 숏 포지션 보유자가 롱 포지션 보유자에게 비용을 지급합니다. 강세장이나 위험 선호가 높은 시장에서는 양수 펀딩비가 더 자주 나타나는 경향이 있으며, 이는 시장 전반의 롱 프리미엄을 반영할 수 있습니다.
Q4. 펀딩비 히스토리로 차익거래 기회를 어떻게 평가하나요?
과거 펀딩비의 평균, 표준편차, 백분위수를 계산해 현재 펀딩비가 과거 대비 얼마나 높은지 비교할 수 있습니다. 예를 들어 현재 펀딩비가 과거 평균보다 1표준편차 이상 높다면, 이론적으로는 무기한 선물을 숏하고 현물을 롱하는 헤지 전략을 검토할 수 있습니다. 다만 이는 재무 조언이 아니며, 슬리피지, 수수료, 베이시스 변동, 청산 위험을 반드시 고려해야 합니다.
Q5. API 응답의 premium과 fundingRate는 어떻게 다른가요?
premium은 마크 가격과 현물 지수 가격 간의 실시간 프리미엄으로, 다음 펀딩비를 계산하는 데 사용되는 주요 입력값입니다. fundingRate는 이미 정산된 해당 기간의 펀딩비이며, 프리미엄 평균과 이자율 기준(Interest Rate)의 영향을 함께 받습니다.
리스크 안내
이 글은 기술 학습과 API 활용 참고용이며, 투자 또는 재무 조언이 아닙니다. 무기한 선물 거래는 높은 위험을 동반하며, 과거 펀딩비 데이터가 미래 수익을 보장하지 않습니다. 거래 전 관련 위험을 충분히 이해하고 신중하게 결정하시기 바랍니다.
