Hyperliquid L1、L2、L3 和 L4 订单簿层级

概述

大多数订单簿视图展示的是压缩后的市场形态。最佳买一价和最佳卖一价的报价器隐藏了这些价格背后的深度，而聚合的深度图则隐藏了构成每个价位的单个订单。Hyperliquid 底层 HyperCore 订单簿包含更多结构，包括单个挂单和匿名参与者地址。

在本指南中，我们将在四种市场数据分辨率下考察同一个 Hyperliquid 主网订单簿。我们将把每种分辨率映射到 Quicknode 的 Hyperliquid gRPC 方法，运行维护的公开订单簿示例，从 L4 数据推导出匿名 L3 视图，并理解 L4 订单如何聚合为 L2 价位。

注意

本指南中的术语 L1、L2、L3 和 L4 描述的是市场数据分辨率。它们并不指代 Hyperliquid 区块链或协议的四个层级。

TLDR

• L1 显示最佳买一价和最佳卖一价。通过 StreamBboBook 订阅。
• L2 显示聚合的价格层级深度，包含价格、总数量和订单数量。通过 StreamL2Book 订阅。
• L3 显示无钱包归属的单个订单。从 L4 数据推导匿名 L3 视图，因为不存在 StreamL3Book 方法。
• L4 显示带有匿名钱包归属的单个订单。使用 StreamL4BookUpdates 获取类型化状态变更，或使用 StreamL4Book 获取更完整的订单及生命周期详情。

你将学到什么

• L1、L2、L3 和 L4 分别揭示和隐藏了什么
• 哪种 Quicknode gRPC 方法适合每种订单簿使用场景
• 精确与分桶的 L2 深度如何改变流动性测量
• 如何维护 L4 状态并移除钱包归属以获取 L3
• 市场标识符和价格-时间优先级如何影响订单簿订阅

你需要准备

• 具备 gRPC 访问权限的 Quicknode Hyperliquid 主网端点（开始前请查看最新的 Hyperliquid 计划访问文档）
• Hyperliquid Orderbook Peel，本指南全程使用的交互式可视化辅助工具（可选）
• Node.js 20.6 或更高版本，以及 npm，用于运行包含 .env 文件的 JavaScript 示例
• 基础的 JavaScript 或 TypeScript、gRPC 及中央限价订单簿知识

一个订单簿，四种分辨率

每个层级回答不同的市场数据问题。更高分辨率增加细节，但也增加了数据负载和客户端状态维护需求。

L1 和 L2 聚合信息。如果三个买单以完全相同的价格挂单，L2 会报告一行，包含它们的 sz 总和及 n: 3。L3 将该行拆分为三个匿名订单。L4 添加每个订单的匿名所有者地址，并在更完整的流中提供更多订单元数据。

选择正确的 Hyperliquid 数据流

Quicknode 通过 OrderBookStreaming gRPC 服务提供了四种相关方法。正确的方法取决于你是需要自包含的消息还是本地维护的订单映射。

StreamBboBook 和 StreamL2Book 消息是自包含的，因此你的应用程序可以用每条有效消息替换之前的视图。两种 L4 方法在快照之间都是有状态的。对于 StreamL4BookUpdates，当 snapshot 为 true 时清除受影响的订单簿，然后将后续类型化 diff 应用到以 oid 为键的映射中。对于 StreamL4Book，将每个 L4BookSnapshot 视为权威替换，然后将每个后续的 L4BookDiff 应用到该本地状态。单个 L4 diff 并不代表完整的订单簿。

不存在单独的 StreamL3Book 方法。要生成 L3，需要从 L4 方法维护单个订单映射，然后在输出中省略 user 字段及任何基于钱包的分组。

使用 Peel 和 gRPC 比较 Hyperliquid 订单簿层级

从 Hyperliquid Orderbook Peel 开始，这是一个交互式解说工具，允许你通过滑块在 L1 和 L4 之间移动同一个订单簿。它使分辨率的变化清晰可见：L1 只保留最佳买一价和最佳卖一价，L2 聚合每个价格层级，L3 暴露匿名的单个订单，L4 添加匿名钱包归属。以下章节的截图展示了这些视图。

Quicknode 还维护了 HyperCore gRPC 示例仓库，这是使用 JavaScript、Python、Go 或 Rust 构建 Hyperliquid 流式客户端的实用参考。它涵盖了端点配置、protobuf 定义、zstd 压缩、保活、重连以及主网或测试网使用。除了订单簿示例，该仓库还包括交易、订单、事件、区块、优先流和服务器端过滤的示例。

对于本指南，JavaScript 订单簿示例是重点起点。它允许你针对实时数据检查 BBO、完整 L2 快照、完整 L4 快照和 diff，以及类型化 L4 更新。

以下命令使用 JavaScript，但仓库也包含等价的 Python、Go 和 Rust 实现。仓库 README 涵盖了连接设置、压缩和连接管理。订单簿示例的 README 列出了其支持的模式和标志。

TypeScript 应用程序可以使用相同的 protobuf 方法和消息字段，配合生成类型或 @grpc/proto-loader。你可以在 orderbook_stream_example.js 中查看完整的 JavaScript 实现。

准备 JavaScript 订单簿示例

克隆仓库，进入 JavaScript 订单簿示例目录，并安装依赖：

1
2
3
git clone https://github.com/quiknode-labs/hypercore-grpc-examples.git
cd hypercore-grpc-examples/javascript/orderbookStreamExample
npm install

在示例目录中创建 .env 文件，用于存放 gRPC 主机名和Token。端点使用端口 10000，不包含 https:// 或Token路径：

1
2
GRPC_ENDPOINT=your-endpoint-name.hype-mainnet.quiknode.pro:10000
AUTH_TOKEN=your-token

在 Quicknode Hyperliquid 端点仪表盘中查找确切的 gRPC 主机名和认证Token。Node 的 --env-file=.env 选项将这些值加载到示例中。脚本通过 x-token gRPC 元数据头发送 AUTH_TOKEN。将 .env 添加到 .gitignore，不要提交或打印你的Token。

使用正确的市场标识符

以下示例使用 BTC。将其替换为你想要检查的市场标识符：

将完整标识符传递给 --coin。

保持演示范围有限

默认情况下，公开示例会打开长时间运行的流。在测试时，尤其是在 L4 中，添加 --max-messages=<N>，以便进程在接收到指定数量的消息后停止。

Hyperliquid L1：读取最佳买一价和最佳卖一价

Peel 的 L1 视图只留下最佳买一价和最佳卖一价——订单簿每一侧的最前端。

运行 BBO 模式，接收一条消息后停止：

1
node --env-file=.env orderbook_stream_example.js --mode=bbo --coin=BTC --max-messages=1

第一条有效的 BboBookUpdate 会产生类似这样的简洁输出：

1
[1] BBO BTC block=<区块号> bid=<价格> / <数量> (<订单数>) ask=<价格> / <数量> (<订单数>)

StreamBboBook 返回当前最佳买一价和最佳卖一价，而非完整的订单簿。它在最佳层级发生变化时（包括同一价格下数量变化）触发，而不是每个区块发送一次快照。一个订阅可以覆盖多个币种，每条消息会标识变化的币种。

当订单簿某一边为空时，bid 或 ask 可能不存在。示例中将缺失的一边格式化为 n/a。

当你需要实时的顶部价格、价差或参考线时选择 L1。它不会告诉你远离价差的流动性情况。

Hyperliquid L2：读取聚合的市场深度

Peel 的 L2 视图将每个价格层级转化为一个柱状，显示聚合的供需，同时隐藏构成每个柱状的单个订单。

运行 L2 模式，每边精确显示 10 个价格层级，接收一个快照后停止：

1
node --env-file=.env orderbook_stream_example.js --mode=l2 --coin=BTC --levels=10 --max-messages=1

示例会打印每一边的最佳层级以及返回的买卖层级数量：

1
[1] L2 BTC block=<区块号> bid=<价格> / <数量> (<订单数>) ask=<价格> / <数量> (<订单数>) bids=<买方层级数> asks=<卖方层级数>

每个 StreamL2Book 消息是单个币种在一个区块上的完整快照。买单按从高到低的价格排列，卖单按从低到高的价格排列。每个 L2Level 包含：

请求控制流对订单簿进行分组的方式和精度：

• n_levels 限制每边返回的价格层级数量。
• 省略 n_sig_figs 返回精确的价格层级。
• n_sig_figs 控制用于价格分桶的有效数字位数。
• mantissa 接受 1、2 或 5，并调整所选有效数字精度下的桶宽度。

要比较分桶后的深度，使用相同的模式并添加 --sig-figs 和 --mantissa：

1
node --env-file=.env orderbook_stream_example.js --mode=l2 --coin=BTC --levels=10 --sig-figs=3 --mantissa=1 --max-messages=1

多个精确价格的订单可能会合并到一个更宽的桶中。

当你需要深度图、滑点模型和价格层级流动性分析时选择 L2。当每个层级内的构成重要时，使用 L4。

Hyperliquid L3：推导匿名单个订单

Peel 的 L3 视图将每个价格层级拆分为单个订单，同时保持所有者匿名。

没有 L3 模式，因为不存在 L3 方法。从一条类型化的 L4 更新消息开始：

1
node --env-file=.env orderbook_stream_example.js --mode=l4-updates --coin=BTC --max-messages=1

第一条类型化的 L4 消息包含 snapshot: true，并以 NEW diff 的形式表示当前的单个订单：

1
2
3
[1] L4 updates height=<区块高度> snapshot=true diffs=<订单数>
  在应用此更新之前，清除本地 L4 订单状态
  L4_ORDER_DIFF_TYPE_NEW BTC oid=<订单ID> side=B px=<价格> sz=<单个数量>

要推导 L3，当 snapshot 为 true 时清除本地订单映射，然后按 oid 应用后续的 NEW、UPDATE 和 REMOVE diff，并暴露每个订单的价格、数量和方向，但不暴露 user。不要按钱包对订单进行着色、分组或标记。你的应用程序可以在内部保留 oid 作为稳定的映射键，而不用于标识参与者。

此工作流从 L4 数据推导出匿名的 L3 视图。它并非 L3 订阅，因为 gRPC 服务没有 StreamL3Book 方法。

Hyperliquid L4：读取带有钱包归属的订单

Peel 的 L4 视图保留单个订单，并在订单详情中暴露匿名的钱包归属。

运行完整的 L4 方法，在接收到快照及一条后续消息后停止：

1
node --env-file=.env orderbook_stream_example.js --mode=l4 --coin=BTC --max-messages=2

示例会总结快照，而不打印完整的订单或钱包地址。如果第二条消息是 diff，输出如下：

1
2
[1] L4 snapshot BTC height=<区块高度> reset=initial bids=<买单订单数> asks=<卖单订单数>
[2] L4 diff height=<区块高度> order_statuses=<状态数> book_diffs=<diff数>

完整的快照对象包含每个订单的匿名 user 地址。如果你要显示它，请缩短地址，而不是在日志或截图中打印完整值。

StreamL4BookUpdates 使用三种类型化的 protobuf diff 表示订单变动：

类型化的 REMOVE 仅说明订单离开了当前订单簿。它不区分是成交还是撤销。

当你需要更完整的订单和生命周期细节时，使用 StreamL4Book。它的第一个 L4BookSnapshot 包含诸如 timestamp、触发信息、reduce_only、order_type、有效期 (tif) 和客户端订单 ID (cloid) 等字段。L4BookDiff 消息包含一个 data 字符串。将该字符串解析为 JSON，然后通过 oid 将 book_diffs 中的每个项目应用到你的本地映射。raw_book_diff 中的 new 表示添加或更新订单，remove 表示删除。

StreamL4Book 可以在常规 diff 之后发送另一个完整快照，包括当 ALO 优先费插入改变队列顺序时。公开示例将其标记为 reset=replacement。将每个替换快照视为权威：丢弃整个本地完整 L4 订单簿，按发出的顺序重建双方，然后从该替换状态继续。

当状态存在时，完整的 L4 方法可以将移除与订单状态关联起来。当生命周期原因重要时，你也可以将类型化的 L4 变更与 Orders 或 Trades 数据集进行关联。

user 字段是参与者地址，而非经过验证的真实世界身份。将其视为匿名钱包归属。

理解同一价格下的队列顺序

Hyperliquid 文档指出，其订单簿按照价格-时间优先级进行匹配。价格更优的订单在价格更差的订单之前执行。在给定价格下，较老的挂单优先于较新的挂单。

有一个重要例外。根据 Hyperliquid 的优先费规则，每个价格层级的最近尾部（约 400 毫秒）按优先费率降序排列。因此，该窗口内的较新订单可以排在较老订单之前。

使用 ORDER_PRIORITY 来观察标准化的优先费订单流。它是一个订单流数据流，而非订单簿。从 StreamL4Book 或 StreamL4BookUpdates 重建当前订单状态。当 StreamL4Book 发送初始或替换快照时，按发出的买卖顺序重建订单簿；该快照是同一价格下相对队列顺序的真相来源。

L4 不返回数字队列位置

API 不提供显式的 queue_position 字段或成交概率估计。不要对订单 ID 进行排序并将其视为队列优先级。价格-时间优先级是基线，但受近期优先费尾部例外影响。ORDER_PRIORITY 可以显示相关的优先费活动，但发出的 StreamL4Book 快照是当前队列顺序的真相来源。

结论

Hyperliquid 的 L1 到 L4 标签描述了同一个 HyperCore 订单簿的四种分辨率。L1 提供当前的最佳买一价和最佳卖一价。L2 提供完整的聚合深度快照。L3 是从 L4 推导出的匿名单个订单视图。L4 添加了匿名钱包归属，而完整的 L4 方法则提供更丰富的订单和生命周期字段。

现在你知道了如何运行 Quicknode 维护的 L1、L2 以及两种 L4 方法的订单簿示例，如何推导匿名 L3 视图，以及如何为永续合约、现货、HIP-3 和 HIP-4 市场选择标识符。选择能够回答你应用程序问题的最低分辨率，然后在使用 L4 流时维护本地状态。

下一步

• 查阅 Hyperliquid gRPC API 和 Hyperliquid 数据流 参考文档。
• 使用 JavaScript 订单簿示例 或等效的 Python、Go、Rust 实现。
• 通过 SQL Explorer 探索索引后的 Hyperliquid 订单、交易、成交和订单簿 diff。
• 浏览更多 Hyperliquid 指南 以了解相关项目和工作流。
• 在构建队列模型之前，阅读 Hyperliquid 的订单簿匹配规则。
• 如果你想交互式地探索这些订单簿层级，请查看 Hyperliquid Orderbook Peel。

常见问题

是否存在独立的 Hyperliquid L3 订单簿流？

不存在。OrderBookStreaming 服务不提供 StreamL3Book 方法。通过保留单个订单同时省略 user 字段和基于钱包的分组，从 L4 数据推导出匿名的 L3 视图。

StreamL4BookUpdates 和 StreamL4Book 有什么区别？

StreamL4BookUpdates 以类型化的复位快照开始，然后发送类型化的 NEW、UPDATE 和 REMOVE diff，这使得当前订单簿的维护变得简单。StreamL4Book 以更完整的快照开始，包含时间戳、触发数据、订单类型、有效期和其他字段，然后发送 JSON 编码的订单状态和订单簿 diff。

Hyperliquid L4 数据能否识别订单的真实所有者？

不能。user 字段是匿名参与者钱包地址。你可以按该地址对可见订单进行分组，但该字段不验证参与者的法律或现实世界身份。

每条 StreamL4Book 消息都是自包含的订单簿吗？

不是。每个 L4BookSnapshot 是完整、权威的订单簿，但每个 L4BookDiff 仅包含增量更改。每当快照到达时重建本地状态，然后按订单 ID 应用每个后续的订单簿 diff。

Hyperliquid 永续合约、现货、HIP-3 和 HIP-4 市场标识符有何不同？

标准永续合约使用诸如 BTC 等符号，现货市场使用 @index（例如 @142），HIP-3 市场使用构建器前缀的符号（例如 xyz:NVDA）。HIP-4 结果方向使用 #N 币种标识符。查询 outcomeMeta 以将每个 HIP-4 标识符映射到其市场和方向。

如何推导 Hyperliquid 某一价格层级下的队列顺序？

Hyperliquid 使用价格-时间优先级：价格更优的订单优先，同一价格下通常较老的订单在前。价格层级的最近尾部（约 400 毫秒）按优先费率降序重新排列。使用 ORDER_PRIORITY 观察优先费订单流，但从 L4 流重建当前订单簿状态。发出的 StreamL4Book 快照是当前相对队列的真相来源。API 不返回数字队列位置，对订单 ID 排序并非文档规定的规则。

我们 ❤️ 反馈！

告诉我们 如果你有任何反馈或对新主题的请求。我们很乐意听取你的意见。