stream_blocks (gRPC) | Hyperliquid API Docs

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) {}

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.
The emitted block number is abci_block.round, and the parent block number is abci_block.parent_round.
Use Position.block_height to place the stream cursor, and use abci_block.round as the canonical block number. They serve different roles and should not be treated as interchangeable values.
Do not assume the request cursor in Position.block_height can be round-tripped from abci_block.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.

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

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