StreamBlocks - Real-time Block Streaming
Stream continuous block data from Hyperliquid L1 Gateway via gRPC. Complete reference for all 47 action types.
Hyperliquid RPC endpoint: endpoint URLs, plans and pricing.
Stream continuous block data starting from a position, providing real-time access to Hyperliquid blockchain state changes.
Full Code Examples
Clone our gRPC Code Examples Repository for complete, runnable implementations in Go, Python, and Node.js.
When to Use This Method
StreamBlocks is essential for:
- Blockchain Monitoring - Track all network activity and state changes
- Block Explorers - Build real-time blockchain data applications
- Analytics Systems - Collect comprehensive blockchain metrics
- Compliance & Auditing - Monitor all network transactions and events
Method signature
rpc StreamBlocks(StreamRequest) returns (stream Record) {}V3 accepts an inclusive position.block_number or Unix-millisecond position.timestamp. Explicit zero is invalid. A positioned call replays from the selected record and then tails live; an empty request tails newly written blocks. Blocks do not accept filters. Set progress to opt in to progress frames.
position: {
block_number: 1058646974
}Each Record returns optional sequential block_number and Unix-millisecond timestamp cursors plus the raw replica_cmds bytes in data. block_number is distinct from the potentially skipping consensus abci_block.round. A pruned position returns NOT_FOUND; malformed cursors and filters return INVALID_ARGUMENT.
grpcurl \
-import-path content/docs/hyperliquid/grpc \
-proto v3.proto \
-H "x-api-key: ${DWELLIR_API_KEY}" \
-d '{"position":{"block_number":"1058646974"}}' \
"${HYPERLIQUID_GRPC_ENDPOINT}" \
hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/StreamBlocksResponse Stream
V3 carries the JSON-encoded replica_cmds block in Record.data.
Decode the data field to access:
- Block header information (consensus
round, timestamptime) - Transaction data and execution results
- State changes and events
- Validator signatures and consensus data
- Note: The sample format does not include a top-level block hash; bundle hashes are present per
signed_action_bundles.
- Note: The sample format does not include a top-level block hash; bundle hashes are present per
Full Block Spec
StreamBlocks emits a JSON payload matching Hyperliquid's replica_cmds BlockData. Below is the exact structure.
Top-level keys (always present):
{
"abci_block": {
"time": "2025-09-08T06:41:57.997372546", // ISO-8601 with nanosecond precision
"round": 992814678, // HyperBFT consensus round; it can skip
"parent_round": 992814677, // Parent consensus round; do not assume round - 1
"proposer": "0x5ac99df645f3414876c816caa18b2d234024b487", // 40 hex chars, lowercase
"hardfork": {
"version": 57, // Protocol version number
"round": 990500929 // Block when this version activated
},
"signed_action_bundles": [ // Array of [hash, bundle_data] pairs
[
"0xb4b1f5a9c233f9d90fd24b9961fd12708b36cc3d56f8fda47f32b667ee8d1227", // Bundle hash (64 hex)
{
"signed_actions": [ // Array of transactions in this bundle
{
"signature": {
"r": "0xd931f13565ae66c3bc41a05da4180bb795dbd9ed2d365efaf639fd23b3774ac6",
"s": "0x4a7a0534bf0a4238dfe404a88d335ab4c9b8222909100d773635e328d2ab864c",
"v": 27 // Recovery ID: always 27 or 28
},
"action": {
"type": "order", // Action type identifier
"orders": [{ // Type-specific payload
"a": 170, // Asset ID
"b": true, // Buy=true, Sell=false
"p": "0.038385", // Price as string
"s": "1514", // Size as string
"r": false, // Reduce-only flag
"t": {
"limit": {
"tif": "Ioc" // Time-in-force: Ioc/Alo/Gtc
}
},
"c": "0x7192c49bcadb32d394e38617ea99cc09" // Client order ID
}]
},
"nonce": 1757313597362 // Unique transaction nonce
}
// ... more signed_actions
],
"broadcaster": "0x67e451964e0421f6e7d07be784f35c530667c2b3", // Who sent bundle
"broadcaster_nonce": 1757313597367 // Bundle-level nonce
}
]
// ... more bundles (typically 1-6 total)
]
},
"resps": {
"Full": [ // Matches signed_action_bundles structure
[
"0xb4b1f5a9c233f9d90fd24b9961fd12708b36cc3d56f8fda47f32b667ee8d1227", // Same bundle hash
[ // One response per signed_action
{
"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00", // Address of action signer
"res": {
"status": "ok", // "ok" or "err"
"response": {
"type": "order", // Response type
"data": {
"statuses": [{
"filled": { // Order state: filled/resting/error
"totalSz": "1514.0", // Filled size
"avgPx": "0.038385", // Average fill price
"oid": 156190414943, // Order ID assigned
"cloid": "0x7192c49bcadb32d394e38617ea99cc09" // Client order ID
}
}]
}
}
}
}
// ... more responses (one per action)
]
]
// ... more response bundles (matches signed_action_bundles count)
]
}
}Bundle Entry Structure
[
"0x...", // bundle_hash
{
"signed_actions": [ /* SignedAction */ ],
"broadcaster": "0x...",
"broadcaster_nonce": 1757313597367
}
]SignedAction Envelope
Common fields across all actions:
{
"signature": { "r": "0x...", "s": "0x...", "v": 27 },
"action": { "type": "order" }, // Action type identifier
"nonce": 1757313597362,
"vaultAddress": "0x...", // optional
"expiresAfter": 1757313718705 // optional
}Data Guarantees
abci_blockandresps.Fullare always present.resps.Full.length === abci_block.signed_action_bundles.length.- For each bundle,
responses.length === signed_actions.length. abci_block.roundandabci_block.parent_roundare HyperBFT consensus rounds, not sequential block numbers; rounds can skip.- The transport's block cursor uses the sequential block-number axis. Do not derive it from
abci_block.round. - Timestamp
abci_block.timeis ISO-8601 with nanosecond precision (treat as UTC if no suffix).
Developer Tips
- Dispatch on
action.typeand handle new types defensively. - Store
bundle_hashas the stable join key between actions and responses. - Normalize prices/sizes (strings) to numeric types as appropriate.
Action Types Reference
Decoded payload references
The pages below document action payloads returned inside StreamBlocks and GetBlock
block data. They are not callable gRPC methods, and Dwellir's gRPC API does not submit
Hyperliquid write actions.
Each block contains signed action bundles where individual actions are categorized by type. Dispatch on action.type to process different categories.
Trading Actions
Core order management and execution operations.
| Action Type | Description |
|---|---|
| order | Limit, market, and trigger order submissions |
| cancel | Order cancellations by order ID |
| cancelByCloid | Order cancellations by client order ID |
| batchModify | Batched order modifications |
| modify | Single-order modifications |
| scheduleCancel | Scheduled cancellation settings |
| twapOrder | Time-weighted average price order submissions |
| twapCancel | TWAP order cancellations |
Transfer Actions
Asset movement between accounts and withdrawals.
| Action Type | Description |
|---|---|
| spotSend | Spot asset transfers to another address |
| sendAsset | Generic asset transfer |
| usdClassTransfer | USD-class asset transfers between margin modes |
| withdraw3 | External withdrawal requests |
| usdSend | USD transfers to another address |
Risk Management Actions
Leverage and margin configuration.
| Action Type | Description |
|---|---|
| updateLeverage | Position leverage updates |
| updateIsolatedMargin | Isolated-margin adjustments |
| userPortfolioMargin | Portfolio-margin configuration changes |
Permissions Actions
Agent authorization and trading permissions.
| Action Type | Description |
|---|---|
| approveAgent | Agent trading authorizations |
| approveBuilderFee | Builder-fee approvals for order routing |
| userDexAbstraction | User DEX abstraction settings |
| agentEnableDexAbstraction | Agent-managed DEX abstraction settings |
SubAccount Actions
Sub-account creation and management.
| Action Type | Description |
|---|---|
| subAccountTransfer | Main-account and sub-account asset transfers |
| createSubAccount | Sub-account creation requests |
| subAccountModify | Sub-account setting changes |
| subAccountSpotTransfer | Sub-account spot transfers |
Vault Actions
Vault creation, deposits, and position management.
| Action Type | Description |
|---|---|
| createVault | Trading-vault creation requests |
| vaultTransfer | Vault deposits and withdrawals |
| NetChildVaultPositionsAction | Net child vault positions |
Validator Actions
Consensus and cross-chain bridge operations.
| Action Type | Description |
|---|---|
| VoteEthDepositAction | Validator vote on ETH deposit |
| VoteEthFinalizedWithdrawalAction | Validator vote on finalized ETH withdrawal |
| ValidatorSignWithdrawalAction | Validator withdrawal signatures |
| voteAppHash | Validator votes on application state hashes |
EVM Actions
HyperEVM transaction execution and configuration.
| Action Type | Description |
|---|---|
| evmRawTx | Raw EVM transactions |
| evmUserModify | EVM user setting changes |
Security Actions
Multi-signature and account security.
| Action Type | Description |
|---|---|
| multiSig | Multi-signature operation |
| convertToMultiSigUser | Account conversions to multi-signature control |
Referral Actions
Referral program management.
| Action Type | Description |
|---|---|
| setReferrer | Account referrer settings |
| registerReferrer | Referrer registrations |
Market Actions
Perpetual market deployment.
| Action Type | Description |
|---|---|
| perpDeploy | Perpetual-market deployments |
Rewards Actions
Reward claiming operations.
| Action Type | Description |
|---|---|
| claimRewards | Accumulated reward claims |
Staking Actions
Token delegation and staking.
| Action Type | Description |
|---|---|
| cDeposit | Native-token transfers from spot into staking |
| cWithdraw | Native-token transfers from staking to spot |
| tokenDelegate | Validator delegation changes |
Lending Actions
Borrow and lending operations.
| Action Type | Description |
|---|---|
| borrowLend | Borrowing, repayment, supply, and withdrawal operations |
Spot Actions
Spot market configuration.
| Action Type | Description |
|---|---|
| spotUser | Spot user configuration |
Protocol and Control Actions
Protocol parameter, request-weight, and nonce-control payloads.
| Action Type | Description |
|---|---|
| noop | Used-nonce markers for invalidating in-flight actions |
| SetGlobalAction | Global system parameter changes |
| reserveRequestWeight | Request-weight reservations |
Progress Frames
Progress frames are an application-level heartbeat. Set StreamRequest.progress to receive one after each interval of silence. Blocks are not filterable, so a healthy stream is rarely silent for a full interval. Here the heartbeat mainly keeps the stream open through idle-limited proxies, which HTTP/2 keepalive pings do not, and exposes a stalled feed.
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 for the full contract.
Best Practices
- Connection Management: Implement robust reconnection logic with exponential backoff
- Memory Management: Use bounded collections for storing recent blocks to prevent memory leaks
- Performance: Process blocks asynchronously to avoid blocking the stream
- Error Recovery: Handle various error types (network, parsing, processing) gracefully
- Resource Cleanup: Properly close streams and connections on shutdown
Current Limitations
- Replay History: Available replay history varies by feed and endpoint
- Unavailable Cursors: A cursor outside retained history returns
NOT_FOUND - Backpressure: High-volume periods may require careful handling to avoid overwhelming downstream systems
Resources
- GitHub: gRPC Code Examples - Complete working implementations in Go, Python, and Node.js
- Copy Trading Bot - Production-ready trading bot example
Need help? Contact our support team or check the Hyperliquid gRPC documentation.
ListFeeds - Discover V3 Raw Feeds
Discover the raw feeds available from a Hyperliquid V3 gRPC endpoint, including supported cursors and server-side filter fields.
StreamFills - Real-time Fill Streaming
Stream continuous fill data from Hyperliquid L1 Gateway via gRPC. Monitor order executions in real-time.