# Blockchain Data API 레퍼런스

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

## 개요

이 Blockchain Data API 레퍼런스를 참조하여 인덱싱된 블록, 트랜잭션, 주소, 토큰, NFT, DEX 활동, 토큰화 주식 및 데이터셋 최신성을 조회하는 REST 요청을 구성하세요. 데이터셋을 선택하고 체인 지원 여부를 확인하려면 [데이터셋 디렉터리](https://docs.blockvectra.com/en/datasets/)부터 살펴보세요. 지갑 토큰 잔액 및 전송 내역은 [지갑 자산 가이드](https://docs.blockvectra.com/en/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 키 필요 — `x-api-key` 요청 헤더로 키를 전달하세요. 요청은 Compute Units (CU) 단위로 측정 및 청구되며, 2xx 성공 응답에 대해서만 과금됩니다
* **Ethereum**: 데이터 제공 범위는 `GET /v1/data/chains`의 `coverage.from_block`에 따라 결정되며, 더 적은 데이터셋을 지원합니다 — [지원 체인 → Ethereum](https://docs.blockvectra.com/en/chains/#ethereum)을 확인하세요

Data API의 CU 가중치는 [요금](https://blockvectra.com/en/pricing/) 페이지에 안내되어 있으며 `GET /v1/plans`로도 반환됩니다. 요청 예제 및 응답 형식은 [빠른 시작 → Data API 호출](https://docs.blockvectra.com/en/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/en/chains/)에서 확인하세요. `GET https://api.blockvectra.com/v1/data/chains`는 각 체인의 `features`, `coverage`, `finality` 및 `limits`를 반환합니다. 데이터셋의 제공 범위를 벗어난 요청은 HTTP `422 no_coverage`를 반환합니다(과금되지 않음). 알 수 없거나 비공개 상태인 체인은 `error.code`가 `not_found`인 HTTP `404`를 반환합니다(과금되지 않음. 체인 이름은 소문자 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`         | 키 CU 전송률 제한(응답에 `Retry-After` 포함) 또는 계정 호출 빈도 제한(`Retry-After` 없음)(과금되지 않음)                                                                   | `Retry-After` 초 후 재시도                                                                                                                             |
| `429` | `cost_exceeds_burst`   | 단일 요청 비용이 키의 버스트 용량을 초과함(`Retry-After` 없음, 과금되지 않음)                                                                                           | 요청 분할(동일하게 재시도해도 성공하지 않음)                                                                                                                         |
| `503` | `unavailable`          | 일시적으로 사용할 수 없음(응답에 `Retry-After` 포함). `coverage.from_block`이 현재 `null`인 체인에 대한 과거 데이터 요청에서도 반환됨                                               | `Retry-After` 초 후 재시도                                                                                                                             |
| `503` | `gateway_overloaded`   | 계정 내 모든 키와 체인 전체의 동시 요청 한도에 도달했거나 서비스가 일시적으로 사용 중임(`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>