# Tài liệu tham khảo Blockchain Data API

> Source: https://docs.blockvectra.com/vi/api/data/

## Tổng quan

Sử dụng tài liệu tham khảo Blockchain Data API này để xây dựng các yêu cầu REST cho các khối, giao dịch, địa chỉ, token, NFT, hoạt động DEX, cổ phiếu token hóa đã được lập chỉ mục và độ tươi mới của bộ dữ liệu. Để chọn một bộ dữ liệu và kiểm tra tính khả dụng của chuỗi, hãy bắt đầu với [danh mục bộ dữ liệu](https://docs.blockvectra.com/en/datasets/); đối với số dư token và lịch sử chuyển tiền của ví, hãy làm theo [hướng dẫn tài sản ví](https://docs.blockvectra.com/vi/guides/wallet-assets/).

* **Base URL**: `https://api.blockvectra.com/v1/data` — mọi route ngoại trừ `/chains` đều có tiền tố là mã định danh chuỗi (ví dụ: `https://api.blockvectra.com/v1/data/{chain}/…`)
* **Giao thức**: HTTP `GET` (cùng với `POST` cho tra cứu token hàng loạt tại `/{chain}/tokens:batch`), phản hồi JSON
* **Xác thực**: Yêu cầu API key — truyền key của bạn trong header yêu cầu `x-api-key`. Các yêu cầu được đo lường và tính phí bằng Compute Units (CU); chỉ các phản hồi thành công 2xx mới bị tính phí
* **Ethereum**: phạm vi bao phủ dữ liệu được xác định bởi `coverage.from_block` trong `GET /v1/data/chains`, và bao gồm một tập hợp các bộ dữ liệu nhỏ hơn — xem [Chuỗi được hỗ trợ → Ethereum](https://docs.blockvectra.com/vi/chains/#ethereum)

Trọng số CU của Data API được liệt kê trên trang [Bảng giá](https://blockvectra.com/vi/pricing/) và được trả về bởi `GET /v1/plans`. Xem [Khởi động nhanh → Gọi Data API](https://docs.blockvectra.com/vi/quickstart/#4-call-the-data-api) để biết các yêu cầu và cấu trúc phản hồi mẫu. Về việc tạo phiên bản đường dẫn, quy tắc tương thích ngược và các khuyến nghị SDK, hãy xem [Phiên bản và tính tương thích của API](https://docs.blockvectra.com/en/api/versioning/).

## Chuỗi

Data API cung cấp dữ liệu đã lập chỉ mục theo phạm vi của từng chuỗi: `https://api.blockvectra.com/v1/data/{chain}/…`.

Các bộ dữ liệu và tính năng khả dụng khác nhau tùy theo chuỗi; xem [Chuỗi được hỗ trợ](https://docs.blockvectra.com/vi/chains/) để biết ma trận khả năng đầy đủ. `GET https://api.blockvectra.com/v1/data/chains` báo cáo `features`, `coverage`, `finality` và `limits` của từng chuỗi. Các yêu cầu nằm ngoài phạm vi bao phủ của một bộ dữ liệu sẽ trả về HTTP `422 no_coverage` (không tính phí); chuỗi không xác định hoặc không công khai sẽ trả về HTTP `404` với `error.code` là `not_found` (không tính phí; tên chuỗi phải là các slug chữ thường chính xác).

## Lỗi

Mỗi phản hồi lỗi đều có dạng `{"error":{"code","message"}}`; chỉ `409 not_indexed_yet` có thể kèm theo `indexed_through` (khối đã được lập chỉ mục cao nhất trên chuỗi đó), và trường này sẽ vắng mặt khi chuỗi chưa có dữ liệu được lập chỉ mục. Các mã lỗi khách hàng thường gặp nhất:

| Trạng thái | `error.code`           | Ý nghĩa                                                                                                                                                                                                    | Hành động                                                                                                                                                                                                                                  |
| ---------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `402`      | `insufficient_balance` | Số dư trả phí hoặc hạn mức miễn phí đã cạn kiệt; khi số dư được xác định, `error.data` bao gồm `balance_units` và `balance_cu` (không tính phí)                                                            | Nạp tiền on-chain trên [trang Thanh toán](https://console.blockvectra.com/billing/) của console, hoặc đợi hạn mức miễn phí được làm mới                                                                                                    |
| `404`      | `not_found`            | `{chain}` không xác định hoặc không công khai, hoặc đối tượng không tồn tại                                                                                                                                | Sửa lại yêu cầu                                                                                                                                                                                                                            |
| `409`      | `not_indexed_yet`      | Yêu cầu vượt quá `as_of_block` (khối mới nhất đã ghi hoàn tất; bao gồm `indexed_through`), hash phân giải vượt quá `as_of_block`, hoặc chuỗi chưa có dữ liệu được lập chỉ mục (không có `indexed_through`) | Khi có `indexed_through`, hãy thăm dò (poll) cho đến khi khối của bạn hoặc `to_block` bằng hoặc thấp hơn giá trị đó; khi không có, hãy đợi chuỗi bắt đầu lập chỉ mục (`coverage.has_data` trong `GET /v1/data/chains` hiển thị trạng thái) |
| `422`      | `no_coverage`          | Thiếu sót vĩnh viễn: chuỗi thiếu khả năng đó, hoặc khối nằm trước phạm vi bao phủ được lập chỉ mục/trace                                                                                                   | Thay đổi yêu cầu; thử lại sẽ không có tác dụng                                                                                                                                                                                             |
| `429`      | `rate_limited`         | Giới hạn tốc độ CU của key (phản hồi bao gồm `Retry-After`) hoặc giới hạn tốc độ gọi của tài khoản (không có `Retry-After`); không tính phí                                                                | Thử lại sau `Retry-After` giây                                                                                                                                                                                                             |
| `429`      | `cost_exceeds_burst`   | Một yêu cầu đơn lẻ có chi phí vượt quá dung lượng burst của key; không có `Retry-After` (không tính phí)                                                                                                   | Chia nhỏ yêu cầu; thử lại nguyên trạng sẽ không bao giờ thành công                                                                                                                                                                         |
| `503`      | `unavailable`          | Tạm thời không khả dụng; phản hồi mang theo `Retry-After`. Cũng được trả về cho các yêu cầu lịch sử trên chuỗi có `coverage.from_block` hiện tại là `null`                                                 | Thử lại sau `Retry-After` giây                                                                                                                                                                                                             |
| `503`      | `gateway_overloaded`   | Đã đạt giới hạn đồng thời của tài khoản trên tất cả các key và chuỗi của tài khoản đó, hoặc dịch vụ tạm thời bận; `Retry-After: 1` (không tính phí)                                                        | Giảm số yêu cầu đồng thời trên toàn bộ tài khoản và đợi `Retry-After` giây trước khi thử lại                                                                                                                                               |

## Danh mục endpoint

Dưới đây là đặc tả gốc bằng tiếng Anh.

<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>