# GetTwapStatuses - Get TWAP Status Data

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

Clone our [gRPC Code Examples Repository](https://github.com/dwellir-public/gRPC-code-examples) 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](https://www.dwellir.com/docs/hyperliquid/stream_twap_statuses) 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`, `coins` and `dexes` filters. User matching is case-insensitive, coin matching is case-sensitive and dex matching is exact on the HIP-3 dex prefix; 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`.

## V3 reference

### Request Parameters

- `position.timestamp` (`int64, optional`): Inclusive V3 Unix-millisecond cursor. Omit the position to wait for the next written record.
- `position.block_number` (`int64, optional`): Inclusive V3 sequential block cursor. Explicit zero is invalid.
- `filter.fields` (`FieldFilter[], optional`): V3 users/coins constraints. Fields AND together; values within one field OR together.
- `filter.fields.field` (`string, required`): Feed-advertised filter field name, either users or coins.
- `filter.fields.op` (`FilterOp, optional`): FILTER_OP_UNSPECIFIED or FILTER_OP_IN.
- `filter.fields.values` (`string[], required`): One or more accepted values; entries within the list use OR semantics.

### Request Example

```bash
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/GetTwapStatuses
```

### Response Fields

- `block_number` (`optional int64, optional`): Sequential Hyperliquid block cursor; never the HyperBFT consensus round.
- `timestamp` (`optional int64, optional`): Record time in Unix milliseconds.
- `data` (`bytes, required`): Bytes from the node_twap_statuses_by_block, with non-matching events removed when a filter is applied.

### Successful Response

```protobuf
block_number: 1058646974
timestamp: 1785736814057
data: "{\"block_number\":1058646974,\"events\":[]}"
```

### Error Responses

#### Invalid argument

- Code: `INVALID_ARGUMENT`
- Description: A cursor is zero or malformed, or a filter has an unsupported field, duplicate field, empty name, or empty value list.

#### Not found

- Code: `NOT_FOUND`
- Description: Available replay history varies by feed and endpoint. A cursor outside retained history returns NOT_FOUND.

#### Filter operator not implemented

- Code: `UNIMPLEMENTED`
- Description: The requested filter operator is well formed but is not implemented by this gateway version.

#### Position ahead of head

- Code: `OUT_OF_RANGE`
- Description: The requested block is above the feed's current head and may become available later.

#### Unauthenticated

- Code: `UNAUTHENTICATED`
- Description: The request did not include usable authentication metadata.

#### Permission denied

- Code: `PERMISSION_DENIED`
- Description: The supplied credential is not permitted to call this service.

## V2 reference

### Request Parameters

- `timestamp_ms` (`int64, optional`): Inclusive Unix-millisecond cursor. Omit it to target the latest data.
- `block_height` (`int64, optional`): Inclusive block-height cursor. Omit it to target the latest data.

### Request Example

```bash
grpcurl \
  -import-path content/docs/hyperliquid/grpc \
  -proto v2.proto \
  -H "x-api-key: ${DWELLIR_API_KEY}" \
  -d '{"block_height":"1058646974"}' \
  "${HYPERLIQUID_GRPC_ENDPOINT}" \
  hyperliquid_l1_gateway.v2.HyperliquidL1Gateway/GetTwapStatuses
```

### Response Fields

- `data` (`bytes, required`): JSON-encoded payload returned in the V2 BlockTwapStatuses wrapper.

### Successful Response

```protobuf
message BlockTwapStatuses {
  bytes data = 1;
}
```

```protobuf
rpc GetTwapStatuses(Position) returns (BlockTwapStatuses) {}
```

V2 accepts `block_height` or Unix-millisecond `timestamp_ms` and returns the source JSON in `BlockTwapStatuses.data`. An empty `Position` targets the latest available TWAP status envelope.

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

V2 returns the envelope in `BlockTwapStatuses.data`:

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

The decoded JSON has the same shape as [StreamTwapStatuses](https://www.dwellir.com/docs/hyperliquid/stream_twap_statuses):

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

### 1. Inspect a Single Block

```python
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

```python
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

```python
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

```python
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)
    ]
```

`GetTwapStatuses` returns the same format as `StreamTwapStatuses`. See the [StreamTwapStatuses documentation](https://www.dwellir.com/docs/hyperliquid/stream_twap_statuses) for the complete field reference, including the [TWAP state object](https://www.dwellir.com/docs/hyperliquid/stream_twap_statuses#twap-state-object) and [status values](https://www.dwellir.com/docs/hyperliquid/stream_twap_statuses#status-values).

## V2 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 the exact sequential block cursor for precise queries; timestamp lookups 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](https://www.dwellir.com/docs/hyperliquid/get_block) or [StreamBlocks](https://www.dwellir.com/docs/hyperliquid/stream_blocks) when you need the original signed `twapOrder` or `twapCancel` action
6. **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](https://github.com/dwellir-public/gRPC-code-examples)** - Complete working examples
- **[StreamTwapStatuses Documentation](https://www.dwellir.com/docs/hyperliquid/stream_twap_statuses)** - Full TWAP status specification and streaming examples
- **[twapOrder Action Type](https://www.dwellir.com/docs/hyperliquid/twapOrder)** - TWAP order submission payloads in StreamBlocks
- **[twapCancel Action Type](https://www.dwellir.com/docs/hyperliquid/twapCancel)** - TWAP cancellation payloads in StreamBlocks

*Need help? Contact our [support team](mailto:support@dwellir.com) or check the [Hyperliquid gRPC documentation](https://www.dwellir.com/docs/hyperliquid/grpc).*
