使用 SQL Explorer 构建 Hyperliquid 情报机器人

概述

从 Hyperliquid 获取结构化市场数据（成交量排名、清算摘要、funding rate 快照）通常意味着你需要自行构建并维护索引管道。SQL Explorer 让你可以直接通过 SQL 访问数十亿行已索引的 Hyperliquid 数据，并将任何查询作为 REST endpoint 调用。在本指南中，你将构建一个 Python bot，查询 Hyperliquid 表，将结果整理成市场摘要，并按每日计划发送到 Telegram channel。

TL;DR

• SQL Explorer 可以将任何 SQL query 转换为 REST endpoint：编写 SQL、POST 提交、返回 JSON。无需 indexer、无需 pipeline、无需额外基础设施
• 本指南使用了 Quicknode 在 X 上发布的每周 Hyperliquid recap 背后的一些 query pattern
• 完整源代码（Python 和 TypeScript）可在 qn-guide-examples 获取

你将学到什么

• SQL Explorer 的 REST API 如何工作，以及如何通过编程方式调用它
• 如何为不同的分析问题选择合适的 Hyperliquid tables
• 关键 query pattern：时间窗口过滤、使用 toFloat64() 进行数值类型转换、snapshot 子查询，以及像 user = liquidated_user 这样的去重过滤器
• 如何将多表查询结果组合成自动化报告

你需要什么

• 一个具有 SQL Explorer 访问权限的 Quicknode account，以及一个 API key（可在付费计划中使用）
• 本地安装 Python 3.10+ 或 Node.js 20+
• （可选） 一个 Telegram bot token 和 chat ID（通过 @BotFather 创建 bot，将其添加到 channel 中，并从 getUpdates endpoint 获取 chat ID）
• 熟悉 SQL 和 REST API

使用 AI 构建你自己的 Query

如果你使用 AI coding agent，请让它们参考 SQL Explorer 文档 和 schema reference。你也可以安装 Quicknode Skill，它提供包括 SQL Explorer 在内的 Quicknode 所有产品知识。

有了 table schema 和 query pattern 作为上下文，你的 agent 就可以为任何 Hyperliquid 分析生成自定义 SQL query。

什么是 SQL Explorer？

SQL Explorer 是一个 REST API，它将链上数据索引为可查询的 table，并暴露一个接受任意 SQL query 的统一 endpoint。每个 table、column 和 pre-built query 都在 schema reference 和 pre-built queries 页面中有文档说明。

endpoint 是：

REST API endpoint

POST https://api.quicknode.com/sql/rest/v1/query

每个 request 的结构都相同：

Request body

{
  "query": "SELECT ...",
  "clusterId": "hyperliquid-core-mainnet"
}

一个 cURL request 示例：

Example cURL request

curl -X POST 'https://api.quicknode.com/sql/rest/v1/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "query": "SELECT ...",
    "clusterId": "hyperliquid-core-mainnet"
  }'

响应包含你的数据、column metadata 和 performance stats：

Response structure

{
  "data": [\
    {\
      "day": "2026-04-07",\
      "total_volume_usd": "24100000000",\
      "total_fills": "12453211",\
      "active_traders": "60142"\
    }\
  ],
  "meta": [\
    { "name": "day", "type": "Date" },\
    { "name": "total_volume_usd", "type": "Decimal(38, 18)" }\
  ],
  "rows": 7,
  "statistics": {
    "elapsed": 0.034,
    "rows_read": 7,
    "bytes_read": 1456
  }
}

需要注意的关键点是：data 是由 row object 组成的数组，所有数值都会以字符串形式返回（你需要在代码中进行类型转换），而 statistics 会告诉你查询耗时以及扫描了多少数据，从而帮助你监控 query 成本，并随着时间推移持续优化。

适用于所有 Use Case 的工具

SQL Explorer 专为对聚合和历史数据进行分析查询而设计。对于需要在数据写入链上时立即投递的事件驱动场景，Quicknode Streams 和 gRPC 才是合适的工具。本指南中的 bot 以计划任务运行，并拉取聚合统计数据。

请注意，本指南重点介绍用于编程访问的 REST API。如果你想先交互式地探索数据，可以打开 SQL Explorer dashboard，先尝试运行下面的 query，再将它们放入代码中。

查询 Hyperliquid 数据集

SQL Explorer 目前索引了 35+ 个 Hyperliquid table，涵盖交易数据、market snapshot、funding、liquidation、bridge activity、staking 等。本文中的 bot 使用了其中四个，但你可以自由组合任意 table 来回答自己的问题。理解如何使用这些 table，比具体的 bot 更重要：一旦你掌握了这些 pattern，就可以将它们适配到任何 Hyperliquid 分析中。

以下是一些最常用的 table：

平台概览

Table:hyperliquid_metrics_overview | Sort key:day

这是一个预聚合的每日 metrics table。与其通过扫描 hyperliquid_trades 中数十亿行数据来计算 volume，不如直接使用这个 table 获取每天的平台总计：volume、fills、active traders、fees、liquidation count 和 liquidation volume。对于任何“大局”类问题，都应从这里开始。

Query 1: 平台概览（7 天）

SELECT
    day,
    total_volume_usd,
    total_fills,
    active_traders,
    total_fees,
    liquidation_count,
    liquidation_volume_usd
FROM hyperliquid_metrics_overview
WHERE day >= today() - INTERVAL 7 DAY
ORDER BY day ASC

在每周 recap 中，这个 query 用于支撑开头的 summary：每周总 volume、每日活跃 traders 峰值，以及总 liquidation 数据。你可以将 interval 改为 INTERVAL 30 DAY 来查看月度视图，或者筛选特定日期范围来分析某个事件。

按 Volume 排名前列的资产

Table:hyperliquid_trades | Sort keys:block_number, trade_id

这是原始 trades table，记录了 Hyperliquid 上的每一笔单独交易。该 query 按 coin 聚合，对资产进行 24 小时 USD volume 排名。toFloat64() 转换是必需的，因为 price 和 size 以高精度 Decimal 类型存储，而算术运算需要显式转换。

Query 2: 按 Volume 排名前列的资产（24h）

SELECT
    coin,
    count() AS trades,
    round(sum(toFloat64(price) * toFloat64(size)), 2) AS volume_usd,
    countDistinct(buyer_address) AS unique_buyers
FROM hyperliquid_trades
WHERE timestamp >= now() - INTERVAL 24 HOUR
GROUP BY coin
ORDER BY volume_usd DESC
LIMIT 10

countDistinct(buyer_address) 这一列提供了市场参与度的一个粗略衡量。若要专门筛选 HIP-3 资产，可在过滤条件中添加 WHERE coin LIKE 'xyz:%' OR coin LIKE 'cash:%'。

tip

像 timestamp >= now() - INTERVAL 24 HOUR 这样的 time-window 过滤器可以启用 partition pruning。对时间 column 进行过滤的 query 比全表扫描快得多。

清算 Recap

Table:hyperliquid_fills | Sort keys:block_number, tid, user

Hyperliquid 上的每一次 fill 都会记录在这里，包括 liquidation。is_liquidation = 1 用于标记强制平仓。关键过滤条件是 user = liquidated_user：每次 liquidation 会生成两条 fill 记录（一条给被清算的一方，一条给接手交易另一侧的对手方）。如果没有这个条件，你会把每次 liquidation event 重复计算一次。

Query 3: 清算 Recap（24h）

SELECT
    coin,
    countDistinct(liquidated_user) AS users_rekt,
    count() AS liq_count,
    round(sum(toFloat64(price) * toFloat64(size)), 2) AS liq_volume_usd
FROM hyperliquid_fills
WHERE is_liquidation = 1
    AND user = liquidated_user
    AND time >= now() - INTERVAL 24 HOUR
GROUP BY coin
ORDER BY liq_volume_usd DESC
LIMIT 10

要按方向拆分 liquidation，可在 SELECT 和 GROUP BY 中添加 side。你也可以查询单个 liquidation event（移除 GROUP BY，在 SELECT 中添加 liquidated_user 和 liquidation_mark_price），以找出最大的单笔 liquidation。

Funding Rate 极值

Table:hyperliquid_perpetual_market_contexts | Sort keys:coin, polled_at

这是一个 snapshot table，定期捕获每个 perpetual market 的状态：funding rate、mark price、oracle price 和 open interest。子查询 SELECT max(polled_at) 会检索最新 snapshot，从而为所有 market 提供一个 point-in-time 视图。

Query 4: Funding Rate 极值

SELECT
    coin,
    round(toFloat64(funding) * 8760 * 100, 2) AS annualized_rate_pct,
    round(toFloat64(open_interest) * toFloat64(mark_px), 2) AS oi_usd,
    round(toFloat64(mark_px), 4) AS mark_price
FROM hyperliquid_perpetual_market_contexts
WHERE polled_at = (
    SELECT max(polled_at)
    FROM hyperliquid_perpetual_market_contexts
)
ORDER BY abs(toFloat64(funding)) DESC
LIMIT 10

年化 rate 的计算公式是：原始 funding 字段是按小时计算的 rate，因此乘以 8,760（每年小时数）再乘以 100，就能把它转换为年度百分比。按 abs(funding) 排序可以抓取两个极端：很大的负 rate 表示 longs 在支付 shorts（看跌持仓），而很大的正 rate 表示 shorts 在支付 longs。

一定要将 funding rate 与 open interest（open_interest * mark_px 得到 USD value）结合起来看。$50K open interest 上的 -800% 年化 rate 只是噪声；相同的 rate 如果出现在 $13M open interest 上（比如 recap 中 TRUMP 的发现），就会成为有意义的 signal。

tip

如果你想跟踪 funding 随时间的变化，而不是查看单个 snapshot，可以使用 hyperliquid_funding_summary_hourly table，它提供了按 coin 预聚合的 hourly funding rate average。

构建 Intelligence Bot

上面的 query 是分析核心。bot 本身很直接：通过 REST API 调用每个 query，格式化结果，然后把它们发送到 Telegram 或 Discord 之类的平台。克隆 repository 以获取完整实现：

git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/sql-explorer/hyperliquid-intel-bot
python3 -m venv .venv && source .venv/bin/activate  # 如果你的系统找不到 python3，则使用 "python"
pip install -r requirements.txt
cp .env.example .env

在你的 .env 中填入 Quicknode API key、Telegram bot token 和 chat ID：

• QUICKNODE_API_KEY：从 dashboard.quicknode.com/api-keys 复制
• TELEGRAM_BOT_TOKEN：通过 @BotFather 创建 bot，并复制它提供的 token
• TELEGRAM_CHAT_ID：这必须是一个数字 ID。将你的 bot 添加到 channel 或 group 中（或者给它发送私信），向它发送任意消息，然后在浏览器中打开 https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates，在响应中找到 "chat": {"id": ...}。该数字就是你的 chat ID（例如 channel/group 的 -1001234567890）

.env

QUICKNODE_API_KEY=your_quicknode_api_key
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_telegram_chat_id

caution

切勿将你的 .env 文件提交到版本控制。把它添加到 .gitignore 中。

项目结构

hyperliquid-intel-bot/
├── /typescript/       # 具有相同功能的 bot 的 TypeScript 版本
├── bot.py           # 入口点，Telegram 发送
├── queries.py       # SQL 定义和 REST API 调用
├── formatter.py     # 摘要格式化
├── .env.example
└── requirements.txt

SQL 到 REST 的桥梁

项目中的关键函数是 queries.py 里的 run_query()。这就是 SQL 和你的应用之间的桥梁：它将任意 SQL string 发送到 REST API，并返回解析后的结果行。

queries.py

import os
import requests
from dotenv import load_dotenv

load_dotenv()

SQL_EXPLORER_URL = "https://api.quicknode.com/sql/rest/v1/query"
QUICKNODE_API_KEY = os.environ.get("QUICKNODE_API_KEY")
if not QUICKNODE_API_KEY:
    raise ValueError("在运行 bot 之前，请先在你的 .env 文件中设置 QUICKNODE_API_KEY。")
CLUSTER_ID = "hyperliquid-core-mainnet"

def run_query(sql: str) -> list[dict]:
    """将 SQL query 发送到 Quicknode SQL Explorer，返回结果行。"""
    resp = requests.post(
        SQL_EXPLORER_URL,
        headers={
            "x-api-key": QUICKNODE_API_KEY,
            "Content-Type": "application/json",
        },
        json={"query": sql, "clusterId": CLUSTER_ID},
    )
    resp.raise_for_status()
    result = resp.json()
    print(f"  {result['rows']} rows in {result['statistics']['elapsed']:.2f}s")
    return result["data"]

项目中的每个 query 函数都只是一个简单包装器，它将 SQL string 通过 run_query() 发送出去。这里的 SQL 与你在 dashboard 中测试时使用的是一样的：

queries.py（续）

def get_platform_overview() -> list[dict]:
    return run_query("""
        SELECT day, total_volume_usd, total_fills, active_traders,
            total_fees, liquidation_count, liquidation_volume_usd
        FROM hyperliquid_metrics_overview
        WHERE day >= today() - INTERVAL 7 DAY
        ORDER BY day ASC
    """)

## get_top_assets(), get_liquidations(), get_funding_extremes()
## 使用与上面各部分相同的 SQL 模式

bot.py 是将所有内容连接起来的入口点：

1. 获取：调用 queries.py 中的每个 query 函数，这些函数会把 SQL 发送到 REST API 并返回结果行
2. 格式化：将原始行传给 formatter.py，由它组织成结构化的文本摘要
3. 发送：将摘要发布到 Telegram（或者在 --dry-run 模式下打印到控制台）

完整实现位于 repository 中。

运行 Bot

python3 bot.py              # 获取数据并发送到 Telegram
python3 bot.py --dry-run    # 将摘要打印到控制台，不发送

在配置 Telegram 之前，先运行 python3 bot.py --dry-run，确认你的 API key 可用且 query 能返回数据。摘要会打印到控制台，不会发送任何内容。

预期输出：

2026-04-14 08:00:01 INFO  Fetching digest data from SQL Explorer...
2026-04-14 08:00:01 INFO  Platform overview: 7 rows in 0.03s
2026-04-14 08:00:02 INFO  Top assets: 10 rows in 0.41s
2026-04-14 08:00:02 INFO  Liquidations: 10 rows in 0.38s
2026-04-14 08:00:03 INFO  Funding extremes: 10 rows in 0.12s
## ...formatted digest output...

Telegram message：

📊 Hyperliquid Daily Digest
April 14, 2026

Overview (7d)
Volume: $105.2B
Fills: 58.6M
Active traders: 60,247
Fees: $16.2M

Top Assets by Volume (24h)
1. BTC       $2.4B
2. xyz:CL    $1.2B
3. ETH       $1.0B
4. xyz:CB    $580M
5. xyz:SP500 $270M

Liquidations (24h)
Total: $78.5M
Longs: $31.4M  |  Shorts: $47.1M
Addresses liquidated: 2,293

Funding Rate Extremes
0G: -871% ann.    OI $2.1M
MAVIA: +733% ann. OI $890K
AXS: -260% ann.   OI $3.4M
TRUMP: -135% ann.  OI $13M
PONKE: +98% ann.   OI $1.2M

Powered by Quicknode SQL Explorer

TypeScript

这个 bot 也提供了 TypeScript 版本，位于 qn-guide-examples repository 中。REST API 调用是完全相同的；不同之处仅在于语言封装。

按计划运行

这个 bot 是一个独立脚本，因此任何 scheduler 都可以使用。cron job 是最简单的选择：

每天 UTC 时间上午 8:00 运行

0 8 * * * cd /path/to/hyperliquid-intel-bot && /path/to/.venv/bin/python3 bot.py

如果想要更稳健的方案，可以将其部署为云服务上的 scheduled task（AWS Lambda 配合 EventBridge、Google Cloud Functions 配合 Cloud Scheduler，或者一台带 cron 的简单 VM）。该脚本没有 server 依赖，只需要 Python 和外发 HTTPS。确保 QUICKNODE_API_KEY、TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID 可通过 .env 或云服务的 secrets manager 在执行环境中使用。

结论

你已经从 SQL query 走到了一个会向 Telegram 发送 Hyperliquid 市场摘要的计划 bot。这个模式很简单：编写 SQL、调用 REST endpoint、再用 JSON 做一些事情。但更有意思的是你能在其之上构建什么。

这些正是驱动 Quicknode 在 X 上发布的每周 Hyperliquid recap 的相同 query pattern。该数据集涵盖了 Hyperliquid 上的每笔交易、每次 liquidation、funding payment、bridge event 和 market snapshot。所有这些都可以通过单一 endpoint 进行查询。

下一步

• 构建 research dashboard。 将 query 结果输入 charting library（Plotly、D3、Recharts），构建一个在每次访问时更新的交互式 dashboard。
• 为 AI agent 提供能力。 让 LLM 将 run_query() 作为工具，并让它回答有关 Hyperliquid 市场的自然语言问题。“本周哪些 coin 的 liquidation 最多？”会变成一次 function call。
• 创建 portfolio tracker。 使用 hyperliquid_fills 和 hyperliquid_clearinghouse_states table，为特定地址构建 PnL tracker，包含历史持仓 snapshot 和 funding payment history。
• 扩展 query。 pre-built query library 有 40+ 个 template，涵盖 whale trades、builder leaderboard、HIP-3 与原生 crypto breakdown、bridge flow、validator reward 等更多内容。

常见问题

SQL Explorer 支持哪些 chain？

SQL Explorer 目前支持 Hyperliquid（HyperCore Mainnet），后续还会支持更多 chain。无论 chain 如何，REST API 接口都是相同的，因此你今天编写的代码只需更改 clusterId 参数，就可以用于新的 chain。

SQL Explorer 多少钱？

SQL Explorer 使用基于 credit 的计费模型。每个 query 至少消耗 10 credits，并根据执行时间和扫描数据量进行计算。

查询结果有 row limit 吗？

有，REST API 每次 request 最多返回 1,000 行。对于更大的结果集，请使用 LIMIT 和 OFFSET 子句进行分页。响应中包含一个 rows_before_limit_at_least 字段，用于告诉你匹配的总 row 数量。

我可以将 SQL Explorer 用于实时 alert 吗？

SQL Explorer 旨在针对历史和聚合数据进行分析查询，而不是实时 event streaming。对于实时通知（例如即时 liquidation alert），请使用 Quicknode Streams 或 gRPC endpoint。SQL Explorer 更适合计划报告、dashboard 和研究查询。

为什么 API 响应中的数值会以字符串返回？

SQL Explorer 运行在 ClickHouse 上，而 ClickHouse 对金融数据使用高精度 Decimal 类型。为了避免浮点精度损失，这些值会在 JSON 中序列化为字符串。你可以根据需要在应用代码中将它们转换为 float 或 Decimal。

我们 ❤️ 反馈！

如果你有任何反馈或新的 topic 请求，请 告诉我们。我们很乐意听到你的意见。

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