JSON-RPC

概述复制锚点链接

每条受支持链上的 JSON-RPC 2.0 访问都通过 BlockVectra 网关计量。所有请求按 计算单位（CU） 计量，并按 key 进行限流。

• 入口：POST /v1/{chain}/{api_key}（key 放在路径中）或 POST /v1/{chain}（key 放在请求头中）。Robinhood Chain 的 {chain} 是 robinhood_mainnet：https://dev-api.blockvectra.network/v1/robinhood_mainnet。同一个 API key 可用于所有已支持的链
• 协议：HTTP POST，单个调用或批量（最多 100 个调用）
• 计量：请求到达时，其全部 CU 开销立即计入该 key 的突发容量；每个被受理并得到应答的调用按该方法公布的 CU 权重计费，不计费的情况见错误码表的「是否计费」列。按小时账期结算扣费（向下取整为整单位，余数结转下一期，账期结束约 15 分钟后执行）
• 可用性：可用方法因链而异。Robinhood Chain 上为 eth_*、net_*、web3_*、debug_trace*（有部分例外，见下文）。其他链见支持的链。
• 以太坊（Beta）：有自己的方法清单，只保留最近约 36 天的数据，见支持的链 → 以太坊。

接入方式复制锚点链接

1. 申请 API Key复制锚点链接

参考快速上手 → 申请 API Key。

2. 调用 JSON-RPC复制锚点链接

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -X POST "https://dev-api.blockvectra.network/v1/robinhood_mainnet/$BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Key 传递方式（优先级顺序）：

• URL 路径：POST /v1/{chain}/{api_key}
• POST /v1/{chain} 的请求头：x-api-key: {api_key}（如果非空，覆盖 Bearer）
• POST /v1/{chain} 的请求头：Authorization: Bearer {api_key}

3. 处理 CU 成本复制锚点链接

每个方法都有对应的 CU（计算单位）权重，请求的成本是其包含的所有调用权重之和。各方法权重与默认值见下方 CU 权重表；具体哪些错误会计费见错误码表的「是否计费」列。用量按账户、按小时账期汇总扣费，向下取整为整计费单位（1 计费单位 = 1000 CU），未满 1 单位的余数结转到下一期（跨期合计扣费等于 floor(累计 CU / 1000)）；结算在账期结束约 15 分钟后执行（例如上期结转 508 CU，本期消耗 2557 CU，合计 3065 CU，本期扣除 3 个计费单位，余数 65 CU 结转至下一期）。

常用调用示例复制锚点链接

常用调用的完整示例。

日志查询（eth_getLogs）复制锚点链接

按合约地址和 topic 过滤最近一段区块的日志——这里以 ERC-20 的 Transfer 事件（topic 为 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef）为例。eth_getLogs 的当前 CU 权重见下方CU 计量规则表；网关会拒绝任何超过该链 eth_getLogs 跨度上限的请求。Robinhood Chain 上该上限为 1000 个区块（-32602 eth_getLogs block range too large: max 1000 blocks）；其他链见支持的链。

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -X POST "https://dev-api.blockvectra.network/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [{
      "fromBlock": "0x45a2409",
      "toBlock": "0x45a2609",
      "address": "0x1111111111111111111111111111111111111111",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }],
    "id": 1
  }'

交易 Trace（debug_traceTransaction）复制锚点链接

用 callTracer 追踪一笔交易的内部调用。debug_trace* 的当前 CU 权重见下方CU 计量规则表。和其他读状态的方法一样，目标区块若超出该链的近期状态窗口就会被拒绝（-32011）。Robinhood Chain 上窗口为链头减 900 个区块；其他链见支持的链。在提供 trace 的链上，历史 trace 请使用 Data API。

注意：待追踪的交易必须处于该链的近期状态窗口内（Robinhood Chain 上约最近 900 个区块，即仅数分钟）；更早的交易会返回 -32011（historical state is not available beyond the most recent 900 blocks）。

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -X POST "https://dev-api.blockvectra.network/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": ["0xYOUR_TRANSACTION_HASH", {"tracer": "callTracer"}],
    "id": 1
  }'

批量请求复制锚点链接

把多个调用合并到一次请求里——不超过前文已经提到的批量上限（每个请求最多 100 个调用）。下面的示例在一次往返里读取区块高度、链 ID 与 gas 价格。

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -X POST "https://dev-api.blockvectra.network/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '[
    {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1},
    {"jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 2},
    {"jsonrpc": "2.0", "method": "eth_gasPrice", "params": [], "id": 3}
  ]'

如果网关直接拒绝整个批量请求——余额不足、限流、突发容量超限，或超过 100 个调用（见下方错误码表）——它会返回一个单独的 JSON-RPC 错误对象而不是数组；此时 viem 的 batch: true 模式只会报出一个不透明的 UnknownRpcError，请改为单独重试一次调用以查看真实错误。

CU 计量规则复制锚点链接

方法策略复制锚点链接

可用方法因链而异，下面按链分别列出，其他说明见支持的链。只有匹配允许的方法名或模式的方法才可调用；其中一部分方法即使匹配了允许模式，仍会被显式拦截（返回 -32601 method not available）。

限制：

• 批量：每个请求最多 100 个调用；同时受该 key 的 CU 突发容量限制，见下文。
• 请求体：最大 2 MiB
• CU 突发：每个 API key 均有 CU 令牌桶（cu_per_sec 补充速率、burst_cu 突发容量——默认 100 CU/s、突发 400 CU；在控制台 Keys 表按 key 显示）。单个请求（包括整批 JSON-RPC 批量调用）的 CU 总开销若超过该 key 的突发容量，会被拒绝并返回 -32022 request_exceeds_burst（request cost <N> CU exceeds burst capacity <M> CU）；请拆分为更小的批次。

错误码表复制锚点链接

完整 OpenAPI 参考复制锚点链接

完整的机器可读规范（含所有方法签名、请求与响应 schema 及交互式参数详情）见完整 OpenAPI 参考。