개발자를 위한 Hyperliquid 인프라 스택 2026: Info API, WebSocket, gRPC, 오더북, HyperEVM RPC

이 글은 영어 원문의 한국어 번역본입니다. 원문은 여기에서 볼 수 있습니다.

REST API를 1초마다 폴링하는 Hyperliquid(하이퍼리퀴드) 트레이딩 봇은 폴링 사이에 발생한 체결을 놓칩니다. 퍼블릭 WebSocket을 쓰는 마켓메이커는 서버가 예고 없이 연결을 끊으면 상태를 잃습니다. 오더북을 읽으려고 eth_call을 보내는 인덱서는 아무것도 받지 못합니다. 오더북은 HyperEVM이 아니라 HyperCore에 있기 때문입니다. 세 경우 모두 같은 실수입니다. 작업에 맞지 않는 Hyperliquid API를 고른 것입니다.

이 가이드는 Hyperliquid의 각 API가 어떤 일을 하는지 정리하고, 요청 형식을 보여주며, 애플리케이션 유형별 스택을 제시합니다. HyperBFT 합의, API 서버, 노드 등 Hyperliquid 자체의 동작 방식은 Hyperliquid 인프라 작동 방식을 참고하세요. 가격, 아카이브, HyperCore 지원 범위로 제공업체를 비교하려면 Hyperliquid RPC 제공업체 순위를 읽어보세요.

한 문단으로 보는 HyperCore와 HyperEVM

Hyperliquid는 하나의 상태를 가진 하나의 체인이며, HyperBFT 합의 아래 두 개의 실행 환경으로 나뉩니다. HyperCore는 네이티브 트레이딩 엔진입니다. 무기한 선물과 현물 오더북, 청산소(clearinghouse), 펀딩, 청산이 모두 온체인에서 처리되며 거래에 가스비가 없습니다. HyperEVM은 체인 ID 999의 범용 EVM입니다. Solidity 컨트랙트를 실행하고 프리컴파일을 통해 HyperCore 상태를 읽을 수 있습니다. EVM 툴링은 HyperEVM에서 그대로 작동합니다. HyperCore 데이터는 Hyperliquid 전용 API가 필요합니다. 대부분의 프로덕션 애플리케이션은 둘 다 필요합니다. 자세한 내용은 아키텍처 페이지에 있습니다.

HyperCore

The trading layer

Fully on-chain order books and matching for perpetuals and spot markets. Every order, cancel, and fill is recorded in a block.

Consensus

HyperBFT

Orders per second

200k

Order books

On-chain

• Perps up to 40x on BTC
• HIP-3 perp DEXs
• HIP-4 outcome markets

HyperEVM

The smart contract layer

An Ethereum-compatible environment for standard Solidity contracts, wallets, and tooling.

Chain ID

999

Block time

< 1s

Gas token

HYPE

• ethers.js
• viem
• Hardhat
• Foundry

Orders, cancels, fills

Transactions

HyperBFT consensusOne state: both layers land in the same blocks, final in under a second. How it works

Blocks

Blocks

Dwellir nodesRead every block and write the seven HyperCore record types listed next.

APIs

JSON-RPC

HyperCore data

Live

Info endpointPositions, open orders, vaults, validators

Order Book WebSocketL2, L4, BBO, and trades from Singapore and Tokyo

gRPC streamingRaw node feeds with replay, 14 typed streams

Historical

Hyperliquid IndexCandles, fills, and outcome markets; order book history soon

S3 archiveNative node files since 2025-01-25

Browse the HyperCore data catalog

HyperEVM endpoints

JSON-RPC

Standard JSON-RPCBlocks, accounts, transactions, logs, contract calls

debug and traceNamespaces for indexers and analytics

Dedicated Node ClustersUnlimited RPS on dedicated backends

Get a HyperEVM endpoint

Hyperliquid API 구성

퍼블릭 엔드포인트에는 IP당 한도가 있습니다. REST는 분당 가중치(weight) 1,200, WebSocket은 연결 10개와 구독 1,000개, HyperEVM JSON-RPC는 분당 100건입니다. 요청 유형별 가중치는 퍼블릭 요청 한도 표에 나와 있습니다. 프로덕션 시스템이 제공업체를 추가하는 이유는 기능보다 이 한도 때문인 경우가 많습니다.

Info 엔드포인트: 계정 상태와 참조 데이터

Info 엔드포인트는 Hyperliquid의 조회용 API입니다. 모든 요청은 /info로 보내는 POST이며, JSON 본문의 type 필드로 쿼리를 지정합니다. POST를 쓰지만 읽기 전용입니다.

Info 엔드포인트가 반환하는 데이터

• 계정 상태: 포지션, 마진, 잔고(clearinghouseState, spotClearinghouseState), 미체결 주문(openOrders, frontendOpenOrders)
• 참조 데이터: 무기한 선물과 현물 메타데이터(meta, spotMeta), 실시간 마크 가격과 펀딩이 포함된 메타데이터(metaAndAssetCtxs)
• 시장 스냅샷: 중간 가격(allMids), L2 오더북 스냅샷(l2Book), 캔들(candleSnapshot)
• 과거 이력: 사용자 체결 내역(userFills), 펀딩 이력(fundingHistory)

제공업체마다 프록시하는 범위가 다릅니다. Dwellir의 Info 엔드포인트(https://api-hyperliquid-mainnet-info.n.dwellir.com/info)는 clearinghouseState, openOrders, meta, metaAndAssetCtxs 등 계정과 상태 쿼리를 지원합니다. 여러 지갑을 한 번의 요청으로 조회하는 batchClearinghouseStates 같은 Dwellir 전용 배치 메서드도 제공합니다. 시장 스냅샷과 과거 이력(l2Book, allMids, candleSnapshot, userFills, fundingHistory)은 프록시하지 않습니다. 이 데이터는 퍼블릭 https://api.hyperliquid.xyz/info나 스트림, 또는 과거 데이터 아카이브에서 가져오세요.

요청 구조

JavaScript:

const ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info';
const API_KEY = 'your-api-key-here';

async function getClearinghouseState(userAddress) {
  const response = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY
    },
    body: JSON.stringify({
      type: 'clearinghouseState',
      user: userAddress
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  return await response.json();
}

Python:

import requests

ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info'
API_KEY = 'your-api-key-here'

def get_clearinghouse_state(user_address: str) -> dict:
    """Get a user's perpetual account state"""
    response = requests.post(
        ENDPOINT,
        json={
            'type': 'clearinghouseState',
            'user': user_address
        },
        headers={
            'Content-Type': 'application/json',
            'X-Api-Key': API_KEY
        },
        timeout=10
    )
    response.raise_for_status()
    return response.json()

API 키를 경로에 넣을 수도 있습니다: https://api-hyperliquid-mainnet-info.n.dwellir.com/<your-api-key>/info. meta는 최대 1시간까지 캐시하고, 전략상 더 빠른 업데이트가 필요하지 않다면 계정 상태는 5~10초마다 폴링하세요. 더 빠른 업데이트가 필요하면 폴링 대신 스트리밍을 사용하세요.

Info 엔드포인트를 써야 할 때

• 시작 시 상태 확인: 주문이 중복되지 않도록 포지션, 잔고, 미체결 주문을 불러옵니다
• 참조 데이터: 자산 사양, 수량 소수점 자릿수, 펀딩 설정
• 정합성 확인(reconciliation): 자체 상태와 잔고, 포지션을 주기적으로 대조합니다
• 일회성 조회: 특정 주문이나 계정을 조사할 때

실시간 오더북 추적이나 체결 모니터링에는 쓰지 마세요. 폴링은 업데이트마다 왕복 지연을 더하고, 폴링 사이의 이벤트는 여전히 놓칩니다.

Exchange 엔드포인트: 주문 제출과 취소

모든 쓰기 작업은 Hyperliquid API 서버의 POST /exchange를 거칩니다. 주문, 취소, 정정, 전송, 그리고 scheduleCancel이 여기에 해당합니다. scheduleCancel은 지정한 시각에 모든 주문을 취소하는 데드맨 스위치(dead man's switch)입니다. 액션은 본인 지갑이나 승인된 에이전트 지갑으로 서명합니다. 응답은 단순한 수신 확인이 아니라 확정된 실행 결과입니다.

/exchange를 프록시하는 매니지드 제공업체는 없으며, Dwellir도 마찬가지입니다. 유료 RPC 플랜을 쓴다고 주문이 더 빨리 체결되지는 않습니다. 쓰기 경로의 성능은 봇이 실행되는 위치(검증자와 가장 가까운 곳은 도쿄), Hyperliquid의 우선순위 수수료, 그리고 주소별 요청 예산에 달려 있습니다. 요청 예산은 10,000건의 액션에서 시작해 거래액 1 USDC마다 1건씩 늘어납니다. 서명은 Hyperliquid Python SDK가 처리합니다.

WebSocket: 퍼블릭 한도 내의 실시간 데이터

Hyperliquid의 퍼블릭 WebSocket(wss://api.hyperliquid.xyz/ws)은 체결, l2Book(20단계), bbo, 캔들, 그리고 userFills, orderUpdates 같은 사용자 채널을 스트리밍합니다. 무료이며 많은 봇에 충분합니다. 한도는 IP당 연결 10개, 구독 1,000개, 사용자별 구독 전체에서 고유 사용자 10명입니다. 서버가 예고 없이 연결을 끊을 수도 있으므로, 클라이언트는 재연결하고 재연결 시 전송되는 스냅샷으로 상태를 다시 구성해야 합니다.

이 한도에 걸리거나 20단계를 넘는 호가 깊이 또는 개별 주문이 필요하면 제공업체의 오더북 피드나 gRPC로 옮기세요.

오더북 피드: L2 호가 깊이와 L4 주문

제공업체의 오더북 피드는 퍼블릭 WebSocket과 같은 구독 형식을 쓰면서 호가 깊이를 늘려줍니다. Dwellir의 Order Book WebSocket은 싱가포르와 도쿄에서 wss://api-hyperliquid-mainnet-orderbook.n.dwellir.com/<your-api-key>/ws로 운영됩니다.

L2 오더북: 가격대별로 집계된 호가, 한쪽당 1~100단계:

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

L4 오더북: 사용자 주소와 주문 ID가 포함된 모든 개별 주문:

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

L4는 전체 스냅샷으로 시작한 뒤 변경분(diff)을 보냅니다. 스냅샷 크기가 수 MB에 달하므로 WebSocket 클라이언트의 최대 메시지 크기를 늘려야 합니다. 체결 가격과 상대방 같은 체결 세부 정보는 L4 채널이 아니라 trades 스트림으로 전달됩니다. 주문 데이터 흐름은 L4 오더북 레퍼런스에서 설명합니다.

2026년 10월 28일 도쿄 벤치마크에서 Dwellir Order Book WebSocket은 전용 노드 기준으로 L2 오더북을 중앙값 177ms에 전달했습니다. 퍼블릭 API의 282ms보다 30% 이상 낮은 수치입니다. 공유 엔드포인트는 중앙값 기준 15ms 이내 차이였습니다. 이 애드온은 월 $199에 메시지당 API 크레딧 1개가 추가됩니다.

호가 제시(quoting), 슬리피지 추정, 스프레드 모니터링, 대기열 위치 확인, 대량 주문 추적에 사용하세요. 과거 오더북 재구성에는 쓰지 마세요. 그 용도에는 과거 데이터 아카이브를 사용하세요.

gRPC: 노드 원시 피드와 타입 지정 마켓 스트림

gRPC로는 Hyperliquid 노드가 기록하는 데이터를 받을 수 있습니다. 모든 블록, 모든 체결, 모든 주문 상태 변경, 모든 오더북 변경분이 하나의 장기 연결 위에서 Protocol Buffers 형식으로 전달됩니다. Hyperliquid 자체는 퍼블릭 gRPC 엔드포인트를 운영하지 않습니다. 제공업체가 노드를 운영하며 피드를 제공합니다.

Dwellir gRPC API에는 두 가지 V3 서비스가 있습니다.

체결, 오더북 원시 변경분, 주문 상태, TWAP 상태 스트림은 users와 coins 필터를 지원합니다. 그래서 카피 트레이딩 봇은 체인의 모든 체결을 파싱하지 않고도 지갑 10개의 체결만 스트리밍할 수 있습니다. 재생 가능한 보관 기간은 짧으며 피드와 엔드포인트마다 다릅니다. 커서가 그보다 오래된 경우(서버가 NOT_FOUND를 반환) 과거 데이터 아카이브에서 백필한 뒤 실시간 스트림으로 전환하세요. 인증은 TLS 위에서 x-api-key 메타데이터 헤더로 합니다. 이 애드온은 월 $299에 스트리밍 메시지당 API 크레딧 1개가 추가됩니다.

curl -fsSLo v3.proto https://www.dwellir.com/docs/hyperliquid/grpc/v3.proto

grpcurl -proto v3.proto \
  -H "x-api-key: ${DWELLIR_API_KEY}" \
  "${HYPERLIQUID_GRPC_ENDPOINT}" \
  hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/ListFeeds

체결 및 청산 모니터링, 카피 트레이딩, 주문 상태 추적, 상태 재구성, 그리고 서버 측에서 필터링하고 싶은 모든 피드에 gRPC를 사용하세요. 시작 시 상태 확인(Info 엔드포인트 사용)이나 재생 기간보다 오래된 이력(아카이브 사용)에는 쓰지 마세요. 첫 스트림은 StreamBlocks와 스트리밍 문제 해결 가이드로 시작하세요.

HyperEVM RPC: 컨트랙트, 토큰, 트레이스

HyperEVM RPC는 표준 이더리움 JSON-RPC입니다. Ethers.js, viem, Web3.py, Hardhat, Foundry를 수정 없이 사용할 수 있습니다.

JavaScript (Ethers.js):

const { ethers } = require('ethers');

const provider = new ethers.JsonRpcProvider(
  'https://api-hyperliquid-mainnet-evm.n.dwellir.com/YOUR_API_KEY'
);

const balance = await provider.getBalance('0x...');
console.log(`Balance: ${ethers.formatEther(balance)} HYPE`);

const contract = new ethers.Contract(contractAddress, abi, provider);
const result = await contract.someReadMethod();

Python (Web3.py):

from web3 import Web3

w3 = Web3(Web3.HTTPProvider(
    'https://api-hyperliquid-mainnet-evm.n.dwellir.com/YOUR_API_KEY'
))

print(f"Chain ID: {w3.eth.chain_id}")  # 999
print(f"Latest block: {w3.eth.block_number}")

balance = w3.eth.get_balance('0x...')
print(f"Balance: {w3.from_wei(balance, 'ether')} HYPE")

HyperEVM의 컨트랙트는 읽기 프리컴파일로 HyperCore 상태를 읽고, 0x3333333333333333333333333333333333333333 주소의 CoreWriter 컨트랙트로 HyperCore 액션을 보냅니다. 두 가지 모두 아키텍처 페이지에서 다룹니다.

컨트랙트 배포, ERC-20 및 DeFi 상호작용, eth_getLogs 인덱싱, 트랜잭션 트레이싱에 HyperEVM RPC를 사용하세요. 오더북, 체결, 포지션에는 쓰지 마세요. 이는 HyperCore 데이터입니다.

애플리케이션별 스택

트레이딩 봇

1. 시작: Info 엔드포인트로 잔고, 포지션, 미체결 주문을 불러옵니다.
2. 실시간 데이터: WebSocket으로 거래할 마켓의 L2 오더북과 체결을 구독합니다.
3. 주문: 서명된 액션을 /exchange로 보내고, scheduleCancel을 데드맨 스위치로 설정합니다.
4. 정합성 확인: 몇 분마다 Info 엔드포인트를 호출해 자체 상태가 체인과 일치하는지 확인합니다.

마켓메이커

+-------------------------------------------+
|           Quote placement logic           |
+-------------------------------------------+
         |                         |
         v                         v
+------------------+     +-------------------+
| Order book feed  |     |   Info endpoint   |
|   (L2 or L4)     |     |    (positions)    |
+------------------+     +-------------------+
         |                         |
         +------------+------------+
                      |
                      v
            +-------------------+
            |    Risk engine    |
            +-------------------+
                      |
                      v
            +-------------------+
            |  /exchange        |
            |  (signed orders)  |
            +-------------------+

오더북 피드가 호가를 결정하고, Info 엔드포인트가 포지션과 마진 상태를 정확하게 유지하며, 리스크 엔진이 이 둘과 /exchange 사이에 위치합니다. 온체인에서 헤징하거나 담보를 관리할 때만 HyperEVM RPC를 추가하세요.

분석 플랫폼

1. 백필: 과거 데이터 아카이브에서 블록 단위로 체결, 주문 상태, 오더북 변경분을 가져옵니다.
2. 실시간 수집: gRPC 원시 피드로 수집하고, 장애가 나면 마지막으로 저장한 블록 번호부터 재개합니다.
3. 참조 데이터: Info 엔드포인트에서 가져옵니다.
4. 선택 사항: EVM 쪽 프로토콜 활동은 HyperEVM eth_getLogs로 수집합니다.

카피 트레이딩

Hyperliquid 카피 트레이딩 봇 튜토리얼은 시작할 때 Info 엔드포인트로 리더의 포지션을 불러오고, 필터링된 gRPC 체결 스트림으로 새 거래를 따라가며, 몇 분마다 다시 Info 엔드포인트로 정합성을 확인합니다.

제공업체를 추가할 시점과 선택 기준

퍼블릭 엔드포인트로 시작하세요. 다음 중 하나에 해당하면 제공업체를 추가하세요.

• HyperEVM 호출이 분당 100건을 넘거나, HyperEVM에서 WebSocket, 아카이브, 트레이스가 필요할 때.
• REST 가중치가 부족할 때: IP당 분당 1,200은 metaAndAssetCtxs 호출 약 60회, 또는 clearinghouseState 호출 600회에 해당합니다.
• 노드 원시 데이터가 필요할 때: 모든 체결, 주문 상태, 오더북 변경분. 이 데이터는 노드나 제공업체의 gRPC 피드에만 있습니다.
• 20단계를 넘는 호가 깊이나 개별 주문(L4)이 필요할 때.

제공업체 간 차이는 HyperEVM보다 HyperCore 지원 범위에서 크게 납니다. Hyperliquid RPC 제공업체 순위에서 5개 제공업체의 Info 지원 범위, gRPC, 오더북 깊이, 호출당 가격을 비교합니다. 완전한 통제가 필요하다면 도쿄에서 자체 비검증 노드를 운영하고 Dwellir와 피어링하세요. 사용량 과금 없이 운영을 맡기고 싶다면 Dedicated Node Cluster(전용 노드 클러스터)가 다음 단계입니다.

Dwellir의 Hyperliquid 스택

전체 가격은 Hyperliquid 가격 페이지에서 확인하세요.

시작하기

1. HyperEVM RPC와 Info 엔드포인트를 쓰려면 무료 Dwellir 계정을 만드세요.
2. 스트림이 필요하면 가격 페이지에서 gRPC API나 Order Book WebSocket을 추가하세요.
3. 사용량 제한 없는 프로덕션 용량이 필요하면 Dedicated Node Cluster에 대해 Dwellir 팀에 문의하세요.

코드 예제

• Hyperliquid gRPC 예제 (Go, Python, Node.js)
• Order Book WebSocket 예제
• Python 카피 트레이딩 봇
• 실시간 청산 트래커

관련 글

• Hyperliquid 인프라 작동 방식
• 2026 최고의 Hyperliquid RPC 제공업체 순위
• Hyperliquid 노드를 확보하는 방법
• 퍼블릭 Hyperliquid API의 대안
• Hyperliquid 지연 시간 해설

자주 묻는 질문

트레이딩 봇은 어떤 Hyperliquid API를 써야 하나요?

대부분의 트레이딩 봇은 세 가지를 함께 씁니다. 시작할 때 포지션, 잔고, 미체결 주문을 불러오는 Info 엔드포인트, 실시간 오더북과 체결 데이터를 받는 WebSocket 또는 gRPC 스트림, 그리고 서명된 주문을 넣고 취소하는 api.hyperliquid.xyz/exchange의 Exchange 엔드포인트입니다. HyperEVM JSON-RPC는 봇이 스마트 컨트랙트도 사용할 때만 필요합니다.

Hyperliquid Info 엔드포인트와 Exchange 엔드포인트는 무엇이 다른가요?

Info 엔드포인트(POST /info)는 읽기 전용이며 시장 데이터, 메타데이터, 계정 상태를 반환합니다. Exchange 엔드포인트(POST /exchange)는 주문, 취소, 전송 같은 서명된 액션을 받습니다. 매니지드 제공업체는 Info 엔드포인트의 일부를 프록시하지만 Exchange 엔드포인트를 프록시하는 곳은 없습니다. 따라서 주문은 항상 Hyperliquid API 서버나 자체 노드로 전송됩니다.

Hyperliquid에서 HyperCore 데이터를 스트리밍하려면 어떻게 하나요?

체결, l2Book, 사용자 이벤트는 퍼블릭 WebSocket(wss://api.hyperliquid.xyz/ws)으로 받을 수 있습니다. 한도는 IP당 연결 10개, 구독 1,000개입니다. 모든 체결, 주문 상태, 오더북 변경분 같은 노드 원시 피드가 필요하면 제공업체의 gRPC 스트림을 사용하세요. Dwellir gRPC API는 커서 기반 재생(replay)을 지원하는 원시 피드와 14개의 타입 지정 마켓 스트림을 월 $299에 사용량 요금을 더해 제공합니다.

HyperEVM 체인 ID는 무엇인가요?

HyperEVM 메인넷의 체인 ID는 999, 테스트넷은 998입니다. 가스 토큰은 소수점 18자리의 HYPE입니다. 공식 RPC(rpc.hyperliquid.xyz/evm)는 HTTP로 분당 100건까지 허용하며 WebSocket은 지원하지 않습니다.