在 Hyperliquid 上构建实时钱包监控列表

概览

如果你正在构建一个钱包监控系统，你可能已经处理过这种情况：一个新钱包需要跟踪，因此你更新了一个硬编码的地址列表，重新部署你的过滤器，并等待所有内容重新连接。对于少数钱包来说，这是可以管理的，但当列表频繁变动时（新用户加入、地址轮换、研究目标转移），这个过程就会变成瓶颈。

本指南将带你学习如何使用 Webhooks 和 Key-Value Store 在 Hyperliquid 上构建一个实时的钱包观察列表。虽然本例侧重于 Hyperliquid，但相同的模式适用于 Webhooks 支持的任何链。KV Store 列表还可以与 Streams 配合使用，以实现更高级的流水线（示例请参见 HyperCore Order Monitor 示例应用）。

摘要

• Quicknode Webhooks 可以引用 Key-Value Store 列表而不是硬编码地址，使观察列表具有动态性且易于更新
• 通过仪表板或 REST API 更新地址列表；Webhook 会立即获取更改，无需重启
• 本指南以 Hyperliquid 钱包事件为例，但该模式适用于任何受支持的链
• 涵盖了仪表板设置和使用 Quicknode 的 REST API 的完全编程化方法

你将学到什么

• Webhooks 和 Key-Value Store 如何协同工作以实现动态地址过滤
• 如何使用 Hyperliquid Wallet Events 模板创建 Webhook
• 如何将 KV Store 列表链接到你的 Webhook 以进行动态地址跟踪
• 如何通过 Quicknode 的 REST API 以编程方式管理你的观察列表和 Webhook
• 如何构建一个简单的服务器来接收和处理 Webhook 事件

你将需要什么

• 一个 Quicknode 账户
• 已安装 Node.js v20+
• 一个 Quicknode API 密钥（用于 REST API 部分）

Webhooks 和 KV Store 如何协同工作？

大多数钱包监控设置都使用硬编码在配置中的固定地址列表。当你需要跟踪一个新钱包或停止跟踪一个旧钱包时，你需要修改配置并重启流水线。

Quicknode Webhooks 与 Key-Value Store 的集成通过将地址列表与 Webhook 配置解耦来改变了这一点。Webhook 不再直接嵌入地址，而是引用存储在 Key-Value Store 中的命名列表。在评估时，Webhook 会查找该列表的当前内容，并将传入事件与其进行匹配。这意味着：

• 添加钱包：将地址插入 KV Store 列表。Webhook 会立即获取它。
• 删除钱包：从列表中删除地址。Webhook 会在下一个事件中停止匹配它。
• 无需更改 Webhook：Webhook 配置保持不变。只有列表内容发生变化。

AI Agents 和自动化

如果你是一个 AI Agent 或正在构建自动化基础设施，请直接跳到 使用 REST API 进行编程化设置 部分，以获取完全由 API 驱动的方法。

通过仪表板创建 Webhook

导航到 Quicknode 仪表板上的 Webhooks 页面，然后点击 Create Webhook。引导向导将分几个步骤带你完成配置。

选择网络和模板

1. 选择 Hyperliquid Hypercore Mainnet 作为你的网络。
2. 选择 Hyperliquid Wallet Events 模板。此模板监控一组钱包地址的存款、提款、转账和金库操作。

链接 Key-Value Store 列表

选择模板后，向导会提示你提供要监控的钱包地址。你有三个选项：

• Saved Lists：选择一个现有的 KV Store 列表。选择后你可以编辑该列表。
• Manual Input：通过逐个添加地址并设置列表名称来创建一个新列表。
• Import：上传一个每行包含一个钱包地址的文本文件，并设置列表名称。

选择适合你工作流程的任何选项。关键点是这三种方式都会创建（或引用）一个 KV Store 列表，因此你以后可以在不触碰 Webhook 的情况下更新它。

info

Hyperliquid Wallet Events 模板会自动将地址转换为小写，以进行不区分大小写的匹配。你可以输入任何大小写格式的地址。

测试过滤器

设置一个区块号，以针对历史数据测试你的过滤器。例如，你可以使用区块 957175080 以及钱包 0x91c65e75f9a869900859ce66bd8719555e66e9c3 来查看示例 Payload。点击 Run 预览匹配的事件。

以下是你可以预期的示例 Payload：

{
  "block_number": 957175080,
  "block_time": "2026-04-13T12:35:01.639703687",
  "matchedEvents": [\
    {\
      "hash": "0xbbacbb092cc34605bd2604390d55280202bc00eec7c664d75f75665bebc71ff0",\
      "inner": {\
        "LedgerUpdate": {\
          "delta": {\
            "amount": "2.291667",\
            "destination": "0x82cd5683ef2013c30915cd84c940f378ad782d4b",\
            "fee": "0.0",\
            "nonce": 1776083700639,\
            "sourceDex": "spot",\
            "token": "USDC",\
            "type": "send",\
            "usdcValue": "2.291667",\
            "user": "0x91c65e75f9a869900859ce66bd8719555e66e9c3"\
          },\
          "users": [\
            "0x91c65e75f9a869900859ce66bd8719555e66e9c3",\
            "0x82cd5683ef2013c30915cd84c940f378ad782d4b"\
          ]\
        }\
      },\
      "time": "2026-04-13T12:35:01.639703687"\
    }\
  ]
}

matchedEvents 数组包含由受监控钱包触发的每个事件。LedgerUpdate 类型涵盖了大多数钱包活动，包括发送、存款、提款和金库操作。有关事件类型的完整列表，请参阅 Hyperliquid Events dataset 文档。

示例 Payload 对于理解数据结构以及在上线前测试服务器的事件处理逻辑非常有用。

配置交付并创建 Webhook

1. Webhook URL：输入你希望接收事件的 HTTP 端点。如果你还没有服务器，可以使用 Webhook.site 进行快速测试，待服务器准备就绪后，再将该 URL 替换为你的生产端点。
2. Security Token：复制生成的安全 Token。在你的服务器上使用它来 验证传入请求是否来自 Quicknode。
3. Compression：可选启用 gzip 压缩以减小 Payload 大小。查看 使用数据压缩优化 Streams 带宽 指南，了解更多关于压缩以及如何在服务器上处理压缩 Payload 的信息。
4. 再次测试：配置交付设置后，你可以再次测试 Webhook，看看你的端点是否正确接收了 Payload。如果你启用了压缩或设置了安全 Token 验证，这一点尤为重要。
5. 名称：为你的 Webhook 起一个描述性名称（例如，“Hyperliquid Wallet Watchlist”）。
6. 点击 Create 激活你的 Webhook。

你的 Webhook 现在已经上线，并正在监控 KV Store 列表中的钱包。

tip

有关处理事件并对其采取行动的完整 Webhook 服务器实现，请查看 HyperCore Order Monitor 示例应用。它使用 Streams，但服务器模式对于 Webhooks 也是一样的。

构建一个简单的 Webhook 服务器

要接收和处理来自 Webhook 的事件，你需要一个接受 POST 请求的 HTTP 服务器。以下是一个使用 Express 的极简示例，它记录传入事件并验证安全 Token：

mkdir hl-watchlist-server && cd hl-watchlist-server
npm init -y
npm install express

创建一个名为 server.js 的文件：

import express from "express";

const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.json());

app.post("/webhook", (req, res) => {
  const payload = req.body;
  const events = payload.matchedEvents || [];

  console.log(`\nBlock #${payload.block_number} | ${events.length} event(s)`);

  for (const event of events) {
    const inner = event.inner;

    if (inner.LedgerUpdate) {
      const delta = inner.LedgerUpdate.delta;
      console.log(
        `  ${delta.type} | ${delta.amount} ${delta.token} | ${delta.user} -> ${delta.destination}`
      );
    }
  }

  res.status(200).json({ status: "ok" });
});

app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});

通过在终端中添加 "type": "module" 或运行 npm pkg set type=module 来更新 package.json 以使用 ES Modules。然后，启动服务器：

node server.js

当你的 Webhook 触发时，你将看到如下输出：

Block #957175080 | 1 event(s)
  send | 2.291667 USDC | 0x91c6...9c3 -> 0x82cd...d4b

要在开发期间将此服务器暴露给互联网，请使用类似 ngrok 的工具：

ngrok http 3000

复制生成的 URL 并将其设置为你的 Webhook URL（例如，https://abc123.ngrok.io/webhook）。对于生产环境，将此服务器部署到你首选的托管提供商，并替换 Webhook 配置中的 URL。

更新你的观察列表

一旦 Webhook 运行，你可以随时通过 Key-Value Store 仪表板 或 KV Store REST API 更新被观察的地址。添加或删除地址，Webhook 会在下一个传入事件中获取更改。无需重启。

使用 REST API 进行编程化设置

你通过仪表板所做的一切也可以通过 Quicknode 的 REST API 完成。这对于自动化、CI/CD 流水线以及需要以编程方式管理 Webhooks 和观察列表的 AI Agent 特别有用。

所有 API 请求都需要在 x-api-key 标头中包含你的 Quicknode API 密钥。你可以从 API Keys 页面 创建一个。

创建一个 KV Store 列表

使用 KV Store REST API 创建一个包含初始钱包地址集的新列表：

创建 KV Store 列表

curl -X POST "https://api.quicknode.com/kv/rest/v1/lists" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "key": "hl-watchlist",
    "items": [\
      "<wallet_address_1>",\
      "<wallet_address_2>",\
      "<wallet_address_3>"\
    ]
  }'

将 YOUR_API_KEY 替换为你实际的 API 密钥，并根据需要调整钱包地址。

创建 Webhook

使用 Webhooks REST API 创建一个引用你的 KV Store 列表的 Webhook。walletsListName 参数将 Webhook 链接到你的 KV Store 列表：

创建 Webhook

curl -X POST "https://api.quicknode.com/webhooks/rest/v1/webhooks/template/hyperliquid-wallets" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Hyperliquid Wallet Watchlist",
    "network": "hyperliquid-hypercore-mainnet",
    "url": "https://your-server.com/webhook",
    "templateArgs": {
      "walletsListName": "hl-watchlist"
    }
  }'

walletsListName 的值必须与你创建的 KV Store 列表的键匹配。Webhook 在评估时解析列表内容，因此对 hl-watchlist 列表的任何更改都会被自动获取。

使用不同的链或模板

此示例在 Hyperliquid Hypercore Mainnet 上使用了 hyperliquid-wallets 模板，但你可以为任何受支持的链更换模板 ID 和网络。walletsListName 参数在所有基于钱包的模板中都以相同的方式工作。有关可用模板，请参阅 Webhooks REST API 文档。

管理观察列表

向你的列表添加新地址：

向观察列表添加地址

curl -X PATCH "https://api.quicknode.com/kv/rest/v1/lists/hl-watchlist" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "add_items": [\
      "<wallet_address_4>"\
    ]
  }'

删除地址：

从观察列表删除地址

curl -X PATCH "https://api.quicknode.com/kv/rest/v1/lists/hl-watchlist" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "remove_items": [\
      "<wallet_address_3>"\
    ]
  }'

检索当前列表以验证其内容：

检索当前观察列表

curl -X GET "https://api.quicknode.com/kv/rest/v1/lists/hl-watchlist" \
  -H "accept: application/json" \
  -H "x-api-key: YOUR_API_KEY"

有关操作的完整列表，请参阅 KV Store REST API 文档。

结论

你现在在 Hyperliquid 上拥有了一个可以随时更新的实时钱包观察列表。Webhooks 和 Key-Value Store 的结合为你提供了一个监控系统，其中基础设施保持稳定，而被观察的数据保持灵活。

这种模式不仅限于 Hyperliquid。你可以将相同的方法应用于 Quicknode Webhooks 支持的任何链，引用 KV Store 列表在 EVM 链、Solana 等链上进行动态地址过滤。

想要完全控制？

使用 Streams 构建一个完全可定制的数据流水线，并可以访问历史数据、额外的目的地和自定义过滤。Streams 也支持 KV Store 列表引用，以实现相同的动态过滤模式。

下一步

• 构建生产环境的 Webhook 服务器：查看 构建跟单交易机器人 指南，获取处理事件并执行交易的完整服务器实现。它使用 Streams，但服务器模式对于 Webhooks 是一样的。
• 探索 Events 数据集：查看 Hyperliquid Events 数据集 文档，获取事件类型和过滤选项的完整列表。
• 了解更多关于 Webhooks 的信息：阅读 Webhooks 入门 指南，深入了解 Webhook 配置、安全 Token 和压缩。
• 大规模管理数据：查看 Key-Value Store 文档 以了解高级列表和集合操作。

常见问题解答

我可以在 Hyperliquid 以外的链上使用这种模式吗？

可以。Quicknode Webhooks 在任何受支持的链上都支持 KV Store 列表引用。模板和事件类型会有所不同，但将 Webhook 链接到 KV Store 列表以进行动态过滤的模式是相同的。

Webhook 获取 KV Store 列表更改的速度有多快？

更改会被快速获取，通常在 15 秒内。当你从 KV Store 列表中添加或删除地址时，Webhook 会在更改传播后的下一个传入事件中评估更新后的列表。

KV Store 列表中的地址数量有限制吗？

KV Store 列表中的项目数量没有硬性限制。

Webhook 捕获哪些类型的 Hyperliquid 事件？

Hyperliquid Wallet Events 模板捕获 LedgerUpdate 事件（转账、存款、提款、金库操作）、资金费用支付、跨链桥操作以及质押相关活动。有关完整细分，请参阅 Hyperliquid Events 数据集文档。

更新观察列表后我需要重启 Webhook 吗？

不需要。这是这种方法的主要优势。Webhook 按名称引用 KV Store 列表，因此它始终使用列表的最新版本。不需要重启或重新配置。

我可以从多个 Webhooks 引用同一个 KV Store 列表吗？

可以。多个 Webhooks 可以引用同一个 KV Store 列表。当你更新列表时，所有引用它的 Webhooks 都会获取到更改。如果你希望同一个观察列表触发不同用途的不同 Webhooks（例如一个用于警报，另一个用于分析），这将非常有用。

我们 ❤️ 反馈！

如果你有任何反馈或对新话题的需求，请告知我们。我们很期待收到你的信。

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