Hyperliquid 플랫폼은 무기한 선물 거래를 위한 고성능 탈중앙화 거래소로서, 개발자에게 낮은 지연 시간 거래와 고급 기능을 제공합니다. 개발자들은 거래를 자동화하고, 시장을 모니터링하며, 맞춤형 애플리케이션을 구축하기 위해 Hyperliquid API를 자주 활용합니다.
Hyperliquid API의 핵심 구성 요소를 이해하는 것부터 시작합니다. API는 주요 범주로 나뉩니다: 시장 데이터를 조회하는 Info API, 거래 작업을 위한 Exchange API, 그리고 실시간 업데이트를 위한 WebSocket입니다. 또한, Python 및 Node.js와 같은 언어의 SDK는 상호 작용을 간소화합니다. 진행하면서 요청 매개변수의 작은 조정이 실행 효율성에 어떻게 상당한 개선을 가져오는지 알게 될 것입니다.
Hyperliquid API란 무엇인가요?
Hyperliquid API는 Hyperliquid의 탈중앙화 무기한 선물 거래소에 대한 프로그래밍 방식의 접근을 가능하게 합니다. 이는 메인넷과 테스트넷 환경 모두에서 작업을 지원합니다. 메인넷과 테스트넷에 연결합니다. API는 요청 및 응답에 JSON을 사용하며, 대부분의 작업에는 HTTP POST를, 구독에는 WebSocket을 사용합니다.
어떤 경우에는 전통적인 API 키 대신 개인 키를 사용하여 인증하지만, Hyperliquid는 보안 위임을 위해 API 지갑도 제공합니다. 이 지갑은 출금 권한 없이 주 계정을 대신하여 작동하여 자동화된 거래의 보안을 강화합니다. 예를 들어, Hyperliquid 앱을 통해 API 지갑을 생성하고, 이를 승인한 다음 스크립트에서 해당 개인 키를 사용합니다.
다음으로 데이터 유형을 고려해 보세요. API는 특정 구조체와 열거형을 사용합니다. 자산은 유니버스 목록의 인덱스로 식별되며, 주문 측면은 불리언(매수는 true, 매도는 false)을 사용하고, 시간 제한 옵션에는 '취소될 때까지 유효(Gtc)'가 포함됩니다. 요청의 정확성을 보장하기 위해 메타데이터 엔드포인트에서 이러한 세부 정보를 검색합니다.
이러한 기반을 바탕으로 개발 환경을 설정합니다. 올바른 구성은 일반적인 오류를 방지하고 반복 속도를 높입니다.
Hyperliquid API를 위한 환경 설정
프로그래밍 언어를 선택하고 관련 SDK를 설치하는 것부터 설정을 시작합니다. Python 사용자에게는 hyperliquid-python-sdk가 강력한 시작점을 제공합니다. pip install hyperliquid-python-sdk 명령어를 사용하여 pip를 통해 설치하세요. 이 SDK는 연결, 인증 및 일반적인 작업을 처리합니다.
그런 다음 자격 증명을 구성합니다. 계정 주소(공개 키)와 비밀 키(개인 키)가 포함된 config.json 파일을 생성합니다. 보안을 위해 전용 API 지갑을 생성합니다. Hyperliquid 앱으로 이동하여 "더보기 > API"를 선택하고, 키 이름을 입력하고, 지갑 주소를 붙여넣은 다음 "생성"을 클릭합니다. API 지갑을 승인하고 해당 개인 키를 구성 파일에 복사합니다.
SDK는 테스트를 위한 constants.TESTNET_API_URL과 같은 URL 상수를 가져옵니다. 클라이언트는 다음과 같이 초기화합니다:
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.TESTNET_API_URL, skip_ws=True)
이 설정은 초기에는 WebSocket을 건너뛰고 HTTP에 중점을 둡니다. 사용자 상태를 쿼리하여 연결을 테스트합니다:
user_state = info.user_state("your_account_address")
print(user_state)
응답에 계정 세부 정보가 표시되면 환경이 올바르게 작동하는 것입니다. 그러나 오류가 발생하면 개인 키와 네트워크 선택을 확인하세요.
Node.js의 경우 @nktkas/hyperliquid 패키지를 사용합니다. npm으로 설치한 다음, 지갑 관리를 위해 ethers를 사용하여 전송 및 클라이언트를 설정합니다. 개발 중 실제 자금을 사용하지 않으려면 isTestnet: true를 지정합니다.
Apidog와 같은 도구는 이 설정을 보완합니다. Hyperliquid API 사양을 Apidog로 가져오고, 키로 인증한 다음 요청을 시뮬레이션합니다. 이 접근 방식은 응답 구조를 빠르게 파악하여 수동 코딩 시간을 절약합니다.
설정이 완료되면 인증 방법으로 넘어갑니다. 올바른 인증은 작업이 안전하게 실행되도록 보장합니다.
Hyperliquid API로 인증하기
Hyperliquid는 블록체인 기반 시스템에서 작동하므로 주로 개인 키 서명을 통해 인증합니다. SDK는 지갑 인스턴스를 제공하면 서명을 자동으로 처리합니다.
SDK 없이 직접 API를 호출하는 경우, 개인 키를 사용하여 페이로드를 서명합니다. 요청 본문에는 재전송 보호를 위한 논스(nonce)가 포함되며, /exchange 또는 /info 엔드포인트에 POST 요청을 보냅니다.
API 지갑은 유연성을 더합니다. 이름을 지정하고, 주 지갑 주소에 연결하고, 키를 생성하고, 승인하여 API 지갑을 만듭니다. 이 지갑은 거래를 수행하지만 자금을 인출할 수는 없어 봇의 위험을 줄입니다. 코드에서는 API 지갑의 개인 키를 사용하면서 주 계정 주소를 지정합니다.
간단한 정보 요청을 보내 인증을 테스트합니다. 승인되지 않은 경우 API는 "사용자 또는 API 지갑이 존재하지 않습니다."와 같은 오류를 반환합니다. 이를 해결하려면 지갑에 무기한 선물 거래를 위한 USDC와 같은 최소 담보가 있는지 확인하세요.
보안은 여전히 가장 중요합니다. 키는 환경 변수나 보안 저장소에 저장하고, 주기적으로 교체하며, 비정상적인 활동을 모니터링합니다. 인증이 완료되면 Info API 엔드포인트를 탐색합니다.
Info API 엔드포인트 탐색
Info API는 시장 및 계정 데이터에 대한 읽기 전용 접근을 제공합니다. 이를 사용하여 메타데이터, 가격, 주문 등을 가져올 수 있으며, 공개 데이터의 경우 인증이 필요 없습니다.
자산 유니버스 및 컨텍스트를 반환하는 메타 엔드포인트부터 시작합니다. Node.js에서는 다음과 같습니다:
const [meta] = await infoClient.metaAndAssetCtxs();
이는 이름, 인덱스, 최대 레버리지와 같은 사양을 가진 자산 배열을 반환합니다. 거래 요청에서 자산 인덱스를 사용합니다.
다음으로, 모든 쌍의 현재 중간값을 반환하는 allMids로 중간 가격을 쿼리합니다. 미결 주문은 openOrders에서 가져오며, 이는 귀하의 주소를 필요로 합니다.
다른 엔드포인트는 다음과 같습니다:
- userState: 포지션, 마진 및 잔액을 검색합니다.
- fundingHistory: 시간 경과에 따른 펀딩 비율을 보여줍니다.
- l2Book: 코인에 대한 레벨 2 오더북을 제공합니다.
{"type": "meta"}와 같은 JSON 본문으로 POST 요청을 /info에 보냅니다. 응답은 일관된 구조를 사용하며, "data"에 결과가 포함됩니다.
Apidog가 여기서 도움이 됩니다. Info API를 위한 컬렉션을 설정하고, 각 유형에 대한 요청을 추가하며, 코인 또는 주소를 매개변수화합니다. 이 시각화는 데이터 흐름을 이해하는 데 도움이 됩니다.
데이터를 수집하면서 거래 실행을 위해 Exchange API로 전환합니다.
거래를 위한 Exchange API 엔드포인트 사용
Exchange API는 주문, 취소, 수정과 같은 작업을 처리합니다. 모든 요청은 서명된 페이로드로 인증합니다.
자산 인덱스, 측면(매수/매도), 가격, 크기, 축소 전용 플래그, 유형(지정가 또는 시장가)과 같은 매개변수를 정의하여 주문을 합니다. 지정가 매도의 경우:
Elixir (SDK 문서에서):
Hyperliquid.Api.Exchange.place_order(order)
여기서 order는 a: 자산, b: false (매도), p: "100", s: "0.1", r: false, t: {limit: {tif: "Gtc"}}를 포함하는 맵입니다.
성공하면 응답에는 상태와 주문 ID가 포함됩니다.
자산과 oid(주문 ID)를 사용하여 주문을 취소합니다:
Hyperliquid.Api.Exchange.cancel_order(asset, oid)
일괄 처리의 경우, 목록과 함께 cancel_orders를 사용합니다.
수정 작업도 비슷하게 진행됩니다: oid와 새 매개변수를 지정합니다.
다른 작업에는 레버리지 업데이트가 포함됩니다:
Hyperliquid.Api.Exchange.update_leverage(asset, is_cross, leverage)
그리고 계정 간 자금 이동을 위한 spot_perp_transfer와 같은 이체도 있습니다.
응답 상태를 확인하여 오류를 처리합니다. 성공 시 "ok", 그렇지 않으면 "마진 부족"과 같은 세부 정보를 확인합니다.
예시는 실제 사용법을 보여줍니다. 예를 들어, 가격 확인을 위해 Info API를 사용하고 주문 배치를 위해 Exchange API를 사용하여 가격이 임계값 아래로 떨어지면 매수 주문을 하는 봇을 구축할 수 있습니다.
또한, 응답성을 높이기 위해 실시간 업데이트를 위한 WebSocket을 통합합니다.
실시간 데이터를 위한 WebSocket 통합
라이브 스트림을 위해 WebSocket에 연결합니다. 메인넷 또는 테스트넷에 해당하는 wss://api.hyperliquid.xyz/ws를 사용합니다.
JSON을 보내 구독합니다: {"method": "subscribe", "subscription": {"type": "trades", "coin": "SOL"}}.
서버는 확인 응답을 보낸 다음, 새로운 거래와 같은 업데이트를 푸시합니다.
오더북, 사용자 이벤트, 알림과 같은 주제를 처리합니다. Python SDK에서는 skip_ws=False로 설정하여 활성화합니다.
이 실시간 기능은 체결 시 주문 조정과 같이 시장 변화에 즉시 반응할 수 있게 해줍니다.
엔드포인트를 다루었으니, Python SDK를 심층적으로 살펴보겠습니다.
Hyperliquid Python SDK 활용
Python SDK는 API 호출을 클래스로 추상화합니다. 쿼리에는 Info를, 작업에는 Exchange를 가져옵니다.
다음과 같이 기본 주문을 할 수 있습니다 (예시에서):
먼저, 설정을 로드합니다:
import json
def address_and_private_key():
with open("examples/config.json") as f:
config = json.load(f)
return config["account_address"], config["secret_key"]
그런 다음 Exchange를 초기화합니다:
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
address, private = address_and_private_key()
exchange = Exchange(address, private, base_url=constants.TESTNET_API_URL)
주문하기:
order_result = exchange.order("BTC", True, 0.02, 30000, {"limit": {"tif": "Gtc"}})
print(order_result)
이것은 0.02 BTC를 $30,000 지정가로 매수합니다.
일괄 주문 또는 취소와 같은 고급 기능을 위해 이를 확장할 수 있습니다.
SDK는 또한 관리 계정을 위한 볼트 주소를 지원합니다.
저장소의 예시는 basic_order, user_state 등을 다루며, 완전한 워크플로우를 보여줍니다.
구축하면서 성능 최적화를 위한 모범 사례를 통합합니다.
Hyperliquid API 사용을 위한 모범 사례
스로틀링을 피하기 위해 속도 제한을 모니터링합니다. Hyperliquid는 IP별 및 계정별 제한을 적용합니다.
재정적 손실을 방지하기 위해 모든 개발에 테스트넷을 사용합니다.
오류 처리는 세부 정보 로깅과 백오프를 사용한 일시적인 실패 재시도를 포함합니다.
확장성을 위해 여러 취소와 같이 가능한 경우 요청을 일괄 처리합니다.
보안은 API 지갑 사용과 최소 권한 원칙까지 확장됩니다.
Hyperliquid는 시맨틱 버전 관리를 따르므로 SDK 업데이트와 함께 코드를 버전 관리합니다.
Apidog와 같은 도구는 단위 테스트를 위한 응답 모의 처리를 돕습니다.
문제가 발생하면 다음으로 문제 해결이 진행됩니다.
일반적인 Hyperliquid API 문제 해결
담보가 부족할 때 "마진 부족" 오류가 발생합니다. USDC를 입금하여 해결하세요.
자산을 찾을 수 없으면 메타에서 인덱스를 확인하세요.
인증 오류는 유효하지 않은 키에서 발생합니다. API 지갑을 재생성하고 승인하세요.
네트워크 문제는 URL을 확인하고 필요한 경우 프록시를 사용해야 합니다.
Apidog로 실패한 요청을 다시 재생하여 디버깅합니다.
SDK의 로그는 분석을 위한 타임스탬프와 페이로드를 제공합니다.
이러한 팁을 통해 안정적인 통합을 유지할 수 있습니다.
Hyperliquid API의 고급 사용 사례
l2Book을 모니터링하고 불균형 시 주문을 하는 트레이딩 봇을 구축합니다.
전략에는 과거 펀딩 비율을 활용한 차익 거래 기회가 포함됩니다.
하위 계정은 분리된 거래를 가능하게 합니다: 이름으로 생성하고, 자금을 이체하며, 별도로 거래합니다.
볼트 이체는 공유 유동성 풀을 지원합니다.
백테스트를 위해 API의 과거 데이터로 시뮬레이션합니다.
Apidog와의 통합은 팀 내에서 협업 디버깅을 가능하게 합니다.
마지막으로, 향후 개선 사항을 고려하여 마무리합니다.
결론: 탈중앙화 거래를 위한 Hyperliquid API 마스터하기
이제 Hyperliquid API를 효과적으로 사용할 수 있는 지식을 갖추게 되었습니다. 설정 및 인증부터 엔드포인트 및 SDK에 이르기까지 이 가이드는 정교한 애플리케이션을 구축할 수 있도록 준비시켜 줍니다. 코드의 점진적인 개선이 상당한 성능 향상을 가져온다는 것을 기억하세요. 테스트넷에서 실험하고, Apidog와 같은 도구를 활용하며, Hyperliquid의 문서를 최신 상태로 유지하세요. 플랫폼이 발전함에 따라 귀하의 기술은 새로운 기능을 활용할 수 있는 위치에 놓이게 될 것입니다.