一个 key 切链：把示例从一条链换到另一条链

同一个 API key 适用于所有支持的链。了解 URL 路径结构、程序化发现链能力，以及跨链共用余额与限流。

1. 一个 key 适用于所有链

同一个 API key 适用于所有支持链的 JSON-RPC；Data API 在已开放的链上可用。key 属于账户，不绑定特定链，无需为每条链单独申请 key。

服务额度和限流在所有网络之间、以及 JSON-RPC API 与 Data API 之间共用，不按网络区分。具体计费规则见定价页。

余额跨链合计：账户充值与免费额度在所有链之间共用，所有链上的调用消耗同一账户余额。
限流跨链合计：同一个 key 的 CU 速率与突发容量跨链共用；免费套餐每秒调用次数上限在所有支持链上合计计算，不分链拆算。
升级路径：充值后不再受免费套餐的每秒调用次数上限约束；每个 key 仍有 CU 速率与突发上限，见 JSON-RPC 文档。

2. URL 结构与链名位置

所有链相关请求都在 URL 中通过 {chain} 标明目标网络。{chain} 是全小写的链标识符（例如 robinhood_mainnet）。

服务类型	鉴权方式	URL 模板	说明
JSON-RPC	key 放在路径中	`POST /v1/{chain}/{api_key}`	key 直接作为 URL 路径段
JSON-RPC	key 放在请求头中	`POST /v1/{chain}`	在 `x-api-key: {api_key}` 请求头中传入 key
Data API	REST 路由	`GET /v1/data/{chain}/…`	在 `x-api-key: {api_key}` 请求头中传入 key
公开链列表	免鉴权	`GET /v1/chains`	返回公开链列表与各链静态参数（不计费、不限流）
公开服务状态	免鉴权	`GET /v1/status`	返回各链运行状态与链头（不计费、不限流）

GET /v1/chains 会返回每条链的 jsonrpc 与 data 两个布尔字段：jsonrpc 为 true 的链用 JSON-RPC 地址，data 为 true 的链用 GET /v1/data/{chain}/…（Data API 只在这些链上提供）。

提示：用请求头传 key 时，URL 以链名结尾，不带结尾斜杠。JSON-RPC 仅在 /v1/{chain} 和 /v1/{chain}/{api_key} 两种路径上提供；带结尾斜杠（如 /v1/{chain}/）或不带链段的请求返回 HTTP 404 且响应体为空。向未知 {chain} 发起的请求返回 HTTP 404 与 error.data.reason: "unknown_chain"（在读取请求体和检查 key 之前判定，不计费且不占限流）。

3. 程序化发现链与可用能力

支持的链与各链能力是动态提供的，请不要在应用里硬编码链列表。可通过公开端点在运行时查询链名与能力：

通过 `GET /v1/chains` 查询静态参数

该端点无需鉴权、不计费、不限流，返回各已公开链及其参数：

GET /v1/chains

响应示例（来自规格）：

{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "methods": {
        "allow": ["eth_*", "net_*", "web3_*", "debug_trace*"],
        "deny": ["eth_newFilter", "eth_newBlockFilter", "eth_newPendingTransactionFilter", "eth_getFilterLogs", "eth_getFilterChanges", "eth_uninstallFilter", "eth_subscribe", "eth_unsubscribe"]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 900,
      "info": {}
    }
  ]
}

字段说明：

chain：链标识符（slug，传给 URL 中的 {chain}）
name：人类可读显示名
chain_id：EIP-155 链 ID
jsonrpc：是否对外提供 JSON-RPC 服务
data：是否对外提供 Data API 服务
methods：该链的 JSON-RPC 方法策略，包含 allow（允许的方法或前缀通配符）与 deny（明确拒绝的方法列表）
max_logs_block_range：单次 eth_getLogs 请求允许的最大区块跨度
state_window_blocks：历史状态窗口大小（区块数）；全历史链为 null
info：扩展信息对象

通过 `GET /v1/status` 查询运行状态

该端点无需鉴权、不计费、不限流，反映服务就绪状态与各链链头：

GET /v1/status

响应示例（来自规格）：

{
  "checked_at": "2026-09-28T12:00:00Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "data_features": ["blocks", "transactions", "address_transactions", "transfers", "token_metadata", "freshness"],
      "status": "ok",
      "head": {
        "block": 73017329,
        "time": "2026-09-28T11:59:58Z",
        "lag_seconds": 2
      }
    }
  ]
}

字段说明：

gateway.status：底层接入服务当前是否就绪（ok 或 degraded）
chains[].data_features：Data API 为该链提供的能力列表
chains[].status：该链的节点状态（ok 或 unavailable）
chains[].head：最近一次成功轮询的链头信息（block、time、lag_seconds）

4. 切链时需要注意的差异

各链在规格与 /v1/chains 字段中体现的差异如下：

方法允许与拒绝策略（methods.allow / methods.deny）：不同链支持的 JSON-RPC 方法集合由其方法策略决定。若请求了该链不允许的方法，返回 HTTP 200 与 JSON-RPC 错误码 -32601（method not available，不计费）。
日志区块跨度（max_logs_block_range）：单次 eth_getLogs 允许跨越的区块数量因链而异。超出该链上限时返回 HTTP 200 与 JSON-RPC 错误码 -32602（eth_getLogs block range too large，不计费）。
历史状态窗口（state_window_blocks）：全历史链该字段为 null；若链设有状态保留窗口，查询超出窗口范围的历史状态将返回 HTTP 200 与 JSON-RPC 错误码 -32011（historical state is not available beyond the most recent <N> blocks，不计费）。
Data API 特性与覆盖（data / data_features）：提供该数据集的链以支持的链页面为准。请求该链未支持的数据集或超出历史覆盖范围的数据时，Data API 返回 HTTP 422（error.code 为 no_coverage，不计费）。服务暂时不可用（例如某条链繁忙）时，返回 HTTP 503（带 Retry-After，不计费）。

5. 跨链调用示例代码

同一段代码只需修改链名变量（或从 GET /v1/chains 动态获取），即可在两条链上分别发起 JSON-RPC eth_blockNumber 调用与 Data API 数据新鲜度端点查询：

export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 修改链名变量即可切换网络，例如换为支持的链里的任一 {chain}
CHAIN="robinhood_mainnet"

# 1. JSON-RPC: 调用 eth_blockNumber（POST /v1/{chain}，key 放在 x-api-key 请求头）
# 默认链端点以链名结尾；把最后一段替换为 $CHAIN。
RPC_URL="https://dev-api.blockvectra.network/v1/robinhood_mainnet"
RPC_URL="${RPC_URL%/*}/$CHAIN"
curl -s "$RPC_URL" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 2. Data API: 查询该链数据新鲜度 (GET /v1/data/{chain}/status/freshness)
curl -s "https://dev-api.blockvectra.network/v1/data/$CHAIN/status/freshness" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

示例响应（来自规格）

JSON-RPC eth_blockNumber 成功响应（按方法权重计费）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45a27f1"
}

Data API GET /v1/data/{chain}/status/freshness 成功响应（按 CU 计费，仅对 2xx 成功响应计费）：

{
  "data": [
    {
      "dataset": "blocks",
      "category": "raw",
      "max_block_number": 72313256,
      "max_day": null,
      "max_time": "2026-09-28T03:41:07Z",
      "seconds_behind": 0,
      "blocks_behind": 0,
      "days_behind": null,
      "checked_at": "2026-09-28T03:41:10Z"
    },
    {
      "dataset": "traces",
      "category": "raw",
      "max_block_number": 72313256,
      "max_day": null,
      "max_time": "2026-09-28T03:41:07Z",
      "seconds_behind": 0,
      "blocks_behind": 0,
      "days_behind": null,
      "coverage_from_block": 72050949,
      "coverage_to_block": 72313256,
      "coverage_complete": true,
      "checked_at": "2026-09-28T03:41:10Z"
    },
    {
      "dataset": "dex_prices",
      "category": "derived",
      "max_block_number": null,
      "max_day": "2026-09-27",
      "max_time": "2026-09-27T00:00:00Z",
      "seconds_behind": 99667,
      "blocks_behind": null,
      "days_behind": 1,
      "checked_at": "2026-09-28T03:41:10Z"
    }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72313256,
    "finalized_block": 72313000,
    "coverage": "full",
    "refreshed_at": "2026-09-28T03:41:10Z"
  }
}

一个 key 切链：把示例从一条链换到另一条链

1. 一个 key 适用于所有链复制锚点链接

2. URL 结构与链名位置复制锚点链接

3. 程序化发现链与可用能力复制锚点链接

通过 GET /v1/chains 查询静态参数复制锚点链接

通过 GET /v1/status 查询运行状态复制锚点链接

4. 切链时需要注意的差异复制锚点链接

5. 跨链调用示例代码复制锚点链接

示例响应（来自规格）复制锚点链接

本页目录