GetTwapStatuses - Get TWAP Status Data

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

When to Use This Method

GetTwapStatuses is essential for:

• TWAP Reconciliation - Verify TWAP lifecycle events at a specific block
• Execution Analysis - Inspect executed size and notional for a TWAP state update
• Auditing - Confirm TWAP status transitions at specific blocks
• Debugging - Investigate specific TWAP order outcomes during development

Use the unary method when you already know the block or timestamp you want to inspect. For continuous ingestion, use StreamTwapStatuses and persist your last processed block_number.

Method Signature

rpc GetTwapStatuses(Position) returns (BlockTwapStatuses) {}

Response Shape

GetTwapStatuses returns one JSON-encoded block envelope in BlockTwapStatuses.data:

message BlockTwapStatuses {
  // JSON-encoded block envelope from "node_twap_statuses_by_block".
  bytes data = 1;
}

The decoded JSON has the same shape as StreamTwapStatuses:

{
  "local_time": "2026-07-03T06:00:14.508835456",
  "block_time": "2026-07-03T06:00:14.057132297",
  "block_number": 1058646974,
  "events": [
    {
      "time": "2026-07-03T06:00:14.057132297",
      "twap_id": 1999381,
      "state": {
        "coin": "kPEPE",
        "user": "0x2ee1f7d5650bb9bc08e101dc5ab2300b4f5c1be9",
        "side": "B",
        "sz": "555555.0",
        "executedSz": "555555.0",
        "executedNtl": "1371.51378",
        "minutes": 5,
        "reduceOnly": false,
        "randomize": false,
        "timestamp": 1783058112775
      },
      "status": "finished"
    }
  ]
}

Most queried blocks can return an empty events array. That means no TWAP lifecycle update was recorded in that block; the block envelope itself is still valid.

Common Use Cases

1. Inspect a Single Block

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

    for event in block.get('events', []):
        state = event['state']
        print(event['status'], event['twap_id'], state['coin'], state['executedSz'])

2. Calculate Execution Progress

from decimal import Decimal

def twap_progress(event):
    state = event['state']
    target = Decimal(state['sz'])
    executed = Decimal(state['executedSz'])
    return executed / target if target else Decimal('0')

3. Replay TWAP Lifecycle Updates

def replay_twap_statuses(client, metadata, start_block, end_block):
    by_twap_id = {}

    for block_height in range(start_block, end_block + 1):
        request = hyperliquid_pb2.Position(block_height=block_height)
        response = client.GetTwapStatuses(request, metadata=metadata)
        block = json.loads(response.data)

        for event in block.get('events', []):
            by_twap_id[event['twap_id']] = event

    return by_twap_id

4. Find Terminal TWAP Events

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

    return [
        event for event in block.get('events', [])
        if event['status'] in ('finished', 'terminated') or isinstance(event['status'], dict)
    ]

Positioning Semantics

Position accepts either block_height or timestamp_ms. Use one field at a time:

• block_height fetches the block-envelope record at that exact block.
• timestamp_ms resolves to the feed position at or after the timestamp.
• Empty Position targets the latest available TWAP status envelope.

For deterministic reconciliation, prefer block_height. Timestamp-based lookups are useful when your upstream system stores wall-clock times but not Hyperliquid block numbers.

Best Practices

1. Position Selection: Use block height for precise queries; timestamps may resolve to different blocks across requests
2. Stable Keys: Index per-TWAP state on twap_id
3. Defensive Parsing: Handle an empty events array, unknown future string statuses, and object status payloads
4. Numeric Precision: Parse size and notional fields as decimals, not floats
5. Action Correlation: Use GetBlock or StreamBlocks when you need the original signed twapOrder or twapCancel action
6. Resource Management: Close gRPC connections properly to avoid resource leaks

Current Limitations

• Data Retention: Historical availability follows the gateway's retained on-disk feed; pruned positions return NotFound
• Schema Coverage: The upstream lifecycle set can grow; treat documented statuses as examples, not an exhaustive list
• Rate Limits: Be mindful of request frequency to avoid overwhelming the service

Resources

• GitHub: gRPC Code Examples - Complete working examples
• StreamTwapStatuses Documentation - Full TWAP status specification and streaming examples
• twapOrder Action Type - TWAP order submission payloads in StreamBlocks
• twapCancel Action Type - TWAP cancellation payloads in StreamBlocks

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