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.

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

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

position: {
  block_number: 1058646974
}

Response Stream

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

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. Below is the exact structure.

Top-level keys (always present):

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

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.

Guarantees and alignment:

• events contains all miscellaneous events from the block, across all users.
• 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.

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

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

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

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

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

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

Common Use Cases

Error Handling and Reconnection

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 - Complete working examples
• GetMiscEvents - Point-in-time miscellaneous event retrieval
• StreamFills - The sibling stream for trade executions; pair with misc events for complete balance coverage
• Hyperliquid L1 Data Schemas - Authoritative upstream event schema reference

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