GetOrderStatuses - Get Order Status Data

Retrieve order status events at a specific position from the Hyperliquid L1 Gateway.

When to Use This Method

GetOrderStatuses is essential for:

• Order Reconciliation - Verify order lifecycle events at a specific block
• Rejection Analysis - Retrieve and classify rejections at a point in time
• Auditing - Confirm status transitions at specific blocks
• Debugging - Investigate specific order outcomes during development

Method Signature

rpc GetOrderStatuses(Position) returns (BlockOrderStatuses) {}

Common Use Cases

1. Inspect a Single Block

def get_block_statuses(client, metadata, block_height):
    request = hyperliquid_pb2.Position(block_height=block_height)
    response = client.GetOrderStatuses(request, metadata=metadata)
    block = json.loads(response.data)

    for event in block.get('events', []):
        print(event['status'], event['order']['coin'], event['order']['oid'])

2. Find Rejections in a Block Range

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

def find_rejections(client, metadata, start_block, end_block):
    rejected = []
    for block_height in range(start_block, end_block + 1):
        request = hyperliquid_pb2.Position(block_height=block_height)
        response = client.GetOrderStatuses(request, metadata=metadata)
        block = json.loads(response.data)
        for event in block.get('events', []):
            if event['status'] in REJECTIONS:
                rejected.append(event)
    return rejected

Best Practices

1. Position Selection: Use block height for precise queries; timestamps may resolve to different blocks across requests
2. Stable Keys: Index per-order state on (coin, oid), never on oid alone
3. Defensive Parsing: Handle nullable hash and builder and the non-exhaustive status set
4. Error Recovery: Implement retry logic with exponential backoff
5. Resource Management: Close gRPC connections properly to avoid resource leaks

Current Limitations

• Backfill Window: Positions outside the node's retained on-disk feed are not available; an unconfigured feed directory returns NotFound
• Rate Limits: Be mindful of request frequency to avoid overwhelming the service

Resources

• GitHub: gRPC Code Examples - Complete working examples
• StreamOrderStatuses Documentation - Full order status specification and streaming examples
• Archival Data - Historical node_order_statuses_by_block downloads

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