# Blockchain Data API リファレンス

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

## 概要

この Blockchain Data API リファレンスを使用して、インデックス済みのブロック、トランザクション、アドレス、トークン、NFT、DEX アクティビティ、トークン化株式、データセットの鮮度に関する REST リクエストを構築します。データセットを選択してチェーンの対応状況を確認するには[データセットディレクトリ](https://docs.blockvectra.com/ja/datasets/)から、ウォレットのトークン残高と送金履歴については[ウォレット資産ガイド](https://docs.blockvectra.com/ja/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` リクエストヘッダーにキーを指定します。リクエストは Compute Units (CU) で計測・課金されます。2xx の成功レスポンスのみが課金対象です
* **Ethereum**：データの対応範囲は `GET /v1/data/chains` の `coverage.from_block` によって決まり、より限定されたデータセットをカバーします — [対応チェーン → Ethereum](https://docs.blockvectra.com/ja/chains/#ethereum)をご覧ください

Data API の CU 重み付けは[料金](https://blockvectra.com/ja/pricing/)ページに記載されており、`GET /v1/plans` から返されます。リクエストとレスポンスの形式の例については、[クイックスタート → Data API の呼び出し](https://docs.blockvectra.com/ja/quickstart/#4-call-the-data-api)をご覧ください。パスのバージョニング、後方互換性ルール、SDK の推奨事項については、[API のバージョニングと互換性](https://docs.blockvectra.com/ja/api/versioning/)をご覧ください。

## チェーン

Data API は、各チェーンにスコープされたインデックス済みデータを提供します：`https://api.blockvectra.com/v1/data/{chain}/…`。

利用可能なデータセットと機能はチェーンによって異なります。完全な機能マトリックスは[対応チェーン](https://docs.blockvectra.com/ja/chains/)をご覧ください。`GET https://api.blockvectra.com/v1/data/chains` は各チェーンの `features`、`coverage`、`finality`、`limits` を返します。データセットの対象範囲外のリクエストは HTTP `422 no_coverage`（課金対象外）を返します。不明または非公開のチェーンは、`error.code` が `not_found` の HTTP `404` を返します（課金対象外。チェーン名は正確な小文字のスラッグである必要があります）。

## エラー

すべてのエラーレスポンスは `{"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`          | 恒久的な欠落：チェーンがその機能に対応していないか、ブロックがインデックス/トレースの対象範囲前です                                                                                                  | リクエストを変更してください。再試行しても成功しません                                                                                                                                   |
| `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>