Hyperliquid 과거 데이터 가져오기: API 활용 방법
- hyperliquid historical data
- hyperliquid data api
- hyperliquid 과거 데이터
- hyperliquid 캔들/K라인 데이터
- hyperliquid 펀딩비 히스토리
퀀트 리서치의 출발점은 데이터입니다. 매매 전략을 백테스트하거나, 펀딩비 패턴을 분석하거나, 시장 미시구조를 연구하려면 신뢰할 수 있고 충분히 긴 과거 데이터가 필요해요.
Hyperliquid는 온체인 무기한 선물 거래소로, REST API를 통해 캔들 데이터(OHLCV), 펀딩비 히스토리, 체결 내역, 주문 체결 상세, 청산 이벤트 등 다양한 과거 데이터를 제공합니다. 이 글에서는 Hyperliquid 과거 데이터를 가져오는 API 방식, 주요 파라미터, 페이지네이션 전략, 로컬 저장 방법을 정리합니다. 사용자별 비공개 데이터처럼 인증이 필요한 경우에는 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()
# 예시: 최근 7일간 BTC 1시간봉 가져오기
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)
반환 필드
각 캔들은 일반적으로 다음 필드를 포함합니다. 실제 필드명은 Hyperliquid 공식 문서를 기준으로 확인해야 합니다.
t: 캔들 시작 시간, 밀리초 타임스탬프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
# 다음 페이지는 마지막 캔들의 타임스탬프 + 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()
반환 데이터에는 각 정산 주기별 펀딩비와 해당 타임스탬프가 포함됩니다. 이 데이터는 다음과 같은 분석에 활용할 수 있습니다.
- 롱/숏 수요 변화 추적
- 과열 또는 공포 구간 식별
- 장기 포지션 보유 비용 계산
- 펀딩비 기반 전략의 백테스트
사용자 체결 내역과 주문 히스토리
사용자별 비공개 데이터에 접근하는 API는 지갑 주소가 필요하며, 일부 요청은 서명 인증이 필요할 수 있습니다. 이때 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})
CSV는 확인과 공유가 쉽지만, 데이터가 커지면 조회 속도와 중복 관리에 한계가 있습니다.
데이터베이스에 저장하기
대규모 데이터나 반복 조회가 필요한 경우에는 SQLite 또는 PostgreSQL을 권장합니다. 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에는 요청 빈도 제한이 있습니다. 정확한 제한은 이 글 작성 시점이 아니라 항상 Hyperliquid 공식 문서를 기준으로 확인해야 합니다. 실무적으로는 다음 방식을 권장합니다.
- 반복 요청 사이에 적절한 지연을 둡니다. 보통 200ms~500ms 정도가 출발점이 될 수 있습니다.
- HTTP 429가 발생하면 즉시 재시도하지 말고, 지수 백오프 방식으로 대기 후 재시도합니다.
- 대량의 과거 데이터는 가능하면 트래픽이 낮은 시간대에 수집합니다.
- 이미 가져온 구간은 로컬에 캐시해 같은 시간대를 반복 요청하지 않도록 합니다.
- 실시간 주문·거래용 API와 대량 데이터 수집 작업이 서로 영향을 주지 않도록 분리합니다.
다른 데이터 소스와 비교
Hyperliquid 네이티브 API의 장점은 거래소 원천 데이터에 직접 접근할 수 있다는 점입니다. 지연이 낮고, Hyperliquid 시장만 분석할 때는 가장 직관적인 선택입니다.
다만 여러 거래소를 함께 비교하는 리서치라면 다른 데이터 소스도 함께 사용할 수 있습니다. dYdX 문서와 GMX 문서도 각각의 과거 데이터 인터페이스를 제공하며, API 설계는 다르지만 캔들, 펀딩비, 체결, 청산이라는 기본 개념은 유사합니다.
OneKey Perps와 함께 활용하기
과거 데이터 분석은 전략의 가설을 세우고 검증하는 데 유용합니다. 다만 백테스트 결과가 실제 성과를 보장하지는 않습니다. 실거래로 넘어갈 때는 주문 실행, 수수료, 슬리피지, 레버리지, 청산 위험까지 함께 고려해야 합니다.
OneKey Perps는 데이터 분석에서 얻은 인사이트를 실제 온체인 무기한 선물 거래 워크플로로 연결하는 실용적인 선택지입니다. OneKey 지갑에서 계정을 안전하게 관리하고, 필요한 경우 OneKey 하드웨어 지갑으로 서명 보안을 강화한 뒤, OneKey Perps를 통해 포지션을 확인하고 거래할 수 있습니다.
아직 OneKey를 사용하고 있지 않다면 OneKey 앱을 다운로드해 지갑을 설정하고, OneKey Perps에서 Hyperliquid 기반 무기한 선물 거래 흐름을 직접 확인해 보세요. 단, 거래 전에는 반드시 소액으로 테스트하고 위험 한도를 먼저 정하는 것이 좋습니다.
자주 묻는 질문
Q1. K라인 데이터의 최소 시간 단위는 무엇인가요?
Hyperliquid 공식 문서의 candleSnapshot 설명을 기준으로 확인해야 합니다. 일반적으로 분봉, 시간봉, 일봉 등 여러 interval이 제공되지만, 실제 지원 값은 문서와 API 응답을 기준으로 해야 합니다. 잘못된 interval을 넣으면 API가 오류를 반환할 수 있습니다.
Q2. 과거 데이터는 얼마나 오래 전까지 가져올 수 있나요?
원칙적으로 Hyperliquid에 시장이 존재한 이후의 데이터는 API로 조회할 수 있습니다. 다만 실제 조회 가능 범위는 각 마켓의 상장 시점과 데이터 존재 여부에 따라 달라집니다. 특정 구간에 데이터가 없으면 빈 배열이 반환될 수 있습니다.
Q3. 대량의 과거 데이터를 가져오는 데 얼마나 걸리나요?
기간, 시간 간격, 페이지네이션 방식, 레이트 리밋에 따라 달라집니다. 예를 들어 1시간봉 전체 히스토리를 가져온다면 수분에서 수십 분이 걸릴 수 있습니다. 매번 전체 데이터를 다시 받기보다는 데이터베이스에 저장한 뒤 증분 업데이트하는 방식이 효율적입니다.
Q4. OneKey 지갑은 데이터 수집에서 어떤 역할을 하나요?
캔들, 펀딩비 같은 공개 시장 데이터는 인증 없이 접근할 수 있습니다. 반면 사용자 체결 내역, 주문 기록처럼 계정과 관련된 비공개 데이터는 서명 인증이 필요할 수 있습니다. OneKey 하드웨어 지갑은 이런 인증 요청에 안전한 서명을 제공해 개인키가 스크립트나 서버로 노출되는 위험을 줄여줍니다.
Q5. 데이터 공백(gap)은 어떻게 처리해야 하나요?
네트워크 오류, API 장애, 레이트 리밋 등으로 일부 시간대 데이터가 누락될 수 있습니다. 각 수집 작업의 시작·종료 시간을 기록하고, 데이터베이스에서 시간 간격이 비는 구간을 주기적으로 스캔해 다시 보충하는 것이 좋습니다. 백테스트에서 데이터 공백은 신호 왜곡으로 이어질 수 있으므로, 사용 전 무결성 검사를 반드시 수행해야 합니다.
마무리
Hyperliquid 과거 데이터 API를 활용하면 캔들, 펀딩비, 사용자 체결, 청산 이벤트까지 다양한 데이터를 Python 코드 몇 줄로 수집할 수 있습니다. 여기에 CSV나 데이터베이스 저장 구조를 더하면 백테스트와 리서치에 필요한 데이터 파이프라인을 만들 수 있습니다.
인증이 필요한 계정 데이터까지 다룬다면 OneKey 하드웨어 지갑의 보안 서명 기능을 함께 사용하는 것이 좋습니다. 그리고 분석 결과를 실제 거래 흐름으로 연결하고 싶다면 OneKey 앱을 다운로드한 뒤 OneKey Perps에서 포지션 관리와 무기한 선물 거래 워크플로를 확인해 보세요.
위험 고지: 과거 데이터는 과거 시장 상황만 보여줄 뿐 미래 성과를 보장하지 않습니다. 과거 데이터 기반 퀀트 전략은 과최적화 위험이 있으며, 실거래 결과는 백테스트와 크게 다를 수 있습니다. 무기한 선물 거래는 레버리지와 청산 위험이 큰 고위험 상품이며 원금 손실이 발생할 수 있습니다. 이 글은 기술 학습 목적의 정보이며, 법률·세무·투자 자문이 아닙니다.
