Skip to content

README.md

Latest commit

 

History

History
260 lines (186 loc) · 7.06 KB

README.md

File metadata and controls

260 lines (186 loc) · 7.06 KB

Hyperliquid gRPC Examples

gRPC streaming examples for Hyperliquid with zstd compression support.

Languages

  • JavaScript - Node.js with @grpc/grpc-js
  • Python - grpcio with zstandard
  • Go - google.golang.org/grpc with klauspost/compress
  • Rust - tonic with zstd

Proto Files

The raw stream proto definition is in proto/hyperliquid.proto.

The dedicated orderbook streaming proto definition is in proto/orderbook.proto. See Orderbook Streaming for runnable examples using your QuickNode endpoint.

Networks

Both mainnet and testnet are supported. Set your GRPC_ENDPOINT accordingly:

Network Endpoint Format
Mainnet your-endpoint.hype-mainnet.quiknode.pro:10000
Testnet your-endpoint.hype-testnet.quiknode.pro:10000

All stream types are available on both networks, except MEMPOOL_TXS which is testnet-only.

Stream Types

Type Description Networks
TRADES Trade executions Mainnet, Testnet
ORDERS Order updates Mainnet, Testnet
EVENTS General events Mainnet, Testnet
BOOK_UPDATES Order book changes Mainnet, Testnet
TWAP TWAP orders Mainnet, Testnet
BLOCKS Raw blocks Mainnet, Testnet
WRITER_ACTIONS Writer actions Mainnet, Testnet
MEMPOOL_TXS Testnet mempool transactions, including priority order submissions Testnet only

Orderbook Streaming Methods

The hyperliquid.OrderBookStreaming service exposes full-book streams plus lower-bandwidth derived streams:

Method Description
StreamL2Book Existing full aggregated L2 snapshots for one coin
StreamL4Book Existing full L4 snapshot for one coin, then raw JSON diffs
StreamBboBook New best bid/offer updates for one or more coins
StreamL2BookDiff New incremental L2 price-level changes
StreamL4BookUpdates New typed L4 order-level changes
StreamTpslUpdates New typed TP/SL trigger-order lifecycle changes

Run BBO with your hosted QuickNode endpoint:

cd javascript/orderbookStreamExample
npm install

export GRPC_ENDPOINT="your-endpoint.hype-mainnet.quiknode.pro:10000"
export AUTH_TOKEN="YOUR_QUICKNODE_TOKEN"

node orderbook_stream_example.js --mode=bbo --coin=BTC --max-messages=5

Testnet Priority Mempool

Priority transactions can be observed on the testnet-only MEMPOOL_TXS stream. Each priority example starts a gRPC watcher against your QuickNode testnet endpoint and prints mempool payloads that contain priority grouping.

cd python/priorityOrderExample
pip install -r requirements.txt
python -m grpc_tools.protoc -I../../proto --python_out=. --grpc_python_out=. ../../proto/hyperliquid.proto

export GRPC_ENDPOINT="your-endpoint.hype-testnet.quiknode.pro:10000"
export AUTH_TOKEN="YOUR_QUICKNODE_TOKEN"

python watch_priority_mempool.py --max-messages 5

Priority examples are available in:

  • javascript/priorityOrderExample/
  • python/priorityOrderExample/
  • golang/priorityOrderExample/
  • rust/src/priorityOrderExample/

Filtering

Each language includes a dedicated filter_example file demonstrating server-side filtering.

Filter Example Files

# JavaScript
node filter_example.js

# Python
python filter_example.py

# Go
go run filter_example.go

# Rust
cargo run --bin filter_example

How Filters Work

Filters are applied server-side via the filters field in the subscription request:

// JavaScript example
call.write({
  subscribe: {
    stream_type: 'TRADES',
    filters: {
      coin: { values: ['ETH', 'BTC'] },
      user: { values: ['0x123...'] }
    },
    filter_name: 'my-filter'
  }
});

CLI Filtering (main examples)

The main examples also support filtering via command line:

# JavaScript
node index.js TRADES --filter coin=ETH,BTC --filter user=0x123

# Python
python main.py TRADES --filter coin=ETH,BTC

# Go
go run main.go -stream TRADES -filter "coin=ETH,BTC;user=0x123"

# Rust
cargo run --bin main -- -s TRADES -f coin=ETH,BTC -f user=0x123

Quick Start

JavaScript

cd javascript
npm install
# Edit index.js to set GRPC_ENDPOINT and AUTH_TOKEN
node index.js TRADES

Python

cd python
pip install -r requirements.txt
./generate_proto.sh
# Edit main.py to set GRPC_ENDPOINT and AUTH_TOKEN
python main.py TRADES

Go

cd golang
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
./generate_proto.sh
go mod tidy
# Edit main.go to set grpcEndpoint and authToken
go run main.go -stream TRADES

Rust

cd rust
# Edit src/main.rs to set GRPC_ENDPOINT and AUTH_TOKEN
cargo run -- -s TRADES

Configuration

Each example requires:

  1. GRPC_ENDPOINT - Your QuickNode endpoint (e.g., your-endpoint.hype-mainnet.quiknode.pro:10000 or your-endpoint.hype-testnet.quiknode.pro:10000)
  2. AUTH_TOKEN - Your authentication token

Connection Requirements

  • Port: 10000 (gRPC streaming port)
  • TLS: Required - all connections must use TLS/SSL
  • Authentication: Pass your token via the x-token metadata header

Zstd Compression

All examples automatically detect and decompress zstd-compressed data by checking for the magic number 0x28 0xB5 0x2F 0xFD.

Connection Management

gRPC streams are long-lived connections that can disconnect due to network issues, server restarts, or idle timeouts. Production systems should implement proper connection management.

Keep-Alive Pings

The server expects periodic pings to keep the connection alive. The examples send pings every 30 seconds:

// JavaScript
setInterval(() => {
  call.write({ ping: { timestamp: Date.now() } });
}, 30000);
# Python
yield pb.SubscribeRequest(ping=pb.Ping(timestamp=int(time.time() * 1000)))

The server responds with a pong message. If you stop receiving pongs, the connection may be dead.

Reconnection Strategy

When a disconnect occurs, implement exponential backoff:

Attempt 1: Wait 1s
Attempt 2: Wait 2s
Attempt 3: Wait 4s
Attempt 4: Wait 8s
...
Max backoff: 60s

Handling Missed Blocks

When your connection drops, you'll miss blocks. On reconnect:

  1. Track the last block_number you received
  2. Reconnect with start_block set to resume from where you left off
  3. For the BLOCKS stream specifically, historical data isn't available via gRPC - see the replicaCmdsOnS3Example for backfilling from the Hyperliquid Foundation S3 bucket

Example Reconnect Flow

1. Connect to gRPC stream
2. Subscribe with start_block=0 (or last known block)
3. Process incoming data, track last block_number
4. Send pings every 30s
5. On disconnect:
   - Log last block_number received
   - Wait with exponential backoff
   - Reconnect and subscribe with start_block=last_block_number
6. Repeat

Note: These examples are starting points. Production systems should add error handling, metrics, circuit breakers, and dead letter queues based on your reliability requirements.