Hyperliquid API 입문: 2026년 초보자 가이드

2026년 5월 6일

hyperliquid api
hyperliquid api guide
Hyperliquid API 튜토리얼
온체인 거래 API

프로그래밍 방식으로 온체인 무기한 선물 거래에 참여하고 싶었다면, Hyperliquid API는 현재 온체인 DEX 중 중앙화 거래소에 가까운 사용 경험을 제공하는 선택지 중 하나입니다. 시세 조회, 계정 관리, 주문 실행 인터페이스를 갖추고 있으며, WebSocket 실시간 스트리밍까지 지원해 간단한 퀀트 전략부터 복잡한 마켓메이킹 프로그램까지 다양한 요구를 처리할 수 있습니다.

이 글은 Hyperliquid API를 처음 접하는 개발자를 위해 API 구조, 인증 방식, 기본 예제, 자주 발생하는 문제를 정리한 입문 가이드입니다. 실제 거래에 앞서서는 반드시 공식 문서의 최신 내용을 확인하고, 작은 규모로 충분히 테스트해야 합니다.

Hyperliquid API로 할 수 있는 것

Hyperliquid 공식 문서 기준으로 API는 크게 세 가지로 나눌 수 있습니다.

정보 조회 엔드포인트, Info Endpoints

시장 데이터를 조회하는 API입니다. 현재 오더북 스냅샷, 최근 체결 내역, 펀딩비 이력, 계정 포지션, 과거 주문 등을 가져올 수 있습니다. 이 유형의 API는 서명이 필요 없으며 공개적으로 접근할 수 있습니다.

거래 엔드포인트, Exchange Endpoints

주문 생성, 주문 취소, 포지션 레버리지 변경, 증거금 조정 같은 쓰기 작업을 수행하는 API입니다. 요청 본문에 대해 지갑 서명이 필요하며, 보안 관리가 매우 중요합니다.

WebSocket 실시간 스트리밍

오더북 변경, 체결 스트림, 계정 이벤트 등 실시간 데이터를 구독할 수 있습니다. 낮은 지연 시간으로 반응해야 하는 자동매매 전략이나 모니터링 시스템에 적합합니다.

기본 URL과 API 구조

Hyperliquid의 REST API 기본 URL은 다음과 같습니다.

https://api.hyperliquid.xyz

모든 요청은 POST 방식이며, 요청 본문은 JSON 형식입니다.

Info 계열 요청: /info
Exchange 계열 요청: /exchange

구체적인 필드 정의와 요청 형식은 공식 문서를 기준으로 확인해야 합니다. 아래 예시는 입문용 설명이며, 실제 운영 환경에서 사용하기 전에는 반드시 최신 문서와 SDK 구현을 대조하는 것이 좋습니다.

인증 방식

Hyperliquid의 거래 API는 전통적인 API Key + Secret 방식이 아니라 EIP-712 구조화 데이터 서명을 사용합니다. 즉, 다음과 같은 방식으로 동작합니다.

이더리움 호환 지갑 주소가 계정 식별자 역할을 합니다.
각 거래 요청은 해당 주소의 개인키로 서명해야 합니다.
서명은 해당 요청이 주소 소유자의 승인을 받았다는 것을 증명합니다.
별도의 중앙화된 API Key를 발급받아 보관하는 구조가 아닙니다.

이 방식은 탈취 가능한 API Key를 줄인다는 점에서 장점이 있습니다. 다만 개인키 관리의 중요성은 훨씬 커집니다. 개인키가 유출되면 공격자는 정상적인 서명을 만들어 계정을 직접 조작할 수 있습니다.

이 지점에서 OneKey 지갑을 함께 사용하는 방식이 유용합니다. OneKey 하드웨어 지갑은 개인키를 보안 칩 내부에 격리하고, 서명 작업을 기기 내부에서 처리합니다. 개인키가 호스트 컴퓨터나 네트워크에 노출되지 않는 구조입니다.

API 기반 전략을 개발한다면 메인 자산을 보관하는 계정과 거래용 계정을 분리하는 것이 좋습니다. OneKey에서 별도 계정 또는 서브 계정을 만들어 Hyperliquid API 거래에 사용하고, 실제 거래 실행과 포지션 확인은 OneKey Perps 워크플로우와 함께 관리하면 수동 확인과 자동화 운영 사이의 균형을 잡기 쉽습니다.

정보 조회 예시: Python + curl

아래는 현재 거래 가능한 자산의 메타데이터를 조회하는 간단한 예시입니다.

curl 사용 예시

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "meta"}'

Python requests 사용 예시

import requests
import json

url = "https://api.hyperliquid.xyz/info"
payload = {"type": "meta"}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(json.dumps(data, indent=2))

응답에는 거래 가능한 선물 계약의 기본 정보가 포함됩니다. 예를 들어 자산 이름, 최대 레버리지, 최소 주문 수량 같은 필드를 확인할 수 있습니다. 이 유형의 조회는 공개 API이므로 인증이 필요 없고, Hyperliquid API를 처음 테스트할 때 가장 좋은 출발점입니다.

계정 포지션 조회

특정 주소의 포지션 상태를 조회하는 것도 Info 계열 API에 속합니다. 지갑 주소를 함께 전달하면 됩니다.

payload = {
    "type": "clearinghouseState",
    "user": "0xYOUR_WALLET_ADDRESS"
}

response = requests.post(url, json=payload, headers=headers)

응답에는 증거금 잔고, 각 계약의 포지션 수량, 미실현 손익 등 계정 상태 정보가 포함됩니다.

주의할 점은 이 데이터가 공개적으로 조회 가능한 온체인 기반 데이터라는 것입니다. 누구든지 임의의 주소에 대해 포지션 상태를 조회할 수 있으므로, 주소 프라이버시와 운용 계정 분리에 신경 써야 합니다.

WebSocket 실시간 구독

WebSocket 엔드포인트는 다음과 같습니다.

wss://api.hyperliquid.xyz/ws

연결을 생성한 뒤 구독 메시지를 보내면 실시간 데이터를 받을 수 있습니다.

import asyncio
import websockets
import json

async def subscribe_orderbook():
    uri = "wss://api.hyperliquid.xyz/ws"

    async with websockets.connect(uri) as ws:
        sub_msg = {
            "method": "subscribe",
            "subscription": {
                "type": "l2Book",
                "coin": "BTC"
            }
        }

        await ws.send(json.dumps(sub_msg))

        while True:
            msg = await ws.recv()
            data = json.loads(msg)
            print(data)

asyncio.run(subscribe_orderbook())

구독 가능한 데이터 유형에는 다음과 같은 항목이 있습니다.

L2 오더북, l2Book
최근 체결, trades
계정 이벤트, userEvents
글로벌 펀딩비 관련 데이터

계정 이벤트처럼 사용자 주소와 관련된 데이터는 인증 또는 주소 기반 구성이 필요할 수 있으므로 공식 문서를 확인해야 합니다.

자주 발생하는 문제

1. 요청 형식 오류

가장 흔한 문제는 JSON 요청 형식 오류입니다. Hyperliquid API는 필드 이름과 타입에 엄격합니다. 예를 들어 정수로 보내야 하는 값을 문자열로 보내거나, 필드명을 잘못 입력하면 요청이 거부될 수 있습니다.

오류 메시지가 항상 직관적이지 않을 수 있으므로, 문제가 발생하면 공식 문서의 요청 예시와 실제 payload를 하나씩 비교하는 것이 좋습니다.

2. 서명 구성 오류

EIP-712 서명은 타입 정의, 도메인 구분자, 메시지 구조 등 세부 요소가 많습니다. 직접 구현하면 실수하기 쉽습니다.

가능하다면 커뮤니티 또는 공식에서 유지보수하는 Hyperliquid SDK를 우선 검토하는 것이 좋습니다. Python과 JavaScript 생태계 모두에서 관련 SDK를 찾을 수 있으며, SDK를 사용하면 서명 구성과 요청 형식 처리의 실수를 줄일 수 있습니다.

3. 타임스탬프 동기화 문제

거래 요청에는 일반적으로 현재 타임스탬프가 포함되며, 유효 시간 범위가 제한됩니다. 로컬 시스템 시간이 네트워크 시간과 크게 차이 나면 요청이 만료된 것으로 처리될 수 있습니다.

운영 서버에서는 NTP 등을 사용해 시간을 안정적으로 동기화하는 것이 좋습니다.

4. 네트워크 예외 처리 부족

운영 환경에서는 네트워크 오류를 반드시 고려해야 합니다. WebSocket 연결은 네트워크 변동으로 끊길 수 있고, REST 요청도 일시적인 실패를 만날 수 있습니다.

전략 코드는 다음 기능을 갖추는 것이 좋습니다.

WebSocket 자동 재연결
구독 채널 재등록
REST 요청 재시도
지수 백오프 적용
중복 주문 방지 로직
주문 상태 재확인 로직

자동매매에서 네트워크 오류는 단순한 장애가 아니라 실제 포지션 리스크로 이어질 수 있습니다.

속도 제한 개요

Hyperliquid는 API 유형별로 서로 다른 rate limit을 적용합니다. 구체적인 수치는 공식 문서의 최신 버전을 확인해야 합니다.

일반적으로는 Info 계열 조회 API의 제한이 상대적으로 완화되어 있고, Exchange 계열 거래 API의 제한은 더 엄격합니다. 특히 짧은 시간에 주문과 취소를 반복하는 전략은 속도 제한에 민감합니다.

429 오류를 받았다면 단순히 즉시 재시도하는 방식은 피해야 합니다. 요청을 잠시 중단하고 지수 백오프를 적용하는 것이 바람직합니다.

개발 환경과 운영 전 체크리스트

실제 전략을 배포하기 전에는 다음 사항을 권장합니다.

1. 작은 포지션으로 실거래 테스트하기

Hyperliquid의 무기한 선물 거래에 대해 독립적인 테스트넷이 항상 제공된다고 가정해서는 안 됩니다. 따라서 처음 실험할 때는 반드시 작은 포지션으로 테스트해야 합니다.

전략 코드가 의도대로 주문을 내는지, 청산 위험이 어떻게 변하는지, 슬리피지와 수수료가 예상 범위 안에 있는지 확인해야 합니다.

2. 서명 키와 메인 자산 분리하기

API 거래용 키와 장기 보관용 메인 계정은 분리하는 것이 좋습니다. 별도의 주소나 서브 계정을 만들고, 해당 계정에 감당 가능한 범위의 자금만 배치하세요.

OneKey 지갑의 다중 계정 관리 기능을 활용하면 이런 분리를 비교적 쉽게 구성할 수 있습니다. OneKey를 다운로드해 데스크톱과 모바일에서 계정을 나누어 관리하고, OneKey Perps를 통해 포지션과 거래 흐름을 확인하는 방식이 실용적입니다.

3. 수동 확인용 워크플로우 만들기

자동화 전략을 운영하더라도 모든 것을 코드에만 맡기는 것은 위험합니다. 다음과 같은 수동 확인 절차를 마련하는 것이 좋습니다.

전략 시작 전 계정 잔고 확인
미체결 주문 확인
포지션 방향과 수량 확인
레버리지와 증거금 상태 확인
비정상 주문 발생 시 즉시 중단할 수 있는 절차 마련

OneKey Perps는 이런 확인 과정을 실제 거래 흐름 안에서 점검하는 데 도움이 됩니다. 개발자는 API로 자동화 로직을 구성하되, OneKey와 OneKey Perps를 통해 계정 보안과 포지션 관리를 병행하는 방식을 고려할 수 있습니다.

4. 코드와 서명 로직 검토하기

지갑 서명 연동을 구현할 때는 서명 대상 메시지가 정확한지, 사용자가 의도한 주문과 실제 서명되는 payload가 일치하는지 확인해야 합니다. OneKey GitHub의 예시는 애플리케이션 레벨에서 지갑 서명을 안전하게 통합하는 방식에 대한 참고 자료가 될 수 있습니다.

FAQ

Q1. Hyperliquid API를 사용하려면 계정 가입이 필요한가요?

전통적인 의미의 회원가입은 필요하지 않습니다. 이더리움 호환 지갑 주소가 있으면 됩니다. 해당 주소가 Hyperliquid에서 최초 입금 등 필요한 초기 작업을 완료하면 API를 사용할 수 있습니다.

일반적인 이메일 가입이나 KYC 절차와는 다른 구조입니다. 다만 지역별 규제와 서비스 접근 가능 여부는 사용자가 직접 확인해야 합니다.

Q2. Python으로 Hyperliquid API를 호출할 때 사용할 수 있는 SDK가 있나요?

공식 또는 커뮤니티에서 제공하는 Python SDK가 있습니다. 최신 유지보수 버전은 Hyperliquid 공식 GitHub 또는 관련 문서에서 확인하는 것이 좋습니다.

SDK를 사용하면 EIP-712 서명 구성, 요청 포맷 처리, 응답 파싱을 직접 구현하는 부담을 줄일 수 있습니다.

Q3. WebSocket 연결이 끊기면 어떻게 자동 재연결하나요?

WebSocket 클라이언트 코드에 heartbeat, ping, 자동 재연결 로직을 구현하는 것이 좋습니다. 연결이 끊기면 짧게 대기한 뒤 다시 연결하고 필요한 채널을 다시 구독해야 합니다.

예를 들어 1~5초 정도 대기 후 재연결을 시도할 수 있으며, 장애가 길어질 경우 지수 백오프를 적용해 서버에 과도한 요청을 보내지 않도록 해야 합니다.

Q4. API 거래의 자금 보안은 어떻게 관리해야 하나요?

API 거래의 보안은 결국 개인키 보관 방식에 달려 있습니다. 개인키가 노출되면 공격자가 정상적인 서명을 만들어 거래를 실행할 수 있습니다.

OneKey 하드웨어 지갑을 사용하면 개인키가 인터넷에 연결된 기기 밖으로 노출되지 않도록 관리할 수 있습니다. 또한 API 전용 계정에는 합리적인 포지션 한도와 자금 한도를 두고, 미체결 주문과 포지션 상태를 정기적으로 확인하는 것이 좋습니다.

Q5. Hyperliquid API는 조건부 주문과 손절 주문을 지원하나요?

Hyperliquid는 Trigger Order 유형을 지원하며, 여기에는 손절과 익절 로직이 포함될 수 있습니다. 구체적인 파라미터와 트리거 조건은 공식 문서의 Order Type 관련 설명을 확인해야 합니다.

복잡한 조건부 로직은 전략 레이어에서 직접 구현할 수도 있습니다. 예를 들어 WebSocket으로 가격과 포지션 상태를 모니터링하다가 조건이 충족되면 거래 API를 호출하는 방식입니다.

정리

Hyperliquid API는 개발자에게 비교적 완성도 높은 온체인 DEX 인터페이스를 제공합니다. Info 계열 API는 시세 모니터링과 데이터 분석 도구를 만드는 데 적합하고, Exchange 계열 API와 WebSocket을 함께 사용하면 단순 자동 주문부터 복잡한 마켓메이킹 전략까지 구현할 수 있습니다.

다만 EIP-712 서명 기반 구조에서는 개인키 관리가 핵심입니다. OneKey 지갑을 서명 및 계정 관리의 보안 기반으로 사용하면, 수동 거래뿐 아니라 API 거래 환경에서도 키를 더 안전하게 분리할 수 있습니다. 실전 운영에서는 OneKey Perps를 통해 포지션과 거래 흐름을 확인하고, API 전략은 제한된 계정과 작은 규모에서 단계적으로 검증하는 접근이 현실적입니다.

Hyperliquid API 개발을 시작하려는 경우, 먼저 OneKey를 다운로드해 별도 거래 계정을 구성하고 OneKey Perps에서 기본적인 포지션 관리 흐름을 익혀보세요. 그다음 작은 규모의 API 테스트부터 시작하는 것을 권장합니다.

---면책 고지---

이 글은 기술 참고용 정보이며 투자 조언이 아닙니다. API 거래에는 자동화 오류, 코드 버그, 네트워크 장애, 예기치 못한 주문 실행 등의 위험이 있습니다. 무기한 선물 거래는 레버리지 특성상 손실 위험이 매우 높으며, 원금 이상의 손실 가능성도 고려해야 합니다. 관련 기술과 시장 리스크를 충분히 이해한 뒤 신중하게 판단하세요. 과거 전략 성과는 미래 수익을 보장하지 않습니다.