> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating from V1 to V2 API
> Step-by-step guide to migrate your application from the beaconcha.in V1 API to the V2 API, with endpoint mappings and code examples.
## Why Migrate?
All new features, endpoints, and improvements are built exclusively for V2. We recommend migrating to V2 for the best experience.
* **Richer data:** V2 endpoints return more detailed, structured responses with fine-grained reward breakdowns
* **Flexible selectors:** Query by validator index, public key, deposit address, withdrawal address, entity, or dashboard
* **Use cases and guides:** 14+ step-by-step guides with code examples for common workflows
* **BeaconScore and entities:** Exclusive V2 features for performance benchmarking and entity comparison
* **Active development:** All new features ship on V2 only
***
## Need Help?
Task-specific guides with code examples for common operations.
V2 error patterns, status codes, and troubleshooting.
Connect your AI assistant to the beaconcha.in docs via MCP or llms.txt.
Ask questions and get help from the community.
***
## Key Differences
| Aspect | V1 API | V2 API |
| ------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| HTTP method | Mostly `GET` | All `POST` |
| Authentication | Query param (`?apikey=`) or header (`apikey: ...`) | Bearer token (`Authorization: Bearer `) |
| Pagination | Offset-based (`offset` and `limit`) | Cursor-based (`cursor` and `page_size`) |
| Validator selection | Path parameter (single index or pubkey) | JSON body selector (batch indices, pubkeys, deposit address, withdrawal address, entity, dashboard, or dashboard group ID) |
| Response envelope | `{ "status": "OK", "data": ... }` | `{ "data": ..., "paging": ... }` |
| Chain selection | Implicit (server URL) | Explicit `"chain"` field in request body (`"mainnet"` or `"hoodi"`) |
***
## Endpoint Mapping
### Network State
| V1 | V2 | Notes |
| ---------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------- |
| [`GET /api/v1/latestState`](/api-reference/network/latest-consensus-and-execution-state) | `POST /api/v2/ethereum/state` | Pending API: the beaconcha.in team is working on this API. |
### Validators
| V1 | V2 | Notes |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`GET /api/v1/validator/{indexOrPubkey}`](/api-reference/validators/validators-overview) | [`POST /api/v2/ethereum/validators`](/api-reference/ethereum/validators) | V2 supports batch lookups in a single request |
| [`POST /api/v1/validator`](/api-reference/validators/validators-overview-post) | [`POST /api/v2/ethereum/validators`](/api-reference/ethereum/validators) | V2 handles batching natively via `validator_identifiers` array |
| [`GET .../validator/eth1/{eth1address}`](/api-reference/validators/validators-by-deposit-address) | [`POST /api/v2/ethereum/validators`](/api-reference/ethereum/validators) | Use the `deposit_address` selector in the request body. |
| [`GET .../validator/withdrawalCredentials/{...}`](/api-reference/validators/validators-by-withdrawal-credentials-or-address) | [`POST /api/v2/ethereum/validators`](/api-reference/ethereum/validators) | Use the `withdrawal` selector in the request body. |
| [`GET .../balancehistory`](/api-reference/validators/validator-balance-history) | [`POST .../validators/balances`](/api-reference/ethereum/validators/balances) | |
| [`GET .../performance`](/api-reference/rewards/consensus-layer-rewards) | [`POST .../validators/performance-aggregate`](/api-reference/ethereum/validators/performance-aggregate) | V1 returns rolling window totals (1d/7d/31d/365d). V2 `performance-aggregate` is the closest match. For per-epoch granularity, use [`performance-list`](/api-reference/ethereum/validators/performance-list) |
| [`GET .../attestations`](/api-reference/validators/validator-attestations-history) | [`POST .../validators/attestation-slots`](/api-reference/ethereum/validators/attestation-slots) | |
| [`GET .../proposals`](/api-reference/validators/validator-proposed-blocks) | [`POST .../validators/proposal-slots`](/api-reference/ethereum/validators/proposal-slots) | |
| [`GET .../attestationefficiency`](/api-reference/validators/attestation-efficiency) | [`POST .../validators/performance-aggregate`](/api-reference/ethereum/validators/performance-aggregate) | BeaconScore in V2 replaces the V1 attestation efficiency metric |
| [`GET .../deposits`](/api-reference/validators/validator-deposits-execution-layer) | `POST .../validators/deposit-slots` | Pending API: the beaconcha.in team is working on this API. |
| [`GET .../withdrawals`](/api-reference/validators/validator-withdrawal-history) | `POST .../validators/withdrawal-slots` | Pending API: the beaconcha.in team is working on this API. |
### Rewards
| V1 | V2 | Notes |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`GET .../incomedetailhistory`](/api-reference/validators/validator-income-detail-history) | [`POST .../validators/rewards-list`](/api-reference/ethereum/validators/rewards-list) | |
| [`GET .../execution/performance`](/api-reference/rewards/execution-layer-rewards) | [`POST .../validators/rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate) | V1 is execution-layer only. V2 includes both consensus and execution layer rewards |
| [`GET .../execution/block/{blockNumber}`](/api-reference/blocks/execution-block-overview) | [`POST .../block/rewards`](/api-reference/ethereum/block/rewards) | Use this endpoint for execution-layer block reward details. |
### Queues and Sync Committees
| V1 | V2 | Notes |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`GET /api/v1/validators/queue`](/api-reference/validators/validator-activation-and-exit-queue) | [`POST /api/v2/ethereum/queues`](/api-reference/ethereum/queues) | Network-wide queue data. For per-validator queue position, see also `validators/queues` `Pending`. The beaconcha.in team is working on this endpoint. |
| [`GET /api/v1/sync_committee/{period}`](/api-reference/sync-committees/sync-committee-for-a-period) | [`POST /api/v2/ethereum/sync-committee`](/api-reference/ethereum/sync-committee/overview) | |
### Network Statistics
| V1 | V2 | Notes |
| ---------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/v1/ethstore/{day}` | [`POST /api/v2/ethereum/eth-store`](/api-reference/ethereum/eth-store) | V2 returns a paginated time series and subsumes V1's single-day, `latest`, and history variants. See the differences below. |
The V2 endpoint reads the same source data as V1 and applies the same ETH.STORE®
methodology, so every value reconciles exactly. Only the presentation changed:
* **Response shape.** V1's flat keys are grouped: `rewards.{}`, `apr.{}`, and
`moving_averages.{}`. `avgapr7d` becomes `moving_averages.window_7d.apr.combined`,
`cl_avgapr31d` becomes `moving_averages.window_31d.apr.consensus_layer`, and so on.
* **Timestamps.** `day_start` and `day_end` are Unix timestamps in seconds, not
RFC 3339 strings.
* **Day selection.** Instead of a `{day}` path parameter, choose an evaluation window
(`24h` returns the latest datapoint, up to `all_time` with pagination). Scale and
Enterprise plans can also request an arbitrary range by timestamp, epoch, or slot.
Both APIs express APR as a fraction, where `1.0` is 100%, and both compute the 7- and
31-day moving averages as unweighted means of the daily APR values.
### Slots
| V1 | V2 | Notes |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`GET /api/v1/slot/{slotOrHash}`](/api-reference/slots/slot-overview) | [`POST /api/v2/ethereum/slot`](/api-reference/ethereum/slot/overview) | |
| [`GET .../slot/{slot}/attestations`](/api-reference/slots/attestations-for-a-slot) | `POST .../slot/attestation-duties` | Pending API: the beaconcha.in team is working on this API. |
| [`GET .../slot/{slot}/deposits`](/api-reference/slots/deposits-for-a-slot) | `POST .../slot/deposits` | Pending API: the beaconcha.in team is working on this API. |
| [`GET .../slot/{slot}/withdrawals`](/api-reference/slots/withdrawals-for-a-slot) | `POST .../slot/withdrawals` | Pending API: the beaconcha.in team is working on this API. |
### V1-Only Endpoints (No V2 Equivalent Yet)
The following V1 endpoints do not have V2 equivalents at this time. They remain accessible via the V1 API.
| Category | V1 | Notes |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| Validators | [`GET .../validator/{indexOrPubkey}/blsChange`](/api-reference/validators/bls-to-execution-credential-changes) | BLS-to-execution credential changes |
| Validators | [`GET .../validator/stats/{index}`](/api-reference/validators/daily-validator-statistics) | Daily validator statistics |
| Validators | [`GET .../validator/leaderboard`](/api-reference/rewards/validator-performance-leaderboard) | Performance leaderboard |
| Validators | [`GET .../validators/proposalLuck`](/api-reference/validators/proposal-luck) | Proposal luck metrics |
| Validators | [`GET .../eth1deposit/{txhash}`](/api-reference/validator-deposits/deposits-by-execution-transaction-hash) | Deposits by execution transaction hash |
| Epochs | [`GET /api/v1/epoch/{epoch}`](/api-reference/epochs/epoch-overview) | Epoch overview |
| Epochs | [`GET /api/v1/epoch/{epoch}/slots`](/api-reference/epochs/epoch-slots) | All slots in an epoch |
| Slots | [`GET .../slot/{slot}/attesterslashings`](/api-reference/slots/attester-slashings-for-a-slot) | Attester slashings |
| Slots | [`GET .../slot/{slot}/proposerslashings`](/api-reference/slots/proposer-slashings) | Proposer slashings |
| Slots | [`GET .../slot/{slot}/voluntaryexits`](/api-reference/slots/voluntary-exits-for-a-slot) | Voluntary exits |
| Execution Layer | [`GET .../execution/address/{address}`](/api-reference/addresses/execution-address-balances) | Address balances |
| Execution Layer | [`GET .../execution/address/{address}/erc20tokens`](/api-reference/addresses/erc-20-token-balances-for-an-address) | ERC-20 token balances |
| Execution Layer | [`GET .../execution/{addressIndexOrPubkey}/produced`](/api-reference/blocks/execution-blocks-produced-by-fee-recipient-proposer-index-or-pubkey) | Blocks produced by fee recipient |
| Execution Layer | [`GET .../execution/gasnow`](/api-reference/gas/current-gas-price-recommendations) | Gas price recommendations |
| Other | [`GET /api/v1/rocketpool/stats`](/api-reference/rocketpool/rocket-pool-network-statistics) | Rocket Pool network statistics |
| Other | [`GET /api/v1/rocketpool/validator/{indexOrPubkey}`](/api-reference/rocketpool/get-rocket-pool-validator-metadata-by-index-or-pubkey) | Rocket Pool validator metadata |
| Other | [`GET /api/v1/ens/lookup/{domain}`](/api-reference/ens/resolve-ens-name-or-address) | ENS resolution |
| Other | [`GET /api/v1/chart/{chart}`](/api-reference/misc/chart) | Chart data |
| Other | [`GET /api/v1/graffitiwall`](/api-reference/misc/graffiti-wall-pixels) | Graffiti wall |
### V2-Only Endpoints (New in V2)
These endpoints are only available in V2 and have no V1 equivalent:
| Category | V2 | Notes |
| ----------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Validator Metrics | [`POST .../validators/metadata`](/api-reference/ethereum/validators/metadata) | Validator metadata (Pro) |
| Validator Metrics | [`POST .../validators/apy-roi`](/api-reference/ethereum/validators/apy-roi) | APY and ROI calculations |
| Validator Duties | `POST .../validators/upcoming-duty-slots` | Pending API: the beaconcha.in team is working on this API. |
| Validator Duties | [`POST .../validators/sync-committee-periods`](/api-reference/ethereum/validators/sync-committee-periods) | Sync committee period history |
| Sync Committees | `POST .../sync-committee/validators` | Pending API: the beaconcha.in team is working on this API. |
| Blocks | [`POST /api/v2/ethereum/block`](/api-reference/ethereum/block/overview) | Block overview |
| Blocks | [`POST .../block/rewards`](/api-reference/ethereum/block/rewards) | Block rewards breakdown |
| Network | `POST /api/v2/ethereum/config` | Pending API: the beaconcha.in team is working on this API. |
| Network | [`POST /api/v2/ethereum/performance-aggregate`](/api-reference/ethereum/performance-aggregate) | Network-wide performance aggregate |
| Entities | [`POST /api/v2/ethereum/entities`](/api-reference/ethereum/entities/overview) | Staking entities overview (Pro) |
| Entities | [`POST .../entity/sub-entities`](/api-reference/ethereum/entity/sub-entities) | Entity sub-entities (Pro) |
***
## Migration Example: Validator Lookup
### Before (V1)
```bash theme={null}
curl 'https://beaconcha.in/api/v1/validator/1?apikey=YOUR_API_KEY'
```
### After (V2)
```bash theme={null}
curl -X POST 'https://beaconcha.in/api/v2/ethereum/validators' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"chain": "mainnet",
"validator": {"validator_identifiers": [1]}
}'
```
Key changes in this example:
1. `GET` becomes `POST` with a JSON body
2. The validator index moves from the URL path into the `validator` object in the request body
3. Authentication moves from query parameter to `Authorization: Bearer` header
4. You must specify the `chain` explicitly
***
## Migration Example: Rewards Data
### Before (V1)
```bash theme={null}
curl -H 'apikey: YOUR_API_KEY' \
'https://beaconcha.in/api/v1/validator/1/incomedetailhistory'
```
### After (V2)
```bash theme={null}
curl -X POST 'https://beaconcha.in/api/v2/ethereum/validators/rewards-list' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"chain": "mainnet",
"validator": {"validator_identifiers": [1]},
"page_size": 10
}'
```
V2 rewards data includes a detailed breakdown by duty type (attestation, sync committee, proposal) with reward, penalty, and missed reward amounts.
***
## Authentication Changes
V1 supported both query parameter and header authentication:
```bash theme={null}
# V1 - query parameter
curl 'https://beaconcha.in/api/v1/validator/1?apikey=YOUR_API_KEY'
# V1 - header
curl -H 'apikey: YOUR_API_KEY' 'https://beaconcha.in/api/v1/validator/1'
```
V2 uses only Bearer token authentication:
```bash theme={null}
# V2 - Bearer token (only method)
curl -H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-X POST 'https://beaconcha.in/api/v2/ethereum/state' \
-d '{"chain": "mainnet"}'
```
The same API key works for both V1 and V2. You do not need a new key to start using V2.
***
## Pagination Changes
V1 uses offset-based pagination:
```bash theme={null}
# V1 - offset pagination
curl 'https://beaconcha.in/api/v1/validator/1/balancehistory?offset=100&limit=25&apikey=YOUR_API_KEY'
```
V2 uses cursor-based pagination. The first request omits the cursor, and subsequent requests use the `cursor` value from the `paging` object in the previous response:
```bash theme={null}
# V2 - first page
curl -X POST 'https://beaconcha.in/api/v2/ethereum/validators/balances' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"chain": "mainnet",
"validator": {"validator_identifiers": [1]},
"page_size": 25
}'
# V2 - next page (use cursor from previous response)
curl -X POST 'https://beaconcha.in/api/v2/ethereum/validators/balances' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"chain": "mainnet",
"validator": {"validator_identifiers": [1]},
"page_size": 25,
"cursor": "eyJlcG9jaCI6MzQ3NTY2fQ=="
}'
```
See the [Pagination Guide](/api/pagination) for full details on cursor-based pagination.
***
## Rate Limit Considerations
When migrating, your rate limit behavior depends on your subscription type:
* **Legacy plans** (Sapphire, Emerald, Diamond): V1 and V2 use separate rate limit buckets. Your V1 quota is unaffected by V2 usage.
* **Current plans** (Hobbyist, Business, Scale): V1 and V2 share a single rate limit bucket.
See the [Rate Limits guide](/api/rate-limits#how-v1-and-v2-rate-limits-work) for full details.