# Blockchain Data API 接口参考

> 原文地址: https://docs.blockvectra.com/zh/api/data/

## 概述

用这份 Blockchain Data API 参考构造 REST 请求，查询已索引的区块、交易、地址、代币、NFT、DEX 活动、代币化股票与数据集新鲜度。选择数据集、检查链支持情况时先看[数据集目录](https://docs.blockvectra.com/zh/datasets/)；查询钱包代币余额与转账历史时参考[钱包资产教程](https://docs.blockvectra.com/zh/guides/wallet-assets/)。

* **基础 URL**：`https://api.blockvectra.com/v1/data`——除 `/chains` 外，所有路由都以链标识为前缀（如 `https://api.blockvectra.com/v1/data/{chain}/…`）
* **协议**：HTTP `GET`（批量查代币元数据 `/{chain}/tokens:batch` 用 `POST`），JSON 响应
* **认证**：需要 API key——在请求头 `x-api-key` 中传入你的 key。请求按 CU 计量与计费，仅对 2xx 成功响应计费
* **以太坊**：数据覆盖以 `GET /v1/data/chains` 的 `coverage.from_block` 为准，可用数据集也更少，见[支持的链 → 以太坊](https://docs.blockvectra.com/zh/chains/#以太坊)
* [TypeScript SDK (GitHub)](https://github.com/blockvectra/data-api-js#installation) · [DEX 日价示例](https://github.com/blockvectra/data-api-js/blob/fcf80e2b3d72e168ba9ffddf5eae89e5ee7e269c/README.md#daily-dex-prices) · [npm](https://www.npmjs.com/package/@blockvectra/data-api) · [WETH/USDG · robinhood\_mainnet · 2026-10-01 UTC](https://github.com/blockvectra/data-api-js/blob/0e24d26e9960469445a6fd8b590d1ec41265913f/README.md#historical-wethusdg-response) · [JSON](https://github.com/blockvectra/data-api-js/blob/0e24d26e9960469445a6fd8b590d1ec41265913f/docs/responses/dex-prices-robinhood-weth-usdg-2026-10-01.json)

```bash
npm install @blockvectra/data-api
```

需要按游标续传历史？[带检查点的 ERC-20 转账示例](https://github.com/blockvectra/data-api-js/blob/fa40d51e322fe94683b4f184289ce48e39ec825f/README.md#checkpointed-erc-20-transfers-one-page-per-run)每次运行保存一页及该页原始 `meta`；用相同的固定查询和状态文件重跑，即从原来的 opaque cursor 继续。分页耗尽不等于历史完整，请另行核对 `coverage`。仅支持 ERC-20。[安装预构建包](https://github.com/blockvectra/data-api-js/blob/fa40d51e322fe94683b4f184289ce48e39ec825f/README.md#install-the-prebuilt-package)即可直接运行，无需本地生成 schema 或从源码编译。

Data API 各操作的 CU 权重列于[定价页](https://blockvectra.com/zh/pricing/)，也可通过 `GET /v1/plans` 接口获取。具体请求与响应示例请参考[快速上手 → 调用 Data API](https://docs.blockvectra.com/zh/quickstart/#4-调用-data-api)。关于路径版本、向后兼容规则与对接建议，请参阅 [API 版本与兼容性](https://docs.blockvectra.com/zh/api/versioning/)。

## 链

Data API 按链提供索引数据：`https://api.blockvectra.com/v1/data/{chain}/…`。

各链支持的数据集与特性因链而异，完整支持矩阵见[支持的链](https://docs.blockvectra.com/zh/chains/)。`GET https://api.blockvectra.com/v1/data/chains` 会返回每条链的 `features`、`coverage`、`finality` 与 `limits`。请求超出数据集覆盖范围时返回 HTTP `422 no_coverage`（不计费）；请求未知或未公开的链名返回 HTTP `404`，`error.code` 为 `not_found`（不计费；链名必须为全小写 slug）。

## 错误

每个错误响应都是 `{"error":{"code","message"}}`；只有 `409 not_indexed_yet` 可能额外带 `indexed_through`（该链已索引到的最高区块）；当整条链尚无任何索引数据时该字段不存在。客户最常遇到的错误码：

| 状态码   | `error.code`           | 含义                                                                                                          | 建议操作                                                                                                             |
| ----- | ---------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `402` | `insufficient_balance` | 付费余额或免费额度已耗尽；余额已知时 error.data 附带 `balance_units` 与 `balance_cu`（不计费）                                        | 在控制台[账单页](https://console.blockvectra.com/billing/)进行链上充值，或等待免费额度补足                                              |
| `404` | `not_found`            | `{chain}` 未知或未公开，或对象不存在                                                                                     | 修正请求                                                                                                             |
| `409` | `not_indexed_yet`      | 请求超过最新已写入区块 `as_of_block`（附带 `indexed_through`）、哈希解析出的区块高于 `as_of_block`，或整条链尚无任何索引数据（不带 `indexed_through`） | 带 `indexed_through` 时轮询等待，直到区块号或 `to_block` 不高于它；不带时等待该链开始索引（`GET /v1/data/chains` 的 `coverage.has_data` 显示当前状态） |
| `422` | `no_coverage`          | 永久性缺口：该链不支持此能力，或区块早于索引/trace 覆盖范围                                                                           | 修改请求；重试不会成功                                                                                                      |
| `429` | `rate_limited`         | key 的 CU 速率超限（响应带 `Retry-After`）或账户调用速率超限（不带 `Retry-After`）；不计费                                             | 等待 `Retry-After` 秒后重试                                                                                            |
| `429` | `cost_exceeds_burst`   | 单个请求的 CU 超过该 key 的突发容量；不带 `Retry-After`（不计费）                                                                | 拆小请求；按原样重试永远不会成功                                                                                                 |
| `503` | `unavailable`          | 暂时不可用；响应带 `Retry-After`。当某条链的 `coverage.from_block` 暂为 `null` 时，对它的历史请求也返回此错误                               | 等待 `Retry-After` 秒后重试                                                                                            |
| `503` | `gateway_overloaded`   | 账户跨所有 key、所有链的并发请求达到上限，或服务暂时繁忙；带 `Retry-After: 1`（不计费）                                                      | 降低本账户的并发请求数，按 `Retry-After` 等待后重试                                                                                |

## 接口一览

### Chain

- GET /chains — 列出支持的链
- GET /{chain}/blocks/{number} — 按区块号获取区块
- GET /{chain}/blocks/hash/{hash} — 按哈希获取区块
- GET /{chain}/blocks/{number}/transactions — 列出区块的交易
- GET /{chain}/transactions/{hash} — 按哈希获取交易

### Status

- GET /{chain}/status/freshness — 各数据集的新鲜度与延迟

### Addresses

- GET /{chain}/addresses/{address}/transactions — 列出地址的交易
- GET /{chain}/addresses/{address}/transfers — 列出地址的代币转账
- GET /{chain}/addresses/{address}/balances — 列出地址的 ERC-20 余额

### Tokens

- GET /{chain}/tokens/{token}/transfers — 列出代币合约的转账
- GET /{chain}/tokens/{token}/holders — 列出代币的持有者
- GET /{chain}/tokens/{token} — 获取代币元数据
- POST /{chain}/tokens:batch — 批量获取代币元数据

### NFTs

- GET /{chain}/nfts/{contract}/{token_id} — 获取单个 NFT 的所有者/持有者
- GET /{chain}/nfts — 列出地址拥有的 NFT

### DEX

- GET /{chain}/dex/swaps — 按资金池或代币列出 DEX 兑换
- GET /{chain}/dex/prices — DEX 代币每日价格

### Stocks

- GET /{chain}/stocks — 代币化股票每日排行榜
- GET /{chain}/stocks/{token} — 获取单个代币化股票

### Traces

- GET /{chain}/blocks/{number}/traces — 整个区块的历史 callTracer 追踪树
- GET /{chain}/transactions/{hash}/trace — 单笔交易的历史 callTracer 追踪树