快速上手

开发者与 AI Agent 都可以先调用免 key 公开 RPC，再创建 key 继续使用。

1. 免 key 读取区块高度

无需注册账号或创建 API key，直接调用示例链的公开 JSON-RPC 端点：

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

响应中的 id: 1 对应本次请求；result 是十六进制区块高度，每次调用可能不同。若返回 error，查看错误码与原因。公开方法、历史范围与按 IP 限额见免费公共 RPC 节点。

2. 创建 API key

前往控制台，用 GitHub、Google 或以太坊钱包登录（首次登录自动开户），然后创建 API key。创建时 secret 只显示一次，请立即妥善保存，并设置为环境变量 BLOCKVECTRA_API_KEY。不要把 key 放进浏览器前端代码。新账户注册即得 30,000,000 CU，无需信用卡。

3. 发出首个带 key 的调用

使用 x-api-key 请求头读取同一条链的区块高度。URL 以链名结尾，不带结尾斜杠：

: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

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

result 仍是十六进制区块高度。此请求按 CU 计费；方法权重与错误码见 JSON-RPC 参考，当前价格见定价。新建 key 约 5 秒后生效；若收到 invalid_api_key，稍等重试。其他失败见下方常见错误。

4. 继续完成业务任务

• 查询 Robinhood Chain 上的股票代币活动
• 分段回填 HyperEVM 日志
• 通过 Webhook 接收钱包活动与代币转账

参考

API key 与余额

完整模板仓库：blockvectra/agent-quickstart

key 的样子是 rgw_ 加 64 位十六进制字符，例如 rgw_1f2e...（已截断）。请保管好， 拿到 key 的任何人都能消耗你的余额。

# 直接调用公开端点：
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 或使用环境变量回退写法（未设置 BLOCKVECTRA_API_KEY 时自动回退至 public）：
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/${BLOCKVECTRA_API_KEY:-public}" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

下面两个公开元数据接口可查看服务状态与各链配置，免鉴权、不计费。

检查服务与各链健康状态

curl https://api.blockvectra.com/v1/status

返回包含检查时间戳 checked_at、服务运行状态 gateway.status，以及各支持链的节点同步进度 sync、链头高度与延迟 head：

{
  "checked_at": "2026-10-03T13:30:47Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "bsc_mainnet",
      "name": "BNB Smart Chain",
      "chain_id": 56,
      "jsonrpc": true,
      "data": true,
      "data_features": [
        "blocks",
        "transactions",
        "address_transactions",
        "transfers",
        "token_metadata",
        "freshness"
      ],
      "data_status": "ok",
      "data_head_block": 125492675,
      "data_head_age_seconds": 3,
      "status": "ok",
      "sync": {
        "stage": "synced",
        "node_block": 125492676,
        "target_block": null
      },
      "head": {
        "block": 125492676,
        "time": "2026-10-03T13:30:45Z",
        "lag_seconds": 2
      }
    }
  ]
}

查询支持的链与方法策略

curl https://api.blockvectra.com/v1/chains

返回所有支持链的 Chain ID、JSON-RPC / Data API / WebSocket 能力标识、方法开放与禁用策略（methods.allow 与 methods.deny）、日志单次查询区间上限 max_logs_block_range，以及历史状态窗口 state_window_blocks：

{
  "chains": [
    {
      "chain": "bsc_mainnet",
      "name": "BNB Smart Chain",
      "chain_id": 56,
      "jsonrpc": true,
      "data": true,
      "ws": false,
      "subscriptions": [],
      "methods": {
        "allow": [
          "eth_blockNumber",
          "eth_call",
          "eth_chainId",
          "eth_getLogs"
        ],
        "deny": [
          "eth_newFilter",
          "eth_subscribe",
          "eth_unsubscribe"
        ]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 100,
      "info": {}
    }
  ]
}

选择链

BlockVectra 的每个端点都按链区分：JSON-RPC 请求在 URL 路径中带上链名 {chain}，Data API 请求则在路由前加上链名。当前已开放的链及对应链名见支持的链。

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/arb_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/arb_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/arb_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/arb_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/base_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/base_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/base_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/base_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/bsc_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/bsc_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/bsc_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/bsc_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/eth_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/eth_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/eth_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/eth_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/eth_sepolia' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/eth_sepolia' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/eth_sepolia/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/eth_sepolia'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/fraxtal_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/fraxtal_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/fraxtal_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/hyperevm_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/hyperevm_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/hyperevm_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/hyperevm_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/ink_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/ink_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/ink_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/katana_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/katana_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/katana_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/polygon_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/polygon_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/polygon_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/polygon_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/robinhood_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/robinhood_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

curl -fsS 'https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/robinhood_mainnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/robinhood_testnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/robinhood_testnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/robinhood_testnet'

set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/unichain_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/unichain_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"

echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/unichain_mainnet'

JSON-RPC 端点示例随示例链选择切换。下文的 Data API 示例使用 robinhood_mainnet。

提示：先在上表中选择支持示例所需服务、方法与历史窗口的链，再把示例 URL 中的 robinhood_mainnet 换成它的 {chain}。同一个 API key 适用于所有支持的链。

其他认证方式与语言示例

JSON-RPC 端点按链区分：POST /v1/{chain}/{api_key}（key 放在路径中），或 POST /v1/{chain}（key 放在 x-api-key 请求头中）。{chain} 是链名，与 Data API 使用的链名相同；示例端点是 https://api.blockvectra.com/v1/robinhood_mainnet。通过 HTTP 调用 eth_subscribe 返回 -32601；各链的 WebSocket 订阅支持情况见支持的链。虽然 API 返回了 Access-Control-Allow-Origin: *，但请妥善保管 API key，端点设计为由后端服务调用，而非在浏览器前端代码中直接暴露 key。

key 有三种传法：放在 URL 路径中（POST /v1/{chain}/{api_key}，只使用路径中的 key，忽略两个请求头）、放在 x-api-key 请求头中，或放在 Authorization: Bearer <api_key> 请求头中。

key 放在 URL 路径中

: "${BLOCKVECTRA_API_KEY:?先设置 BLOCKVECTRA_API_KEY}"

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

key 放在请求头中

: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

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

Authorization: Bearer <api_key> 请求头同样有效。在 POST /v1/{chain} 上，非空的 x-api-key 优先于 Bearer；只有 x-api-key 缺失或为空时才使用 Bearer。路径传法忽略两个请求头。

批量调用

传一个数组即可在一次请求里发起多个调用（单批最多 100 个）。注意每个 API key 都有一个 CU 令牌桶（cu_per_sec 补充速率、burst_cu 突发容量——默认 100 CU/s、突发 400 CU；付费充值后每个 key 至少 2,000 CU/s、突发 10,000 CU，更高的自定义限额保持不变；在控制台 Keys 表按 key 显示）；单个请求（包括整批 JSON-RPC 批量调用）若总 CU 超过该 key 的突发容量，即使未达到 100 个调用的上限也会被拒绝并返回 -32022 request_exceeds_burst；需拆分为较小的批次。下面这个例子在一次往返里 同时读取链 ID 和某个地址的余额：

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '[
    {"jsonrpc":"2.0","id":1,"method":"eth_chainId"},
    {"jsonrpc":"2.0","id":2,"method":"eth_getBalance","params":["0x1111111111111111111111111111111111111111","latest"]}
  ]'

响应是一个数组，顺序与请求一致，按 id 对应。

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

了解 CU 计量

每个被计费的调用都会消耗一定的 CU（Compute Unit）：便宜的调用比如 eth_blockNumber、 eth_chainId 最便宜；常见读取比如 eth_getBlockByNumber 稍贵；较重的调用比如 eth_call、eth_getLogs 更贵；执行跟踪方法（如 debug_traceTransaction）最贵。 结算按账户、按小时账期汇总扣费，向下取整为整计费单位（1 计费单位 = 1,000 CU），未满 1 单位的余数结转到下一期（跨期合计扣费为 floor(累计 CU / 1,000)）；结算在账期结束约 15 分钟后执行。例如：上期结转 508 CU，本期消耗 2557 CU，合计 3065 CU，本期扣除 3 个计费单位，余数 65 CU 继续结转至下一期。当前价格见定价。

完整的方法权重表与错误码见 API 参考 → JSON-RPC； 本页只演示请求的基本形态。

常见错误

对于使用 key 鉴权的 JSON-RPC 请求，在这两项限额检查中，先检查免费套餐调用数，再检查 key 的 CU 突发容量；若两项都超限，reason 为 free_plan_batch_too_large。两种 -32022 拒绝都不带 Retry-After，应拆分请求，而非原样重试。

以上这些拒绝一律不计费；每个被受理并得到应答的调用按公布的 CU 权重计费，不计费的情况见错误码表的「是否计费」列。

调用 Data API

Data API 把只读链数据（区块、交易、余额、持有者、DEX 活动等）包装成 REST/JSON 接口。除 GET https://api.blockvectra.com/v1/data/chains 外，所有路由都带链标识前缀：下面路径中的 robinhood_mainnet 就是链标识（即 /chains 和 meta 中的 chain 字段）。GET https://api.blockvectra.com/v1/data/chains 仅列出已公开的链，只返回 {"data": [...]}（没有 meta，也没有 next_cursor）。请求按 CU 计费（仅对 2xx 成功响应计费）。

每次请求需要带与 JSON-RPC 相同的 API key——通过 x-api-key 请求头传递。链级成功响应包含 data（数据本体）和 meta（chain、chain_slug（chain 的大写形式）、chain_external_id、as_of_block、safe_block、finalized_block、coverage、refreshed_at；refreshed_at 可能为 null，表示这份数据的更新时间未知，应按过期处理，区块类接口始终有值）。支持分页的列表端点还可能返回 next_cursor（不透明字符串，不是 null）。将返回的游标原样传入后续请求，直到 next_cursor 不再出现；部分端点在返回满页时会给出乐观游标，下一页可能为空。具体端点的分页规则见 Data API 参考。每个错误响应一般是 {"error":{"code","message"}} 两个字段，仅 409 not_indexed_yet 额外带 indexed_through（已索引到的最高区块）；链未知或暂未公开时返回 HTTP 404，error.code 为 not_found（不计费；链名必须为全小写 slug）；API key 缺失、未知或被禁用时返回 HTTP 401，error.code 为 missing_api_key 或 invalid_api_key。超出限流时返回 HTTP 429（error.code 为 rate_limited，data.reason 为 key_rate_limit），余额耗尽时返回 HTTP 402（error.code 为 insufficient_balance），两者均不计费。超过 2^53 的数值（余额、代币数量）一律是十进制字符串，不是 JSON 数字。

按区块号查区块：

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/72838701" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": {
    "number": 72838701,
    "hash": "0x9f2c1e7a4b6d3f805e1c9a72b4d6f1e0a3c8b5d7e2f4a1c6b9d3e7f0a2c4b6d8",
    "parent_hash": "0x1a3c5e7f9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a",
    "timestamp": "2026-09-26T05:41:07Z",
    "miner": "0x00000000000000000000000000000000000a4b05",
    "gas_limit": 32000000,
    "gas_used": 4821932,
    "base_fee_per_gas": "100000000",
    "state_root": "0x2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d",
    "transactions_root": "0x3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e",
    "receipts_root": "0x4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f",
    "tx_count": 239,
    "size": 48213,
    "l1_block_number": null,
    "extra": {}
  },
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:03Z"
  }
}

高于已索引链头（as_of_block）的区块号返回 409（error.code: "not_indexed_yet"），indexed_through 会告诉你已索引到的最高区块——数据还没到，稍后重试即可。完全早于该链覆盖起点（coverage.from_block）的区块号返回 422（error.code: "no_coverage"）。在覆盖范围内，不高于 as_of_block 但没有对应行的区块号（从未索引过，或被 reorg 回滚）返回 404（error.code: "not_found"）。

查看数据新鲜度（每个被跟踪的数据集落后链头多少，适合做状态页或调用前的自检）：

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": [
    {
      "dataset": "blocks",
      "category": "raw",
      "max_block_number": 72838957,
      "max_day": null,
      "max_time": "2026-09-27T02:15:01Z",
      "seconds_behind": 0,
      "blocks_behind": null,
      "days_behind": null,
      "checked_at": "2026-09-27T02:15:07Z"
    }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:07Z"
  }
}

（示例已精简：实际响应每个数据集一行，这里只列出 blocks 这一行；traces 行还会额外带 coverage_from_block、coverage_to_block、coverage_complete。）

如果该链的新鲜度数据暂时不可用，会返回 503（error.code: "unavailable"），而不是返回不完整的结果；响应头带 Retry-After（秒）——请至少等待该时长后重试。

查询某地址的 ERC-20 余额（快照，只保留非零余额，按 token 排序）：

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/balances" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

{
  "data": [
    { "token": "0x0bd7d308f8e1639fab988df18a8011f41eacad73", "balance": "185371464119396", "symbol": "WETH", "decimals": 18 },
    { "token": "0x2295f15bd4914ae9b4685f01d52f4e6f89bf8b03", "balance": "10000000000000000", "symbol": "WNVDA", "decimals": 18 }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:10:00Z"
  }
}

没有任何非零余额的地址仍会返回 200 + data: []——不会是 404。可以传 ?limit=（默认 50，最大 500），并用返回的 next_cursor 翻页。

完整的端点覆盖——区块、交易、地址、代币、NFT、DEX、代币化股票——参见 API 参考 → Data API。

更多参考

• API 参考 → JSON-RPC —— 方法、CU 权重、错误码
• 完整 JSON-RPC 参考 —— 全部支持方法的完整规范、请求参数与返回格式
• API 参考 → Data API —— 链数据的 REST 接口
• 数据集 —— 各支持链上可用的派生数据集
• 指南 —— API 集成、CU 用量管理与多链工作流实战指南
• 支持的链 —— 网络标识符与端点 URL

常见问题