WebSocket 订阅使用指南
用 WebSocket 订阅实时区块头与日志:连接后用 eth_subscribe 订阅新区块头,日志过滤器需指定地址或主题,否则返回 -32602;单 key 连接数有上限,断线后按退避重连并补扫缺失区块。
BlockVectra 提供基于 TLS 的安全 WebSocket(wss://)连接,支持在单一长连接中处理实时以太坊事件订阅与标准 JSON-RPC 2.0 请求。
选择 WebSocket、Webhook 或轮询
应用能维持长连接、需要实时 newHeads 与过滤后的 logs 时使用 WebSocket。需要在 HTTPS 接收端获取钱包地址活动时,使用区块链 Webhook API,并实现原始正文验签、重试处理与保留窗口内已匹配事件的重放。定时监听 ERC-20 收款或补扫历史日志使用 HTTP 轮询;收款指南也提供 USDT / USDC Webhook 接收示例。如需面向开发者与 AI Agent 详细对比三种方式的链支持、接收端条件、恢复流程与计费差异,请参阅选择 Webhook、WebSocket 或 RPC 轮询指南。
WebSocket 支持读取 GET /v1/chains 的 ws 与 subscriptions;Push 支持读取带 key 的 GET /v1/push/chains。没有 WebSocket 的链,只要出现在后者列表,仍可使用地址 Webhook。
WebSocket 断线后需要重新订阅并补扫,不会发送 Push 的 subscription.gap 或 chain.reorg 控制事件。Webhook 的 gap 需扫描缺失区间;重组通知需先标记或丢弃被替换的旧事件,再保留自动重投的规范链事件。Push 重放只重投保留的已匹配事件,不补地址或链加入前、订阅离线期间的数据。实现恢复时同时参阅计费规则与错误参考。
可用链
客户端可通过公开的 GET /v1/chains 端点读取每个网络的 ws(布尔值)和 subscriptions(支持的订阅类型数组)确认实时状态。
下表列出当前已启用 WebSocket 的网络:
| 链 | WebSocket 端点(路径携带 Key) |
|---|---|
| Arbitrum One | wss://api.blockvectra.com/v1/arb_mainnet/{api_key} |
| Arc | wss://api.blockvectra.com/v1/arc_mainnet/{api_key} |
| Avalanche C-Chain | wss://api.blockvectra.com/v1/avax_mainnet/{api_key} |
| Base | wss://api.blockvectra.com/v1/base_mainnet/{api_key} |
| Berachain | wss://api.blockvectra.com/v1/berachain_mainnet/{api_key} |
| Boba | wss://api.blockvectra.com/v1/boba_mainnet/{api_key} |
| BNB Smart Chain | wss://api.blockvectra.com/v1/bsc_mainnet/{api_key} |
| Celo | wss://api.blockvectra.com/v1/celo_mainnet/{api_key} |
| 以太坊 | wss://api.blockvectra.com/v1/eth_mainnet/{api_key} |
| Ethereum Sepolia | wss://api.blockvectra.com/v1/eth_sepolia/{api_key} |
| Fraxtal | wss://api.blockvectra.com/v1/fraxtal_mainnet/{api_key} |
| Gnosis | wss://api.blockvectra.com/v1/gnosis_mainnet/{api_key} |
| HyperEVM | wss://api.blockvectra.com/v1/hyperevm_mainnet/{api_key} |
| Ink | wss://api.blockvectra.com/v1/ink_mainnet/{api_key} |
| Katana | wss://api.blockvectra.com/v1/katana_mainnet/{api_key} |
| Linea | wss://api.blockvectra.com/v1/linea_mainnet/{api_key} |
| Metal L2 | wss://api.blockvectra.com/v1/metall2_mainnet/{api_key} |
| Mode | wss://api.blockvectra.com/v1/mode_mainnet/{api_key} |
| OP Mainnet | wss://api.blockvectra.com/v1/op_mainnet/{api_key} |
| Polygon | wss://api.blockvectra.com/v1/polygon_mainnet/{api_key} |
| Robinhood Chain | wss://api.blockvectra.com/v1/robinhood_mainnet/{api_key} |
| Robinhood Chain Testnet | wss://api.blockvectra.com/v1/robinhood_testnet/{api_key} |
| Rootstock | wss://api.blockvectra.com/v1/rootstock_mainnet/{api_key} |
| Soneium | wss://api.blockvectra.com/v1/soneium_mainnet/{api_key} |
| Sonic | wss://api.blockvectra.com/v1/sonic_mainnet/{api_key} |
| Unichain | wss://api.blockvectra.com/v1/unichain_mainnet/{api_key} |
| World Chain | wss://api.blockvectra.com/v1/world_mainnet/{api_key} |
| X Layer | wss://api.blockvectra.com/v1/xlayer_mainnet/{api_key} |
| Zora | wss://api.blockvectra.com/v1/zora_mainnet/{api_key} |
连接与鉴权
客户端通过标准 TLS 建立 WebSocket 连接(wss://)。API key 支持两种传入方式:
- 路径携带 Key:
wss://api.blockvectra.com/v1/{chain}/{api_key} - 请求头携带 Key:
wss://api.blockvectra.com/v1/{chain},在 HTTP 升级(Upgrade)握手阶段传入x-api-key: {api_key}或Authorization: Bearer {api_key}请求头。
带路径 key 时只使用路径 key,忽略上述两个鉴权请求头;无路径 key 时,非空 x-api-key 优先于 Authorization: Bearer。浏览器 WebSocket API 无法设置这些请求头,请使用路径携带 key 的 URL。
握手阶段准入检查
握手可能返回以下失败:
- 身份认证:未提供 API key 返回 HTTP 401(
missing_api_key);key 未知、已停用或已吊销返回 HTTP 401(invalid_api_key);若认证服务暂不可用则返回 HTTP 503(auth_unavailable)。 - 账户余额:账户预付余额为 0 或负数返回 HTTP 402(
balance_exhausted);计费状态暂未确认返回 HTTP 503(billing_unavailable)。 - 连接数限制:单 key 连接数超过 20 条,或单账户连接数超过 50 条返回 HTTP 429(
ws_connection_limit)。 - 链可用性:请求未知或未开放的链返回 HTTP 404(
unknown_chain)。 - 服务容量:当服务端繁忙或过载时,握手返回 HTTP 503(
overloaded)并附带Retry-After头。
连接建立后,客户端可以发送标准 JSON-RPC 2.0 请求(如 eth_blockNumber 或 eth_call)以及 UTF-8 文本帧格式的订阅控制方法。
计费规则
- 建立连接、保持空闲连接与 ping/pong 心跳不计费。
- 成功的
eth_subscribe与eth_unsubscribe调用计费,包括返回false的退订;失败调用不计费。普通 JSON-RPC 调用遵循 JSON-RPC 计费规则。 newHeads推送按同一连接、同一区块哈希计一次,与该连接的newHeads订阅数量无关。logs推送按每个订阅、每个有匹配日志的区块哈希与阶段计一次;没有匹配日志的区块不计费。同一区块同一阶段匹配多条日志不增加计费次数;不同订阅分别计量,即使过滤条件重叠。重组日志(removed: true)另计一个单位;同一高度的替代区块具有不同哈希,作为不同单位计量。- 推送成功写入 socket 发送缓冲区后才计费;排队或被丢弃且未写出的推送不计费。
eth_unsubscribe应答前已排队的推送若成功写出则照常计费。WebSocket 消息不携带 HTTP 计费响应头;可通过账户用量查询已计量的 CU。
订阅方法
服务端支持以太坊标准的发布/订阅接口:eth_subscribe 与 eth_unsubscribe。
newHeads
当新区块追加到链头时,实时推送区块头对象。
- 订阅请求:
{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]} - 订阅响应:返回十六进制订阅标识符:
{"jsonrpc":"2.0","id":1,"result":"0x1"} - 推送通知帧:
{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"number":"0x1b4","hash":"0x..."}}}
logs
推送与指定过滤条件匹配的事件日志。
-
过滤条件硬性要求:每个
logs订阅过滤器必须指定address(合约地址或地址数组)或topic0(第一位置的主题,非 null)。两者均未指定的过滤请求(例如{}或{"topics":[null,"0x..."]})会被服务端拒绝,返回错误码-32602(logs_filter_required)。 -
过滤规模限制:单次订阅最多指定 100 个地址;主题最多 4 个位置,每个位置最多 16 个候选哈希。
-
过滤容量:若活跃的日志过滤器达到上限,订阅返回错误码
-32022(ws_filter_capacity)。 -
链重组:发生区块重组时,被移除区块的日志推送通知中会标记
"removed": true。 -
订阅请求:
{"jsonrpc":"2.0","id":2,"method":"eth_subscribe","params":["logs",{"address":"0x1234567890123456789012345678901234567890"}]}
eth_unsubscribe
通过订阅标识符取消指定订阅。
- 退订请求:
{"jsonrpc":"2.0","id":3,"method":"eth_unsubscribe","params":["0x1"]} - 退订响应:
{"jsonrpc":"2.0","id":3,"result":true}
运行示例
使用 viem v2 的 createPublicClient 与 webSocket 传输层连接。请将 {chain} 替换为目标链标识,{api_key} 替换为你的 API key:
import { createPublicClient, webSocket } from 'viem';
const apiKey = process.env.BLOCKVECTRA_API_KEY || '{api_key}';
const url = `wss://api.blockvectra.com/v1/robinhood_mainnet/${apiKey}`;
const client = createPublicClient({
transport: webSocket(url),
});
// 1. 订阅新区块头 (newHeads)
const unwatchBlocks = client.watchBlocks({
onBlock: (block) => {
console.log('收到新区块头:', block.number, block.hash);
},
onError: (error) => {
console.error('watchBlocks 错误:', error);
},
});
// 2. 订阅合约事件日志 (logs 过滤必须包含 address 或 topic0)
const unwatchEvents = client.watchEvent({
address: '0x1234567890123456789012345678901234567890',
onLogs: (logs) => {
console.log('收到匹配日志:', logs);
},
onError: (error) => {
console.error('watchEvent 错误:', error);
},
});关闭码与客户端处理
服务端主动终止 WebSocket 连接时会发送带有特定关闭码与简短原因的 Close 帧。下表列出服务端发出的关闭码及建议的处理方式:
| 关闭码 | 原因字符串 | 描述 | 能否重试 | 客户端动作 |
|---|---|---|---|---|
| 1001 | idle | 连接在 3600 秒(1 小时)内无活跃订阅且未收到任何消息 | 是 | 按需重新连接。 |
| 1003 | binary frames are not accepted | 客户端发送了二进制帧;服务端仅接收 UTF-8 文本帧 | 否 | 不要自动重连。修改客户端以发送纯文本帧。 |
| 1009 | message too large | 客户端入站消息超过 1 MiB 限制 | 否 | 不要自动重连。拆分大请求或缩减请求体大小。 |
| 1012 | service restart | 服务端维护重启,或单连接已达最长生命周期(24 小时) | 是 | 使用带随机抖动的退避策略重连,重新建立订阅并补全数据。 |
| 1013 | chain unavailable | 链停止接受 WebSocket 会话 | 是 | 使用带全抖动的指数退避重连,重建订阅并通过 eth_getLogs 补全数据。 |
| 1013 | overloaded | 服务端临时过载 | 是 | 使用带全抖动的指数退避重连,重建订阅并通过 eth_getLogs 补全数据。 |
| 4402 | insufficient balance | 账户预付余额已耗尽 | 否 | 不要自动重连。充值后再重连。 |
| 4404 | invalid api key | API key 未知、已停用或已吊销 | 否 | 不要自动重连。在控制台检查并更换有效的 API key。 |
| 4408 | slow consumer | 会话推送队列超过 512 KiB 时服务端关闭连接并丢弃待发通知;客户端可能收不到关闭帧(浏览器报 1006) | 是 | 意外断开(没收到关闭帧,浏览器报 1006)按 4408 处理:退避重连,并减少订阅或加快读取;重新建立订阅并通过 eth_getLogs 补全数据。 |
| 4429 | push rate exceeded | 推送频率超过 1,000 次/秒 | 是 | 减少订阅数或收窄过滤条件;带退避重连后重建订阅并补全数据。 |
| 4503 | billing unavailable | 计费暂时不可用 | 是 | 此为暂时状态,使用带全抖动的指数退避策略重连。 |
控制快速出块链的日志查询频率
每条 newHeads 通知不必各触发一次 eth_getLogs。在快速出块的链上,逐通知查询可能比自然合并了多个区块的轮询发出更多请求。如果应用允许一个较短的更新间隔,可先合并区块头通知,再开始下一轮扫描:
- 每条链同时只执行一轮扫描,用有界的待处理区块头记录代替逐通知排队。待处理区块头只是检查链状态的线索,不是已提交检查点,也不能证明历史已成为 canonical。
- 每轮开始时,固定区块编号和哈希作为上界。按目录中的
max_logs_block_range分段读取整个未提交区间;合并多条通知时不能跳过中间区块。将结果和检查点一同提交;失败时保留此前已提交的检查点,停止本轮扫描。 - 扫描期间收到的通知可安排后续一轮,并遵守选定间隔和资源限制。重新核对区块哈希,按断线后的数据补全策略处理重组;仅看到更高的区块编号不能消除哈希冲突。
更新间隔以时效性换取更少的扫描机会,不保证总 CU 一定降低。记录实际日志查询、区块读取和端到端延迟,并按计费规则单独计算 WebSocket 通知。带过滤条件的 logs 订阅可直接传递匹配事件,但仍需下文的断线补全与重组恢复。
断线重连与指数退避
当服务端重启或网络断开时,为避免大量客户端同时重连导致流量洪峰,客户端必须遵循全抖动(full jitter)指数退避算法:
- 退避公式:在第 n 次重试连接前(n = 0, 1, 2, ...),在区间内均匀随机选择等待时长:
delay = random(0, min(20s, 0.5s * 2^n)) - 重置计数器:仅在会话持续稳定保持连接至少 60 秒后,才将重试计数器 n 重置为 0。
- 1012 首次随机延迟:首次重试时引入随机初始延迟,避免所有连接同步打散。
- 不可重连关闭码:遇到 4402、4404、1003 或 1009 时禁止自动重连。
断线后的数据补全策略
WebSocket 订阅状态不跨连接持久化;断线期间产生的推送通知不会在服务端保留。客户端重连成功后,应实施补全:
- 通过
eth_getLogs补全日志:- 将
last_processed_block连同其区块哈希持久化,作为连续已提交工作的恢复检查点。把它与见过的最高实时区块通知分开记录;收到一条日志不代表该区块其余部分已处理完成。 - 重连时,先用相同的
address/topics过滤条件重新订阅,并在追赶期间缓冲传入的实时事件。缓冲区必须有界;若溢出或追赶失败,停止推进检查点,改从持久化状态继续,不要静默丢弃事件。 - 订阅后,针对这次追赶调用一次
eth_getBlockByNumber("latest", false),记录其编号与哈希作为固定上界(catchup_to_block)。不要等日志通知才决定上界,也不要在分段之间移动latest标签。 - 用相同过滤条件,从
fromBlock: last_processed_block到固定的toBlock: catchup_to_block含端点重放检查点区块。含端点的重放覆盖在该区块中途断线的情况。按GET /v1/chains中网络的max_logs_block_range将区间切成不超限的分段。 - 按
(blockHash, transactionHash, logIndex)对重放日志和缓冲的实时事件去重。只有整段连续重放成功,且其效果与检查点都已持久化提交后,才推进检查点;失败时保留之前已提交的检查点。仅收到一条实时日志永远不会推进这条恢复边界。 - 将保存的区块哈希与链比对以发现 reorg。不一致时须回滚到已知共同祖先并重放;仅靠去重不会执行回滚。
- 将
- 通过
eth_getBlockByNumber补全区块头:- 记录断线前收到的最新区块高度与哈希。
- 重新订阅
newHeads。 - 调用
eth_getBlockByNumber("latest", false)确认当前高度;若存在缺失高度,按顺序拉取中间区块头并核对parentHash链连续性以排查可能发生的分叉重组。
限制与配额
| 限额 | 数值 | 超出时的结果 |
|---|---|---|
| 单个 WebSocket 连接订阅数 | 100 | -32022 subscription_limit |
单个 WebSocket 连接 newHeads 订阅数 | 4 | -32022 subscription_limit |
logs 订阅过滤条件要求 | 必须指定 address 或 topic0(topics 的首个位置) | -32602 logs_filter_required |
下一步
最后更新: