WebSocket 订阅使用指南

BlockVectra 提供基于 TLS 的安全 WebSocket（wss://）连接，支持在单一长连接中处理实时以太坊事件订阅与标准 JSON-RPC 2.0 请求。

可用链

WebSocket 支持按链动态开放。客户端可通过公开的 GET /v1/chains 端点读取每个网络的 ws（布尔值）和 subscriptions（支持的订阅类型数组）确认实时状态。

下表列出当前已启用 WebSocket 的网络：

连接与鉴权

客户端通过标准 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} 请求头。

握手阶段准入检查

在建立 WebSocket 会话前，服务端会在 HTTP 升级握手阶段进行准入校验：

• 身份认证：未提供 API key 返回 HTTP 401（missing_api_key）；key 未知、已停用或已吊销返回 HTTP 401（invalid_api_key）；若服务端 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 文本帧格式的订阅控制方法。

订阅方法

服务端支持以太坊标准的发布/订阅接口：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}

运行示例

import { createPublicClient, webSocket } from 'viem';

const apiKey = process.env.BLOCKVECTRA_API_KEY || '{api_key}';
const url = `wss://api.blockvectra.com/v1/{chain}/${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 帧。下表列出服务端发出的关闭码及建议的处理方式：

断线重连与指数退避

当服务端重启或网络断开时，为避免大量客户端同时重连导致流量洪峰，客户端必须遵循 API 规格 §15.4 要求的全抖动（full jitter）指数退避算法：

• 退避公式：在第 n 次重试连接前（n = 0, 1, 2, ...），在区间内均匀随机选择等待时长：

  复制文字

  delay = random(0, min(20s, 0.5s * 2^n))

• 参数规格（API 规格 §15.4）：
  • 初始基础退避：0.5 s（0.5 s * 2^0 = 0.5 s）
  • 指数倍增乘数：2^n（0.5 s、1.0 s、2.0 s、4.0 s……）
  • 最大退避上限：20 s
  • 全抖动（Full jitter）：在 0 到 min(20 s, 0.5 s * 2^n) 之间均匀选取伪随机值
  • 重置计数器：仅在会话持续稳定保持连接至少 60 秒 后，才将重试计数 n 重置为 0
  • 关闭码 1012：首次重试时引入随机初始延迟，避免集群重启时所有连接同步打散
  • 不可重连关闭码：遇到 4402、4404、1003 或 1009 时禁止自动重连。
  • 意外断开：意外断开（没收到关闭帧，浏览器报 1006）按 4408 处理：退避重连，并减少订阅或加快读取。

断线后的数据补全策略

WebSocket 订阅状态不跨连接持久化；断线期间产生的推送通知不会在服务端保留。客户端重连成功后，应按 API 规格 §15.5 实施补全：

1. 通过 eth_getLogs 补全日志：
   • 持久化记录已处理并提交的最高区块高度（last_processed_block）。
   • 重连成功后立即调用 eth_subscribe("logs", ...) 恢复实时日志接收。
   • 调用 eth_getLogs 查询断线区间：设置 fromBlock 为 last_processed_block + 1，toBlock 为 "latest"（或新订阅收到的第一条通知区块），保持地址与主题过滤条件一致。
   • 若断线跨度超过 1,000 个区块（受限于 max_logs_block_range: 1000），将查询切分为每个最多 1,000 区块的连续批次。
   • 以 (blockHash, transactionHash, logIndex) 三元组对补全日志与实时通知进行边界去重。
2. 通过 eth_getBlockByNumber 补全区块头：
   • 记录断线前收到的最新区块高度与哈希。
   • 重新订阅 newHeads。
   • 调用 eth_getBlockByNumber("latest", false) 确认当前高度；若存在缺失高度，按顺序拉取中间区块头并核对 parentHash 链连续性以排查可能发生的分叉重组。

限制与配额

下一步

• 浏览数据集目录，查看 BlockVectra 索引的全部数据集。
• 查看免费额度与定价，确认账户可用的方案。
• 登录控制台创建 API key。