Hyperliquid API 속도 제한과 운영 모범 사례

2026년 5월 6일

hyperliquid rate limit
hyperliquid api limit
Hyperliquid API 속도 제한
API 모범 사례

Hyperliquid API에 의존하는 퀀트 전략이나 데이터 도구를 운영한다면, 속도 제한(rate limit)은 반드시 고려해야 하는 기본 요소입니다. 속도 제한에 걸리면 전략 실행이 중단될 수 있고, 특히 긴급 청산이나 포지션 축소가 필요한 순간에는 치명적인 지연으로 이어질 수 있어요.

이 글에서는 Hyperliquid API의 속도 제한 구조를 살펴보고, 프로덕션 환경에서 API 클라이언트를 더 안정적이고 효율적으로 운영하기 위한 실무적인 대응 전략을 정리합니다. 또한 실제 거래 워크플로에서는 OneKey Perps를 활용해 보안과 사용성을 함께 챙기는 방법도 함께 다룹니다.

속도 제한이 중요한 이유

속도 제한의 핵심 목적은 서버 리소스를 보호하고, 일부 고빈도 요청자가 전체 사용자 경험을 저하시키는 것을 막는 데 있습니다. Hyperliquid처럼 온체인 기반 거래 인프라를 제공하는 플랫폼에서는 서버 안정성이 수많은 동시 사용자들의 주문, 체결, 데이터 조회 경험과 직접 연결됩니다.

전략 개발자 입장에서는 속도 제한이 일종의 하드 리밋입니다. 즉, 전략이 얼마나 자주 데이터를 가져올 수 있는지, 얼마나 빠르게 주문 명령을 보낼 수 있는지를 결정합니다. 전략 아키텍처를 설계할 때 속도 제한을 고려하지 않으면, 실제 운영 중 429 오류가 발생했을 때 대응이 어려워질 수 있습니다.

Info 엔드포인트의 속도 제한

Info 엔드포인트(/info)는 읽기 전용 데이터 조회에 사용됩니다. 일반적으로 Exchange 엔드포인트보다 제한이 완화된 편이지만, 정확한 제한 수치는 Hyperliquid 공식 문서의 최신 내용을 기준으로 확인해야 합니다. 이 글에서는 검증되지 않은 구체적인 숫자를 인용하지 않습니다.

기본 원칙은 다음과 같습니다. Info 엔드포인트는 합리적인 수준의 시세 모니터링에는 적합하지만, L2 오더북을 초당 수십 회 REST로 폴링하는 방식은 제한에 걸릴 가능성이 있습니다. 실시간 데이터가 필요한 경우에는 REST 폴링보다 WebSocket 구독을 사용하는 편이 더 적절합니다. 요청 부담을 줄일 수 있고, 지연 시간도 낮출 수 있기 때문입니다.

자주 사용되는 Info 조회 유형과 권장 접근 방식은 다음과 같습니다.

조회 유형	권장 방식
계정 상태 조회(`clearinghouseState`)	저빈도 폴링에 적합하며, 초당 여러 번을 넘기지 않는 것이 좋습니다.
사용자 체결 내역(`userFills`)	일회성 또는 저빈도 조회에 적합합니다.
시장 메타데이터(`meta`)	시작 시 1회 조회 후 로컬 캐싱하는 방식이 좋습니다.
L2 오더북 스냅샷	REST 반복 조회보다 WebSocket 구독을 권장합니다.

Exchange 엔드포인트의 속도 제한

Exchange 엔드포인트(/exchange)는 모든 쓰기 작업, 즉 주문 제출·취소·수정과 같은 거래 요청을 처리합니다. 이 엔드포인트의 속도 제한은 보통 Info 엔드포인트보다 더 엄격합니다. 잦은 주문·취소 요청은 서버 리소스를 더 많이 사용하고, 다른 사용자의 매칭 경험에도 영향을 줄 수 있기 때문입니다.

특히 주의해야 할 부분은 주문 수정이 많은 전략입니다. 단순히 주문을 넣고 취소하는 것보다 빈번한 주문 수정이 더 많은 서버 리소스를 사용할 수 있습니다. 전략을 설계할 때 정말 그 정도의 고빈도 주문 수정이 필요한지, 주문 로직을 단순화할 수 있는지 검토해야 합니다.

각 Exchange 작업별 제한과 세부 정책은 Hyperliquid 공식 문서를 기준으로 확인하는 것이 안전합니다. 운영 전에는 반드시 최신 문서를 읽고, 전략별 요청 예산을 별도로 잡아두는 것을 권장합니다.

WebSocket 연결과 구독 제한

WebSocket은 REST API와 다른 기준으로 제한이 적용됩니다. 주로 동시 연결 수, 연결당 구독 채널 수, 구독하는 데이터의 종류가 중요합니다. 여러 종목의 L2 오더북을 대량으로 구독하면 서버 리소스를 많이 사용할 수 있으므로 다음 원칙을 지키는 것이 좋습니다.

가능한 한 적은 수의 WebSocket 연결에 여러 채널 구독을 모읍니다.
더 이상 필요하지 않은 채널은 즉시 구독 해제 메시지를 보냅니다.
동일 계정에서 과도하게 많은 동시 연결을 열지 않습니다.
수신한 메시지를 처리하는 로직과 네트워크 수신 로직을 분리해 병목을 줄입니다.

429 오류를 처리하는 올바른 방법

HTTP 429, 즉 Too Many Requests는 속도 제한에 걸렸을 때 서버가 반환하는 표준 상태 코드입니다. 429를 받은 직후 즉시 재시도하는 것은 좋지 않습니다. 같은 요청을 계속 반복하면 더 많은 429가 발생하고, 제한 시간이 더 길어질 수 있습니다.

권장 처리 절차는 다음과 같습니다.

같은 유형의 요청을 즉시 멈춥니다. 429가 발생한 요청 하나만 멈추는 것이 아니라, 동일한 엔드포인트나 요청 그룹 전체를 일시 중단해야 합니다.
응답 헤더의 Retry-After 값을 확인합니다. 서버가 Retry-After 헤더를 제공한다면, 해당 초 단위 대기 시간을 그대로 따라야 합니다.
Retry-After가 없다면 지수 백오프를 적용합니다. 예를 들어 1초, 2초, 4초, 8초처럼 대기 시간을 늘리되, 최대 대기 시간은 60초처럼 상한을 두는 방식입니다.
로그와 알림을 남깁니다. 429는 조용히 무시할 오류가 아닙니다. 반복적으로 발생한다면 전략의 요청 패턴을 조정해야 한다는 신호입니다.

Python에서 지수 백오프를 구현하는 기본 예시는 다음과 같습니다.

import time
import requests


def request_with_backoff(url, payload, max_retries=5):
    wait_time = 1

    for attempt in range(max_retries):
        response = requests.post(url, json=payload)

        if response.status_code == 200:
            return response.json()

        elif response.status_code == 429:
            retry_after = response.headers.get("Retry-After")
            sleep_duration = int(retry_after) if retry_after else wait_time

            print(f"Rate limited. Waiting {sleep_duration}s before retry.")
            time.sleep(sleep_duration)
            wait_time = min(wait_time * 2, 60)

        else:
            response.raise_for_status()

    raise Exception("Max retries exceeded")

요청 배치 처리 전략

요청 빈도를 줄이는 가장 효과적인 방법 중 하나는 배치 처리입니다. 여러 개의 독립 요청을 더 적은 수의 API 호출로 합치는 방식입니다.

데이터 조회의 경우 여러 계정이나 여러 종목의 정보를 가져와야 한다면, 먼저 API가 배치 조회 파라미터를 지원하는지 확인해보세요. 가능하다면 계정이나 종목별로 따로 요청하지 말고, 한 번의 요청으로 필요한 데이터를 가져오는 편이 낫습니다.

거래 작업에서도 Hyperliquid는 배치 주문(Batch Order)을 지원합니다. 단일 Exchange 요청 안에서 여러 주문을 제출할 수 있어, 여러 포지션을 동시에 구성해야 하는 전략에서는 지연 시간을 낮추고 요청 수도 줄일 수 있습니다. 구체적인 배치 주문 포맷은 Hyperliquid 공식 문서를 기준으로 확인해야 합니다.

연결 풀과 동시성 제어

멀티스레드 또는 비동기 환경에서 Hyperliquid API를 호출할 때는 클라이언트 레벨에서 동시성 제어를 반드시 구현해야 합니다. 그렇지 않으면 짧은 시간에 많은 요청이 폭발적으로 발생해 속도 제한에 쉽게 걸릴 수 있습니다.

예를 들어 Python 비동기 환경에서는 Semaphore를 사용해 최대 동시 요청 수를 제한할 수 있습니다.

import asyncio
import aiohttp

# 최대 동시 요청 수를 10개로 제한
semaphore = asyncio.Semaphore(10)


async def rate_limited_request(session, payload):
    async with semaphore:
        async with session.post(
            "https://api.hyperliquid.xyz/info",
            json=payload
        ) as response:
            return await response.json()

HTTP 연결 재사용도 중요합니다. Python에서는 매 요청마다 새 연결 객체를 만드는 대신 requests.Session 또는 aiohttp.ClientSession을 사용하면 HTTP Keep-Alive를 활용할 수 있습니다. 이를 통해 TCP 핸드셰이크 비용을 줄이고 응답 지연도 낮출 수 있습니다.

로컬 캐싱 전략

모든 데이터를 매번 API에서 실시간으로 가져올 필요는 없습니다. 적절한 로컬 캐싱은 불필요한 요청을 크게 줄여줍니다.

시장 메타데이터, 예를 들어 종목 목록이나 최대 레버리지 정보는 변화가 느리므로 몇 시간 단위로 메모리에 캐싱할 수 있습니다.
펀딩비 데이터는 다음 정산 주기까지 캐싱하는 방식이 유용합니다.
계정 상태는 WebSocket 계정 이벤트로 갱신하고, REST 폴링은 보조 수단으로만 사용하는 것이 좋습니다.
캐시 만료 정책을 명확히 두고, API 응답과 캐시 데이터의 차이를 주기적으로 점검해야 합니다.

API 상태 모니터링

프로덕션 환경에서는 API 호출에 대한 체계적인 모니터링이 필요합니다.

엔드포인트별 요청 성공률과 응답 시간을 기록합니다.
429 오류에 대해 알림 기준을 설정합니다.
WebSocket 연결 끊김 빈도를 추적합니다. 끊김이 잦다면 네트워크 또는 구독 구조에 문제가 있을 수 있습니다.
로컬 캐시와 API 응답의 일관성을 정기적으로 확인합니다.
주문 관련 오류는 단순 API 오류와 분리해 별도로 추적합니다.

모범 사례 요약

영역	권장 사항
실시간 시세	REST 폴링보다 WebSocket 구독을 우선 사용합니다.
429 처리	즉시 재시도하지 말고 `Retry-After` 또는 지수 백오프를 적용합니다.
주문 요청	가능하면 배치 주문을 활용하고, 불필요한 주문 수정을 줄입니다.
동시성	Semaphore, 큐, 중앙 요청 프록시 등으로 요청량을 제어합니다.
캐싱	시장 메타데이터와 펀딩비처럼 변화가 느린 데이터는 로컬 캐싱합니다.
모니터링	성공률, 지연 시간, 429 발생률, WebSocket 끊김을 모두 추적합니다.
보안	API 서명 키와 주요 자금을 분리하고, 키 관리 체계를 문서화합니다.

프라이빗 키 보안과 OneKey의 역할

API 제한과 성능 최적화를 이야기할 때도 프라이빗 키 보안은 절대 타협해서는 안 되는 기본선입니다. Exchange 엔드포인트의 모든 거래 요청은 서명이 필요합니다. 즉, API 전략을 실행하는 환경은 어떤 방식으로든 서명 권한에 접근할 수 있어야 합니다.

보안성과 편의성 사이의 균형을 맞추는 현실적인 방법은 OneKey 지갑을 사용해 전용 API 서명 키를 생성·관리하고, 이를 주요 자금 계정과 분리하는 것입니다. 하드웨어 지갑의 보안 칩을 활용하면 프라이빗 키가 소프트웨어 레이어에 평문으로 노출되는 위험을 줄일 수 있습니다. 전략 서버가 공격받더라도 공격자가 서명 키 자체를 직접 추출하기 어렵게 만드는 구조가 중요합니다.

OneKey의 오픈소스 코드와 WalletConnect 지원은 지갑 서명을 애플리케이션 레이어에 통합하려는 개발자에게 유용한 참고 지점이 될 수 있습니다. 또한 EU MiCA와 같은 규제 프레임워크를 고려하는 팀이라면, 키 관리 기록과 권한 분리 체계는 감사 대응 측면에서도 중요한 운영 요소입니다.

실제 거래 워크플로에서는 OneKey Perps를 Hyperliquid 기반 퍼프 거래 접근점으로 활용할 수 있습니다. API 전략을 직접 운영하더라도, 포지션 확인, 리스크 점검, 수동 대응이 필요한 순간에는 신뢰할 수 있는 지갑 환경과 직관적인 Perps 인터페이스가 도움이 됩니다.

OneKey를 처음 사용한다면 OneKey를 다운로드해 지갑을 설정하고, OneKey Perps에서 지원되는 퍼프 거래 환경을 직접 확인해보세요. 이는 수익을 보장하는 방법이 아니라, 키 관리와 거래 접근성을 함께 고려하기 위한 실용적인 선택지입니다.

FAQ

Q1. 속도 제한에 걸리면 계정이 바로 정지되나요?

일시적으로 속도 제한에 걸린 경우 보통 요청이 거절되고 429 오류가 반환됩니다. 이것만으로 계정이 곧바로 정지된다고 단정할 수는 없습니다. 다만 지속적인 남용 행위는 더 심각한 조치로 이어질 수 있으므로, 구체적인 정책은 Hyperliquid 공식 문서를 기준으로 확인해야 합니다. 좋은 속도 제한 관리는 기술적 안정성뿐 아니라 플랫폼 사용 규칙을 지키는 데도 필요합니다.

Q2. WebSocket 메시지 처리 속도가 푸시 속도를 따라가지 못하면 어떻게 해야 하나요?

메시지 소비 속도가 느리면 큐가 쌓이고, 데이터가 점점 오래된 상태가 됩니다. 해결 방법은 메시지 처리 로직 최적화, 수신과 처리를 분리하는 구조 설계, 불필요한 구독 채널 축소 등이 있습니다. 모든 최적화를 해도 따라가지 못한다면 전략 자체가 과도하게 많은 데이터를 요구하는 것은 아닌지 다시 검토해야 합니다.

Q3. 여러 전략 인스턴스가 속도 제한 한도를 공유하려면 어떻게 해야 하나요?

여러 전략 인스턴스를 동시에 운영한다면 중앙 요청 프록시나 레이트 리밋 미들웨어를 두고 API 접근을 통합 관리하는 것이 좋습니다. 각 인스턴스가 독립적으로 제한을 계산하면 전체 요청량이 쉽게 초과될 수 있습니다. Redis 같은 인메모리 데이터베이스를 활용해 분산 속도 제한 카운터를 구현하는 방식도 많이 사용됩니다.

Q4. 429가 진짜 속도 제한 때문인지 어떻게 알 수 있나요?

일반적인 429 응답은 응답 본문에 오류 원인을 설명하며, 경우에 따라 Retry-After 헤더를 포함합니다. 응답이 명확히 속도 제한을 나타낸다면 지수 백오프를 적용하면 됩니다. 반면 계정 잔고 부족, 주문 파라미터 오류 등 다른 원인이라면 단순 재시도가 아니라 원인을 수정해야 합니다.

Q5. Info 엔드포인트와 Exchange 엔드포인트의 속도 제한은 따로 계산되나요?

Hyperliquid 공식 문서의 설명에 따르면 두 엔드포인트 유형의 제한은 분리되어 있습니다. 즉, 고빈도 데이터 조회가 주문 한도를 직접 소모하지 않고, 반대의 경우도 마찬가지입니다. 전략 설계 시 데이터 조회와 거래 요청을 별도 예산으로 나누어 관리하는 것이 좋습니다.

정리

Hyperliquid API 개발에서 속도 제한 관리는 쉽게 지나치기 쉽지만 매우 중요한 영역입니다. WebSocket을 활용해 불필요한 폴링을 줄이고, 429 오류에 지수 백오프를 적용하며, 배치 요청과 로컬 캐싱을 활용하는 것만으로도 전략의 안정성과 효율성을 크게 높일 수 있습니다.

그 위에 반드시 더해야 할 것이 프라이빗 키 보안입니다. OneKey Perps는 Hyperliquid의 유동성에 접근하면서도 OneKey의 키 관리 환경을 함께 활용할 수 있는 실용적인 워크플로를 제공합니다. 온체인 퀀트 전략을 처음 구축하는 개발자든, 기존 시스템의 보안 기준을 높이려는 팀이든, OneKey를 다운로드해 지갑을 설정하고 OneKey Perps를 테스트해보는 것은 좋은 출발점이 될 수 있습니다.

---면책 고지---

이 글은 기술 참고용이며 투자 조언이나 재무 자문이 아닙니다. API 거래에는 기술 장애, 네트워크 중단, 코드 오류 등의 위험이 있으며, 자동화 전략은 예상치 못한 손실을 만들 수 있습니다. 무기한 선물 거래는 높은 레버리지 위험을 수반하므로, 관련 위험을 충분히 이해한 뒤 본인의 위험 감수 능력에 맞게 신중하게 참여해야 합니다.