BlockVectra

快速上手

用 API key 调用 JSON-RPC 与 Data API。

本页只讲最少够用的内容：怎么拿到 API key、怎么用 curl 调用 JSON-RPC、Data API 请求长什么样。 内容依据 rpc-gateway（数据面）当前的真实行为，以及 chain-indexer Data API 的设计文档。

1. 获取 API key

控制台（自助管理 key）还没上线。目前由运营手工开户和发 key：前往官网的 获取 API key 页面，我们会为你开户。

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

2. 调用 JSON-RPC

所有 JSON-RPC 流量都经过同一个网关入口 https://dev-api.blockvectra.network/v1/。没有 WebSocket，也没有 CORS—— 这个入口是给后端调用的，不是给浏览器直接调用的。

key 有两种传法。

key 放在 URL 路径中

API_KEY="rgw_your_api_key"

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

key 放在请求头中

API_KEY="rgw_your_api_key"

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

别漏掉结尾的斜杠

用请求头传 key 时，路径必须是 https://dev-api.blockvectra.network/v1/——带结尾斜杠。少了这个斜杠会被 301 重定向到带斜杠的地址，而大多数 HTTP 客户端在跟随 301 时会把原来的 POST 变成 GET，随后请求失败。key 放在 URL 路径里则不受这个问题影响。

Authorization: Bearer <api_key> 请求头同样有效，在 x-api-key 缺失或为空时才会被使用； 两者都存在时，非空的 x-api-key 优先。

批量调用

传一个数组即可在一次请求里发起多个调用（单批最多 100 个）。下面这个例子在一次往返里 同时读取链 ID 和某个地址的余额：

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

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

3. 了解 CU 计量

每个被计费的调用都会消耗一定的 CU（Compute Unit）：便宜的调用比如 eth_blockNumber、 eth_chainId 只要 1 CU；常见读取比如 eth_getBlockByNumber 是几 CU；较重的调用比如 eth_call、eth_getLogs 更贵；debug_trace* 最贵。命中缓存的调用统一按 1 CU 计费。 结算按账户、按小时账期汇总：扣费 = floor(该账期内全部 CU / 1000)，具体单价尚未由业务侧确定。

完整的方法权重表、缓存规则与错误码会在 API 参考 → JSON-RPC 上线后提供； 本页只演示请求的基本形态。

常见错误

你做了什么会收到什么
key 缺失、未知或被禁用HTTP 404，空 body（网关不区分具体原因）
余额为零或为负HTTP 402，JSON-RPC 错误码 -32020
请求过于频繁，或单次请求超过了突发容量HTTP 429，JSON-RPC 错误码 -32005
调用了不被允许的方法（例如 eth_subscribe，或任何不在 eth_*/net_*/web3_*/debug_trace* 范围内的方法）HTTP 200，JSON-RPC 错误码 -32601，不计费
请求体不是合法 JSONHTTP 200，JSON-RPC 错误码 -32700，不计费
单批调用数超过 100HTTP 200，JSON-RPC 错误码 -32600（batch too large），不计费

以上这些网关侧的拒绝一律不计费；只有节点真正给出应答的调用才会计费。

4. 调用 Data API

Data API 把只读链数据（区块、交易、余额、持有者、DEX 活动等）包装成 REST/JSON 接口， 由 chain-indexer 的 serve-data 进程实现。它目前只监听回环地址（127.0.0.1:8546）， 经 rpc-gateway 转发后对外生效的路径前缀尚未最终确定。请始终使用环境中的 https://dev-api.blockvectra.network/v1，不要写死域名或前缀——转发接好之后它会自动指向正确的地址。

下面的路径（/blocks/{number}、/status/freshness、/addresses/{address}/balances） 是 serve-data 自身定义的真实路径。每个成功响应使用同一套信封：data（数据本体）、 next_cursor（只在有下一页时才出现，否则这个字段整个不存在，不是 null）、以及 meta（as_of_block、finalized_block、coverage、refreshed_at、已知时才有的 rows_read、query_ms）。每个错误响应都是 {"error":{"code","message"}}——只有这 两个字段。超过 2^53 的数值（余额、代币数量）一律是十进制字符串，不是 JSON 数字。

按区块号查区块：

curl -s "https://dev-api.blockvectra.network/v1/blocks/72838701"
{
  "data": {
    "number": 72838701,
    "hash": "0x9f2c1e7a4b6d3f805e1c9a72b4d6f1e0a3c8b5d7e2f4a1c6b9d3e7f0a2c4b6d8",
    "parent_hash": "0x1a3c5e7f9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a",
    "timestamp": "2026-09-26T05:41:07Z",
    "miner": "0x0000000000000000000000000000000000a4b05",
    "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": {
    "as_of_block": 72838957,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:03Z",
    "rows_read": 1,
    "query_ms": 4
  }
}

没有对应行的区块号（从未索引过，或被 reorg 回滚）返回 409 （error.code: "finality_exceeded",超出 finalized_block 时）或 404 （error.code: "not_found"，未超出但确实没有数据）；新鲜度水位落后索引头 256 块。

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

curl -s "https://dev-api.blockvectra.network/v1/status/freshness"
{
  "data": [
    {
      "database": "robinhood",
      "table_name": "blocks",
      "category": "chain",
      "key_kind": "block",
      "max_block_number": 72838957,
      "max_day": null,
      "max_time": "2026-09-27T02:15:01Z",
      "seconds_behind": 6,
      "blocks_behind": 0,
      "days_behind": null,
      "rows_estimate": 72838958,
      "bytes_estimate": 12345678901,
      "follow_last_block": 72838957,
      "follow_lag_blocks": 0,
      "trace_min_block": null,
      "trace_max_block": null,
      "trace_gap_ranges": null,
      "trace_gap_blocks": null,
      "checked_at": "2026-09-27T02:15:07Z"
    }
  ],
  "meta": {
    "as_of_block": 72838957,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:07Z",
    "query_ms": 412
  }
}

某个环境下如果 data_freshness 视图还没装上，会返回 422 （error.code: "dataset_not_installed"），而不是返回不完整的结果。

查询某地址的 ERC-20 余额（每 6 小时整体刷新一次的快照，只保留非零余额，按 token 排序）：

curl -s "https://dev-api.blockvectra.network/v1/addresses/0x1111111111111111111111111111111111111111/balances"
{
  "data": [
    { "token": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "balance": "500000000", "symbol": "WBTC", "decimals": 8 },
    { "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "balance": "1250000000", "symbol": "USDC", "decimals": 6 }
  ],
  "meta": {
    "as_of_block": 72838957,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:10:00Z",
    "rows_read": 2,
    "query_ms": 9
  }
}

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

完整的端点覆盖——区块、交易、地址、代币、NFT、DEX、代币化股票——会在 API 参考 → Data API 上线，由本页示例所依据的同一份钉版本 OpenAPI 生成。

接下来看什么

概览

Robinhood Chain 的 JSON-RPC 与 Data API 文档。

网络与端点

当前环境下的 chain_id 与各服务端点。

本页目录

1. 获取 API key2. 调用 JSON-RPCkey 放在 URL 路径中key 放在请求头中批量调用3. 了解 CU 计量常见错误4. 调用 Data API接下来看什么