交易机器人最大的瓶颈在于 API 层

你花了几周时间打磨信号引擎。Cohort 背离、清算风险评分、资金费率极值。回测结果相当漂亮。然后你部署了机器人，不到 48 小时，它就错过了三笔交易，原因是数据轮询循环触发了速率限制，在长达二十分钟的时间里静默返回了过期数据。信号本身没有问题，问题出在围绕它构建的架构上。

这是 Hyperliquid 交易机器人中最常见的故障模式，而且几乎与 alpha 生成毫无关系。数据摄取层，也就是通过 API 调用将机器人与市场连接起来的那一部分，才是大多数机器人崩溃的地方。冗余轮询、低效的端点选择、没有缓存、没有退避机制、不清楚数据实际何时刷新。开发者优化信号，却把 API 层当成普通管道。但会漏水的管道会毁掉整栋房子，不管蓝图画得多么漂亮。

本指南的主题是从一开始就正确设计该层，专门针对在 Hyperliquid 上使用 HyperTracker 分析 API 的机器人。

为什么数据层比信号更重要

信号引擎是一个纯函数。输入相同，输出就相同，每次都是如此。如果你以可靠的节奏向它提供干净的数据，它就会产出干净的决策。如果你向它提供过期数据、重复数据，或者因为某个端点报错而你的代码吞掉了异常、导致数据格式与预期不符，信号引擎就无法恢复。它会基于不再反映市场状态的信息，产出看上去很有把握的决策。

数据层位于机器人与其所依赖的每一条市场情报之间。在 Hyperliquid 上，我们的数据按滚动间隔刷新：状态快照每 15 到 20 分钟一次，订单流快照每 5 分钟一个窗口。这意味着你的轮询节奏、缓存逻辑和错误处理都需要围绕这些具体的刷新节律来设计。轮询频率快于数据刷新速度会浪费你的请求配额；轮询频率慢于刷新速度则会错过信号窗口。

将轮询节奏与数据刷新对齐

机器人能做的最浪费的事，就是轮询端点的频率快于底层数据的变化速度。如果 cohort 指标每 15 到 20 分钟刷新一次，而你的机器人每 60 秒轮询一次，那么这十六次调用中有十五次返回的是完全相同的数据。你耗尽配额、为事件循环增加延迟，却一无所获。

需要围绕其设计的刷新计划

HyperTracker 的 API 根据端点类别有不同的刷新节奏：

| 端点类别 | 刷新节奏 | 推荐轮询间隔 | | --- | --- | --- | | Cohort 指标 (/cohort-metrics) | 约 15-20 分钟 | 每 5 分钟（及时捕获更新） | | 订单流快照 (/orders) | 滚动 5 分钟窗口 | 每 5 分钟（与窗口对齐） | | 清算风险 (/liq-risk) | 约 15-20 分钟 | 每 5 分钟 | | 仓位指标 (/position-metrics) | 约 15-20 分钟 | 每 5 分钟 | | 排行榜 (/leaderboard) | 约 15-20 分钟 | 每 15-30 分钟（时效性要求较低） |

大多数端点推荐 5 分钟的轮询间隔是一种平衡。你希望在数据更新后尽快捕获到新数据，但你不知道它会在 15 到 20 分钟窗口内的哪个确切时刻刷新。每 5 分钟轮询一次，意味着你会在新快照可用后的 5 分钟内获取到它，对于运行在 1 小时或更长时间框架的策略来说，这已经足够快了。

设计请求预算

每个 API 套餐都有月度请求上限和每分钟速率限制。你的机器人架构需要同时遵守这两项约束，而且根据你所在的套餐，限制条件也有所不同。

| 套餐 | 月度请求数 | 速率限制 | 每日有效预算 | | --- | --- | --- | --- | | Pulse ($179/mo) | 50,000 | 60/分钟 | 约 1,667 次请求 | | Surge ($399/mo) | 150,000 | 100/分钟 | 约 5,000 次请求 | | Flow ($799/mo) | 400,000 | 200/分钟 | 约 13,333 次请求 | | Stream ($1,999/mo) | 2,000,000 | 500/分钟 | 约 66,667 次请求 |

在 Pulse 套餐上，机器人每 5 分钟轮询 4 个端点，每天使用 4 x 288 = 1,152 次请求。这为临时查询、补全历史数据或针对其他资产的第二个轮询循环留下了 515 次请求的余量。有一定的余裕，但如果你在没有规划的情况下添加更多端点或更多资产，就会变得紧张。

在 Surge 套餐上，同样的 4 个端点、5 分钟轮询循环消耗同样的 1,152 次请求，但你的每日预算约为 5,000 次，所以你可以监控多个资产，或者为主要资产的订单流添加第二个更快速的循环。关键在于：在编写轮询代码之前，先对预算进行建模，因为在一个没有速率限制意识的机器人上事后补救，是非常痛苦的。

请求预算电子表格模式

在编写任何轮询代码之前，先草拟一张这样的表格：

端点               | 资产数 | 间隔    | 每日调用次数
-------------------+--------+---------+----------
/cohort-metrics    |   3    |  5 分钟  |    864
/orders            |   1    |  5 分钟  |    288
/liq-risk          |   3    |  5 分钟  |    864
/position-metrics  |   1    | 15 分钟  |     96
-------------------+--------+---------+----------
合计               |        |         |  2,112
预算 (Pulse)       |        |         |  1,667   <- 超出

修正：将 /liq-risk 改为 15 分钟间隔：
/liq-risk          |   3    | 15 分钟  |    288
新合计             |        |         |  1,536   <- 可行

这是一个简单的算术练习，但大多数开发者会跳过它，等到机器人在生产环境中开始返回 429 错误时才发现超出预算。先建模，再构建。

缓存：大多数机器人跳过的那一层

你的机器人应该维护一个本地数据存储（哪怕只是内存中的一个简单字典），保存它轮询的每个端点的最新响应。这有三个作用。

第一，去重。 如果你每 5 分钟轮询一次 /cohort-metrics，但数据每 15 到 20 分钟才刷新一次，那么四次轮询中有三次会返回完全相同的数据。你的缓存应该将传入的响应与已存储的版本进行比较，只有在确实发生变化时才向信号引擎传递。这可以防止你的机器人基于过期数据反复评估信号，并产生冗余的日志噪声。

第二，过期检测。 为每个缓存条目附加一个时间戳。如果某个端点的缓存超过预期刷新间隔两倍的时间没有更新（例如，20 分钟刷新对应 40 分钟），就说明出了问题。要么 API 宕机，要么你的网络不稳定，要么机器人的事件循环卡住了。过期告警可以在机器人基于可能已有一小时历史的数据进行交易之前触发调查。

第三，优雅降级。 如果某次轮询失败（网络错误、500 错误、速率限制），缓存中仍然保存着上一次成功的响应。机器人可以继续基于该数据运行，并明确知晓自己正在使用过期信息。这种感知至关重要：一个明确知道数据过期的机器人可以缩小仓位规模或放宽止损；一个不知道数据已过期的机器人则无法做出调整。

class DataCache:
    def __init__(self, stale_threshold_seconds=2400):
        self.store = {}
        self.stale_threshold = stale_threshold_seconds

    def update(self, endpoint, data):
        prev = self.store.get(endpoint)
        changed = prev is None or prev["data"] != data
        self.store[endpoint] = {
            "data": data,
            "fetched_at": time.time(),
            "changed": changed,
        }
        return changed

    def get(self, endpoint):
        entry = self.store.get(endpoint)
        if entry is None:
            return None, True  # no data, considered stale
        age = time.time() - entry["fetched_at"]
        return entry["data"], age > self.stale_threshold

    def is_stale(self, endpoint):
        _, stale = self.get(endpoint)
        return stale

错误处理与退避

API 调用会失败。网络会断线。速率限制会被触发。问题在于你的机器人是优雅地处理这些失败，还是崩溃、激进重试（耗光更多配额），或者更糟糕的是，在没有数据的情况下静默继续运行。

三种失败模式

速率限制（HTTP 429）。 API 在告诉你放慢速度。正确的应对方式是指数退避：等待 1 秒，然后 2 秒，然后 4 秒，然后 8 秒，上限为 60 秒。不要立即重试，不要以固定的 1 秒间隔重试。在已经触发速率限制的情况下，每次立即重试只会让情况越来越糟。

服务器错误（HTTP 5xx）。 API 端出了问题。带退避机制重试，最多 3 次。如果三次全部失败，记录错误，将缓存条目标记为可能过期，然后继续。不要让整个事件循环阻塞在等待恢复上。

客户端错误（HTTP 4xx，非 429）。 你的请求格式有误。重试没有用。记录错误并附上完整的请求载荷以便调试，跳过本次轮询周期。

async def poll_with_backoff(endpoint, params, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = await fetch(endpoint, params)
            if response.status == 200:
                return response.json()
            elif response.status == 429:
                wait = min(2 ** attempt, 60)
                logger.warning(f"Rate limited on {endpoint}, waiting {wait}s")
                await asyncio.sleep(wait)
            elif response.status >= 500:
                wait = min(2 ** attempt, 30)
                logger.warning(f"Server error {response.status} on {endpoint}")
                await asyncio.sleep(wait)
            else:
                logger.error(f"Client error {response.status} on {endpoint}")
                return None
        except NetworkError as e:
            logger.error(f"Network error on {endpoint}: {e}")
            await asyncio.sleep(min(2 ** attempt, 30))
    logger.error(f"All retries exhausted for {endpoint}")
    return None

端点选择：只获取你需要的数据

HyperTracker 提供 21 个端点。你的机器人可能只需要其中 3 到 5 个。最大的预算浪费之一，就是"以防万一"地轮询那些信号引擎实际上并不消耗其数据的端点。

从信号出发，而不是从 API 出发。问自己：我的信号函数需要哪些数据作为输入？如果它使用 cohort 仓位，就轮询 /cohort-metrics。如果它使用清算风险，就轮询 /liq-risk。如果它不使用排行榜数据，就不要轮询 /leaderboard。你加入轮询循环的每个端点，都会消耗你的每日请求预算，并增加一个潜在的故障点。

常见信号与端点的对应关系

| 信号类型 | 所需端点 | 可选补充端点 | | --- | --- | --- | | Cohort 背离 | /cohort-metrics | /position-metrics（OI 背景信息） | | 清算风险衰退 | /liq-risk | /cohort-metrics（方向确认） | | 订单流失衡 | /orders | /cohort-metrics（识别驱动力量） | | 资金费率极值 | Hyperliquid 原生 API | /cohort-metrics（Smart Money 立场） | | 跟单交易 / 钱包跟踪 | /positions | /leaderboard（目标钱包筛选） |

注意 /cohort-metrics 几乎出现在每种信号类型中，无论是作为主要端点还是补充来源。如果你的策略围绕 cohort 情报构建，这就是你的核心端点。我们的数据将每个 Hyperliquid 钱包归入 16 个行为 cohort 之一（8 个按账户规模，8 个按历史 PnL），cohort 级别的聚合数据是信号密度最高的地方。

构建轮询循环

轮询循环是机器人的心跳。设计正确，系统就能顺畅运行数周。设计错误，你就会在凌晨三点调试竞态条件和遗漏的轮询。

错开间隔模式

不要让所有端点轮询在同一秒触发。如果你以 5 分钟为节奏轮询 4 个端点，就把它们错开分布在这个间隔内。在 t+0 轮询 /cohort-metrics，在 t+75s 轮询 /orders，在 t+150s 轮询 /liq-risk，在 t+225s 轮询 /position-metrics。这能平滑你的请求速率，避免可能触发每分钟速率限制的突发请求。

POLL_SCHEDULE = [
    {"endpoint": "/cohort-metrics", "offset_sec": 0,   "interval_sec": 300},
    {"endpoint": "/orders",         "offset_sec": 75,  "interval_sec": 300},
    {"endpoint": "/liq-risk",       "offset_sec": 150, "interval_sec": 300},
    {"endpoint": "/position-metrics","offset_sec": 225, "interval_sec": 900},
]

async def run_polling_loop(cache, signal_engine):
    while True:
        now = time.time()
        for task in POLL_SCHEDULE:
            elapsed = (now - start_time) % task["interval_sec"]
            if abs(elapsed - task["offset_sec"]) < 2:
                data = await poll_with_backoff(task["endpoint"], params)
                if data and cache.update(task["endpoint"], data):
                    signal_engine.evaluate(cache)
        await asyncio.sleep(1)

关键细节：只有当缓存检测到真实的数据变化时，信号引擎才会被调用。没有冗余评估，没有浪费的计算，机器人做出的每个决策都基于最新信息。

Webhook 和 WebSocket 替代方案

在 Flow ($799/mo) 和 Stream ($1,999/mo) 套餐上，HyperTracker 支持 webhook 和 WebSocket 连接。这从根本上颠覆了轮询模型：不再是机器人按计时器向 API 请求数据，而是 API 在数据变化时主动推送给机器人。

Webhook 消除了它所覆盖端点的整个轮询循环。你注册一个回调 URL，当 cohort 指标更新时，机器人就会收到一个包含新数据的 POST 请求。无需轮询，无需浪费请求，没有过期窗口。

WebSocket 连接（Stream 套餐）提供持续更新的持久通道。如果你正在构建一个需要在数据刷新后几秒内做出反应的高频系统，WebSocket 路径可以完全消除周期性轮询带来的延迟。

但对于大多数初学的开发者来说，上面描述的轮询模式才是正确的基础。Webhook 和 WebSocket 是优化手段，等你的机器人策略得到验证、你需要更低延迟或更高吞吐量时再升级到它们。

整合起来：参考架构

以下是一个设计良好的 Hyperliquid 交易机器人的完整技术栈，从 API 到执行：

+----------------------------------------------------------+
|                      风险管理                             |
|  （否决信号、强制执行仓位限制、可以暂停运行）               |
+----------------------------------------------------------+
        |                                    ^
        v                                    |
+------------------+   +------------------+  |
|     信号引擎     |-->|       执行        |--+
|   （纯函数）     |   |   (Hyperliquid    |
|                  |   |   Python SDK)    |
+------------------+   +------------------+
        ^
        |  （仅在缓存变化时）
+----------------------------------------------------------+
|                      数据缓存                             |
|  - 去重（跳过未变化的响应）                                |
|  - 过期检测（数据超过 2 倍刷新周期时告警）                  |
|  - 优雅降级（出错时提供最后已知的良好数据）                  |
+----------------------------------------------------------+
        ^
        |  （带退避的错开轮询）
+----------------------------------------------------------+
|                     API 轮询层                             |
|  - 按端点设置错开间隔                                      |
|  - 对 429/5xx 进行指数退避                                 |
|  - 请求预算追踪（每日 + 每分钟）                            |
|  - 根据信号需求选择端点                                     |
+----------------------------------------------------------+
        |
        v
   HyperTracker API
   (REST / Webhooks / WebSocket)

每一层都有单一的职责。轮询层处理 API 通信和错误恢复。缓存层处理数据新鲜度和去重。信号引擎处理决策。执行层处理订单管理。风险管理位于所有层之上，有权阻止任何层的任何操作。

数据在技术栈中向上流动，每一层都添加了特定的保证。当信号到达执行层时，你知道数据是新鲜的，信号是基于已变化（而非重复）的输入进行评估的，风险层也已批准该交易。这才是一个可以放心让它整夜运行的机器人。

基于预计算情报构建你的机器人

HyperTracker 的 API 为你提供跨 Hyperliquid 全市场的 cohort 分析、清算风险评分、订单流快照和仓位指标。16 个行为 cohort，每个钱包都有分类，通过 REST、webhook 或 WebSocket 交付。从免费套餐开始，随着机器人的成熟逐步升级。

探索 API

常见错误（以及如何避免）

以相同频率轮询所有端点。 排行榜数据的变化速度不如订单流快照。将每个端点的轮询间隔与其刷新节奏以及你的信号对该数据的敏感度匹配起来。不是每个端点都需要 5 分钟的频率。

等到为时已晚才注意到月度上限。 一个运行三周没问题、然后在第四周耗尽月度配额的机器人，比一个稍慢但全月持续运行的机器人更糟糕。每天追踪累计请求数，并在某个阈值触发告警（例如，当你当天已使用的请求数超过了按当月日期比例应使用的月度预算时）。

静默吞掉错误。 最糟糕的情形是：一个 try/except 块捕获所有异常并返回 None，然后该值作为"无数据"被传入信号引擎。你的信号引擎对"无数据"的解读与"数据显示没有什么有趣的事情发生"不同。要区分"API 返回了空结果"（有效）和"API 调用失败"（错误）。它们是不同的状态。

在热循环中获取历史数据。 HyperTracker 拥有数月的仓位和成交历史数据。这些数据用于回测和研究，应该一次性获取、本地存储，绝不在实时轮询循环中重复获取。历史数据端点与实时端点共享相同的速率限制，反复获取它们会无谓地消耗你的预算。

先构建信号，最后才处理数据层。 信号是有趣的部分：cohort 背离评分、复合信号、阈值调优。但如果你在不知道自己能负担多少 API 调用、数据多久刷新一次、错误如何传播的情况下构建信号，你就会在事后被迫围绕本应从一开始就设计进去的约束条件改造数据层。先构建管道，用纯日志模式（不交易）测试几天，再接入信号。

要点总结

信号是 alpha 的来源。API 层是日复一日可靠交付该 alpha 的基础设施，不会耗尽你的请求预算，也不会悄无声息地退化。把这一点做对的开发者，构建出的机器人能运行数月。把数据层当作事后补丁的人，花在调试基础设施上的时间比打磨自己的优势更多。

在写代码之前先对请求预算建模。积极使用缓存。显式处理错误。以数据实际刷新的节奏进行轮询，并错开你的请求，永远不要产生突发流量。做到这五件事，API 层就会变得无感知，这正是优秀基础设施应有的样子。