From Polling to Push: A Builder's Guide to Hyperliquid WebSockets

By @CoinMarketMan - 19-Jul-2026

폴링에서 푸시로: Hyperliquid WebSocket 빌더 가이드

모든 Hyperliquid 봇은 같은 방식으로 시작한다. 루프, 슬립 타이머, 그리고 몇 초마다 실행되는 REST 호출. 잘 작동하다가, 어느 순간 그렇지 않게 된다. 소수의 자산 이상을 추적하기 시작하는 순간, 폴링은 예상치 못한 병목이 된다. 소모되는 요청 한도, 갱신 주기 사이의 오래된 데이터, 추가하는 자산마다 선형으로 늘어나는 아키텍처까지.

WebSocket은 이 모델을 뒤집어 문제를 해결한다. 봇이 서버에 "뭔가 바뀌었나요?"라고 수천 번 묻는 대신, 서버가 무언가 바뀌는 순간 봇에게 알려준다. 수천 개의 개별 요청 대신 하나의 지속적인 연결로 대체되고, 봇은 시장 이벤트가 발생하는 즉시 반응한다. 몇 초 혹은 몇 분 뒤에야 알아채는 것이 아니라.

이 가이드는 Hyperliquid의 네이티브 WebSocket API를 트레이딩 봇에 연결하는 방법, 대부분의 빌더들이 놓치는 재연결 엣지 케이스 처리 방법, 그리고 HyperTracker의 푸시 딜리버리를 통한 사전 계산된 분석 데이터를 레이어로 추가해 봇이 원시 시장 데이터와 코호트 수준의 인텔리전스를 동시에 수신하는 방법을 다룬다.

규모에서의 폴링 문제

REST 폴링은 대부분의 봇에게 올바른 출발점이다. 단순하고, 무상태이며, 디버깅이 쉽다. 코호트 포지셔닝과 펀딩 비율을 시간당 몇 번 확인하는 스윙 트레이딩 봇은 전체 수명 동안 REST로도 충분하다. 아키텍처가 직관적이고 요청 볼륨도 관리 가능한 수준이다.

문제는 팬아웃할 때 시작된다. 10개의 자산을 1초 갱신 주기로 추적한다면, 한 시간에 36,000번의 요청이 발생한다. 30개 자산이면 100,000번을 넘는다. Hyperliquid의 퍼블릭 API는 분당 1,200의 공유 가중치 예산을 가지며, 대부분의 엔드포인트에서 개별 info 쿼리는 2에서 20 가중치 단위를 소비한다(일부 특수 엔드포인트는 최대 60). 가장 가벼운 경우라도, 10개 자산을 초당 한 번 폴링하는 봇은 몇 분 안에 그 예산을 다 써버린다.

Polling Vs Push

또 다른 문제는 지연이다. 1초 폴링에서는 데이터가 항상 0~1초 지연된다. 대부분의 경우 "뭔가 바뀌었나요?"라고 물어도 같은 대답이 돌아온다. WebSocket은 서버가 실제로 새로운 데이터가 있을 때만 전송하므로, 이 낭비되는 대역폭을 완전히 제거한다.

Hyperliquid의 WebSocket 채널

Hyperliquid는 메인넷용 단일 WebSocket 엔드포인트 wss://api.hyperliquid.xyz/ws를 제공한다(테스트넷 미러는 wss://api.hyperliquid-testnet.xyz/ws). 연결 후 JSON 메시지를 전송해 특정 데이터 피드를 구독한다.

사용 가능한 구독 유형은 트레이딩 봇에 필요한 핵심 데이터를 포괄한다.

AllMids: 모든 상장 자산의 최신 중간 가격. 구독 하나로 코인별 폴링 없이 모든 가격의 지속적인 피드를 받는다.
L2Book: 특정 코인의 오더북 스냅샷. 진입 규모 결정이나 유동성 파악을 위해 깊이 데이터가 필요한 봇에 유용하다.
Trades: 실시간 체결 데이터. 거래소에서 실행되는 모든 거래가 여기에 표시된다.
Candle: 1분부터 1일까지의 OHLCV 캔들. 서버가 캔들이 마감되는 즉시 새 캔들을 푸시한다.
UserEvents: 본인의 체결, 펀딩 지급, 청산 이벤트. 봇의 주문이 체결됐는지 알려주는 피드다.

구독 메시지는 다음과 같은 형식이다.

{
  "method": "subscribe",
  "subscription": {
    "type": "allMids"
  }
}

특정 코인의 L2Book 구독:

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC"
  }
}

서버는 현재 상태의 스냅샷(isSnapshot: true 태그 포함)이 담긴 구독 확인으로 응답한다. 봇은 별도의 REST 호출 없이 즉시 로컬 상태를 초기화할 수 있다.

연결 유지

Hyperliquid는 60초 동안 아무런 통신이 없으면 WebSocket 연결을 끊는다. 연결을 유지하려면 20초마다 하트비트 핑을 전송해야 한다. 메시지는 최소한이다.

{"method": "ping"}

구현은 쉽지만, 놀랍도록 자주 잊어버린다. 많은 빌더들이 구독 로직을 연결하고, 트래픽이 적은 환경에서 테스트한 후 연결이 안정적이라고 가정한다. 그러다 조용한 야간 세션에 봇이 침묵하고, 서버가 연결을 끊고, 아무도 재연결을 처리하지 않아 아시아 세션 시작을 놓치게 된다.

재연결을 계획하라: 반드시 발생한다

Hyperliquid의 문서에는 명확히 나와 있다. 연결 끊김은 예고 없이 주기적으로 발생한다. 봇은 재연결을 정상적인 운영 이벤트로 처리해야 한다. 프로덕션 봇들이 사용하는 흐름은 다음과 같다.

Reconnection Flow

연결 끊김 감지. 핑 타임아웃(적절한 시간 내에 퐁 응답 없음) 또는 WebSocket 오류/종료 이벤트.
지수 백오프로 대기. 1초부터 시작해 재시도마다 두 배로 늘린다. 장애 중 서버를 과도하게 요청하다가 원래 문제에 더해 요청 제한까지 받는 상황을 방지한다.
재연결 및 재구독. 새 WebSocket 연결을 열고 모든 구독 메시지를 다시 전송한다. 서버는 새 스냅샷으로 응답한다.
스냅샷 처리. isSnapshot: true 태그가 붙어 있으며 구독된 각 피드의 현재 상태를 담고 있다. 이를 사용해 로컬 상태를 재구축한다.
REST로 보정. 연결이 몇 초 이상 끊겼다면 Info API를 조회해 누락된 부분을 채운다. 체결과 사용자 이벤트는 REST를 통해 조회할 수 있어 장애 중 누락된 내용이 없는지 확인할 수 있다.

핵심은 다섯 번째 단계다. 스냅샷은 현재 상태를 제공하지만, 놓친 이벤트를 재생하지는 않는다. 연결이 끊긴 동안 포지션이 열렸다 닫혔다면, 스냅샷에는 아무것도 나타나지 않는다. 재연결 후 빠른 REST 쿼리로 이런 엣지 케이스를 잡아낼 수 있다.

멀티 자산 모니터링 패턴

WebSocket의 가장 큰 아키텍처 이점은 멀티 자산 모니터링이다. 30개 자산을 추적하는 REST 기반 봇은 30개의 별도 폴링 루프(또는 30개의 순차적 요청을 가진 하나의 루프)가 필요하다. WebSocket 기반 봇은 AllMids를 한 번 구독하면 단일 연결로 모든 자산의 업데이트를 받는다.

더 세분화된 데이터를 위해 같은 연결에서 구독 유형을 혼합할 수 있다. 일반적인 멀티 자산 봇은 다음과 같이 구독할 수 있다.

전체 시장의 가격 피드를 위한 AllMids
실제로 거래하는 3~4개 자산의 L2Book (규모 결정을 위한 깊이 데이터)
동일 자산의 Trades (대형 체결을 실시간으로 감지)
봇 자신의 주문 체결과 펀딩 지급을 추적하는 UserEvents

총 약 10개의 구독으로 멀티 전략 봇이 필요로 하는 모든 것을 처리한다. 1초 간격 REST 폴링으로 동일한 데이터를 받으려면 초당 수십 번의 요청이 필요하다.

최소한의 Python 연결 관리자

Python의 websockets 라이브러리를 사용한 WebSocket 연결 관리자의 뼈대다. 하트비트, 자동 재연결, 메시지 라우팅을 처리한다.

import asyncio
import json
import websockets

WS_URL = "wss://api.hyperliquid.xyz/ws"

class HyperliquidWS:
    def __init__(self, subscriptions):
        self.subscriptions = subscriptions
        self.ws = None

    async def connect(self):
        while True:
            try:
                async with websockets.connect(WS_URL) as ws:
                    self.ws = ws
                    await self._subscribe_all()
                    await asyncio.gather(
                        self._heartbeat(),
                        self._listen()
                    )
            except websockets.ConnectionClosed:
                print("Disconnected. Reconnecting...")
                await asyncio.sleep(1)

    async def _subscribe_all(self):
        for sub in self.subscriptions:
            await self.ws.send(json.dumps({
                "method": "subscribe",
                "subscription": sub
            }))

    async def _heartbeat(self):
        while True:
            await self.ws.send('{"method": "ping"}')
            await asyncio.sleep(20)

    async def _listen(self):
        async for msg in self.ws:
            data = json.loads(msg)
            self._route(data)

    def _route(self, data):
        channel = data.get("channel")
        if channel == "allMids":
            self.on_price_update(data["data"])
        elif channel == "l2Book":
            self.on_book_update(data["data"])
        elif channel == "trades":
            self.on_trade(data["data"])

의도적으로 단순화했다. 프로덕션 버전에는 지수 백오프, 채널별 상태 추적, 재연결 후 REST 기반 갭 보정, 잘못된 형식의 메시지 오류 처리가 추가된다. 하지만 핵심 패턴은 여기에 있다. 연결, 구독, 하트비트, 수신, 끊김 시 재연결.

분석 레이어 추가: 시장 데이터와 인텔리전스

원시 시장 데이터는 봇에게 무슨 일이 일어나고 있는지 알려준다. 가격이 움직였고, 체결이 발생했고, 오더북이 변했다. 하지만 누가 그 움직임을 이끌고 있는지는 알려주지 않는다. 고래가 매집하는 건가? 지속적으로 수익을 내는 트레이더들이 같은 방향으로 기울고 있나? Leviathan 코호트(선물 자산 $5M 이상 보유 지갑)가 소매 투자자들이 매도하는 동안 포지션을 쌓고 있나?

이것이 분석 푸시 딜리버리가 필요한 이유다. 우리 데이터는 Hyperliquid의 모든 지갑을 16개의 행동 코호트로 분류한다. 계정 크기 기준 8개(Shrimp부터 Leviathan), 누적 PnL 실적 기준 8개(Giga-Rekt부터 Money Printer). 코호트 지표는 5분마다 업데이트된다. 봇은 Hyperliquid 네이티브 WebSocket의 틱 수준 시장 데이터와 HyperTracker 푸시 딜리버리의 코호트 포지셔닝 인텔리전스를 결합할 수 있다.

Websocket Architecture

아키텍처는 다음과 같다. Hyperliquid의 WebSocket이 가격, 거래, 오더북 데이터를 봇에 직접 전달해 틱 수준의 반응을 지원한다. HyperTracker는 Flow 티어($799/월)와 Stream 티어($1,999/월)에서 웹훅을 통해 사전 계산된 분석 데이터(코호트 포지셔닝, Smart Money 알림, 청산 위험 점수, 주문 흐름 요약)를 전달한다. HyperTracker의 네이티브 WebSocket 딜리버리는 곧 출시 예정이며, 스트리밍 인프라가 현재 활발히 개발 중이다. 봇은 두 데이터 스트림을 결합해 원시 시장 데이터와 행동 인텔리전스를 모두 갖추고 결정을 내린다.

예를 들어, 봇이 Hyperliquid Trades 피드에서 갑작스러운 가격 하락을 감지한다고 하자. 원시 데이터는 이렇게 말한다. 가격이 떨어졌다. 웹훅을 통해 전달된 코호트 데이터는 이렇게 말한다. Money Printer 지갑들(누적 수익 $1M 이상의 코호트)이 하락 중에 롱 포지션을 늘렸다. 이는 Giga-Rekt 지갑들(최악의 누적 PnL을 가진 코호트)이 매수하는 경우와는 완전히 다른 신호다.

REST가 여전히 정답인 경우

WebSocket은 복잡성을 더한다. 연결 관리, 하트비트 루프, 재연결 로직, 상태 보정. 많은 봇에게 그 복잡성은 정당화되지 않는다.

봇이 포지션이나 신호를 자주 확인하지 않을 때(시간당 몇 번 이하), 거래를 실행할 때(Hyperliquid의 Exchange API는 주문 체결을 REST 전용으로 처리), 일별 리포팅 도구나 포트폴리오 추적기를 만들 때, 또는 프로토타이핑 중에 가장 단순한 아키텍처를 원할 때는 REST 폴링이 더 나은 선택이다.

대부분의 프로덕션 시스템이 수렴하는 것은 하이브리드 패턴이다. 주문 실행과 계정 관리에는 REST를 사용한다. 실시간 시장 데이터에는 WebSocket을 사용한다. 분석 데이터에는 코호트 업데이트가 얼마나 자주 필요한지에 따라 HyperTracker의 REST API 또는 푸시 딜리버리를 사용한다.

| 데이터 유형 | 최적 전달 방식 | 이유 | | --- | --- | --- | | 가격 피드, 체결, 오더북 | WebSocket (Hyperliquid 네이티브) | 틱 수준 신선도, 대규모에서 낮은 오버헤드 | | 주문 체결, 취소 | REST (Hyperliquid Exchange API) | 요청-응답 모델이 실행 의미론에 적합 | | 코호트 포지셔닝, Smart Money 신호 | REST 폴링 또는 푸시 (HyperTracker) | 분석은 5분마다 갱신, 임계값 알림에는 푸시 | | 청산 위험, 리더보드 변화 | REST 또는 웹훅 (HyperTracker) | 이벤트 기반: 임계값이 넘을 때만 관련 있음 | | 과거 데이터, 백테스팅 | REST (HyperTracker) | 수개월의 체결 및 포지션에 대한 배치 쿼리 |

흔한 실수와 예방법

두 패턴 모두를 사용하는 봇을 출시하면서 몇 가지 실패 패턴이 반복적으로 나타난다.

재연결 로직 없음

가장 흔한 WebSocket 버그는 눈치채지 못하는 버그다. 봇이 연결되고, 구독하고, 몇 시간 동안 잘 실행된다. 그러다 서버가 연결을 끊는다(정기 유지보수, 네트워크 일시 장애, Hyperliquid 노드 교체). 봇은 아무것도 처리하지 않으며 침묵 속에 앉아 있고, 여전히 실행 중이라고 가정한다. 항상 지수 백오프를 포함한 재연결을 구현하라. 모든 연결 끊김을 로깅해 나중에 누락 구간을 감사할 수 있도록 하라.

스냅샷 무시

재연결하고 재구독하면 서버는 isSnapshot: true 태그가 붙은 현재 상태 스냅샷을 전송한다. 일부 봇은 이를 무시하고 증분 업데이트만 처리한다. 그 결과 재연결할 때마다 로컬 상태가 영구적으로 오래된 상태로 남는다. 스냅샷을 처리해 상태를 재구축한 다음 증분 업데이트 처리로 전환하라.

실행에 REST와 WebSocket 혼용

Hyperliquid의 WebSocket은 시장 데이터만 전달한다. 주문 체결은 REST Exchange API를 통해 이루어지며 EIP-712 서명된 요청이 필요하다. WebSocket으로 주문을 전송하려 하면 아무 일도 일어나지 않는다. 봇의 데이터 파이프라인과 실행 파이프라인은 별도의 루프여야 한다.

틱 속도로 분석 데이터 폴링

코호트 수준의 분석(Smart Money 포지셔닝이나 청산 위험 등)은 매 틱마다 바뀌지 않는다. 우리 데이터는 5분마다 갱신되며, 이는 행동 코호트 분석에 적합한 단위다. 코호트 엔드포인트를 초당 한 번 폴링하면 요청 한도 예산만 낭비되고 더 신선한 데이터를 얻지 못한다. 폴링 빈도를 데이터의 실제 갱신 주기에 맞추거나, 웹훅/푸시 딜리버리로 전환해 변화가 생길 때 서버가 알려주도록 하라.

시장 데이터와 코호트 인텔리전스, 둘 다 활용하기

HyperTracker의 API는 봇에게 16개 행동 세그먼트에 걸친 사전 계산된 코호트 분석 데이터를 제공한다. 무료 티어(하루 100회 요청)로 REST 폴링을 시작하고, 봇의 데이터 수요가 늘어나면 웹훅(Flow, $799/월) 또는 WebSocket 푸시(Stream, $1,999/월)로 업그레이드하라.

API 살펴보기

성장 경로

성공적인 Hyperliquid 봇 대부분은 예측 가능한 궤적을 따른다. 추론하기 쉽고 빠르게 프로토타입을 만들 수 있기 때문에 REST 폴링으로 시작한다. 봇이 작동하고 엣지가 증명되면, 폴링으로는 요청 볼륨이 감당이 안 되기 때문에 시장 데이터 레이어를 WebSocket으로 졸업한다. 분석 레이어도 비슷한 경로를 따른다. HyperTracker의 REST 엔드포인트를 몇 분마다 폴링하다가, 코호트 변화에 더 즉각적으로 반응해야 할 때 푸시 딜리버리로 전환한다.

이 졸업은 어느 프로토콜이 "더 낫다"의 문제가 아니다. 전달 방식을 데이터의 자연스러운 리듬에 맞추는 문제다. 가격 데이터는 매 틱마다 변하니 WebSocket에 속한다. 코호트 분석은 5분마다 업데이트되니 REST나 푸시 딜리버리 모두 작동한다. 주문 실행은 개별적인 요청-응답 액션이니 REST가 자연스러운 선택이다.

각 데이터 스트림을 그 리듬에 맞는 전달 방식에 연결하면, 요청 한도를 소진하지 않고 확장되며, 재연결 중에도 놓치는 것이 없고, 원시 시장 데이터와 행동 인텔리전스 모두를 갖추고 결정을 내리는 봇을 얻는다. 대부분의 빌더들이 결국 도달하는 아키텍처다. 설계에 의해 그곳에 도달하느냐, 몇 번의 고통스러운 장애를 겪은 후에야 도달하느냐의 차이일 뿐이다.