Data API
REST endpoints over indexed blockchain data across supported chains.
Overview
The Data API provides REST endpoints for querying indexed blockchain data — blocks, transactions, addresses, tokens, NFTs, DEX activity, tokenized stocks, and dataset freshness.
- Base URL:
https://dev-api.blockvectra.network/v1/data— every route except/chainsis prefixed with a chain identifier (e.g.https://dev-api.blockvectra.network/v1/data/{chain}/…) - Protocol: HTTP
GET(plusPOSTfor batch token lookups at/{chain}/tokens:batch), JSON responses - Authentication: API key required — pass your key in the
x-api-keyrequest header. Requests are metered and billed in Compute Units (CU); only 2xx successful responses are billed - Ethereum (Beta): roughly the last 30 days of data and a smaller set of datasets — see Supported Chains → Ethereum
Data API CU weights are listed on the Pricing page and returned by GET /v1/plans. See Quickstart → Call the Data API for example requests and response shapes.
Chains
The Data API serves indexed data scoped to each chain: https://dev-api.blockvectra.network/v1/data/{chain}/….
Available datasets and features vary by chain; see Supported Chains for the full capability matrix. GET https://dev-api.blockvectra.network/v1/data/chains reports each chain's features, coverage, finality and limits. Requests outside a dataset's coverage return HTTP 422 no_coverage (not billed); an unknown or not-public chain returns HTTP 404 with error.code not_found (decided before the key check, not billed, and not rate-limited; chain names must be exact lowercase slugs).
Errors
Every error response is {"error":{"code","message"}}; only 409 not_indexed_yet may add indexed_through (the highest indexed block on that chain), and it is absent when the chain has no indexed data yet. Codes customers hit most often:
| Status | error.code | Meaning | Action |
|---|---|---|---|
402 | insufficient_balance | Paid balance or free grant exhausted (not billed) | Top up in the console or wait for free grant refill |
404 | not_found | Unknown or not-public {chain}, or the object does not exist | Fix the request |
409 | not_indexed_yet | The block number is above the indexed head (indexed_through says how far the chain has indexed), or the chain has no indexed data at all yet (no indexed_through) | With indexed_through, poll until your block is at or below it; without it, wait for the chain to start indexing |
409 | finality_exceeded | Block is indexed but above finalized_block (not yet reorg-safe) | Wait for finality, or read an older block |
422 | no_coverage | Permanent gap: the chain lacks that capability, or the block is before indexed/trace coverage | Change the request; retrying will not help |
429 | rate_limited | Key CU rate limit (response includes Retry-After) or account call rate limit (no Retry-After); not billed | Retry after Retry-After seconds |
429 | cost_exceeds_burst | A single request costs more than the key's burst capacity; no Retry-After (not billed) | Split the request; retrying as sent never succeeds |
503 | unavailable | Temporarily unavailable; the response carries Retry-After. Also returned for historical requests on a chain whose coverage.from_block is currently null | Retry after Retry-After seconds |
503 | gateway_overloaded | The chain is busy (Ethereum's Data API handles few concurrent requests); Retry-After: 1 | Retry with backoff |
409 not_indexed_yet covers two situations. Block above the indexed head: the requested block is higher than what the chain has indexed, the response includes indexed_through, and the data may arrive later — retry. No indexed data yet: for a chain that has just launched and has no indexed data at all, the response has no indexed_through and GET /v1/data/chains reports that chain's coverage.has_data as false. Wait for the chain to start indexing; /v1/status (data_status) and /v1/data/chains (coverage.has_data) show the current state, and these values change automatically once indexing begins.
Only 2xx responses are billed; errors never are.
Chain
| Method | Path | Summary |
|---|---|---|
| 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
| Method | Path | Summary |
|---|---|---|
| GET | /{chain}/status/freshness | Freshness and lag per dataset |
Addresses
| Method | Path | Summary |
|---|---|---|
| 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
| Method | Path | Summary |
|---|---|---|
| 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
| Method | Path | Summary |
|---|---|---|
| GET | /{chain}/nfts/{contract}/{token_id} | Get one NFT's owner/holders |
| GET | /{chain}/nfts | List NFTs owned by an address |
DEX
| Method | Path | Summary |
|---|---|---|
| GET | /{chain}/dex/swaps | List DEX swaps by pool or token |
| GET | /{chain}/dex/prices | Daily DEX token prices |
Stocks
| Method | Path | Summary |
|---|---|---|
| GET | /{chain}/stocks | Daily leaderboard of tokenized stocks |
| GET | /{chain}/stocks/{token} | Get one tokenized stock |
Traces
| Method | Path | Summary |
|---|---|---|
| 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 |