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 four 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
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 →

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 {
  rpc StreamBlocks(Position) returns (stream Block) {}
  rpc StreamFills(Position) returns (stream BlockFills) {}
  rpc StreamOrderbookSnapshots(Position) returns (stream OrderBookSnapshot) {}
  rpc GetOrderBookSnapshot(Timestamp) returns (OrderBookSnapshot) {}
}

message Position {
  oneof position {
    int64 timestamp_ms = 1;  // ms since Unix epoch
    int64 block_height = 2;  // block height
  }
}

message Timestamp {
  int64 timestamp_ms = 1;
}

message Block {
  bytes data = 1;  // JSON-encoded block
}

message OrderBookSnapshot {
  bytes data = 1;  // JSON-encoded snapshot
}

message BlockFills {
  bytes data = 1;  // JSON-encoded fills
}

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 →