给 USDC 余额设闹钟：别让预付额度在任务跑到一半时归零

长时任务最怕的不是报错，是静默失败。预付余额归零时，API 会返回错误，但如果你在睡觉，可能几小时后才发现任务已经停了。本文用几段脚本解决这个问题。

为什么需要轮询余额

聚合站采用预付 USDC 扣费，余额扣完即停。对于通宵批处理、大规模数据生成、参数扫描等场景，这个停止点可能发生在凌晨三点。轮询脚本的思路很简单：定时调用余额查询接口，如果低于阈值就发通知。

确定余额查询端点

不同聚合站的余额接口路径不同。常见设计：

• GET /api/v1/balance 或 GET /api/user/balance
• 返回字段通常包含 remaining、quota、balance 等，单位可能是 USDC 或美元
• 认证方式通常是 Authorization: Bearer <API_KEY> 或独立的用户 token

先手动用 curl 调一次，确认返回结构和字段名。不要假设，每个站实现不一样。

写一个最小可用的轮询脚本

下面是一个 Python 示例，每 5 分钟检查一次，低于阈值时调用 webhook。

import os
import time
import requests

API_KEY = os.environ["AGGREGATOR_API_KEY"]
BALANCE_URL = os.environ["BALANCE_URL"]
WEBHOOK_URL = os.environ["WEBHOOK_URL"]
THRESHOLD = float(os.environ.get("THRESHOLD", "10"))
INTERVAL = int(os.environ.get("INTERVAL", "300"))

def get_balance():
    r = requests.get(
        BALANCE_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=10,
    )
    r.raise_for_status()
    data = r.json()
    return float(data["remaining"])

def notify(balance):
    requests.post(
        WEBHOOK_URL,
        json={"text": f"余额告警: 当前 {balance} USDC, 低于阈值 {THRESHOLD}"},
        timeout=10,
    )

while True:
    try:
        bal = get_balance()
        if bal < THRESHOLD:
            notify(bal)
    except Exception as e:
        print("check failed:", e)
    time.sleep(INTERVAL)

关键点：字段名、认证头、阈值单位都要根据实际接口调整。

选择通知渠道

Slack 最容易，创建一个 Incoming Webhook，把 URL 填进 WEBHOOK_URL 即可。邮件可以用 SMTP 或第三方 API。如果你已经有告警系统（如 Prometheus Alertmanager、Grafana），也可以把余额作为一个自定义指标推过去。

注意：不要用同一个脚本同时做余额检查和通知重试。通知失败可能会阻塞下一次检查。

阈值怎么定

阈值取决于两个变量：你的任务消耗速率和你想留出的响应时间。

• 如果任务每小时消耗 5 USDC，你希望至少提前 2 小时收到告警，阈值设为 10 以上。
• 如果任务可以无缝续跑，阈值可以低一些。
• 如果任务一旦中断就要从头再来，阈值应该更高。

也可以做两级告警：低于 20 发提醒，低于 5 发紧急通知。

部署和容错

最简单的方式是用 cron 跑一个短脚本，而不是长驻进程。cron 每 5 分钟执行一次，检查余额、发通知、退出。这样即使脚本崩溃也不会永久卡住。

如果需要长驻，建议用 systemd 或容器编排加 restart 策略。日志要保留，方便回溯什么时候开始余额不足。

别忘了监控脚本本身

轮询脚本自己也可能挂。一个办法是让脚本每次成功检查后，向一个健康检查服务（如 healthchecks.io）发心跳。如果心跳断了，说明监控本身出了问题。

总结

预付余额监控不需要复杂系统。一个定时脚本、一个阈值、一个 webhook，就能避免大部分“跑到一半停了”的事故。关键是先确认余额接口的真实返回，再根据消耗速率设定阈值，最后给监控脚本本身加一层心跳。