Hyperliquid REST vs WebSocket: 언제 무엇을 써야 할까
Hyperliquid API를 연동할 때 많은 개발자가 가장 먼저 부딪히는 질문이 있어요. “내 전략에는 REST가 맞을까, WebSocket이 맞을까?”
두 인터페이스는 동작 방식부터 적합한 용도까지 완전히 다릅니다. 잘못 선택하면 단순히 대역폭을 낭비하는 수준을 넘어, 전략의 반응 속도가 늦어지고 예상보다 큰 슬리피지가 발생할 수 있어요.
이 글에서는 Hyperliquid REST API와 WebSocket의 작동 원리, 사용해야 하는 상황, 지연 특성, 실무에서 자주 만나는 함정을 정리합니다. 또한 실제 트레이딩 워크플로에서는 OneKey Perps와 OneKey 지갑을 어떻게 함께 활용할 수 있는지도 살펴볼게요.
REST API: 요청하고 응답받는 모델
REST, 즉 Representational State Transfer는 가장 익숙한 HTTP API 방식입니다. 클라이언트가 요청을 보내면 서버가 응답을 반환하고, 기본적으로 하나의 요청-응답 흐름이 끝나면 작업도 종료됩니다.
Hyperliquid의 REST 인터페이스는 크게 두 종류의 엔드포인트로 나눌 수 있습니다.
Info 엔드포인트: /info
/info는 읽기 전용 조회에 사용됩니다. 예를 들어 다음과 같은 데이터를 가져올 수 있어요.
- 현재 마켓 메타데이터
- 과거 체결 내역
- 계정 포지션 스냅샷
- 오더북 스냅샷
- 펀딩비 이력
이런 요청은 서명이 필요하지 않으며, 클라이언트가 비교적 간단하게 호출할 수 있습니다.
Exchange 엔드포인트: /exchange
/exchange는 쓰기 작업에 사용됩니다. 대표적으로 다음 작업이 여기에 해당합니다.
- 주문 제출
- 주문 취소
- 레버리지 변경
- 증거금 조정
이런 요청은 반드시 EIP-712 구조화 서명을 포함해야 합니다. 서버는 서명자가 실제 계정 주소와 일치하는지 검증한 뒤에만 작업을 실행합니다.
REST가 잘 맞는 상황
REST는 “필요할 때 한 번 조회하고, 한 번 응답받으면 되는” 작업에 적합합니다.
예를 들어 전략을 시작할 때 현재 포지션과 계정 상태를 가져오거나, 일정 간격으로 잔고를 확인하거나, 특정 선물/무기한 계약의 펀딩비 이력을 조회하는 경우가 있습니다. 이런 작업은 실시간 스트리밍이 필요하지 않고, 요청을 보낸 시점의 결과만 있으면 충분합니다.
주문과 취소도 REST를 통해 처리합니다. 전략이 실시간 시세를 WebSocket으로 받더라도, 실제 주문 제출은 Hyperliquid의 Exchange 엔드포인트에 REST 방식으로 보내야 합니다. 이 부분은 우회할 수 없는 구조적 요구사항입니다.
대량의 과거 데이터를 가져오는 작업도 REST에 적합합니다. 백테스트를 위해 과거 체결 데이터나 캔들 데이터를 페이지 단위로 반복 조회하는 방식은 실무적으로도 흔히 사용됩니다.
REST의 한계
REST의 본질적인 한계는 “끌어오는 방식”이라는 점입니다. 시장이 언제 변할지 알 수 없기 때문에 클라이언트가 주기적으로 폴링해야 합니다.
예를 들어 100ms마다 오더북을 조회하면 금방 레이트 리밋에 걸릴 수 있습니다. 반대로 1초에 한 번만 조회하면 빠른 장세에서는 전략이 이미 늦게 반응할 수 있어요.
즉, 실시간 시장 변화에 즉각 반응해야 하는 전략에서 REST만으로 고빈도 폴링을 하는 것은 비효율적이고 안정적이지도 않습니다.
WebSocket: 지속 연결과 실시간 푸시
WebSocket은 한 번 연결을 맺은 뒤, 서버가 클라이언트에게 지속적으로 데이터를 푸시할 수 있는 양방향 프로토콜입니다.
Hyperliquid의 WebSocket 엔드포인트는 다음과 같습니다.
wss://api.hyperliquid.xyz/ws
연결을 만든 뒤 클라이언트는 관심 있는 데이터 타입을 구독합니다. 이후 서버는 해당 데이터의 업데이트 이벤트를 계속 보내며, 연결이 끊기거나 클라이언트가 구독을 해제할 때까지 스트림이 유지됩니다.
WebSocket이 잘 맞는 상황
WebSocket의 대표적인 용도는 실시간 오더북 모니터링입니다. l2Book 채널을 구독하면 오더북이 변경될 때마다 업데이트를 받을 수 있어, 전략이 밀리초 단위로 시장 깊이 변화를 감지할 수 있습니다.
실시간 체결 스트림인 trades 채널도 중요합니다. 시장 충격, 체결 속도, 단기 매수·매도 압력 등을 관찰하는 데 유용한 신호가 됩니다.
계정 이벤트 구독인 userEvents 채널은 체결 결과, 청산 알림 등 계정 단위의 중요한 이벤트를 실시간으로 파악하는 데 활용됩니다. 계정 상태를 계속 REST로 폴링하는 부담을 줄일 수 있어요.
펀딩비를 실시간으로 추적해야 하는 전략, 특히 펀딩비 차익거래나 포지션 비용을 민감하게 관리하는 전략에서도 WebSocket은 유용합니다. 다음 폴링 주기를 기다리지 않고 변화가 발생했을 때 즉시 알 수 있기 때문입니다.
WebSocket 사용 시 주의할 점
WebSocket에서 가장 중요한 운영 이슈는 연결 안정성입니다.
네트워크 불안정, 서버 재시작, 장시간 유휴 상태 등으로 연결이 끊길 수 있습니다. 따라서 프로덕션 환경에서는 반드시 다음 로직을 구현해야 합니다.
- ping/pong 기반의 heartbeat
- 자동 재연결
- 재연결 후 전체 채널 재구독
- 끊긴 동안 누락된 데이터 보정
메시지 처리 성능도 중요합니다. 주요 코인의 L2 오더북처럼 업데이트가 매우 잦은 채널을 구독하면 메시지 유입 속도가 빠를 수 있습니다. 클라이언트의 파싱, 큐 처리, 전략 계산 로직이 충분히 빠르지 않으면 메시지가 쌓이고, 결국 “실시간 데이터”가 아니라 “뒤늦게 도착한 데이터”가 됩니다.
REST vs WebSocket 비교
한 줄로 정리하면 이렇습니다.
- 현재 시점의 상태가 필요하면 REST
- 계속 변하는 데이터를 실시간으로 받아야 하면 WebSocket
- 주문·취소 같은 쓰기 작업은 REST
코드 예시 비교
REST로 오더북 스냅샷 조회하기
import requests
response = requests.post(
"https://api.hyperliquid.xyz/info",
json={"type": "l2Book", "coin": "ETH"}
)
book = response.json()
# 현재 시점의 오더북 스냅샷을 가져옵니다.
# 이후 변화는 자동으로 업데이트되지 않습니다.
print(book)
REST 방식은 호출한 순간의 결과만 가져옵니다. 이후 오더북이 바뀌어도 다시 요청하지 않으면 알 수 없습니다.
WebSocket으로 오더북 실시간 업데이트 구독하기
import asyncio
import websockets
import json
async def stream_orderbook():
uri = "wss://api.hyperliquid.xyz/ws"
async with websockets.connect(uri) as ws:
await ws.send(json.dumps({
"method": "subscribe",
"subscription": {"type": "l2Book", "coin": "ETH"}
}))
# 오더북이 변경될 때마다 새 메시지를 계속 받습니다.
async for message in ws:
data = json.loads(message)
print(data)
asyncio.run(stream_orderbook())
두 코드의 차이는 명확합니다. REST는 한 번 가져오고 끝납니다. WebSocket은 연결을 유지하면서 계속 업데이트를 받습니다.
주문 서명과 OneKey 연동
Hyperliquid에서 쓰기 작업을 하려면 EIP-712 서명이 필요합니다. REST로 주문을 제출하든, WebSocket으로 계정 이벤트를 모니터링하든, 실제 주문·취소·레버리지 변경 같은 작업은 서명된 요청을 통해 처리됩니다.
이때 서명 키의 보안은 계정 보안의 핵심입니다. 개인키가 노출되면 자동화 전략의 수익성보다 훨씬 큰 손실이 발생할 수 있습니다.
OneKey 지갑은 하드웨어 수준의 서명 격리를 제공합니다. 개인키는 보안 칩 안에 보관되고, 서명 작업은 기기 내부에서 수행됩니다. 호스트 PC나 전략 코드가 원본 개인키에 접근하지 못하는 구조입니다.
실무적인 흐름은 다음과 같습니다.
- 전략 코드가 서명할 주문 요청 본문을 구성합니다.
- WalletConnect 등을 통해 OneKey 기기에 서명 요청을 보냅니다.
- 사용자가 OneKey 기기 화면에서 내용을 확인합니다.
- 서명 결과가 전략 코드로 반환됩니다.
- 전략 코드가 Hyperliquid Exchange 엔드포인트로 주문을 제출합니다.
이 방식은 사용자의 확인 단계가 들어가기 때문에 중저빈도 전략에 특히 잘 맞습니다. 반대로 초고빈도 완전 자동 전략이라면 전용 핫월렛을 별도로 두고, 주 계정과 권한·자금을 분리해 관리할지 신중히 검토해야 합니다.
OneKey 앱은 데스크톱과 모바일 환경을 지원하며, 개발자는 오픈소스 구현을 참고해 서명 연동 방식을 이해할 수 있습니다. 일반 사용자의 경우에는 OneKey Perps를 통해 Hyperliquid의 유동성을 더 간단한 워크플로로 이용할 수 있습니다.
혼합 아키텍처: 실전에서 가장 많이 쓰는 방식
실제 운영 환경에서는 REST와 WebSocket 중 하나만 선택하기보다, 두 방식을 함께 사용하는 경우가 많습니다. 둘은 경쟁 관계가 아니라 서로 보완하는 도구입니다.
전형적인 Hyperliquid 전략 구조는 다음과 같습니다.
- WebSocket으로 L2 오더북, 체결 스트림, 계정 이벤트를 실시간 구독
- REST로 주문 제출, 주문 취소 등 거래 명령 실행
- 전략 시작 시 REST로 계정 상태와 현재 포지션을 한 번 조회
- 일정 주기마다 REST로 전체 계정 상태를 다시 확인해 WebSocket 누락 가능성 보정
- WebSocket 재연결 후 REST 스냅샷을 기준 상태로 다시 설정
이런 혼합 구조는 REST의 안정적인 조회·실행 기능과 WebSocket의 실시간성을 함께 활용합니다. Hyperliquid 기반 자동화 전략을 설계할 때 가장 현실적인 접근법이라고 볼 수 있습니다.
OneKey Perps를 사용하는 경우에도 이 관점은 유용합니다. 실시간 시장 흐름을 이해하고, 주문·포지션 관리에서는 서명 보안과 계정 분리를 우선순위에 두는 것이 좋습니다.
FAQ
Q1. 단순한 정기 주문 전략에도 WebSocket이 필요한가요?
필수는 아닙니다. 정해진 시간에 주문을 넣는 전략이라면 REST만으로도 충분한 경우가 많습니다.
전략이 실행될 때 REST로 현재 가격과 계정 상태를 조회하고, 주문을 구성한 뒤 Exchange 엔드포인트로 제출하면 됩니다. 이런 전략에 WebSocket을 추가하면 실시간성보다 유지보수 복잡도만 늘어날 수 있습니다.
Q2. WebSocket 연결이 끊기면 놓친 데이터는 어떻게 확인하나요?
WebSocket 개발에서 매우 흔한 문제입니다.
일반적인 방법은 재연결 직후 REST로 현재 전체 상태를 다시 가져오는 것입니다. 예를 들어 오더북 스냅샷과 현재 포지션을 REST로 조회한 뒤, 그것을 새로운 기준 상태로 삼습니다.
체결 스트림처럼 과거 데이터 조회가 가능한 항목은 연결이 끊긴 시간대의 기록을 REST로 다시 조회해 빈 구간을 보정할 수 있습니다.
Q3. REST로 주문한 뒤 체결 결과를 받기까지 지연은 어느 정도인가요?
REST 주문 응답은 보통 주문이 접수되었는지를 확인하는 성격에 가깝습니다. 실제 체결 결과는 WebSocket의 userEvents 채널을 통해 받거나, 계정 상태를 다시 조회해 확인해야 합니다.
전체 지연은 네트워크 상태와 Hyperliquid 체인의 처리 상황에 따라 달라집니다. 정상적인 환경에서는 매우 짧게 보고되는 경우가 많지만, 극단적인 변동성 상황에서는 지연이 발생할 수 있습니다.
Q4. WebSocket 연결은 몇 개까지 여는 것이 좋나요?
가능하면 같은 계정의 구독은 적은 수의 연결에 모으는 것이 좋습니다. 너무 많은 동시 연결을 열면 연결 수 제한에 걸릴 수 있습니다.
정확한 제한은 Hyperliquid 공식 문서의 최신 내용을 확인해야 합니다. 여러 독립 전략이 있다면 내부 메시지 버스나 공용 스트림 서비스를 두어 하나의 WebSocket 연결을 공유하는 방식도 고려할 수 있습니다.
Q5. Jupyter Notebook에서 WebSocket 코드를 테스트할 때 주의할 점은 무엇인가요?
Jupyter의 기본 event loop는 asyncio와 충돌할 수 있습니다. asyncio.run()을 그대로 실행하면 오류가 날 수 있어요.
이 경우 nest_asyncio를 설치하고 노트북 시작 부분에서 nest_asyncio.apply()를 호출하거나, WebSocket 코드를 별도의 Python 스크립트로 분리해 실행하는 것이 더 안정적입니다.
마무리
REST와 WebSocket은 서로 대체하는 기술이 아니라, 서로 다른 목적을 위해 설계된 보완적인 도구입니다.
간단히 말하면 다음과 같습니다.
- “그 시점의 데이터”가 필요하면 REST
- “실시간으로 변하는 데이터”가 필요하면 WebSocket
- 쓰기 작업, 즉 주문·취소·설정 변경은 REST
이 역할 분담을 이해하면 Hyperliquid API 구조의 핵심을 잡을 수 있습니다. 여기에 OneKey 지갑을 서명 백엔드로 활용하면 개인키 노출 위험을 줄이면서 온체인 파생상품 거래 시스템을 더 안전하게 설계할 수 있습니다.
직접 자동화 전략을 만들지 않더라도, OneKey Perps를 사용하면 더 간단한 방식으로 Hyperliquid의 깊은 유동성에 접근할 수 있습니다. OneKey를 다운로드해 지갑을 설정하고, OneKey Perps에서 주문·포지션 관리 흐름을 직접 확인해 보세요. 다만 모든 파생상품 거래와 자동화 전략에는 손실 위험이 있으므로, 충분히 이해한 범위 안에서 신중하게 사용해야 합니다.
면책 고지
이 글은 기술 학습과 정보 제공을 위한 내용이며 투자 조언이 아닙니다. 자동화 거래 전략에는 코드 결함, 네트워크 장애, API 변경, 데이터 누락 등 기술적 위험이 있으며 예상치 못한 손실이 발생할 수 있습니다. 무기한 선물과 고레버리지 거래는 매우 높은 위험을 수반하므로, 본인의 기술 역량과 위험 감수 능력을 충분히 평가한 뒤 신중하게 참여하시기 바랍니다.
