get_twap_statuses (gRPC) | Hyperliquid API Docs

Retrieve TWAP order lifecycle events at a specific position from Hyperliquid L1 Gateway via gRPC. Get TWAP status data for reconciliation and auditing.

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

Full Code Examples

Clone our gRPC Code Examples Repository for complete, runnable implementations in Go, Python, and Node.js.

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

protobuf

rpc GetTwapStatuses(GetRequest) returns (Record) {}

V3 accepts an inclusive position.block_number or Unix-millisecond position.timestamp; explicit zero is invalid. A positioned call returns the selected envelope. An empty GetRequest waits for the next TWAP-status record written after the call begins, so set a deadline.

protobuf

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

TWAP statuses accept users and coins filters. User matching is case-insensitive and coin matching is case-sensitive; values within a field use OR semantics and separate fields use AND semantics. A zero-match unary request returns the selected Record with data containing events: []. A pruned position returns NOT_FOUND; malformed filters return INVALID_ARGUMENT.

Response Shape

Both versions return one JSON-encoded block envelope in a data field.

V3 returns a Record; decode Record.data. Its optional block_number and timestamp fields are typed transport cursors.

The decoded JSON has the same shape as StreamTwapStatuses:

JSON

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

For V3, select each record with GetRequest.position.block_number, decode Record.data, and process its events array. Index lifecycle state by twap_id; calculate progress from executedSz / sz, and treat both unknown string statuses and object status payloads defensively.

TWAP Status Field Reference

GetTwapStatuses returns the same format as StreamTwapStatuses. See the StreamTwapStatuses documentation for the complete field reference, including the TWAP state object and status values.

Best Practices

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

Current Limitations

Replay History: Available replay history varies by feed and endpoint. A cursor outside retained history returns NOT_FOUND
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.

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

Full Code Examples

Clone our gRPC Code Examples Repository for complete, runnable implementations in Go, Python, and Node.js.

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

protobuf

rpc GetTwapStatuses(GetRequest) returns (Record) {}

protobuf

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

Response Shape

Both versions return one JSON-encoded block envelope in a data field.

V3 returns a Record; decode Record.data. Its optional block_number and timestamp fields are typed transport cursors.

The decoded JSON has the same shape as StreamTwapStatuses:

JSON

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

TWAP Status Field Reference

GetTwapStatuses returns the same format as StreamTwapStatuses. See the StreamTwapStatuses documentation for the complete field reference, including the TWAP state object and status values.

Best Practices

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

Current Limitations

Replay History: Available replay history varies by feed and endpoint. A cursor outside retained history returns NOT_FOUND
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.

GetTwapStatuses - Get TWAP Status Data

When to Use This Method

Method signature

Response Shape

Common Use Cases

Best Practices

Current Limitations

Resources

On this page

GetTwapStatuses - Get TWAP Status Data

When to Use This Method

Method signature

Response Shape

Common Use Cases

Best Practices

Current Limitations

Resources

On this page