Overview

Hyperliquid gRPC is a high-performance streaming API that enables real-time blockchain data access through gRPC interfaces. It serves as a powerful tool for developers who need to:

• Stream blockchain data in real-time
• Monitor on-chain activities (trades, orders, liquidations, funding events)
• Query HyperCore blockchain states efficiently
• Track TWAP executions and order book changes with minimal latency

The API provides enterprise-grade reliability with granular control over data streams, supporting both HyperCore and HyperEVM data.

Plan Requirement

Please note that to access Hyperliquid's JSON-RPC API, WebSocket (WSS), and gRPC streaming, you need a Quicknode Build plan or higher. View pricing to upgrade.

Protocol Buffers and gRPC

Hyperliquid gRPC uses Protocol Buffers (protobuf) as its interface definition language and data serialization format. Protocol Buffers are Google's language-neutral, platform-neutral mechanism for serializing structured data.

Why Proto Files?

Proto files (.proto files) serve as the contract between client and server, defining:

• Data structures - The exact format of messages exchanged (fields, types, required vs optional)
• Service methods - Available RPC calls and their request/response types
• Type safety - Compile-time validation ensuring data correctness
• Versioning - Built-in backward compatibility as APIs evolve

Why gRPC Uses Proto Files

1. Language-Agnostic - Write the proto definition once, generate client libraries for 10+ languages (Go, Python, JavaScript, Java, C++, etc.). The same proto file works across all platforms.
2. High Performance - Binary serialization is significantly faster and smaller than JSON. Protobuf messages are typically 3-10x smaller than equivalent JSON, reducing bandwidth and improving latency.
3. Strong Typing - Proto definitions enforce strict types at compile time, catching errors before runtime. Field types, message structures, and enums are validated automatically.
4. Code Generation - The protoc compiler automatically generates client stubs, server interfaces, and message classes from proto files. This eliminates manual serialization code and reduces bugs.
5. Schema Evolution - Proto files support backward and forward compatibility through field numbering. You can add new fields without breaking existing clients, enabling seamless API updates.
6. Streaming Support - Proto definitions natively support unary, server streaming, client streaming, and bidirectional streaming patterns, which Hyperliquid uses extensively for real-time data.

Using Proto Files with Hyperliquid

When working with Hyperliquid gRPC, you'll download the proto files and use them to generate client code. Hyperliquid provides two proto files for different services:

1. streaming.proto - Core blockchain streaming services:

• Ping - Connection health checks
• StreamBlocks - Raw blockchain data streaming
• StreamData - Multi-stream data subscriptions (trades, orders, events, etc.)

2. orderbook.proto - Orderbook streaming services:

• StreamL2Book - Aggregated price level data
• StreamL4Book - Individual order-level data

# Example: Generate Go client from proto files
protoc --go_out=. --go-grpc_out=. streaming.proto
protoc --go_out=. --go-grpc_out=. orderbook.proto

The generated code provides type-safe methods like:

// Type-safe subscription with auto-complete
const request = new Subscribe({
  stream_type: StreamType.TRADES,
  filters: {
    coin: { values: ['BTC', 'ETH'] }
  }
});

All setup guides in the next sections include instructions for downloading proto files and generating client code for your language.

Access

To access Hyperliquid gRPC, you need to have a Quicknode endpoint with gRPC streaming enabled.

Endpoint and Token Configuration

Hyperliquid gRPC operates on port 10000. This is a dedicated secure port for gRPC communication and is separate from the standard Hyperliquid RPC endpoint. When connecting to the service the port must be specified in the URL:

• Endpoint: The name of your gRPC-enabled endpoint followed by .hype-mainnet.quiknode.pro and the port number 10000 (e.g., https://example-guide-demo.hype-mainnet.quiknode.pro:10000)
• Token: Your API key that can be generated from the Quicknode Dashboard Endpoint Security tab.

Given the following example HTTP Provider URL: https://example-guide-demo.hype-mainnet.quiknode.pro/abc123def456/, your authentication credentials would be:

• Endpoint: https://example-guide-demo.hype-mainnet.quiknode.pro:10000
• Token: abc123def456

Here is a sample for using this endpoint to connect with Node.js:

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
// For HTTP Provider URL: https://example-guide-demo.hype-mainnet.quiknode.pro/abc123def456/
const ENDPOINT = 'example-guide-demo.hype-mainnet.quiknode.pro:10000';
const TOKEN = 'abc123def456';

const client = new hyperliquid.Hyperliquid(ENDPOINT, credentials);
const metadata = new grpc.Metadata();
metadata.add('x-token', TOKEN);

Metered Data Pricing

All Hyperliquid gRPC methods are metered based on data consumption:

• Standard methods (Ping, StreamBlocks, StreamData): 0.1 MB = 10 API credits
• OrderBook methods (StreamL2Book, StreamL4Book): 0.0165 MB = 10 API credits

Available gRPC Methods

Hyperliquid provides the following gRPC streaming methods:

Core Streaming Methods (streaming.proto)

• Ping - Test connectivity and keep connections alive
• StreamBlocks - Stream raw HyperCore blockchain data
• StreamData - Bidirectional streaming for trades, orders, events, and more

Orderbook Streaming Methods (orderbook.proto)

• StreamL2Book - Stream aggregated orderbook with configurable price levels (L2 data)
• StreamL4Book - Stream individual order data with full snapshots and incremental diffs (L4 data)

StreamData Stream Types

The StreamData method supports the following stream types for real-time blockchain data:

Stream Type	Description	Primary Use Case
TRADES	All executed trades with price, size, and direction	Trading analytics, price tracking
ORDERS	Order lifecycle events (18+ status types including fills, cancellations)	Order management, execution monitoring
BOOK_UPDATES	Order book changes (Level 2 data)	Market depth analysis, liquidity monitoring
TWAP	TWAP execution data and algorithm progress	Algorithmic trading, execution analytics
EVENTS	System events (funding, liquidations, governance)	Risk management, system monitoring
BLOCKS	Raw HyperCore blockchain data (all transaction types)	Blockchain analysis, data archiving
WRITER_ACTIONS	System operations for spot token transfers	Cross-environment asset tracking, system monitoring

Stream Filtering

All Hyperliquid gRPC streams support powerful filtering capabilities to help you receive only the data you need. Filters allow you to focus on specific trading pairs, users, event types, and more, significantly reducing bandwidth and improving performance.

Example gRPC filter:

Subscribe {
  stream_type: TRADES,
  filters: {
    "coin": FilterValues { values: ["BTC", "ETH"] },
    "side": FilterValues { values: ["B"] }
  }
}

Complete Filtering Guide - Detailed documentation with syntax, examples, and field references for all stream types.

Making Hyperliquid gRPC Requests

Core Streaming API Setup

To make requests to the core streaming API (StreamData, StreamBlocks, Ping) using different languages:

• Go
• Node.js
• Python

OrderBook Streaming API Setup

To stream L2/L4 orderbook data (StreamL2Book, StreamL4Book):

• Go OrderBook Setup - Complete guide with step-by-step instructions from project setup to sending requests
• Python OrderBook Setup - Complete guide with step-by-step instructions from project setup to sending requests
• Node.js OrderBook Setup - Complete guide with step-by-step instructions from project setup to sending requests

We ❤️ Feedback!

If you have any feedback or questions about this documentation, let us know. We'd love to hear from you!