Skip to main content

StreamBlocks

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(Position) returns (stream Block) {}

Request Message#

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#

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):

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

[
  "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_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 TypeDescription
orderSubmit new limit or market orders
cancelCancel orders by order ID
cancelByCloidCancel orders by client order ID
batchModifyModify multiple orders atomically
modifyModify a single existing order
scheduleCancelSchedule future order cancellation
twapOrderSubmit time-weighted average price order
twapCancelCancel TWAP order

Transfer Actions#

Asset movement between accounts and withdrawals.

Action TypeDescription
spotSendSend spot assets to another address
sendAssetGeneric asset transfer
usdClassTransferTransfer USD-class assets between margin modes
withdraw3Withdraw assets to external address
usdSendSend USD to another address

Risk Management Actions#

Leverage and margin configuration.

Action TypeDescription
updateLeverageUpdate position leverage
updateIsolatedMarginAdjust isolated margin for position
userPortfolioMarginEnable or configure portfolio margin mode

Permissions Actions#

Agent authorization and trading permissions.

Action TypeDescription
approveAgentAuthorize agent to trade on behalf of user
approveBuilderFeeApprove builder fee for order routing
userDexAbstractionConfigure DEX abstraction settings
agentEnableDexAbstractionAgent enables DEX abstraction for user

SubAccount Actions#

Sub-account creation and management.

Action TypeDescription
subAccountTransferTransfer assets between main and sub-account
createSubAccountCreate new sub-account
subAccountModifyModify sub-account settings
subAccountSpotTransferTransfer spot assets to/from sub-account

Vault Actions#

Vault creation, deposits, and position management.

Action TypeDescription
createVaultCreate new trading vault
vaultTransferDeposit or withdraw from vault
NetChildVaultPositionsActionNet child vault positions

Validator Actions#

Consensus and cross-chain bridge operations.

Action TypeDescription
VoteEthDepositActionValidator vote on ETH deposit
VoteEthFinalizedWithdrawalActionValidator vote on finalized ETH withdrawal
ValidatorSignWithdrawalActionValidator signs withdrawal transaction
voteAppHashValidator votes on application state hash

EVM Actions#

HyperEVM transaction execution and configuration.

Action TypeDescription
evmRawTxExecute raw EVM transaction
evmUserModifyModify EVM user settings

Security Actions#

Multi-signature and account security.

Action TypeDescription
multiSigMulti-signature operation
convertToMultiSigUserConvert account to multi-sig

Referral Actions#

Referral program management.

Action TypeDescription
setReferrerSet referrer for account
registerReferrerRegister as referrer

Market Actions#

Perpetual market deployment.

Action TypeDescription
perpDeployDeploy new perpetual market

Rewards Actions#

Reward claiming operations.

Action TypeDescription
claimRewardsClaim accumulated rewards

Staking Actions#

Token delegation and staking.

Action TypeDescription
tokenDelegateDelegate tokens to validator

Lending Actions#

Borrow and lending operations.

Action TypeDescription
borrowLendBorrow or lend assets

Collateral Actions#

Collateral deposits and withdrawals.

Action TypeDescription
cDepositDeposit collateral
cWithdrawWithdraw collateral

Spot Actions#

Spot market configuration.

Action TypeDescription
spotUserSpot user configuration

System Actions#

Internal system operations.

Action TypeDescription
noopNo operation (heartbeat/padding)
SetGlobalActionSet global system parameters
reserveRequestWeightReserve request weight allocation

Best Practices#

  1. Connection Management: Implement robust reconnection logic with exponential backoff
  2. Memory Management: Use bounded collections for storing recent blocks to prevent memory leaks
  3. Performance: Process blocks asynchronously to avoid blocking the stream
  4. Error Recovery: Handle various error types (network, parsing, processing) gracefully
  5. 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#

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