# StreamBlocks

> HyperCore private-preview documentation.

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

<Callout intent="info">
  This API is in private preview. Target September 2026; timing is subject to change.
</Callout>


# Stream blocks

`StreamBlocks` delivers raw HyperCore blocks as they are produced — every signed action
the block contained, together with its execution results. This is ideal for full-chain
indexers, action and response analysis, deposit and transfer monitoring, and
reconciliation against your own records.

## Overview

HyperCore produces a block roughly every 70 ms, and block numbers increment by exactly
one. The stream reflects that directly:

* One message per block, in order, including blocks with no activity
* Block number is the stream sequence — there is no separate sequence counter to track
* A missing block number is therefore an unambiguous gap
* Blocks are delivered as passthrough — the raw block, not a normalized projection

Because the stream is dense, gap detection needs no heartbeat and no bookkeeping beyond
remembering the last block you processed.

## Request structure

```proto
message StreamBlocksRequest {
  optional uint64 start_height = 1;
  string cursor = 2;
}
```

### Start height

**Field**: `start_height`
**Type**: `uint64`

Block number to begin streaming from. Omit to start from the current head.

### Cursor

**Field**: `cursor`
**Type**: `string`

Resume token from a previous session. Opaque — store it and return it unmodified.
Takes precedence over `start_height` when both are supplied.

## Response structure

```proto
message BlockEnvelope {
  uint64 height = 1;
  string cursor = 2;
  BlockData block = 3;
}
```

### Key fields

**`height`**: Block number and stream sequence. Compare it with the last processed block
to detect a gap.

**`cursor`**: Resume position for this message. Persist it after processing.

**`block`**: The raw block.

## Block contents

| Field | Description |
| --- | --- |
| `abci_block.round` | Block number. Use this as the block identifier. |
| `abci_block.parent_round` | Preceding block number, for verifying continuity. |
| `abci_block.time` | Block timestamp. |
| `abci_block.proposer` | Validator that proposed the block. |
| `abci_block.hardfork` | Protocol version and the round it activated. |
| `abci_block.signed_action_bundles` | Signed actions in the block, each with signature, action type, nonce, and vault address, plus builder attribution where present. |
| `resps` | Execution result per action, keyed by transaction hash, with the acting user and an ok or error status. |

See [raw and normalized HyperCore blocks](/docs/chains/hyperliquid/hypercore/concepts/raw-and-normalized-blocks)
for how these relate to the normalized objects returned by the JSON-RPC block methods.

## Recovering from a gap

1. Track the block number of the last message you processed.
2. On reconnect, send that number plus one as `start_height`, or send your stored `cursor`.
3. If `parent_round` does not match your last processed block, fetch the missing range
   with [`hl_getBatchBlocks`](/docs/chains/hyperliquid/hypercore/json-rpc/overview)
   and reconcile before resuming.

Replay covers a short reconnect window, not long-range recovery. Gaps wider than that window cannot be replayed on the stream — use the block lookup methods above to fetch the missing range, then resume.

## Stream vs block lookup

| | StreamBlocks | JSON-RPC block methods |
| --- | --- | --- |
| **Delivery** | Push, one message per block | Request/response |
| **Latency** | Lowest available | Higher — per-call round trip |
| **Range** | Live, plus bounded replay | Bounded historical lookup |
| **Use case** | Continuous indexing | Backfill, gap repair, spot checks |

## Message size

Raw HyperCore blocks can be large, and high-activity blocks substantially more so.
Configure your client's maximum receive size and processing queues accordingly.