# Blockchain Data API 參考

> Source: https://docs.blockvectra.com/zh-hant/api/data/

## 概述

使用這份 Blockchain Data API 參考建構 REST 請求，查詢已索引的區塊、交易、地址、代幣、NFT、DEX 活動、代幣化股票與資料集新鮮度。選擇資料集並檢查鏈支援情況，請先參閱[資料集目錄](https://docs.blockvectra.com/en/datasets/)；查詢錢包代幣餘額與轉帳歷史，請依照[錢包資產指南](https://docs.blockvectra.com/zh-hant/guides/wallet-assets/)。

* **Base 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。請求按 Compute Units (CU) 計量與計費；僅對 2xx 成功回應計費
* **以太坊**：資料涵蓋範圍以 `GET /v1/data/chains` 中的 `coverage.from_block` 為準，且僅涵蓋較少資料集——請參閱[支援的鏈 → 以太坊](https://docs.blockvectra.com/zh-hant/chains/#ethereum)

Data API 的 CU 權重列於[定價](https://blockvectra.com/zh-hant/pricing/)頁面，也可透過 `GET /v1/plans` 取得。具體請求與回應結構範例請參閱[快速入門 → 呼叫 Data API](https://docs.blockvectra.com/zh-hant/quickstart/#4-call-the-data-api)。關於路徑版本控制、回溯相容性規則與 SDK 建議，請參閱 [API 版本控制與相容性](https://docs.blockvectra.com/en/api/versioning/)。

## 鏈

Data API 依每條鏈的範圍提供已索引資料：`https://api.blockvectra.com/v1/data/{chain}/…`。

可用資料集與功能因鏈而異；完整功能矩陣請參閱[支援的鏈](https://docs.blockvectra.com/zh-hant/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` 秒後重試                                                                                   |

## 端點一覽

以下為英文原規格。

<div lang="en">

### Chain

- GET /chains — List supported chains
- GET /{chain}/blocks/{number} — Get a block by number
- GET /{chain}/blocks/hash/{hash} — Get a block by hash
- GET /{chain}/blocks/{number}/transactions — List a block's transactions
- GET /{chain}/transactions/{hash} — Get a transaction by hash

### Status

- GET /{chain}/status/freshness — Freshness and lag per dataset

### Addresses

- GET /{chain}/addresses/{address}/transactions — List an address's transactions
- GET /{chain}/addresses/{address}/transfers — List an address's token transfers
- GET /{chain}/addresses/{address}/balances — List an address's ERC-20 balances

### Tokens

- GET /{chain}/tokens/{token}/transfers — List a token contract's transfers
- GET /{chain}/tokens/{token}/holders — List a token's holders
- GET /{chain}/tokens/{token} — Get token metadata
- POST /{chain}/tokens:batch — Batch get token metadata

### NFTs

- GET /{chain}/nfts/{contract}/{token_id} — Get one NFT's owner/holders
- GET /{chain}/nfts — List NFTs owned by an address

### DEX

- GET /{chain}/dex/swaps — List DEX swaps by pool or token
- GET /{chain}/dex/prices — Daily DEX token prices

### Stocks

- GET /{chain}/stocks — Daily leaderboard of tokenized stocks
- GET /{chain}/stocks/{token} — Get one tokenized stock

### Traces

- GET /{chain}/blocks/{number}/traces — Historical callTracer trace tree for a whole block
- GET /{chain}/transactions/{hash}/trace — Historical callTracer trace tree for one transaction

</div>