GetOrderBookSnapshot - Get Order Book Data

Retrieve a full order book snapshot at a specific point in time from the Hyperliquid L1 Gateway. Returns every individual open order across all markets with complete metadata including order IDs, timestamps, trigger conditions, and child orders.

When to Use This MethodCopy Anchor Link

GetOrderBookSnapshot is essential for:

• Market Microstructure Analysis - Access every individual order with full metadata
• Queue Position Tracking - See exact order placement timestamps and sizes
• Whale Watching - Monitor large orders with their original sizes and trigger conditions
• Trading Strategies - Analyze order distribution, TP/SL clustering, and trigger order density
• Risk Management - Assess market impact with individual order granularity

rpc GetOrderbookSnapshot(GetRequest) returns (Record) {}

position: {
  timestamp: 1785736814057
}

grpcurl \
  -import-path content/docs/hyperliquid/grpc \
  -proto v3.proto \
  -H "x-api-key: ${DWELLIR_API_KEY}" \
  -d '{"position":{"timestamp":"1785736814057"}}' \
  "${HYPERLIQUID_GRPC_ENDPOINT}" \
  hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/GetOrderbookSnapshot

Response ExamplesCopy Anchor Link

Simple Limit Order (Bid)Copy Anchor Link

{
  "coin": "0G",
  "side": "B",
  "limitPx": "0.59341",
  "sz": "52.0",
  "oid": 333003526755,
  "timestamp": 1772276628506,
  "triggerCondition": "N/A",
  "isTrigger": false,
  "triggerPx": "0.0",
  "children": [],
  "isPositionTpsl": false,
  "reduceOnly": false,
  "orderType": "Limit",
  "origSz": "52.0",
  "tif": "Alo",
  "cloid": "0x00000000000000000000000000000318"
}

Order with TP/SL ChildrenCopy Anchor Link

A parent limit order can have up to 2 child orders (stop-loss and/or take-profit) attached:

{
  "coin": "AAVE",
  "side": "B",
  "limitPx": "104.6",
  "sz": "1.94",
  "oid": 332954766819,
  "timestamp": 1772272640873,
  "triggerCondition": "N/A",
  "isTrigger": false,
  "triggerPx": "0.0",
  "children": [
    {
      "coin": "AAVE",
      "side": "A",
      "limitPx": "94.3",
      "sz": "1.94",
      "oid": 332954766820,
      "timestamp": 1772272640873,
      "triggerCondition": "Price below 102.5",
      "isTrigger": true,
      "triggerPx": "102.5",
      "children": [],
      "isPositionTpsl": false,
      "reduceOnly": true,
      "orderType": "Stop Market",
      "origSz": "1.94",
      "tif": null,
      "cloid": null
    },
    {
      "coin": "AAVE",
      "side": "A",
      "limitPx": "102.0",
      "sz": "1.94",
      "oid": 332954766821,
      "timestamp": 1772272640873,
      "triggerCondition": "Price above 110.87",
      "isTrigger": true,
      "triggerPx": "110.87",
      "children": [],
      "isPositionTpsl": false,
      "reduceOnly": true,
      "orderType": "Take Profit Market",
      "origSz": "1.94",
      "tif": null,
      "cloid": null
    }
  ],
  "isPositionTpsl": false,
  "reduceOnly": false,
  "orderType": "Limit",
  "origSz": "1.94",
  "tif": "Gtc",
  "cloid": null
}

Triggered OrderCopy Anchor Link

An order where the trigger condition has already been met and the order is now active:

{
  "coin": "ARB",
  "side": "A",
  "limitPx": "0.1099",
  "sz": "601.7",
  "oid": 331886608601,
  "timestamp": 1772189655929,
  "triggerCondition": "Triggered",
  "isTrigger": false,
  "triggerPx": "0.0",
  "children": [],
  "isPositionTpsl": false,
  "reduceOnly": true,
  "orderType": "Take Profit Limit",
  "origSz": "601.7",
  "tif": "Gtc",
  "cloid": null
}

Important NotesCopy Anchor Link

• Individual orders, not aggregated levels. Each entry is an individual order with full metadata (order ID, timestamp, trigger info, children, etc.).
• Bids are sorted by price descending (highest price first). Asks are sorted by price ascending (lowest price first).
• Children are never nested. Child orders always have an empty children array.
• Trigger orders (isTrigger: true) have tif: null and meaningful triggerCondition / triggerPx values.
• Once triggered, the order becomes isTrigger: false, triggerCondition: "Triggered", triggerPx: "0.0", and receives a tif value (typically "Gtc").

Best PracticesCopy Anchor Link

1. Message Size Configuration: Configure the client inbound message limit per client and workload, and account separately for endpoint delivery limits; oversized responses return RESOURCE_EXHAUSTED
2. Timeout: Use a generous timeout (60-120 seconds) for the RPC call due to the large response
3. Data Validation: Always validate JSON structure before processing
4. Error Recovery: Implement retry logic with exponential backoff
5. Resource Management: Close gRPC connections properly to avoid resource leaks
6. Streaming Alternative: For continuous updates, consider using StreamOrderbookSnapshots instead

Current LimitationsCopy Anchor Link

• Replay History: Available snapshot history varies by endpoint; a timestamp outside retained history returns NOT_FOUND
• Rate Limits: Be mindful of request frequency to avoid overwhelming the service
• Availability: Snapshot availability and maximum response size vary by endpoint; oversized responses return RESOURCE_EXHAUSTED

ResourcesCopy Anchor Link

• GitHub: gRPC Code Examples - Complete working examples
• Copy Trading Bot - Production-ready trading bot example
• Pricing - Dedicated node cluster pricing details

Need help? Contact our support team or check the Hyperliquid gRPC documentation.