选择 Webhook、WebSocket 或 RPC 轮询
对比地址 Webhook、WebSocket 订阅与有界 RPC 轮询:推送按事件 id 去重,长连接断线期间不保留通知,轮询从游标按各链区块上限分段调用日志接口;按链支持、接收端条件、重组恢复与计费选择。
向 HTTPS 接收端投递可选地址 Webhook,支持的实时订阅可用 WebSocket,需要自己维护游标和恢复时采用有界轮询。
面向开发者与 AI Agent 构建链上事件监听流程时,选择合适的技术方案取决于网络支持能力、投递保证、接收端基础设施与调用成本。
决策对比表
下表从链支持、接收端要求、重组与故障恢复、计费模型等维度对比三种接入方式:
| 维度 | 地址 Webhook | WebSocket 订阅 | 有界 RPC 轮询 |
|---|---|---|---|
| 接入机制 | 通过 HTTPS POST 向公共服务端点投递推送通知 | 基于 TLS 的长连接(wss://)流式订阅 | 客户端自主发起的 HTTP JSON-RPC 批量或定时查询 |
| 链支持 | 在 GET /v1/push/chains 中声明的全部受支持网络 | GET /v1/chains 中 ws: true 的网络;订阅类型取 subscriptions | GET /v1/chains 中的全部受支持网络均支持免 key 公共 RPC 或认证 JSON-RPC |
| 接收端要求 | 公网可访问的 HTTPS URL、有效 TLS 证书、超时时间内返回 2xx 响应、原始正文 HMAC SHA-256 签名校验 | 出站 TCP/TLS 客户端长连接(wss://);需处理心跳(ping/pong)与重连退避 | 无状态 HTTP 客户端或定时任务;需自行保存本地区块游标 |
| 投递与保序 | 至少投递一次(At-least-once)并带指数退避重试;接收端需按事件 id 去重,跨订阅按 ref + type 去重 | 单条活动长连接内严格保序;连接断开期间服务端不保留离线消息 | 针对已确认区块高度的确定性拉取;客户端完全自主控制查询节奏 |
| 链重组处理 | 发送 chain.reorg 控制通知;接收端先标记或丢弃被替换的旧事件,再保留重投的规范链事件 | 日志通知携带 "removed": true 标识被重组移除的日志;newHeads 需比对父区块哈希 | 客户端在轮询间隔中检查 parentHash 链式连续性以检测重组 |
| 故障与断线恢复 | 在服务端保留窗口内可通过 POST /v1/push/subscriptions/{id}/replay 重放已匹配事件;生效前历史需用 eth_getLogs 回补 | 服务端不保留跨连接队列;客户端重连后需基于 eth_getLogs 与 (blockHash, transactionHash, logIndex) 三元组去重回补 | 从保存的 last_synced_block 游标继续查询;按 GET /v1/chains 中各网络的 max_logs_block_range 切片请求 |
| 计费模型 | 按组独立收取地址日费与已送达数据事件 CU;地址日费按组在 UTC 日内在线期间的最大地址数计算,详见 Webhook 计费 | 建连与心跳免费;eth_subscribe / eth_unsubscribe 与成功冲刷至套接字发送缓冲区的通知帧按 CU 计费 | 按请求以 Compute Units 计量:eth_blockNumber、eth_call、eth_getLogs;方法权重与每美元 CU 取自 GET /v1/plans,见下表 |
| 适用场景 | 用户充值监控、热钱包地址跟踪、商户收款通知、异步事件分发 | 实时 newHeads 与过滤后的 logs、即时响应机器人、支持网络上的交互式界面 | 离线对账、定时脚本、ETL 数据同步 |
当前换算基准参数
1 USD = 10,000 计费单位,1 计费单位 = 1,000 CU(即 1 USD = 10,000,000 CU)。
换算公式:单次调用 CU 权重 × 1,000,000 ÷ (10,000 × 1,000) 美元。
| 方法 | 单次调用 CU | 每百万次调用价格(USD) |
|---|---|---|
eth_blockNumber | 1 | $0.10 |
eth_call | 15 | $1.50 |
eth_getLogs | 30 | $3.00 |
debug_traceTransaction | 100 | $10.00 |
data.block | 5 | $0.50 |
何时选择地址 Webhook
当业务后端作为可接收外部 HTTPS 请求的常规 Web 服务运行时,优先使用区块链 Webhook API:
- 大规模地址监控:跟踪数千甚至更多用户充值或提现地址的变动,无需为每个地址维护长连接。
- 无状态与 Serverless 接收端:云函数或容器化服务(如 AWS Lambda、Cloudflare Workers)可在收到通知时按需启动,避免空闲常驻连接成本。
- 自动重试与已匹配重放:接收端偶发离线或报错时享受自动指数退避重试;在服务端数据保留窗口内,还可通过重放接口补投历史已匹配事件。
- 生效边界说明:事件匹配仅从地址变更生效的区块(
applied_from_block)开始;地址添加前或订阅处于offline期间的历史事件需通过 RPC 日志回补。
在对外提供生产接收端前,请仔细核对原始正文验签与重放流程。
何时选择 WebSocket 订阅
当应用对事件到达延迟极其敏感,且客户端进程能够维持出站 TCP 长连接时,选用 WebSocket 订阅:
- 实时区块头推送:在网络产生新区块时立即接收
newHeads。 - 合约日志流:根据合约地址或指定
topic0实时接收符合过滤条件的logs。 - 私网或受限环境:适合跑在 NAT 或防火墙后、无法对外暴露公网 HTTPS 端口的本地脚本、命令行 Agent 或内部服务。
- 网络支持确认:在 GET /v1/chains 中查看目标网络的
ws与subscriptions。HyperEVM 同样可以选择 WebSocket,可用性始终以该目录为准。网络未提供 WebSocket 时,连接会返回 HTTP 404(unknown_chain)。 - 断线重连纪律:WebSocket 通知在断线期间不会保留在服务端队列。连接中断后客户端必须以随机化指数退避重新建连,并使用
eth_getLogs扫描补全缺失区间。
关于连接限制(每 key 上限 20 连接、每账户上限 50 连接)与过滤器上限,请参阅 WebSocket 订阅使用指南。
何时选择有界 RPC 轮询
当运行定时对账任务、数据离线导入流水线,或在未支持 WebSocket 的网络上运行时,选用有界 JSON-RPC 轮询:
- 定时处理与历史回补:HyperEVM(
hyperevm_mainnet)仍可使用 HTTPeth_blockNumber与eth_getLogs做有界轮询和历史回补;这并不表示没有 WebSocket。 - 精确控制查询节奏:轮询允许开发者与 AI Agent 自主调节调用频次,管理 Compute Unit 消耗并遵守每 key 速率限额,避免长时间长连接带来的意外断开。每 key 限额——默认 100 CU/s、突发 400 CU;付费充值后每个 key 至少 2,000 CU/s、突发 10,000 CU,更高的自定义限额保持不变。
- 区块区间跨度限制:认证
eth_getLogs请求的单次区间受限于 GET /v1/chains 中各网络的max_logs_block_range。请求范围超过该限制将返回错误码-32602(logs_range_too_large)。宽区间需拆分为不超过目标网络max_logs_block_range的连续分段分别查询。
| 链 | 链标识 | max_logs_block_range(区块数) |
|---|---|---|
| Arbitrum One | arb_mainnet | 1,000 |
| Arc | arc_mainnet | 1,000 |
| Avalanche C-Chain | avax_mainnet | 1,000 |
| Base | base_mainnet | 1,000 |
| Berachain | berachain_mainnet | 1,000 |
| Boba | boba_mainnet | 1,000 |
| BNB Smart Chain | bsc_mainnet | 1,000 |
| Celo | celo_mainnet | 1,000 |
| Ethereum | eth_mainnet | 1,000 |
| Ethereum Sepolia | eth_sepolia | 1,000 |
| Fraxtal | fraxtal_mainnet | 1,000 |
| Gnosis | gnosis_mainnet | 1,000 |
| HyperEVM | hyperevm_mainnet | 1,000 |
| Ink | ink_mainnet | 1,000 |
| Katana | katana_mainnet | 1,000 |
| Linea | linea_mainnet | 1,000 |
| Metal L2 | metall2_mainnet | 1,000 |
| Mode | mode_mainnet | 1,000 |
| OP Mainnet | op_mainnet | 1,000 |
| Polygon | polygon_mainnet | 1,000 |
| Robinhood Chain | robinhood_mainnet | 1,000 |
| Robinhood Chain Testnet | robinhood_testnet | 1,000 |
| Rootstock | rootstock_mainnet | 1,000 |
| Soneium | soneium_mainnet | 1,000 |
| Sonic | sonic_mainnet | 1,000 |
| Unichain | unichain_mainnet | 1,000 |
| World Chain | world_mainnet | 1,000 |
| X Layer | xlayer_mainnet | 1,000 |
| Zora | zora_mainnet | 1,000 |
分段扫描与游标维护算法请参阅 HyperEVM 日志回补指南 与 eth_getLogs 区块范围限制指南。
完整的工作负载清单与自测方法见如何选择 RPC 服务商。
为低量轮询选服务商时,可对比服务商的常规 RPC 计费与覆盖。比较按量计费与试用、订阅费用;通知和回填的成本计量不同于 RPC 读取。
接入指南
Robinhood Chain 上的 WebSocket
需要 Robinhood Chain 上的实时 newHeads 或过滤后的 logs 时,按 WebSocket 订阅指南完成鉴权与订阅请求。断线后退避重连、重新订阅,并从保存的游标使用 eth_getLogs 回补缺失区块;日志按 (blockHash, transactionHash, logIndex) 去重。
HyperEVM 上的有界轮询
需要 HyperEVM(hyperevm_mainnet)上的有界轮询与恢复时,按 HyperEVM 日志回补指南接入。从保存的游标按 max_logs_block_range 分段查询,每段成功处理后将事件与进度一并持久化,失败时重试未完成区段。检查链连续性并回扫重叠区间以处理重组。
下一步
最后更新: