Skip to main content

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.

Code Examples Available

Complete working examples in Go, Python, and Node.js are available in our gRPC Code Examples Repository. Clone the repo to get started quickly.

Available Endpoints#

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

EndpointTypeBest For
StreamBlocksStreamingReal-time blockchain monitoring, block explorers, analytics
StreamFillsStreamingOrder execution tracking, trade settlement, PnL calculation
StreamOrderbookSnapshotsStreamingMarket depth monitoring, liquidity analysis, arbitrage
GetBlockUnaryPoint-in-time block data, backtesting, historical analysis
GetFillsUnaryPoint-in-time fill data, reconciliation, auditing
GetOrderBookSnapshotUnaryPoint-in-time market state, backtesting, historical analysis

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 →

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 →

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

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

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

Connection Best Practices#

Implement Reconnection Logic

Streams may disconnect due to network issues or server maintenance. Your client must include automatic reconnection with exponential backoff. See our gRPC Code Examples for production-ready reconnection patterns.

Important Notes#

Current Limitations#

  1. Data Retention: The node maintains only 24 hours of historical data
  2. Position Parameter: Supports both timestamp_ms and block_height for flexible stream positioning
  3. Historical Queries: Historical data within the retention window can be queried using the Position message

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#

Need Help?#

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