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 Onewss://api.blockvectra.com/v1/arb_mainnet/{api_key}
Arcwss://api.blockvectra.com/v1/arc_mainnet/{api_key}
Avalanche C-Chainwss://api.blockvectra.com/v1/avax_mainnet/{api_key}
Basewss://api.blockvectra.com/v1/base_mainnet/{api_key}
Berachainwss://api.blockvectra.com/v1/berachain_mainnet/{api_key}
Bobawss://api.blockvectra.com/v1/boba_mainnet/{api_key}
BNB Smart Chainwss://api.blockvectra.com/v1/bsc_mainnet/{api_key}
Celowss://api.blockvectra.com/v1/celo_mainnet/{api_key}
以太坊wss://api.blockvectra.com/v1/eth_mainnet/{api_key}
Ethereum Sepoliawss://api.blockvectra.com/v1/eth_sepolia/{api_key}
Fraxtalwss://api.blockvectra.com/v1/fraxtal_mainnet/{api_key}
Gnosiswss://api.blockvectra.com/v1/gnosis_mainnet/{api_key}
HyperEVMwss://api.blockvectra.com/v1/hyperevm_mainnet/{api_key}
Inkwss://api.blockvectra.com/v1/ink_mainnet/{api_key}
Katanawss://api.blockvectra.com/v1/katana_mainnet/{api_key}
Lineawss://api.blockvectra.com/v1/linea_mainnet/{api_key}
Metal L2wss://api.blockvectra.com/v1/metall2_mainnet/{api_key}
Modewss://api.blockvectra.com/v1/mode_mainnet/{api_key}
OP Mainnetwss://api.blockvectra.com/v1/op_mainnet/{api_key}
Polygonwss://api.blockvectra.com/v1/polygon_mainnet/{api_key}
Robinhood Chainwss://api.blockvectra.com/v1/robinhood_mainnet/{api_key}
Robinhood Chain Testnetwss://api.blockvectra.com/v1/robinhood_testnet/{api_key}
Rootstockwss://api.blockvectra.com/v1/rootstock_mainnet/{api_key}
Soneiumwss://api.blockvectra.com/v1/soneium_mainnet/{api_key}
Sonicwss://api.blockvectra.com/v1/sonic_mainnet/{api_key}
Unichainwss://api.blockvectra.com/v1/unichain_mainnet/{api_key}
World Chainwss://api.blockvectra.com/v1/world_mainnet/{api_key}
X Layerwss://api.blockvectra.com/v1/xlayer_mainnet/{api_key}
Zorawss://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 帧。下表列出服务端发出的关闭码及建议的处理方式:

关闭码原因字符串描述能否重试客户端动作
1001idle连接在 3600 秒(1 小时)内无活跃订阅且未收到任何消息是按需重新连接。
1003binary frames are not accepted客户端发送了二进制帧;服务端仅接收 UTF-8 文本帧否不要自动重连。修改客户端以发送纯文本帧。
1009message too large客户端入站消息超过 1 MiB 限制否不要自动重连。拆分大请求或缩减请求体大小。
1012service restart服务端维护重启,或单连接已达最长生命周期(24 小时)是使用带随机抖动的退避策略重连,重新建立订阅并补全数据。
1013chain unavailable链停止接受 WebSocket 会话是使用带全抖动的指数退避重连,重建订阅并通过 eth_getLogs 补全数据。
1013overloaded服务端临时过载是使用带全抖动的指数退避重连,重建订阅并通过 eth_getLogs 补全数据。
4402insufficient balance账户预付余额已耗尽否不要自动重连。充值后再重连。
4404invalid api keyAPI key 未知、已停用或已吊销否不要自动重连。在控制台检查并更换有效的 API key。
4408slow consumer会话推送队列超过 512 KiB 时服务端关闭连接并丢弃待发通知;客户端可能收不到关闭帧(浏览器报 1006)是意外断开(没收到关闭帧,浏览器报 1006)按 4408 处理:退避重连,并减少订阅或加快读取;重新建立订阅并通过 eth_getLogs 补全数据。
4429push rate exceeded推送频率超过 1,000 次/秒是减少订阅数或收窄过滤条件;带退避重连后重建订阅并补全数据。
4503billing 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 订阅状态不跨连接持久化;断线期间产生的推送通知不会在服务端保留。客户端重连成功后,应实施补全:

  1. 通过 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。不一致时须回滚到已知共同祖先并重放;仅靠去重不会执行回滚。
  2. 通过 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

下一步

最后更新:

本页目录