Skip to main content

HyperLiquid gRPC API Reference

HyperLiquid L1 Gateway provides a gRPC-based API for accessing blockchain and trading data. The API is defined using Protocol Buffers (proto3).

Service Definition​

service HyperLiquidL1Gateway {
  // Get single OrderBookSnapshot at timestamp
  rpc GetOrderBookSnapshot(Timestamp) returns (OrderBookSnapshot) {}

  // Stream Blocks starting from timestamp
  rpc StreamBlocks(Timestamp) returns (stream Block) {}

  // Stream OrderBookSnapshots starting from timestamp
  rpc StreamOrderBookSnapshots(Timestamp) returns (stream OrderBookSnapshot) {}

  // Stream BlockTrades starting from timestamp
  rpc StreamBlockTrades(Timestamp) returns (stream BlockTrades) {}

  // Stream BlockFills starting from timestamp
  rpc StreamBlockFills(Timestamp) returns (stream BlockFills) {}
}

Message Types​

message Timestamp {   
  int64 timestamp = 1;
}

Note: Timestamp functionality is not yet implemented. Currently, all streams start from "now" and stream forward.

Available Methods​

1. GetOrderBookSnapshot​

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

Request: Timestamp
Response: OrderBookSnapshot
Current Limitation: Timestamp parameter not implemented; returns current snapshot

2. StreamBlocks​

Stream continuous block data starting from a timestamp.

Request: Timestamp
Response: stream Block
Use Case: Monitor blockchain state changes in real-time

3. StreamOrderBookSnapshots​

Stream continuous order book snapshots.

Request: Timestamp
Response: stream OrderBookSnapshot
Use Case: Track order book changes for trading strategies

4. StreamBlockTrades​

Stream trade data as blocks are produced.

Request: Timestamp
Response: stream BlockTrades
Use Case: Monitor trading activity and volume

5. StreamBlockFills​

Stream fill data for executed orders.

Request: Timestamp
Response: stream BlockFills
Use Case: Track order execution and settlement

Implementation Examples​

package main

import (
    "context"
    "log"
    
    pb "your-project/hyperliquid_l1_gateway/v1"
    "google.golang.org/grpc"
)

func main() {
    // Connect to HyperLiquid L1 Gateway
    conn, err := grpc.Dial(
        "<YOUR_HYPERLIQUID_ENDPOINT>", // Contact support@dwellir.com
        grpc.WithInsecure(),
    )
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()
    
    client := pb.NewHyperLiquidL1GatewayClient(conn)
    
    // Stream order book snapshots
    stream, err := client.StreamOrderBookSnapshots(
        context.Background(),
        &pb.Timestamp{Timestamp: 0}, // Start from now
    )
    if err != nil {
        log.Fatalf("Failed to stream: %v", err)
    }
    
    for {
        snapshot, err := stream.Recv()
        if err != nil {
            log.Fatalf("Stream error: %v", err)
        }
        
        // Process JSON data
        log.Printf("Received snapshot: %s", snapshot.Data)
    }
}

Network Information​

Protocol

gRPC

Binary Protocol

Data Format

JSON

In Protocol Buffers

Data Retention

24 Hours

Rolling Window

Streaming

Real-time

From Current Time

Important Notes​

⚠️ Current Limitations​

  1. Timestamp Parameter: The Timestamp parameter is not yet implemented. All streams currently start from "now" and stream forward only.

  2. Data Retention: The node currently maintains only 24 hours of historical data.

  3. Historical Queries: Historical data queries are not available; only real-time streaming from the current moment is supported.

🛠️ 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.

Best Practices​

1. Connection Management​

Maintain persistent gRPC connections for streaming:

// Implement reconnection logic
func connectWithRetry(addr string, maxRetries int) (*grpc.ClientConn, error) {
    var conn *grpc.ClientConn
    var err error
    
    for i := 0; i < maxRetries; i++ {
        conn, err = grpc.Dial(addr, grpc.WithInsecure())
        if err == nil {
            return conn, nil
        }
        time.Sleep(time.Second * time.Duration(i+1))
    }
    
    return nil, err
}

2. Error Handling​

Implement robust error handling for stream interruptions:

def stream_with_retry(stub, max_retries=5):
    retries = 0
    while retries < max_retries:
        try:
            timestamp = Timestamp(timestamp=0)
            for data in stub.StreamBlocks(timestamp):
                yield data
        except grpc.RpcError as e:
            retries += 1
            time.sleep(2 ** retries)
    raise Exception("Max retries exceeded")

3. Data Processing​

Process JSON data efficiently:

// Use streaming JSON parser for large datasets
const JSONStream = require('jsonstream');

stream.on('data', (chunk) => {
    const parser = JSONStream.parse('*');
    parser.on('data', (data) => {
        // Process individual JSON objects
        processOrderBook(data);
    });
    parser.write(chunk.data);
});

Proto File Package Information​

syntax = "proto3";

package hyperliquid_l1_gateway.v1;
option go_package = "internal/api";

When generating client code, use the appropriate package name for your language:

  • Go: internal/api
  • Python: hyperliquid_l1_gateway.v1
  • Node.js: hyperliquid_l1_gateway.v1

Resources & Support​

Developer Resources​

  • Proto definition files available upon request
  • Testing binary (16MB Go application) available for streaming verification
  • Integration examples and best practices

Need Help?​

Start building on HyperLiquid with Dwellir's enterprise-grade gRPC infrastructure. Get your free API key →