Migrating from V1 to V2 API

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?

Use Cases

Task-specific guides with code examples for common operations.

Error Handling

V2 error patterns, status codes, and troubleshooting.

AI Integration

Connect your AI assistant to the beaconcha.in docs via MCP or llms.txt.

Discord

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 <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

V1	V2	Notes
`GET /api/v1/validator/{indexOrPubkey}`	`POST /api/v2/ethereum/validators`	V2 supports batch lookups in a single request
`POST /api/v1/validator`	`POST /api/v2/ethereum/validators`	V2 handles batching natively via `validator_identifiers` array
`GET .../validator/eth1/{eth1address}`	`POST /api/v2/ethereum/validators`	Use the `deposit_address` selector in the request body.
`GET .../validator/withdrawalCredentials/{...}`	`POST /api/v2/ethereum/validators`	Use the `withdrawal` selector in the request body.
`GET .../balancehistory`	`POST .../validators/balances`
`GET .../performance`	`POST .../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`
`GET .../attestations`	`POST .../validators/attestation-slots`
`GET .../proposals`	`POST .../validators/proposal-slots`
`GET .../attestationefficiency`	`POST .../validators/performance-aggregate`	BeaconScore in V2 replaces the V1 attestation efficiency metric
`GET .../deposits`	`POST .../validators/deposit-slots`	Pending API: the beaconcha.in team is working on this API.
`GET .../withdrawals`	`POST .../validators/withdrawal-slots`	Pending API: the beaconcha.in team is working on this API.

Rewards

V1	V2	Notes
`GET .../incomedetailhistory`	`POST .../validators/rewards-list`
`GET .../execution/performance`	`POST .../validators/rewards-aggregate`	V1 is execution-layer only. V2 includes both consensus and execution layer rewards
`GET .../execution/block/{blockNumber}`	`POST .../block/rewards`	Use this endpoint for execution-layer block reward details.

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]}
  }'

Key changes in this example:

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
  }'

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:

# 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:

# 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:

# 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:

# 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 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 for full details.

Introduction

V2 API Docs

V1 API Docs

Migrating from V1 to V2 API

Why Migrate?

Need Help?

Use Cases

Error Handling

AI Integration

Discord

Key Differences

Endpoint Mapping

Network State

Validators

Rewards

Queues and Sync Committees

Slots

V1-Only Endpoints (No V2 Equivalent Yet)

V2-Only Endpoints (New in V2)

Migration Example: Validator Lookup

Before (V1)

After (V2)

Migration Example: Rewards Data

Before (V1)

After (V2)

Authentication Changes

Rate Limit Considerations

Introduction

V2 API Docs

V1 API Docs

Documentation Index

​Why Migrate?

​Need Help?

Use Cases

Error Handling

AI Integration

Discord

​Key Differences

​Endpoint Mapping

​Network State

​Validators

​Rewards

​Queues and Sync Committees

​Slots

​V1-Only Endpoints (No V2 Equivalent Yet)

​V2-Only Endpoints (New in V2)

​Migration Example: Validator Lookup

​Before (V1)

​After (V2)

​Migration Example: Rewards Data

​Before (V1)

​After (V2)

​Authentication Changes

​Pagination Changes

​Rate Limit Considerations

Why Migrate?

Need Help?

Key Differences

Endpoint Mapping

Network State

Validators

Rewards

Queues and Sync Committees

Slots

V1-Only Endpoints (No V2 Equivalent Yet)

V2-Only Endpoints (New in V2)

Migration Example: Validator Lookup

Before (V1)

After (V2)

Migration Example: Rewards Data

Before (V1)

After (V2)

Authentication Changes

Pagination Changes

Rate Limit Considerations