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 Method

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"
  }
}

Response Stream

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 Spec

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 Values

Observed status values (the list is not exhaustive):

Order Object

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 Identifiers

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 Cases

1. Rejection Monitor

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 Python

Error Handling and Reconnection

Best Practices

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 Limitations

• 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

Resources

• 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.