Hyperliquid gRPC API

Dwellir provides a high-performance gRPC API for streaming real-time blockchain and trading data from Hyperliquid L1 Gateway. Built on Protocol Buffers, this service offers low-latency access to blocks, fills, and order book snapshots.

Available Endpoints

The gRPC API provides twelve distinct endpoints for accessing Hyperliquid data:

StreamBlocks

Stream continuous block data from the Hyperliquid blockchain. Each block contains transaction data, execution results, and state changes.

Ideal for:

• Block explorer backends
• Blockchain analytics and metrics
• Compliance and auditing systems
• Real-time network monitoring

View StreamBlocks Documentation →

StreamFills

Stream fill data for executed orders as they occur on the network.

Ideal for:

• Order execution monitoring
• Trade settlement tracking
• PnL calculation systems
• Execution quality analysis

View StreamFills Documentation →

StreamOrderbookSnapshots

Stream continuous order book snapshots showing complete market depth.

Ideal for:

• Real-time market depth monitoring
• Liquidity analysis
• Market making strategies
• Arbitrage detection

View StreamOrderbookSnapshots Documentation →

StreamRawBookDiffs

Stream incremental order book changes: additions, size updates, and removals per block.

Ideal for:

• Local order book reconstruction
• Depth and liquidity analysis
• Market microstructure research
• Backtesting inputs from a chosen position

View StreamRawBookDiffs Documentation →

StreamOrderStatuses

Stream order lifecycle events: opens, fills, cancellations, and rejections.

Ideal for:

• Order lifecycle tracking
• Rejection analysis
• Resting-order context per status change
• Compliance and auditing

View StreamOrderStatuses Documentation →

StreamMiscEvents

Stream non-fill balance-affecting events: deposits, withdrawals, transfers, staking delegations, and validator rewards.

Ideal for:

• Deposit and withdrawal monitoring
• Treasury and transfer tracking
• Staking and delegation analytics
• Validator reward accounting

View StreamMiscEvents Documentation →

GetBlock

Retrieve a single block at a specific position.

Ideal for:

• Point-in-time blockchain analysis
• Backtesting with historical block data
• Auditing and compliance verification
• Debugging specific transactions

View GetBlock Documentation →

GetFills

Retrieve fills at a specific position.

Ideal for:

• Trade reconciliation
• Historical fill analysis
• PnL verification at specific points
• Audit trail generation

View GetFills Documentation →

GetOrderBookSnapshot

Retrieve a single order book snapshot at a specific point in time.

Ideal for:

• Point-in-time market analysis
• Backtesting trading strategies
• Historical market research
• Snapshot-based analytics

View GetOrderBookSnapshot Documentation →

GetRawBookDiffs

Retrieve order book diffs at a specific position.

Ideal for:

• Targeted book reconstruction at a specific block
• Historical book-change analysis
• Auditing resting-book transitions
• Debugging specific book states

View GetRawBookDiffs Documentation →

GetOrderStatuses

Retrieve order status events at a specific position.

Ideal for:

• Order reconciliation at specific blocks
• Point-in-time rejection analysis
• Auditing status transitions
• Debugging specific order outcomes

View GetOrderStatuses Documentation →

GetMiscEvents

Retrieve miscellaneous events at a specific position.

Ideal for:

• Deposit and withdrawal reconciliation
• Point-in-time transfer and staking analysis
• Validator reward verification at specific blocks
• Audit trail generation

View GetMiscEvents Documentation →

StreamBlocks Action Types

The StreamBlocks endpoint returns blocks containing 47 different action types covering trading, transfers, permissions, staking, and more. Each block contains signed action bundles with their execution responses, allowing you to track both the actions submitted and their outcomes.

View Action Types Reference →

Key Features

• Low latency - gRPC binary protocol with Protocol Buffers for efficient serialization
• Flexible positioning - Start streams from specific timestamps or block heights
• Complete data - Access to full block data, fills, and order book snapshots
• Real-time streaming - Server-side push model for immediate updates
• 24-hour retention - Historical data available within the retention window

Quick Start

Get started with complete working examples in Go, Python, and Node.js from our gRPC Code Examples Repository. The repository includes connection setup, stream handling, and reconnection logic.

Service Definition

syntax = "proto3";

package hyperliquid_l1_gateway.v2;

service HyperliquidL1Gateway {
  // Start a blocks stream from the given Position
  rpc StreamBlocks(Position) returns (stream Block) {}

  // Start a fills stream from the given Position
  rpc StreamFills(Position) returns (stream BlockFills) {}

  // Start an order book snapshots stream from the given Position
  rpc StreamOrderbookSnapshots(Position) returns (stream OrderBookSnapshot) {}

  // Start a raw book diffs stream from the given Position
  rpc StreamRawBookDiffs(Position) returns (stream BlockRawBookDiffs) {}

  // Start an order statuses stream from the given Position
  rpc StreamOrderStatuses(Position) returns (stream BlockOrderStatuses) {}

  // Start a miscellaneous events stream from the given Position
  rpc StreamMiscEvents(Position) returns (stream BlockMiscEvents) {}

  // Return a single block at the requested Position
  rpc GetBlock(Position) returns (Block) {}

  // Return fills at the requested Position
  rpc GetFills(Position) returns (BlockFills) {}

  // Return an order book snapshot at the requested Timestamp
  rpc GetOrderBookSnapshot(Timestamp) returns (OrderBookSnapshot) {}

  // Return raw book diffs at the requested Position
  rpc GetRawBookDiffs(Position) returns (BlockRawBookDiffs) {}

  // Return order statuses at the requested Position
  rpc GetOrderStatuses(Position) returns (BlockOrderStatuses) {}

  // Return miscellaneous events at the requested Position
  rpc GetMiscEvents(Position) returns (BlockMiscEvents) {}
}

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

message Timestamp {
  int64 timestamp_ms = 1;
}

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

message OrderBookSnapshot {
  // JSON-encoded Hyperliquid order book snapshot.
  bytes data = 1;
}

message BlockFills {
  // JSON-encoded object from "node_fills" or "node_fills_by_block".
  bytes data = 1;
}

message BlockRawBookDiffs {
  // JSON-encoded object from "node_raw_book_diffs_by_block".
  bytes data = 1;
}

message BlockOrderStatuses {
  // JSON-encoded object from "node_order_statuses_by_block".
  bytes data = 1;
}

message BlockMiscEvents {
  // JSON-encoded block envelope from "misc_events_by_block".
  bytes data = 1;
}

Connection Best Practices

Important Notes

Current Limitations

1. Data Retention: The node maintains only 24 hours of historical data
2. Position Parameter: Blocks and fills support both timestamp_ms and block_height; order book snapshot streams use timestamp-based positioning
3. Historical Queries: Historical data within the retention window can be queried using the Position message
4. Authentication Flow: Connect to the gRPC host over TLS and pass your API key in the x-api-key metadata header. The endpoint catalog may display placeholder /<key> renderings, but gRPC clients send credentials as metadata rather than as part of the path.

Testing Tools

A Go testing application is available for customers who want to test the streaming functionality. This is a 16MB binary that prints stream data to the terminal. Contact our support team to obtain this testing tool.

Resources

• GitHub: gRPC Code Examples - Complete working examples in Go, Python, and Node.js
• Copy Trading Bot Example - Production-ready copy trading implementation
• Proto definition files available upon request

Need Help?

• Email: support@dwellir.com
• Dashboard: dashboard.dwellir.com

Stream real-time Hyperliquid blockchain data with Dwellir's enterprise-grade gRPC infrastructure. Get your API key →