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

syntax = "proto3";

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

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 BlockFills starting from timestamp
  rpc StreamBlockFills(Timestamp) returns (stream BlockFills) {};
}

message Timestamp {   
  int64 timestamp = 1;
} 

message Block {
  // JSON-encoded object conforming to files of HyperLiquid data dir "replica_cmds"
  bytes data = 1;
}

message OrderBookSnapshot {
  // JSON-encoded object conforming to a HyperLiquid order book snapshot
  bytes data = 1;
}

message BlockFills {
  // JSON-encoded object conforming to files of HyperLiquid data dir "node_fills"
  bytes data = 1;
}

Message Types

Timestamp

message Timestamp {   
  int64 timestamp = 1;
} 

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

Block

message Block {
  // JSON-encoded object conforming to files of 
  // Hyperliquid data dir "replica_cmds"
  bytes data = 1;
}

The data field contains a JSON-encoded object with block information.

OrderBookSnapshot

message OrderBookSnapshot {
  // JSON-encoded object conforming to a 
  // Hyperliquid order book snapshot
  bytes data = 1;
}

The data field contains a complete order book snapshot in JSON format.

BlockTrades

message BlockTrades {
  // JSON-encoded object conforming to files of 
  // Hyperliquid data dir "node_trades"
  bytes data = 1;
}

The data field contains trade data for a specific block.

BlockFills

message BlockFills {
  // JSON-encoded object conforming to files of 
  // Hyperliquid data dir "node_fills"
  bytes data = 1;
}

The data field contains fill data for executed orders.

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. StreamBlockTrades

Stream trade data as blocks are produced.

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

4. StreamBlockFills

Stream fill data for executed orders.

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

Implementation Examples

Go

package main

import (
    "context"
    "log"
    "os"

    pb "your-project/hyperliquid_l1_gateway/v1"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

func main() {
    endpoint := os.Getenv("HYPERLIQUID_ENDPOINT")
    apiKey := os.Getenv("API_KEY")

    // Set up TLS credentials
    creds := credentials.NewTLS(nil)

    // Connect with TLS
    conn, err := grpc.NewClient(endpoint, grpc.WithTransportCredentials(creds))
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()

    client := pb.NewHyperLiquidL1GatewayClient(conn)

    // Add API key to context
    ctx := metadata.AppendToOutgoingContext(context.Background(), "x-api-key", apiKey)

    // Stream blocks
    stream, err := client.StreamBlocks(ctx, &pb.Timestamp{Timestamp: 0})
    if err != nil {
        log.Fatalf("Failed to stream: %v", err)
    }

    for {
        block, err := stream.Recv()
        if err != nil {
            log.Fatalf("Stream error: %v", err)
        }

        // Process JSON data
        log.Printf("Received block: %s", block.Data)
    }
}

Python

import grpc
import json
import os
from dotenv import load_dotenv
import hyperliquid_pb2
import hyperliquid_pb2_grpc

# Load environment variables
load_dotenv()

def stream_blocks():
    endpoint = os.getenv('HYPERLIQUID_ENDPOINT')
    api_key = os.getenv('API_KEY')

    # Create SSL credentials
    credentials = grpc.ssl_channel_credentials()

    # Create secure channel with API key metadata
    metadata = [('x-api-key', api_key)]

    with grpc.secure_channel(endpoint, credentials) as channel:
        client = hyperliquid_pb2_grpc.HyperLiquidL1GatewayStub(channel)

        # Start streaming from now
        request = hyperliquid_pb2.Timestamp(timestamp=0)

        # Stream blocks
        for block in client.StreamBlocks(request, metadata=metadata):
            # Parse JSON data
            data = json.loads(block.data)
            print(f"Block update: {data}")

if __name__ == '__main__':
    stream_blocks()

Node.js

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
require('dotenv').config();

// Load proto file
const packageDefinition = protoLoader.loadSync(
    'hyperliquid.proto',
    {
        keepCase: true,
        longs: String,
        enums: String,
        defaults: true,
        oneofs: true
    }
);

const proto = grpc.loadPackageDefinition(packageDefinition);

// Load environment variables
const endpoint = process.env.HYPERLIQUID_ENDPOINT;
const apiKey = process.env.API_KEY;

// Create metadata with API key
const metadata = new grpc.Metadata();
metadata.add('x-api-key', apiKey);

// Create client with SSL credentials
const client = new proto.hyperliquid_l1_gateway.v1.HyperLiquidL1Gateway(
    endpoint,
    grpc.credentials.createSsl()
);

// Stream blocks with metadata
const stream = client.StreamBlocks({ timestamp: 0 }, metadata);

stream.on('data', (block) => {
    const data = JSON.parse(block.data.toString());
    console.log('Block received:', data);
});

stream.on('error', (err) => {
    console.error('Stream error:', err);
});

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 with TLS
func connectWithRetry(addr string, maxRetries int) (*grpc.ClientConn, error) {
    var conn *grpc.ClientConn
    var err error

    creds := credentials.NewTLS(nil)

    for i := 0; i < maxRetries; i++ {
        conn, err = grpc.NewClient(addr, grpc.WithTransportCredentials(creds))
        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?

• 📧 Email: support@dwellir.com
• 📚 Documentation: You're here!
• 🎯 Dashboard: dashboard.dwellir.com
• 🔧 Testing Tool: Contact support for the Go testing binary

---

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