StreamOrderStatuses - Real-time Order Status Streaming

Stream order status events starting from a position, providing real-time access to the lifecycle of every order on Hyperliquid: opens, fills, cancellations, and rejections.

When to Use This MethodCopy Anchor Link

StreamOrderStatuses is essential for:

• Order Lifecycle Tracking - Follow an order from open through fill, cancel, or rejection
• Rejection Analysis - Identify why orders are rejected using the status field
• Resting-Order Context - Read the full order object behind each status change
• Compliance and Auditing - Record every status transition with block alignment

rpc StreamOrderStatuses(StreamRequest) returns (stream Record) {}

filter: {
  fields: {
    field: "users"
    op: FILTER_OP_IN
    values: "0x1111111111111111111111111111111111111111"
  }
}

grpcurl \
  -import-path content/docs/hyperliquid/grpc \
  -proto v3.proto \
  -H "x-api-key: ${DWELLIR_API_KEY}" \
  -d '{"position":{"block_number":"1058646974"},"filter":{"fields":[{"field":"coins","op":"FILTER_OP_IN","values":["BTC"]}]}}' \
  "${HYPERLIQUID_GRPC_ENDPOINT}" \
  hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/StreamOrderStatuses

Response StreamCopy Anchor Link

Decode the data field to access:

• Block reference (local_time, block_time, block_number)
• An events array of status records
• A full order object behind each status change

Full Order Status SpecCopy Anchor Link

StreamOrderStatuses emits a JSON payload matching Hyperliquid's node_order_statuses_by_block format. The envelope is the same block-envelope shape as fills, but events holds status-record objects rather than [address, fill] tuples.

Top-level keys (always present):

{
  "local_time": "2026-04-20T00:00:00.040479928",   // ISO-8601 timestamp when node processed the block (nanosecond precision)
  "block_time": "2026-04-19T23:59:59.576040791",    // ISO-8601 timestamp from block consensus
  "block_number": 12345,                            // Block height containing these events
  "events": [                                       // Array of status-record objects
    {
      "time": "2026-04-19T23:59:59.576040791",      // Event timestamp (string, not integer ms)
      "user": "0x1234567890abcdef1234567890abcdef12345678",  // User address
      "hash": "0x00...",                            // Transaction hash (nullable)
      "builder": { "b": "0x00...", "f": 50 },       // Builder address and fee (nullable)
      "status": "open",                             // Status value (see table below)
      "order": { }                                  // Full order object (see Order Object)
    }
  ]
}

Status event fields (events[i]):

Status ValuesCopy Anchor Link

Observed status values (the list is not exhaustive):

Order ObjectCopy Anchor Link

The order field is the shared resting-order schema, the same object returned by GetOrderBookSnapshot.

Guarantees and alignment:

• events contains all status records from the block, across all coins and users.
• Messages arrive in strictly increasing block_number, one per source block (including blocks with an empty events array).
• block_number is sequential and distinct from the potentially skipping abci_block.round consensus value in StreamBlocks; block_time aligns with abci_block.time.

Developer tips:

• Branch on status to track lifecycle transitions and isolate rejections.
• Handle hash and builder defensively; both can be null.
• Treat time as a formatted string, distinct from the integer-millisecond time on fill events.

Order IdentifiersCopy Anchor Link

oid is not reliably unique across coins. Consumers that index or join per-order state must key on the (coin, oid) tuple, never on oid alone.

Outcome markets (HIP-4) demonstrably reuse oids across the two sides of a single market (for example #30 and #31) within one block. Keying on (coin, oid) is safe whether or not oids turn out to be globally unique elsewhere.

Common Use CasesCopy Anchor Link

1. Rejection MonitorCopy Anchor Link

REJECTIONS = {
    'badAloPxRejected', 'insufficientSpotBalanceRejected', 'iocCancelRejected',
    'minTradeNtlRejected', 'perpMarginRejected', 'reduceOnlyRejected',
}

def count_rejections(block):
    counts = {}
    for event in block.get('events', []):
        status = event['status']
        if status in REJECTIONS:
            counts[status] = counts.get(status, 0) + 1
    return counts

2. Streaming Statuses in PythonCopy Anchor Link

Progress FramesCopy Anchor Link

Error Handling and ReconnectionCopy Anchor Link

Best PracticesCopy Anchor Link

1. Connection Management: Implement robust reconnection logic with exponential backoff
2. Resumable State: Follow the version-specific recovery guidance above and persist the cursor required by your selected API version
3. Stable Keys: Index per-order state on (coin, oid) to stay correct across coins
4. Defensive Parsing: Handle nullable hash and builder and the non-exhaustive status set
5. Resource Cleanup: Properly close streams and connections on shutdown

Current LimitationsCopy Anchor Link

• Replay History: Available replay history varies by feed and endpoint. A cursor outside retained history returns NOT_FOUND.
• Backpressure: High-volume periods may require careful handling to avoid overwhelming downstream systems

ResourcesCopy Anchor Link

• GitHub: gRPC Code Examples - Complete working examples
• GetOrderStatuses - Point-in-time order status retrieval
• StreamRawBookDiffs - The sibling block-envelope stream for resting-book changes
• Historical Data - Historical node_order_statuses_by_block downloads

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