# GetMiscEvents - Get Miscellaneous Event Data

Retrieve miscellaneous 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

`GetMiscEvents` is essential for:

- **Reconciliation** - Verify deposits, withdrawals, and transfers at a specific block
- **Historical Analysis** - Retrieve misc events for reporting or accounting
- **Auditing** - Confirm staking and validator reward activity at a specific block
- **Debugging** - Investigate specific events during development

Method signature

```protobuf
rpc GetMiscEvents(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 miscellaneous-event record written after the call begins, so set a deadline.

```protobuf
position: {
  timestamp: 1785736814057
}
filter: {
  fields: {
    field: "users"
    op: FILTER_OP_IN
    values: "0x1111111111111111111111111111111111111111"
  }
}
```

Miscellaneous events accept a `users` filter. User matching is case-insensitive, and values within the field use OR semantics. This feed does not accept `coins`. A zero-match unary request returns the selected `Record` with `data` containing `events: []`. The record also exposes optional `block_number` and `timestamp` cursors. A pruned position returns `NOT_FOUND`; malformed filters return `INVALID_ARGUMENT`. A filtered `Funding` event keeps only the filtered users' deltas, so one user's hourly funding fits the default 4 MiB gRPC receive limit. See [StreamMiscEvents user filtering](https://www.dwellir.com/docs/hyperliquid/stream_misc_events#user-filtering) for which addresses match each event kind.

## 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 constraints. Values within the field OR together. This feed does not accept coins.
- `filter.fields.field` (`string, required`): Feed-advertised filter field name. This feed accepts users only.
- `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":"users","op":"FILTER_OP_IN","values":["0x1111111111111111111111111111111111111111"]}]}}' \
  "${HYPERLIQUID_GRPC_ENDPOINT}" \
  hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/GetMiscEvents
```

### 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 misc_events_by_block, with non-matching events removed and Funding deltas trimmed to the filtered users 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/GetMiscEvents
```

### Response Fields

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

### Successful Response

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

```protobuf
rpc GetMiscEvents(Position) returns (BlockMiscEvents) {}
```

V2 accepts `block_height` or Unix-millisecond `timestamp_ms` and returns the source JSON in `BlockMiscEvents.data`.

## Common Use Cases

For V3, select a record with `GetRequest.position.block_number`, decode `Record.data`, and branch on each event's `inner` discriminator. Repeat positioned unary calls when reconciling a bounded block range.

### 1. Inspect a Single Block

```python
def get_block_misc_events(client, metadata, block_height):
    request = hyperliquid_pb2.Position(block_height=block_height)
    response = client.GetMiscEvents(request, metadata=metadata)
    block = json.loads(response.data)

    for event in block.get('events', []):
        kind = next(iter(event['inner']))  # the discriminator key
        print(kind, event['hash'])
```

### 2. Replay a Block Range

```python
def replay_misc_events(client, metadata, start_block, end_block):
    for block_height in range(start_block, end_block + 1):
        request = hyperliquid_pb2.Position(block_height=block_height)
        response = client.GetMiscEvents(request, metadata=metadata)
        process(json.loads(response.data))
```

`GetMiscEvents` returns the same format as `StreamMiscEvents`. See the [StreamMiscEvents documentation](https://www.dwellir.com/docs/hyperliquid/stream_misc_events) for the complete field reference, including the [block envelope](https://www.dwellir.com/docs/hyperliquid/stream_misc_events#full-misc-events-spec) and per-[event type](https://www.dwellir.com/docs/hyperliquid/stream_misc_events#event-types) shapes.

## Best Practices

1. **Position Selection**: Use the exact sequential block cursor for precise queries; timestamp lookups may resolve to different blocks across requests
2. **Defensive Parsing**: Branch on the key inside `inner` (and `delta.type` for `LedgerUpdate`) and handle unknown types gracefully
3. **Data Validation**: Always validate JSON structure and handle the common empty `events` array
4. **Error Recovery**: Implement retry logic with exponential backoff
5. **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`
- **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
- **[StreamMiscEvents Documentation](https://www.dwellir.com/docs/hyperliquid/stream_misc_events)** - Full misc event specification and streaming examples
- **[Hyperliquid L1 Data Schemas](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/nodes/l1-data-schemas)** - Authoritative upstream event schema reference

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