StreamBlocks - Real-time Block Streaming | Hyperliquid API Documentation

Stream continuous block data from Hyperliquid L1 Gateway via gRPC. Complete reference for all 47 action types.

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

protobuf

rpc StreamBlocks(Position) returns (stream Block) {}

Request Message

protobuf

message Position {
  // Leave all fields unset or zero to target the latest data.
  oneof position {
    int64 timestamp_ms = 1; // ms since Unix epoch, inclusive
    int64 block_height = 2; // block height, inclusive
  }
}

The Position message allows flexible stream starting points:

timestamp_ms: Start streaming from a specific time (milliseconds since Unix epoch)
block_height: Start streaming from a specific block height
Empty/zero: Start streaming from the latest block

Response Stream

protobuf

message Block {
  // JSON-encoded Hyperliquid block from "replica_cmds".
  bytes data = 1;
}

The data field contains a JSON-encoded block object with:

Block header information (height round, timestamp time)
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.

Full Block Spec

StreamBlocks emits a JSON payload matching Hyperliquid's replica_cmds BlockData. Below is the exact structure.

Top-level keys (always present):

JSON

{
  "abci_block": {
    "time": "2025-09-08T06:41:57.997372546",  // ISO-8601 with nanosecond precision
    "round": 992814678,                        // Current block number (always incrementing)
    "parent_round": 992814677,                 // Previous block (always 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

jsonc

[
  "0x...", // bundle_hash
  {
    "signed_actions": [ /* SignedAction */ ],
    "broadcaster": "0x...",
    "broadcaster_nonce": 1757313597367
  }
]

SignedAction Envelope

Common fields across all actions:

jsonc

{
  "signature": { "r": "0x...", "s": "0x...", "v": 27 },
  "action": { "type": "order" },               // Action type identifier
  "nonce": 1757313597362,
  "vaultAddress": "0x...",                      // optional
  "expiresAfter": 1757313718705                 // optional
}

Data Guarantees

abci_block and resps.Full are always present.
resps.Full.length === abci_block.signed_action_bundles.length.
For each bundle, responses.length === signed_actions.length.
Height is abci_block.round, parent is abci_block.parent_round.
Timestamp abci_block.time is ISO-8601 with nanosecond precision (treat as UTC if no suffix).

Developer Tips

Dispatch on action.type and handle new types defensively.
Store bundle_hash as the stable join key between actions and responses.
Normalize prices/sizes (strings) to numeric types as appropriate.

Action Types Reference

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	Submit new limit or market orders
cancel	Cancel orders by order ID
cancelByCloid	Cancel orders by client order ID
batchModify	Modify multiple orders atomically
modify	Modify a single existing order
scheduleCancel	Schedule future order cancellation
twapOrder	Submit time-weighted average price order
twapCancel	Cancel TWAP order

Transfer Actions

Asset movement between accounts and withdrawals.

Action Type	Description
spotSend	Send spot assets to another address
sendAsset	Generic asset transfer
usdClassTransfer	Transfer USD-class assets between margin modes
withdraw3	Withdraw assets to external address
usdSend	Send USD to another address

Risk Management Actions

Leverage and margin configuration.

Action Type	Description
updateLeverage	Update position leverage
updateIsolatedMargin	Adjust isolated margin for position
userPortfolioMargin	Enable or configure portfolio margin mode

Permissions Actions

Agent authorization and trading permissions.

Action Type	Description
approveAgent	Authorize agent to trade on behalf of user
approveBuilderFee	Approve builder fee for order routing
userDexAbstraction	Configure DEX abstraction settings
agentEnableDexAbstraction	Agent enables DEX abstraction for user

SubAccount Actions

Sub-account creation and management.

Action Type	Description
subAccountTransfer	Transfer assets between main and sub-account
createSubAccount	Create new sub-account
subAccountModify	Modify sub-account settings
subAccountSpotTransfer	Transfer spot assets to/from sub-account

Vault Actions

Vault creation, deposits, and position management.

Action Type	Description
createVault	Create new trading vault
vaultTransfer	Deposit or withdraw from vault
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 signs withdrawal transaction
voteAppHash	Validator votes on application state hash

EVM Actions

HyperEVM transaction execution and configuration.

Action Type	Description
evmRawTx	Execute raw EVM transaction
evmUserModify	Modify EVM user settings

Security Actions

Multi-signature and account security.

Action Type	Description
multiSig	Multi-signature operation
convertToMultiSigUser	Convert account to multi-sig

Referral Actions

Referral program management.

Action Type	Description
setReferrer	Set referrer for account
registerReferrer	Register as referrer

Market Actions

Perpetual market deployment.

Action Type	Description
perpDeploy	Deploy new perpetual market

Rewards Actions

Reward claiming operations.

Action Type	Description
claimRewards	Claim accumulated rewards

Staking Actions

Token delegation and staking.

Action Type	Description
tokenDelegate	Delegate tokens to validator

Lending Actions

Borrow and lending operations.

Action Type	Description
borrowLend	Borrow or lend assets

Collateral Actions

Collateral deposits and withdrawals.

Action Type	Description
cDeposit	Deposit collateral
cWithdraw	Withdraw collateral

Spot Actions

Spot market configuration.

Action Type	Description
spotUser	Spot user configuration

System Actions

Internal system operations.

Action Type	Description
noop	No operation (heartbeat/padding)
SetGlobalAction	Set global system parameters
reserveRequestWeight	Reserve request weight allocation

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

Historical Data: Cannot stream from historical timestamps; only real-time streaming available
Data Retention: Node maintains only 24 hours of historical block data
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.

StreamBlocks - Real-time Block Streaming

On this page