본문으로 건너뛰기

데이터셋 업데이트

업데이트됨:
2026년 7월 18일

개요​

‘북 업데이트 스트림’( book_diffs라고도 함)에는 Hyperliquid 레벨 2 호가장부 업데이트 정보가 포함되어 있습니다. 이 데이터셋은 모든 주문 체결, 수정 및 취소를 추적하여 호가장부의 증분 변경 사항을 보여줍니다.

하천 유형: 책_업데이트
API 이용 가능 여부: gRPC API + JSON-RPC/WebSocket API
권수: 매우 높음 - 주문장 변경 시마다 이벤트가 발생합니다

데이터 구조​

각 블록에는 주문장 업데이트 이벤트 배열이 포함되어 있습니다. 이러한 이벤트는 주문장의 특정 가격 수준에 발생한 변경 사항(추가 또는 삭제)을 나타냅니다:

{
  "local_time": "2025-12-04T17:00:00.071039761",
  "block_time": "2025-12-04T16:59:59.912486449", 
  "block_number": 817824076,
  "events": [
    {
      "user": "0x1c1c270b573d55b68b3d14722b5d5d401511bed0",
      "oid": 258166296856,
      "coin": "ETH",
      "side": "B",
      "px": "3167.4",
      "raw_book_diff": {
        "new": {
          "sz": "1.5785"
        }
      }
    }
  ]
}

필드 정의​

분야유형설명
사용자문자열주문을 접수·수정·취소한 사용자의 주소
oid정수주문 ID - 주문을 식별하는 고유 식별자
동전문자열거래 쌍 식별자 (예: "ETH", "BTC", "xyz:NVDA", "@198")
측면문자열주문 유형: “B”(매수 호가) 또는 “A”(매도 호가)
px문자열이 주문의 가격 수준
raw_book_diff문자열 또는 객체책 업데이트 유형 (아래의 ‘책 차이 유형’ 참조)

책의 차이 유형​

그 raw_book_diff 이 필드는 어떤 유형의 변경이 발생했는지를 나타냅니다:

유형값설명
뉴 오더{"new": {"sz": "1.5785"}}이 가격대에서 새로운 주문이 접수되었거나 기존 주문의 수량이 업데이트되었습니다. `sz` 필드는 이 가격대에서 해당 주문의 새로운 총 수량을 나타냅니다. `insertBefore`가 지정되지 않은 경우, 주문은 해당 가격대의 대기열 맨 뒤쪽에 추가됩니다.
우선순위 삽입{"new": {"sz": "0.116", "insertBefore": 498404769094}}`insertBefore`와 `oid`가 일치하는 대기 중인 주문 바로 앞에 대기열에 즉시 삽입되는 새로운 주문으로, 대기열의 맨 뒤쪽에 추가되는 것이 아닙니다. ALO 우선순위 수수료 변경으로 인해 대기열 내 위치가 변경될 때 발생합니다.
주문 취소"제거"주문이 취소되었거나 완전히 체결되어 주문 장부에서 삭제되었습니다.

중요 사항​


  • 주문이 수정되면(사이즈 변경 시), 다음과 같이 표시됩니다. "제거" 행사가 끝난 뒤 {"new": {...}} 크기가 업데이트된 이벤트
  • 그 sz ~에 있는 필드 {"new": {...}} ~를 나타내며 전체 크기 이 특정 주문에 대한 이 가격대의 주문이며, 델타가 아닙니다
  • 서로 다른 사용자가 동일한 가격 수준에서 여러 건의 주문을 등록할 수 있습니다.
  • 선택 사항인 insertBefore 내부의 필드 {"new": {...}} ~을 담고 있다 oid 기존 순서 중, 새로운 순서가 그 앞에 삽입되는 순서입니다. 이는 ALO 우선 처리 수수료 대기열 순위를 구매합니다. 가격대별로 대기열 순서를 추적하는 경우, 해당 가격대보다 앞쪽에 주문을 삽입합니다. oid; 해당 항목이 없으면 주문을 목록의 맨 뒤에 추가한다

업데이트 예시​

새 주문 등록
{
  "user": "0x1c1c270b573d55b68b3d14722b5d5d401511bed0",
  "oid": 258166296856,
  "coin": "ETH",
  "side": "B",
  "px": "3167.4",
  "raw_book_diff": {
    "new": {
      "sz": "1.5785"
    }
  }
}
우선순위 대기열 삽입 (ALO 우선순위 수수료)

그 insertBefore 이 필드는 이 주문이 다음 조건을 가진 대기 주문 바로 앞에 가격 수준 대기열에 즉시 진입함을 나타냅니다. oid 498404769094, 꼬리에 연결하는 대신:

{
  "user": "0xf0480a7892bc260658e82359f3c9374bc0a75444",
  "oid": 498404769141,
  "coin": "BTC",
  "side": "B",
  "px": "64470.0",
  "raw_book_diff": {
    "new": {
      "sz": "0.116",
      "insertBefore": 498404769094
    }
  }
}
주문 철회 (취소 또는 체결)
{
  "user": "0xe9acfdc9322f6f924f007016c082e6891a3c653c",
  "oid": 258166160909,
  "coin": "BIO",
  "side": "A",
  "px": "0.053056",
  "raw_book_diff": "remove"
}
주문 수량 변경

주문 규모가 수정되면, 서버는 두 개의 이벤트 시퀀스나 단일 현장 업데이트 이벤트 중 하나를 발생시킬 수 있습니다.

두 단계 순서 (삭제 + 추가):


  1. 기존 주문을 삭제하세요:
{
  "user": "0x1234567890abcdef1234567890abcdef12345678",
  "oid": 258166123456,
  "coin": "BTC",
  "side": "B", 
  "px": "95000.0",
  "raw_book_diff": "remove"
}

  1. 수정된 주문을 추가하세요:
{
  "user": "0x1234567890abcdef1234567890abcdef12345678",
  "oid": 258166123456,
  "coin": "BTC", 
  "side": "B",
  "px": "95000.0",
  "raw_book_diff": {
    "new": {
      "sz": "2.5"
    }
  }
}

단일 인플레이스 업데이트 이벤트 (서버가 원래 크기와 새 크기를 포함하는 하나의 이벤트를 전송함):

{
  "user": "0xab3f8d09ae381d7f09bcbd8189ccc8aa99e8577d",
  "oid": 407302564659,
  "coin": "#1",
  "side": "B",
  "px": "0.4",
  "raw_book_diff": {
    "update": {
      "origSz": "40.0",
      "newSz": "0.0"
    }
  }
}
성과 시장 보고서 업데이트 (HIP-4)

성과 자산(HIP-4)은 다음과 같이 표시됩니다. #N- 접두사가 붙은 코인이 포함된 책 업데이트 이벤트. 해당 raw_book_diff 형식은 다른 동전과 동일합니다.

{
  "user": "0xab3f8d09ae381d7f09bcbd8189ccc8aa99e8577d",
  "oid": 407302564659,
  "coin": "#1",
  "side": "B",
  "px": "0.4",
  "raw_book_diff": {
    "update": {
      "origSz": "40.0",
      "newSz": "0.0"
    }
  }
}
주문장부 작성

이 스트림에서 완전한 주문 장부를 구축하려면:

1. 빈 책 초기화​

const orderBook = {
  bids: new Map(), // price -> Map(oid -> size)
  asks: new Map()  // price -> Map(oid -> size)
};

2. 도서 업데이트 처리​

function processBookUpdate(event) {
  const { side, px, oid, raw_book_diff } = event;
  const book = side === 'B' ? orderBook.bids : orderBook.asks;
  
  if (!book.has(px)) {
    book.set(px, new Map());
  }
  
  const priceLevel = book.get(px);
  
  if (raw_book_diff === 'remove') {
    // Remove order from this price level
    priceLevel.delete(oid);
    
    // Remove price level if empty
    if (priceLevel.size === 0) {
      book.delete(px);
    }
  } else if (raw_book_diff.new) {
    // Add/update order at this price level
    priceLevel.set(oid, raw_book_diff.new.sz);
  }
}

3. 물가 수준 합계 계산​

function getPriceLevelSize(priceLevel) {
  let total = 0;
  for (const size of priceLevel.values()) {
    total += parseFloat(size);
  }
  return total;
}

API 사용법​

gRPC
// Subscribe to book updates for specific coins and side
const request = {
  subscribe: {
    stream_type: 'BOOK_UPDATES',
    filters: {
      coin: { values: ['BTC', 'ETH'] },
      side: { values: ['B'] }
    }
  }
};
JSON-RPC
# Get latest book update blocks
curl -X POST https://your-endpoint.hype-mainnet.quiknode.pro/your-token/hypercore \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "hl_getLatestBlocks",
    "params": {
      "stream": "book",
      "count": 10
    },
    "id": 1
  }'
WebSocket
// Subscribe to book updates
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "hl_subscribe",
  "params": {
    "streamType": "book_updates"
  },
  "id": 1
}));

중요 사항​


  • 높은 빈도: 책 관련 업데이트가 가장 빈번하게 발생하는 이벤트입니다. 특정 시장을 대상으로 할 때는 코인 필터링 기능을 활용하세요.
  • 주문 집계: 서로 다른 사용자가 동일한 가격 수준에서 여러 건의 주문을 등록할 수 있습니다.
  • 상태 재구성: 이러한 증분 업데이트를 처리하면 전체 주문 내역을 재구성할 수 있습니다.
  • 크기 의미론: sz 증분 변경 사항이 아닌 총 주문 규모를 나타냅니다.
  • 수정 패턴: 주문 수정 내역은 동일한 oid

  • 주문 - 이러한 장부 변경을 유발하는 주문 라이프사이클 이벤트를 확인하세요
  • 거래 - 주문 장부에서 유동성을 제거하는 체결 내역 보기
  • 이벤트 - 주문장 상태에 영향을 미칠 수 있는 시스템 이벤트를 모니터링합니다
최종 업데이트 ~에서