Hyperliquid gRPC 示例

语言

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

Proto 文件

原始数据流的 proto 定义在 proto/hyperliquid.proto 中。

专用订单簿数据流的 proto 定义在 proto/orderbook.proto 中。有关使用 QuickNode 端点运行的可执行示例，请参阅 订单簿流。

网络

支持 主网 和 测试网。请相应设置你的 GRPC_ENDPOINT：

以下所有流类型在主网和测试网上均可用。端点决定你接收哪个网络的节点数据。

流类型

订单簿流方法

hyperliquid.OrderBookStreaming 服务提供全量订单簿流以及较低带宽的派生流：

当 ALO 优先级费用改变队列位置时，L4 流会保持订单簿的正确排序。 公共响应模式不变：StreamL4Book 发送一个权威的替换快照，StreamL4BookUpdates 发送一个带有 snapshot=true 的更新。当任意一个流发送快照时（不仅仅是在初始订阅时），客户端都必须清除并重建本地状态。参见 L4 ALO 队列优先级。

使用你的托管 QuickNode 端点运行 BBO：

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

优先级流

ORDER_PRIORITY 和 GOSSIP_PRIORITY 在主网和测试网上均可用。ORDER_PRIORITY 允许客户通过 cloid、user、tx_hash、coin 和 source 等字段过滤优先级订单。GOSSIP_PRIORITY 允许客户通过 user、tx_hash、ip、slot_id 和 source 过滤竞价操作。

这些示例默认使用 source=mempool_txs，因此其输出是共识前的，尚未最终确定。对于 IOC 订单，这是试图在 mempool 排序中超越其他相似时间订单的订单视图。GOSSIP_PRIORITY 揭示 gossipPriorityBid 操作；它不衡量连接是否更快地接收数据。

使用 --include-confirmed 也可接收已确认的 source=replica_cmds 订单优先级事件，或使用 --raw-mempool 检查原始 MEMPOOL_TXS 负载。参见 优先级流 了解可搜索字段、负载和特定网络的费用行为。

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-mainnet.quiknode.pro:10000"
export AUTH_TOKEN="YOUR_QUICKNODE_TOKEN"

python watch_priority_mempool.py --max-messages 5

优先级示例位于以下目录中：

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

原始 Mempool 币种过滤

MEMPOOL_TXS 支持虚拟服务器端字段 coin 和 coins。原始 mempool 负载包含数字资产 ID，因此服务器会动态解析当前币种名称，并在任何涉及订单的操作使用所请求的资产时匹配该交易。响应仍然是原始的 JSON 元组或对象，不会被替换为规范化事件。

专用示例默认使用 coin=BTC，并独立验证每个返回的原始交易中的资产 ID 0：

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

## JavaScript
node javascript/mempoolFilterExample/mempool_filter_example.js --max-messages=5

## Python
python3 python/mempoolFilterExample/mempool_filter_example.py --max-messages 5

## Go
(cd golang && go run ./mempoolFilterExample -max-messages 5)

## Rust
(cd rust && cargo run --bin mempool_filter_example -- --max-messages 5)

过滤范围包括 order、cancel、cancelByCloid、batchModify、modify、twapOrder 和 twapCancel。参见 Mempool 过滤 了解语义、可见的 30 秒 Ping/Pong 心跳、不匹配的控制、原始输出和单元测试命令。

过滤

每种语言都包含一个专用的 filter_example 文件，用于演示服务器端过滤。

过滤示例文件

## JavaScript
node filter_example.js

## Python
python filter_example.py

## Go
go run filter_example.go

## Rust
cargo run --bin filter_example

过滤器工作原理

过滤器通过订阅请求中的 filters 字段在服务器端应用。

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

命令行过滤（主示例）

主示例也支持通过命令行过滤：

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

快速开始

JavaScript

cd javascript
npm install
## 编辑 index.js 以设置 GRPC_ENDPOINT 和 AUTH_TOKEN
node index.js TRADES

Python

cd python
pip install -r requirements.txt
./generate_proto.sh
## 编辑 main.py 以设置 GRPC_ENDPOINT 和 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
## 编辑 main.go 以设置 grpcEndpoint 和 authToken
go run main.go -stream TRADES

Rust

cd rust
## 编辑 src/main.rs 以设置 GRPC_ENDPOINT 和 AUTH_TOKEN
cargo run -- -s TRADES

配置

每个示例都需要：

1. GRPC_ENDPOINT - 你的 QuickNode 端点（例如 your-endpoint.hype-mainnet.quiknode.pro:10000 或 your-endpoint.hype-testnet.quiknode.pro:10000）
2. AUTH_TOKEN - 你的身份验证Token

连接要求

• 端口：10000（gRPC 流端口）
• TLS：必需 - 所有连接必须使用 TLS/SSL
• 认证：通过 x-token 元数据标头传递你的Token

Zstd 压缩

所有示例通过检查幻数 0x28 0xB5 0x2F 0xFD 自动检测并解压 zstd 压缩的数据。

连接管理

gRPC 流是长期存在的连接，可能因网络问题、服务器重启或空闲超时而断开。生产系统应实施适当的连接管理。

保活 Ping

服务器期望定期发送 ping 以保持连接存活。示例每 30 秒发送一次 ping：

// JavaScript
setInterval(() => {
  call.write({ ping: { timestamp: Date.now() } });
}, 30000);

## Python
yield pb.SubscribeRequest(ping=pb.Ping(timestamp=int(time.time() * 1000)))

服务器会响应一条 pong 消息。如果你停止接收 pong，则连接可能已断开。

重连策略

当断开连接时，实施指数退避：

尝试 1：等待 1 秒
尝试 2：等待 2 秒
尝试 3：等待 4 秒
尝试 4：等待 8 秒
...
最大退避：60 秒

处理错过的区块

当连接断开时，你会错过一些区块。重新连接时：

1. 记录你收到的最后一个 block_number
2. 将 start_block 设置为从上次中断的位置继续
3. 对于 BLOCKS 流，历史数据无法通过 gRPC 获取——请参阅 replicaCmdsOnS3Example，以从 Hyperliquid 基金会 S3 存储桶回溯填充

示例重连流程

1. 连接到 gRPC 流
2. 使用 start_block=0（或上一个已知区块）订阅
3. 处理传入数据，跟踪最后的 block_number
4. 每 30 秒发送一次 ping
5. 断开时：
   - 记录收到的最后一个 block_number
   - 以指数退避方式等待
   - 重新连接并使用 start_block=last_block_number 订阅
6. 重复

注意： 这些示例是起点。生产系统应根据你的可靠性要求添加错误处理、指标、断路器和死信队列。

• 原文链接： github.com/quiknode-labs...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～