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"
    
    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 blocks
    stream, err := client.StreamBlocks(
        context.Background(),
        &pb.Timestamp{Timestamp: 0}, // Start from now
    )
    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
from hyperliquid_l1_gateway_pb2 import Timestamp
from hyperliquid_l1_gateway_pb2_grpc import HyperliquidL1GatewayStub

def stream_blocks():
    # Create gRPC channel
    channel = grpc.insecure_channel(
        '<YOUR_HYPERLIQUID_ENDPOINT>'  # Contact support@dwellir.com
    )
    stub = HyperliquidL1GatewayStub(channel)
    
    # Start streaming from now
    timestamp = Timestamp(timestamp=0)
    
    # Stream blocks
    for block in stub.StreamBlocks(timestamp):
        # 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');

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

const proto = grpc.loadPackageDefinition(packageDefinition);
const client = new proto.hyperliquid_l1_gateway.v1.HyperliquidL1Gateway(
    '<YOUR_HYPERLIQUID_ENDPOINT>', // Contact support@dwellir.com
    grpc.credentials.createInsecure()
);

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

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

• 📧 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 →