Hyperliquid SDK로 프로그래매틱 트레이딩하기

2026년 5월 6일

  • hyperliquid sdk

  • hyperliquid programmatic trade

  • hyperliquid python sdk

  • hyperliquid api 프로그래매틱 트레이딩

  • 온체인 무기한 선물 봇

프로그래매틱 트레이딩은 더 이상 기관만의 영역이 아닙니다. 기본적인 프로그래밍 지식이 있는 개인 투자자도 API와 SDK를 활용해 주문, 포지션 조회, 체결 모니터링, 리스크 제어를 자동화할 수 있습니다.

Hyperliquid는 온체인 무기한 선물 거래소로, REST API와 WebSocket 인터페이스를 제공하며 공식 및 커뮤니티 SDK도 활발히 관리되고 있습니다. 개발자는 Python 또는 JavaScript/TypeScript로 비교적 짧은 코드만 작성해 주문 실행, 포지션 확인, 오류 처리 같은 핵심 흐름을 구성할 수 있습니다.

이 글에서는 환경 설정부터 Python·JavaScript SDK 사용 방식, 주문 및 WebSocket 처리, 운영 환경에서의 보안 설계까지 단계별로 살펴봅니다. 특히 실제 자금을 다루는 봇에서는 OneKey 하드웨어 지갑을 서명 레이어로 활용하는 것이 왜 중요한지도 함께 설명합니다.

Hyperliquid를 프로그래매틱 트레이딩에 사용하는 이유

중앙화 거래소와 비교했을 때 Hyperliquid의 장점은 다음과 같습니다.

  • 거래 정산이 온체인에서 이루어져 자금을 제3자에게 예치할 필요가 적습니다.
  • 오더북은 오프체인 매칭과 온체인 정산을 결합한 구조로, 속도와 투명성을 함께 추구합니다.
  • API 설계가 비교적 간결하고, 공식 문서와 커뮤니티 자료가 지속적으로 업데이트됩니다.
  • 지갑 기반으로 접근할 수 있어 셀프 커스터디 환경에서 자동화 전략을 구현하기 좋습니다.

퀀트 트레이더나 자동화 전략 개발자 입장에서는 중앙화 거래소에 가까운 체감 속도를 활용하면서도, 온체인 기반의 자산 관리 방식을 유지할 수 있다는 점이 큰 장점입니다.

환경 준비와 SDK 설치

Python 환경

현재 커뮤니티에서 관리되는 Python SDK는 pip로 설치할 수 있습니다. 의존성 충돌을 줄이기 위해 가상환경에서 작업하는 것을 권장합니다.

python -m venv hl_env
source hl_env/bin/activate
pip install hyperliquid-python-sdk

SDK 소스 코드는 OneKey GitHub의 생태계 협력 저장소 및 Hyperliquid 공식 조직에서 확인할 수 있습니다. 최신 저장소 주소와 사용법은 Hyperliquid 공식 문서를 기준으로 확인하는 것이 좋습니다.

JavaScript/TypeScript 환경

Node.js 환경을 선호한다면 다음과 같이 설치할 수 있습니다.

npm install @nktkas/hyperliquid

또는 공식 유지보수 패키지를 사용할 수 있으며, 실제 설치 시에는 npm registry의 최신 버전을 확인하세요. TypeScript 사용자는 타입 정의를 함께 활용할 수 있어 IDE 자동완성과 코드 안정성 측면에서 유리합니다.

API 연결과 클라이언트 초기화

인증 방식

Hyperliquid는 거래 요청 인증에 개인키 서명을 사용합니다. 주문을 제출할 때마다 지갑 개인키로 EIP-712 구조화 메시지에 서명해 요청이 위조되지 않았음을 증명합니다.

Python 예시 의사코드는 다음과 같습니다.

from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from eth_account import Account
import os

# 개인키는 환경변수에서 읽고, 코드에 하드코딩하지 마세요.
private_key = os.environ["HL_PRIVATE_KEY"]

account = Account.from_key(private_key)

info = Info(base_url="https://api.hyperliquid.xyz")
exchange = Exchange(account, base_url="https://api.hyperliquid.xyz")

운영 환경에서는 소프트웨어 개인키 대신 OneKey 하드웨어 지갑을 서명 레이어로 사용하는 것을 강력히 권장합니다. 개인키가 하드웨어 보안 칩 밖으로 나오지 않기 때문에, 서버가 침해되더라도 키 자체가 유출될 가능성을 크게 줄일 수 있습니다.

시장 데이터와 계정 상태 조회

시세 스냅샷 가져오기

# 모든 무기한 선물의 메타 정보와 현재 가격 조회
meta_and_asset_ctx = info.meta_and_asset_ctxs()

# 반환값에는 markPx(마크 가격), funding(펀딩비율) 등의 필드가 포함됩니다.

포지션과 잔고 조회

user_state = info.user_state(account.address)

# user_state에는 marginSummary(증거금 요약)와 assetPositions(종목별 포지션)이 포함됩니다.
for pos in user_state["assetPositions"]:
    print(pos["position"]["coin"], pos["position"]["szi"])  # 종목과 포지션 수량

자동화 전략에서는 단순히 주문만 보내는 것이 아니라, 주문 전후로 계정 상태를 확인하는 루틴이 중요합니다. 특히 레버리지를 사용하는 무기한 선물에서는 증거금 상태와 미실현 손익을 주기적으로 확인해야 합니다.

주문 실행

시장가 주문

order_result = exchange.market_open(
    coin="BTC",
    is_buy=True,
    sz=0.001,      # 주문 수량
    slippage=0.01  # 최대 허용 슬리피지 1%
)

print(order_result)

시장가 주문은 빠르게 진입하거나 청산할 때 유용하지만, 변동성이 큰 구간에서는 슬리피지가 커질 수 있습니다. 전략 코드에는 최대 허용 슬리피지와 주문 실패 시 처리 로직을 반드시 포함하는 것이 좋습니다.

지정가 주문

order_result = exchange.order(
    coin="ETH",
    is_buy=False,
    sz=0.1,
    limit_px=3200.0,  # 지정가
    order_type={"limit": {"tif": "Gtc"}}  # Good Till Cancel
)

tif 필드는 다음과 같은 옵션을 지원합니다.

  • Gtc: 취소 전까지 유효
  • Ioc: 즉시 체결 가능한 수량만 체결하고 나머지는 취소
  • Alo: 메이커 주문만 허용

전략의 목적이 추세 추종인지, 시장 조성인지, 그리드인지에 따라 적절한 옵션을 선택해야 합니다.

배치 주문

마켓메이킹이나 그리드 전략에서는 한 번에 여러 주문을 제출해야 하는 경우가 많습니다. SDK의 배치 주문 인터페이스를 사용하면 네트워크 왕복 횟수를 줄일 수 있습니다.

orders = [
    {
        "coin": "BTC",
        "is_buy": True,
        "sz": 0.001,
        "limit_px": 60000,
        "order_type": {"limit": {"tif": "Gtc"}}
    },
    {
        "coin": "BTC",
        "is_buy": False,
        "sz": 0.001,
        "limit_px": 61000,
        "order_type": {"limit": {"tif": "Gtc"}}
    },
]

result = exchange.bulk_orders(orders)

배치 주문은 편리하지만, 동시에 여러 주문이 제출되는 만큼 포지션 한도, 증거금 사용량, 취소 로직을 함께 설계해야 합니다.

주문 취소와 수정

# 주문 취소에는 coin과 oid(주문 ID)가 필요합니다.
cancel_result = exchange.cancel(coin="BTC", oid=123456789)

# 주문 수정은 일반적으로 cancel + replace 방식으로 처리됩니다.
modify_result = exchange.modify_order(
    oid=123456789,
    coin="BTC",
    is_buy=True,
    sz=0.002,
    limit_px=59500,
    order_type={"limit": {"tif": "Gtc"}}
)

운영 중인 봇에서는 주문 ID를 안정적으로 저장하고, 체결·부분 체결·취소 상태를 일관되게 추적해야 합니다. 데이터베이스나 로그 시스템을 함께 사용하는 것이 좋습니다.

오류 처리 베스트 프랙티스

프로그래매틱 트레이딩에서 오류 처리는 일반 비즈니스 로직만큼 중요합니다. 네트워크 지연, API 제한, 주문 거절, 서명 실패, 잔고 부족, 가격 급변 등 다양한 예외가 발생할 수 있습니다.

예를 들어 재시도 로직은 다음과 같이 구성할 수 있습니다.

import time

def place_with_retry(exchange, kwargs, max_retries=3):
    for attempt in range(max_retries):
        try:
            return exchange.order(**kwargs)
        except Exception as e:
            if attempt == max_retries - 1:
                raise

            wait = 2 ** attempt  # 지수 백오프: 1초, 2초, 4초
            time.sleep(wait)

다만 모든 오류를 무조건 재시도해서는 안 됩니다. 잔고 부족, 잘못된 파라미터, 전략상 금지된 포지션 증가 같은 오류는 재시도보다 즉시 중단하고 알림을 보내는 편이 안전합니다.

WebSocket으로 체결 실시간 감지

REST 폴링은 저빈도 전략에 적합하지만, 더 빠른 반응이 필요한 경우 WebSocket 구독을 사용하는 것이 좋습니다.

from hyperliquid.websocket_manager import WebsocketManager

def on_fill(data):
    print("체결 콜백:", data)

ws = WebsocketManager(base_url="wss://api.hyperliquid.xyz")

ws.subscribe(
    {"type": "userFills", "user": account.address},
    callback=on_fill
)

ws.start()

정확한 WebSocket 구독 형식과 이벤트 필드는 Hyperliquid 공식 문서를 확인하세요. 실전에서는 WebSocket 연결 끊김, 중복 이벤트, 지연 이벤트를 처리하는 로직도 필요합니다.

OneKey 하드웨어 지갑으로 운영 봇 보호하기

소프트웨어 지갑, 즉 핫월렛의 개인키는 보통 메모리나 디스크에 저장됩니다. 서버가 공격을 받으면 개인키가 유출되어 자금이 빠르게 이동될 수 있습니다. 실제 자금을 운용하는 운영 봇이라면 서명 구조를 더 보수적으로 설계해야 합니다.

권장 아키텍처는 다음과 같습니다.

  1. OneKey 하드웨어 지갑을 별도의 서명 서버에 연결합니다.
  2. 트레이딩 봇은 주문에 필요한 서명 메시지를 생성합니다.
  3. 메시지를 OneKey로 전달해 하드웨어 보안 요소 안에서 서명합니다.
  4. 서명 결과만 봇으로 반환하고, 봇은 이를 Hyperliquid에 제출합니다.

이 구조에서는 개인키가 항상 하드웨어 내부에 머물며, 소프트웨어 계층에서 개인키를 직접 추출할 수 없습니다. 또한 EIP-712 구조화 서명은 OneKey 화면에서 서명 대상 정보를 확인할 수 있게 해주므로, 필요할 경우 사용자가 직접 내용을 검토할 수 있습니다.

Hyperliquid가 지원하는 API Agent 지갑 또는 권한 위임 구조를 함께 사용하는 것도 좋습니다. 봇 전용 지갑을 설정하고 특정 계정에서만 작동하도록 제한하면, 운영 리스크를 더 세밀하게 관리할 수 있습니다.

OneKey Perps를 활용한 실전 워크플로우

코드를 직접 작성하지 않고 온체인 무기한 선물 거래를 경험하고 싶다면 OneKey Perps를 먼저 사용해보는 것도 현실적인 선택입니다.

OneKey Perps는 지갑 기반으로 무기한 선물 거래에 접근할 수 있는 인터페이스를 제공하며, OneKey 하드웨어 지갑과 함께 사용할 경우 키 관리 부담을 줄이는 데 도움이 됩니다. 개발자라면 OneKey Perps로 실제 주문 흐름과 포지션 관리 방식을 먼저 이해한 뒤, 필요한 부분만 Hyperliquid SDK로 자동화하는 방식이 효율적입니다.

예를 들어 다음과 같은 순서로 접근할 수 있습니다.

  1. OneKey 앱에서 지갑을 준비합니다.
  2. OneKey Perps를 통해 소액으로 주문, 청산, 포지션 관리 흐름을 익힙니다.
  3. 전략이 명확해지면 Hyperliquid SDK로 주문 로직을 자동화합니다.
  4. 운영 환경에서는 OneKey 하드웨어 지갑을 서명 레이어로 분리합니다.

이 방식은 처음부터 모든 것을 코드로 구현하는 것보다 실수를 줄이고, 실제 거래 흐름을 더 안전하게 파악하는 데 도움이 됩니다.

자주 쓰는 보조 도구와 자료

  • Hyperliquid 공식 문서: API 명세, 필드 설명, WebSocket 구독 형식 확인
  • OneKey 공식 자료: 하드웨어 지갑 제품 정보와 서명 관련 기능 확인
  • WalletConnect 문서: WalletConnect 프로토콜을 통해 서명을 연결해야 하는 경우 참고

최신 API 스펙, 패키지 이름, 제한 정책은 변경될 수 있으므로 운영 전 반드시 공식 문서를 다시 확인하세요.

자주 묻는 질문

Q1. SDK와 REST API를 직접 호출하는 방식은 무엇이 다른가요?

SDK는 서명 로직, 요청 포맷, 일부 오류 처리를 감싸주기 때문에 보일러플레이트 코드를 줄일 수 있습니다. REST API를 직접 호출하면 더 유연하지만, EIP-712 서명과 요청 형식을 직접 구현해야 합니다. 처음 시작한다면 SDK를 사용하고, 구조를 충분히 이해한 뒤 필요에 따라 네이티브 HTTP 호출로 전환하는 편이 좋습니다.

Q2. 프로그래매틱 트레이딩에 KYC가 필요한가요?

Hyperliquid는 탈중앙화 프로토콜이며, 현재 기준으로 지갑 주소를 통해 거래할 수 있습니다. 다만 거주 지역의 규제와 세무 요건은 사용자가 직접 확인해야 합니다. 이 글은 법률 또는 세무 자문이 아닙니다.

Q3. 극단적인 시장 상황에서 봇 손실을 줄이려면 어떻게 해야 하나요?

전략 레이어에서 다음과 같은 보호 장치를 구현하는 것이 좋습니다.

  • 최대 손실 한도 설정 및 도달 시 주문 중단
  • 미실현 손익과 계정 순자산 비율 모니터링
  • 손절 주문 또는 SL 주문 유형 활용
  • 실제 포지션이 전략상 예상 포지션과 일치하는지 주기적으로 확인
  • WebSocket 장애 시 REST 기반 백업 조회 루틴 구성

무기한 선물은 레버리지 상품이므로 작은 가격 변동도 큰 손익으로 이어질 수 있습니다.

Q4. OneKey 하드웨어 지갑은 자동화 스크립트와 어떻게 연동하나요?

OneKey 공식 SDK를 통해 하드웨어 서명 인터페이스를 호출하거나, USB/Bluetooth 연결과 eth_sign 계열 인터페이스를 조합해 서명할 수 있습니다. 운영 배포에서는 보통 서명 서비스를 거래 로직과 분리해 별도 프로세스 또는 서버로 구성합니다. 이렇게 하면 공격 표면을 줄이고, 키 관리 정책을 더 명확하게 유지할 수 있습니다.

Q5. 배치 주문 API에는 빈도 제한이 있나요?

최신 제한 정책은 Hyperliquid 공식 문서를 확인해야 합니다. 일반적으로는 요청 사이에 적절한 지연을 두고, 토큰 버킷 또는 슬라이딩 윈도우 방식으로 요청 빈도를 제어하는 것이 좋습니다. 제한에 걸리면 주문 실패나 지연이 발생할 수 있으므로, 봇은 이를 감지하고 안전하게 중단하거나 재시도해야 합니다.

마무리: 실행 가능한 스크립트에서 신뢰할 수 있는 시스템으로

Hyperliquid SDK는 온체인 무기한 선물의 프로그래매틱 트레이딩 진입 장벽을 크게 낮춰줍니다. 하지만 단순히 “작동하는 스크립트”와 “신뢰할 수 있는 운영 시스템”은 다릅니다. 실제 자금을 다룬다면 서명 보안, 오류 처리, 포지션 모니터링, 손실 제한, API 제한 대응까지 함께 설계해야 합니다.

코드 없이 먼저 온체인 무기한 선물 거래 흐름을 경험하고 싶다면 OneKey 앱을 설치하고 OneKey Perps를 사용해보세요. 과도한 기대수익을 전제로 하기보다, 지갑 기반 거래와 포지션 관리 방식을 이해하는 실용적인 출발점으로 활용하는 것이 좋습니다. 개발 역량이 있는 팀이라면 OneKey를 서명 백엔드로 통합해 봇 아키텍처의 키 관리 리스크를 낮출 수 있습니다.

OneKey를 다운로드해 지갑을 준비한 뒤, OneKey Perps에서 소액으로 워크플로우를 확인해보세요. 이후 필요에 따라 Hyperliquid SDK를 활용해 전략 자동화를 단계적으로 확장할 수 있습니다.

리스크 안내: 프로그래매틱 트레이딩은 기술적 복잡성과 시장 리스크를 모두 수반합니다. 무기한 선물 거래는 레버리지 특성을 가지며, 초기 투입금보다 큰 손실이 발생할 수 있습니다. 이 글은 기술 참고용이며 투자, 법률, 세무 자문이 아닙니다. 관련 위험을 충분히 이해하고 본인의 위험 감수 능력에 맞춰 신중하게 판단하세요. 가상자산 시장은 변동성이 크며, 과거 성과가 미래 수익을 보장하지 않습니다.

OneKey로 암호화 여정 보호하기

View details for OneKeyOneKey

OneKey

세계에서 가장 진보한 하드웨어 지갑.

View details for 앱 다운로드앱 다운로드

앱 다운로드

스캠 경고. 모든 코인 지원.

View details for OneKey SifuOneKey Sifu

OneKey Sifu

암호화 의문을 해결하기 위해, 한 번의 전화로.