# StreamMiscEvents - Real-time Miscellaneous Event Streaming

Stream miscellaneous L1 events starting from a position, providing real-time access to every non-fill balance-affecting action on Hyperliquid: deposits, withdrawals, transfers, staking delegations, and validator rewards.

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

`StreamMiscEvents` is essential for:

- **Deposit & Withdrawal Monitoring** - Track funds entering and leaving accounts in real-time
- **Treasury & Transfer Tracking** - Follow spot transfers and internal `send` movements
- **Staking & Delegation Analytics** - Observe delegations, undelegations, and staking withdrawals
- **Validator Reward Accounting** - Reconcile per-epoch validator reward distributions
- **Compliance & Audit Trails** - Build a complete record of balance-affecting activity

`StreamMiscEvents` covers everything `StreamFills` does not. Fills are trades; misc events are every other action that moves funds. Consume both streams together for a complete view of all balance-affecting activity.

Method signature

```protobuf
rpc StreamMiscEvents(StreamRequest) returns (stream Record) {}
```

V3 accepts an inclusive `position.block_number` or Unix-millisecond `position.timestamp`. Explicit zero is invalid. A positioned call replays inclusively and then tails live; an empty request tails newly written miscellaneous events. Set `progress` to opt in to [progress frames](#progress-frames).

```protobuf
position: {
  block_number: 1058646974
}
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`. Stream records with no matching events are skipped. Each returned `Record` contains optional `block_number` and `timestamp` cursors plus the filtered block envelope in `data`. 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 tail newly written records.
- `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.
- `progress.interval_ms` (`uint32, optional`): Set progress to opt in to progress frames; leave it unset for none. Longest silence in milliseconds before a progress frame. 0 selects the feed default, currently 20000 within bounds of 10000 to 60000; ListFeeds reports the bounds in FeedInfo.progress.

### 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/StreamMiscEvents
```

### 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.
- `progress` (`StreamProgress, optional`): Set only on progress frames, which leave data, block_number, and timestamp unset. Check it before decoding data.
- `progress.scanned_through.block_number` (`int64, optional`): Inclusive cursor of the newest block the stream examined, sent or removed by the filter. A valid resume position; unset until the stream has examined a record.
- `progress.timestamp` (`optional int64, optional`): Source time at scanned_through in Unix milliseconds.

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

#### Invalid progress request

- Code: `INVALID_ARGUMENT`
- Description: A nonzero progress.interval_ms is outside the bounds advertised in FeedInfo.progress.

#### Not found

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

#### Replay capacity exhausted

- Code: `RESOURCE_EXHAUSTED`
- Description: Replay capacity is temporarily unavailable; retry with backoff.

#### Filter operator not implemented

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

#### Stream unavailable

- Code: `UNAVAILABLE`
- Description: No new records arrived before the stream timeout, or the stream failed mid-stream. Progress frames do not reset the timeout. Reconnect from the last cursor received.

#### Records lost

- Code: `DATA_LOSS`
- Description: The stream lost records, for example because it fell behind the live feed. It ends before sending any cursor past them; reconnect from the last cursor received to re-read the gap.

#### Slow consumer

- Code: `DEADLINE_EXCEEDED`
- Description: The stream could not deliver records in time because the client read too slowly or stopped reading; reconnect from the last processed cursor.

#### 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 start from the latest data and continue streaming.
- `block_height` (`int64, optional`): Inclusive block-height cursor. Omit it to start from the latest data and continue streaming.

### 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/StreamMiscEvents
```

### Response Fields

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

### Successful Response

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

```protobuf
rpc StreamMiscEvents(Position) returns (stream BlockMiscEvents) {}
```

V2 accepts the inclusive cursor fields `block_height` and `timestamp_ms`; an empty `Position` tails new event records. It returns the source JSON in `BlockMiscEvents.data`.

## Response Stream

V3 carries the JSON-encoded `misc_events_by_block` envelope in `Record.data`.

V2 carries the JSON-encoded `misc_events_by_block` envelope in `BlockMiscEvents.data`.

Decode the `data` field to access:

- Block reference (`local_time`, `block_time`, `block_number`)
- An `events` array of miscellaneous L1 event objects (empty for most blocks)

## Per-Block Delivery

An unfiltered source envelope can contain an empty `events` array. That is a valid source record, not a transport heartbeat, and it does not prove that the connection is healthy. A `users` filter skips records with zero matching events, so those empty envelopes are not delivered.

Clients must detect discontinuities and duplicates and persist only a cursor they actually received. Stream health comes from RPC status, deadlines, and reconnect handling; `UNAVAILABLE` means no new records arrived before the stream timeout.

## Full Misc Events Spec

`StreamMiscEvents` emits a JSON payload matching Hyperliquid's `misc_events_by_block` format, passed through byte-for-byte from the node with no normalization. The one exception is a `Funding` event on a `users`-filtered call, which keeps only the filtered users' deltas. Below is the exact structure.

Top-level keys (always present):

```json
{
  "local_time": "2026-07-02T11:10:49.483839100",   // ISO-8601 timestamp when node processed the block (nanosecond precision)
  "block_time": "2026-07-02T11:10:47.023075863",    // ISO-8601 timestamp from block consensus
  "block_number": 1057659853,                        // Block height containing these events
  "events": []                                       // Array of miscellaneous event objects (empty for most blocks)
}
```

Each entry in `events` is a raw upstream Hyperliquid L1 event object:

| Field   | Type   | Description                                                                                                                                |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `time`  | string | ISO-8601 timestamp of the event                                                                                                            |
| `hash`  | string | Transaction hash. An all-zeros hash indicates a system-generated event (e.g. validator rewards) rather than a user transaction             |
| `inner` | object | Single-key object whose key is the event type discriminator (e.g. `"LedgerUpdate"`, `"Delegation"`, `"CWithdrawal"`, `"ValidatorRewards"`) |

Branch on the single key inside `inner` to determine the event type. The sections below cover the event types observed on mainnet; the upstream schema defines additional types, so treat these as examples rather than an exhaustive list. The authoritative schema reference is Hyperliquid's [L1 data schemas documentation](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/nodes/l1-data-schemas).

Guarantees and alignment:

- Unfiltered `events` contains all miscellaneous events from the block, across all users.
- A `users` filter keeps only matching events in `events` and trims each kept `Funding` event to the filtered users' deltas. See [User filtering](#user-filtering).
- An envelope may contain an empty `events` array; treat it as source data rather than a liveness signal.
- `block_number` is sequential and distinct from the potentially skipping `abci_block.round` consensus value in StreamBlocks; `block_time` aligns with `abci_block.time`.

Developer tips:

- Branch on the key inside `inner` and handle unknown event types defensively — the upstream set can grow.
- Track the last processed `block_number` so you can resume cleanly after a reconnect.
- Normalize amount fields (strings) to numeric types as appropriate.
- Treat the all-zeros `hash` as the marker for system-generated events.

## Event Types

### LedgerUpdate

`LedgerUpdate` is the most common event type. It carries a `users` array (the involved addresses) and a `delta` object whose `type` field discriminates the specific ledger action.

```json
{
  "time": "2026-07-02T11:10:47.023075863",
  "hash": "0xae740acbd26e0108afed043f0a9bcd02022d00b16d611fda523cb61e9161daf3",
  "inner": {
    "LedgerUpdate": {
      "users": [
        "0x2000000000000000000000000000000000000000",
        "0x0a82a35f3e54aede3a20931f446836e6c69cae0b"
      ],
      "delta": {
        "type": "spotTransfer",
        "token": "USDC",
        "amount": "100.058362",
        "usdcValue": "100.058362",
        "user": "0x2000000000000000000000000000000000000000",
        "destination": "0x0a82a35f3e54aede3a20931f446836e6c69cae0b",
        "fee": "0.0",
        "nativeTokenFee": "0.0",
        "nonce": 2053915,
        "feeToken": ""
      }
    }
  }
}
```

The `delta.type` discriminator determines the remaining fields. Observed types on mainnet include:

| `delta.type`   | Meaning                            | Notable fields                                               |
| -------------- | ---------------------------------- | ------------------------------------------------------------ |
| `send`         | Internal transfer between accounts | `user`, `destination`, `token`, `amount`, `usdcValue`, `fee` |
| `spotTransfer` | Spot balance transfer              | `user`, `destination`, `token`, `amount`, `usdcValue`, `fee` |
| `deposit`      | Funds deposited into an account    | `usdc`                                                       |
| `withdraw`     | Funds withdrawn from an account    | `usdc`, `nonce`, `fee`                                       |
| `rewardsClaim` | Rewards claimed                    | `token`, `amount`                                            |
| `borrowLend`   | Borrow/lend operation              | `token`, `operation`, `amount`, `interestAmount`             |

More `delta.type` values exist upstream; branch defensively on `delta.type` and treat this table as examples, not an exhaustive list. Example deltas:

```json
{ "type": "deposit", "usdc": "3494.915745" }
{ "type": "withdraw", "usdc": "89.15", "nonce": 1782990425200000, "fee": "1.0" }
{ "type": "rewardsClaim", "amount": "1.097128", "token": "USDC" }
{ "type": "borrowLend", "token": "USDC", "operation": "supply", "amount": "0.23068", "interestAmount": "0.0" }
```

### Delegation

Staking delegation and undelegation. The `is_undelegate` flag distinguishes the two directions.

```json
{
  "time": "2026-07-02T11:11:06.583481947",
  "hash": "0xfa0716eba98e39b0fb80043f0a9cec02029400d1448158839dcfc23e6882139b",
  "inner": {
    "Delegation": {
      "user": "0xd5a5ae523080973946ac67e34f5fc70671bd8667",
      "validator": "0x5ac99df645f3414876c816caa18b2d234024b487",
      "amount": "20.65611502",
      "is_undelegate": true
    }
  }
}
```

### CWithdrawal

A staking withdrawal, which enters a pending state until finalization. The `is_finalized` flag reflects whether the withdrawal has completed.

```json
{
  "time": "2026-07-02T11:11:07.283636968",
  "hash": "0xae4f651df8ef488eafc9043f0a9cf6021348000393e2676052181070b7e32279",
  "inner": {
    "CWithdrawal": {
      "user": "0xd5a5ae523080973946ac67e34f5fc70671bd8667",
      "amount": "20.65611502",
      "is_finalized": false
    }
  }
}
```

### ValidatorRewards

Per-epoch validator reward distributions. These are system-generated, so they carry an all-zeros `hash`. The `validator_to_reward` array holds `[validator_address, amount]` pairs.

```json
{
  "time": "2026-07-02T11:11:00.042812129",
  "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "inner": {
    "ValidatorRewards": {
      "validator_to_reward": [
        ["0x000000000056f99d36b6f2e0c51fd41496bbacb8", "0.2806444"],
        ["0x15458aed3c7a49b215fbfa863c6ff550c31e1a31", "0.22056816"],
        ["0x30c66ebc7f5ef4f340b424a26e4d944f60129815", "0.34709989"]
      ]
    }
  }
}
```

## User filtering

A `users` filter keeps an event when any of its user-role addresses is in the request list. Matching is case-insensitive. Validator-role addresses are not matched.

| Event kind                                         | Addresses that match                                                              |
| -------------------------------------------------- | --------------------------------------------------------------------------------- |
| `LedgerUpdate`                                     | `users[]`, plus `delta.user`, `delta.destination`, and `delta.vault` when present |
| `CDeposit`, `CWithdrawal`, `Delegation`            | `user` (not `validator`)                                                          |
| `Funding`                                          | any `deltas[].user`                                                               |
| `ValidatorRewards`, `GossipPriorityAuctionRestart` | none; these never match                                                           |

A `LedgerUpdate` `send` matches the sender and the destination.

A `Funding` match returns the event with only the filtered users' deltas, in source order. Each kept delta and every other byte of the event stay as the node wrote them. When every delta matches, the event is unchanged. Hyperliquid writes one `Funding` event per hourly settlement, and on mainnet the whole batch can exceed 50 MB. A filtered event holds only your wallets' deltas. One wallet's hourly payments fit the default 4 MiB gRPC receive limit. A long `users` list can still exceed it, and unfiltered calls still return the whole batch. In those cases, raise the client inbound message limit above the expected event size.

`ListFeeds` advertises `users` for this feed. A `coins` field, an empty value list, or an unknown field name returns `INVALID_ARGUMENT`. An unknown `inner` kind fails a filtered call with `INTERNAL`; unfiltered calls still deliver the record.

## Common Use Cases

Open V3 with an empty `StreamRequest` to tail newly written records, decode each `Record.data` envelope, and branch on the event's `inner` discriminator. Pass `filter.fields` with `users` to receive only events that involve those addresses. To resume, set `StreamRequest.position.block_number` to a cursor you persisted and replay inclusively, deduplicating the committed record.

### 1. Deposit and Withdrawal Monitor

```python
def classify_event(event):
    """Return a (kind, detail) tuple for a misc event."""
    inner = event['inner']
    kind = next(iter(inner))          # the single discriminator key
    body = inner[kind]

    if kind == 'LedgerUpdate':
        delta = body['delta']
        return (delta['type'], delta)  # e.g. ('deposit', {...})
    return (kind, body)                # e.g. ('Delegation', {...})

def watch_flows(client, metadata):
    request = hyperliquid_pb2.Position()  # latest
    for response in client.StreamMiscEvents(request, metadata=metadata):
        block = json.loads(response.data)
        for event in block.get('events', []):
            kind, detail = classify_event(event)
            if kind in ('deposit', 'withdraw'):
                print(f"block {block['block_number']}: {kind} {detail.get('usdc')} USDC")
```

### 2. Streaming Misc Events in Python

```python
import grpc
import json
import os
import hyperliquid_pb2
import hyperliquid_pb2_grpc

def stream_misc_events():
    endpoint = os.getenv('HYPERLIQUID_ENDPOINT')
    api_key = os.getenv('API_KEY')

    credentials = grpc.ssl_channel_credentials()
    options = [('grpc.max_receive_message_length', 150 * 1024 * 1024)]  # 150MB max
    metadata = [('x-api-key', api_key)]

    with grpc.secure_channel(endpoint, credentials, options=options) as channel:
        client = hyperliquid_pb2_grpc.HyperliquidL1GatewayStub(channel)

        # Empty Position means latest; set block_height or timestamp_ms to backfill
        request = hyperliquid_pb2.Position()

        for response in client.StreamMiscEvents(request, metadata=metadata):
            block = json.loads(response.data)
            events = block.get('events', [])
            if events:
                print(f"block {block['block_number']}: {len(events)} misc events")
```

## Progress Frames

Progress frames are an application-level heartbeat. Set `StreamRequest.progress` to receive one after each interval of silence. A `users` filter can leave the stream silent for minutes. They keep it open through idle-limited proxies, which HTTP/2 keepalive pings do not, and advance your resume cursor through blocks the filter removed.

A progress frame sets `Record.progress.scanned_through.block_number` and leaves the data fields unset, so check `progress` before decoding `data`. Persist `scanned_through` as an inclusive resume cursor. See [progress frames](https://www.dwellir.com/docs/hyperliquid/grpc#progress-frames) for the full contract.

V2 streams do not send progress frames. Use the V3 method to opt in.

## Error Handling and Reconnection

Reconnect with `StreamRequest.position.block_number` set to the last committed V3 cursor, from a data record or a progress frame's `scanned_through`. Replay is inclusive, so deduplicate that record before advancing. Use bounded backoff for retryable RPC statuses.

Reconnect by replaying from the last processed block. Pass the next `block_height` in the `Position` so no events are skipped or double-counted.

```python
def stream_with_resume(client, metadata, start_block):
    next_block = start_block
    while True:
        request = hyperliquid_pb2.Position(block_height=next_block)
        try:
            for response in client.StreamMiscEvents(request, metadata=metadata):
                block = json.loads(response.data)
                process(block)
                next_block = block['block_number'] + 1
        except grpc.RpcError as e:
            print(f"stream error, resuming from {next_block}: {e}")
```

## Best Practices

1. **Connection Management**: Implement robust reconnection logic with exponential backoff
2. **Resumable State**: Follow the version-specific recovery guidance above and persist the cursor required by your selected API version
3. **Defensive Parsing**: Branch on the key inside `inner` (and `delta.type` for `LedgerUpdate`) and handle unknown types gracefully
4. **Health Monitoring**: Use RPC status, deadlines, and reconnect handling; empty source envelopes are not heartbeats
5. **Performance**: Process events asynchronously to avoid blocking the stream
6. **Resource Cleanup**: Properly close streams and connections on shutdown

## Current Limitations

- **Replay History**: Available replay history varies by feed and endpoint. A cursor outside retained history returns `NOT_FOUND`
- **Schema Coverage**: The upstream event set can grow; treat the documented event and delta types as examples, not an exhaustive list
- **Backpressure**: High-volume periods may require careful handling to avoid overwhelming downstream systems

## Resources

- **[GitHub: gRPC Code Examples](https://github.com/dwellir-public/gRPC-code-examples)** - Complete working examples
- **[GetMiscEvents](https://www.dwellir.com/docs/hyperliquid/get_misc_events)** - Point-in-time miscellaneous event retrieval
- **[StreamFills](https://www.dwellir.com/docs/hyperliquid/stream_fills)** - The sibling stream for trade executions; pair with misc events for complete balance coverage
- **[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).*
