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?
Key Differences
| Aspect | V1 API | V2 API |
|---|
| HTTP method | Mostly GET | All POST |
| Authentication | Query param (?apikey=) or header (apikey: ...) | Bearer token (Authorization: Bearer <key>) |
| 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 | POST /api/v2/ethereum/state | Pending API: the beaconcha.in team is working on this API. |
Validators
Rewards
Queues and Sync Committees
| V1 | V2 | Notes |
|---|
GET /api/v1/validators/queue | POST /api/v2/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} | POST /api/v2/ethereum/sync-committee | |
Slots
| V1 | V2 | Notes |
|---|
GET /api/v1/slot/{slotOrHash} | POST /api/v2/ethereum/slot | |
GET .../slot/{slot}/attestations | POST .../slot/attestation-duties | Pending API: the beaconcha.in team is working on this API. |
GET .../slot/{slot}/deposits | POST .../slot/deposits | Pending API: the beaconcha.in team is working on this API. |
GET .../slot/{slot}/withdrawals | 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 | BLS-to-execution credential changes |
| Validators | GET .../validator/stats/{index} | Daily validator statistics |
| Validators | GET .../validator/leaderboard | Performance leaderboard |
| Validators | GET .../validators/proposalLuck | Proposal luck metrics |
| Validators | GET .../eth1deposit/{txhash} | Deposits by execution transaction hash |
| Epochs | GET /api/v1/epoch/{epoch} | Epoch overview |
| Epochs | GET /api/v1/epoch/{epoch}/slots | All slots in an epoch |
| Slots | GET .../slot/{slot}/attesterslashings | Attester slashings |
| Slots | GET .../slot/{slot}/proposerslashings | Proposer slashings |
| Slots | GET .../slot/{slot}/voluntaryexits | Voluntary exits |
| Execution Layer | GET .../execution/address/{address} | Address balances |
| Execution Layer | GET .../execution/address/{address}/erc20tokens | ERC-20 token balances |
| Execution Layer | GET .../execution/{addressIndexOrPubkey}/produced | Blocks produced by fee recipient |
| Execution Layer | GET .../execution/gasnow | Gas price recommendations |
| Other | GET /api/v1/rocketpool/stats | Rocket Pool network statistics |
| Other | GET /api/v1/rocketpool/validator/{indexOrPubkey} | Rocket Pool validator metadata |
| Other | GET /api/v1/ethstore/{day} | ETH.Store daily aggregates |
| Other | GET /api/v1/ens/lookup/{domain} | ENS resolution |
| Other | GET /api/v1/chart/{chart} | Chart data |
| Other | GET /api/v1/graffitiwall | 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 | Validator metadata (Pro) |
| Validator Metrics | POST .../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 | 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 | Block overview |
| Blocks | POST .../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 | Network-wide performance aggregate |
| Entities | POST /api/v2/ethereum/entities | Staking entities overview (Pro) |
| Entities | POST .../entity/sub-entities | Entity sub-entities (Pro) |
Migration Example: Validator Lookup
Before (V1)
curl 'https://beaconcha.in/api/v1/validator/1?apikey=YOUR_API_KEY'
After (V2)
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]}
}'
GET becomes POST with a JSON body- The validator index moves from the URL path into the
validator object in the request body
- Authentication moves from query parameter to
Authorization: Bearer header
- You must specify the
chain explicitly
Migration Example: Rewards Data
Before (V1)
curl -H 'apikey: YOUR_API_KEY' \
'https://beaconcha.in/api/v1/validator/1/incomedetailhistory'
After (V2)
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
}'
Authentication Changes
V1 supported both query parameter and header authentication:
# 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 - 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.
V1 uses offset-based pagination:
# V1 - offset pagination
curl 'https://beaconcha.in/api/v1/validator/1/balancehistory?offset=100&limit=25&apikey=YOUR_API_KEY'
cursor value from the paging object in the previous response:
# 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=="
}'
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 for full details.
