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, or dashboard, and on Scale and Enterprise plans by deposit address, withdrawal address, or entity
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>`), recommended; the V1 methods also work
Pagination	Offset-based (`offset` and `limit`)	Cursor-based (`cursor` and `page_size`), at most 10 items per page
Validator selection	Path parameter: up to 100 comma-separated validator indices or public keys	JSON body selector: validator indices or public keys (up to 100, or 20 on the Free Trial and legacy plans), or a dashboard. The deposit address, withdrawal address, and entity selectors require a Scale or Enterprise plan
History	Many epochs per request, for example 100 epochs of balances	Per-epoch endpoints take one `epoch` per request. Aggregate endpoints take an evaluation window (`24h` to `all_time`), or a custom range on Scale and Enterprise plans
Amounts	Mostly Gwei, as integers	Wei, as decimal strings
Response envelope	`{ "status": "OK", "data": ... }`	`{ "data": ..., "paging": ... }`
Chain selection	Implicit (server URL)	`"chain"` field in request body (`"mainnet"` or `"hoodi"`), defaults to `"mainnet"` on most endpoints

Endpoint Mapping

V1 endpoints that have a V2 equivalent are no longer listed in the V1 API reference. They still respond, so existing integrations keep working, but they receive no new development. The tables below map each of them to its V2 replacement. 💎 marks a V2 feature that requires a Scale or Enterprise plan.

Validators

V1	V2	Notes
`GET /api/v1/validator/{indexOrPubkey}`	`POST /api/v2/ethereum/validators`	Returns status, balances, withdrawal credentials, and lifecycle epochs. For `total_withdrawals`, list the slots with `validators/withdrawal-slots`, then add up the amounts of the `slot/withdrawals` rows with `status: completed`. Rejected withdrawal requests are also returned, with the requested amount, but were never paid. `name` and `last_attestation_slot` are not returned.
`POST /api/v1/validator`	`POST /api/v2/ethereum/validators`	Send the indices or public keys in the `validator_identifiers` array.
`GET .../validator/eth1/{eth1address}`	`POST /api/v2/ethereum/validators`	💎 Use the `deposit_address` selector. ENS names are not resolved. Validators that do not have an index yet appear only in `validators/queues`.
`GET .../validator/withdrawalCredentials/{...}`	`POST /api/v2/ethereum/validators`	💎 Use the `withdrawal` selector with an address or a `0x00`, `0x01`, or `0x02` credential. ENS names are not resolved.
`GET .../balancehistory`	`POST .../validators/balances`	One `epoch` per request: send one request for each epoch you need.
`GET .../attestations`	`POST .../validators/attestation-slots`	Lists the slots with attestation duties. For the status and inclusion slot of each duty, use `slot/attestation-duties` per slot, or `performance-list` per epoch. Finalized epochs only.
`GET .../attestationefficiency`	`POST .../validators/performance-aggregate`	BeaconScore® replaces the attestation efficiency metric; the two values cannot be converted into each other. The result aggregates all selected validators.
`GET .../proposals`	`POST .../validators/proposal-slots`	Returns the proposal slots and execution block numbers of finalized epochs. Use `slot` for the proposal status and `block` for the block details.
`GET .../withdrawals`	`POST .../validators/withdrawal-slots`	Lists the slots with withdrawals; `slot/withdrawals` returns the amounts.
`GET .../validator/stats/{index}`	`POST .../validators/performance-aggregate`	💎 For a day’s duty counts (attestations, proposals, included slashings, sync committee), request a custom range of that day; custom ranges cover whole UTC days. Without one, add up `performance-list` over the day’s epochs. Balances come from `validators/balances` at the day’s first and last epoch (the minimum and maximum need every epoch of the day), deposits and withdrawals from `deposit-slots` and `withdrawal-slots`, with the amounts from `slot/deposits` and `slot/withdrawals` (for withdrawals, only rows with `status: completed`). For the split into attester and proposer slashings, request `slot` for each proposed block.
`GET /api/v1/validators/queue`	`POST /api/v2/ethereum/queues`	Network-wide queue data. The active validator count is `validators_count` in `epoch`. For per-validator queue positions, use `validators/queues`.

Rewards

V1	V2	Notes
`GET .../incomedetailhistory`	`POST .../validators/rewards-list`	One `epoch` per request. The missed proposal count is in `performance-list`.
`GET .../performance`	`POST .../validators/rewards-aggregate`	V1’s 1-day, 7-day, 31-day, and total values map to the `24h`, `7d`, `30d`, and `all_time` windows; 💎 365 days needs a custom range. `total` includes execution layer rewards: subtract `proposal.execution_layer_reward` to get consensus layer rewards only. The result aggregates all selected validators, and `rank7d` has no equivalent. V1 measures income as the balance change, so it includes slashing penalties that V2’s reward columns leave out: values for slashed validators differ. V2 counts finalized epochs only, so it can trail V1. The current balance is in `validators`.
`GET .../execution/performance`	`POST .../validators/rewards-aggregate`	Use `proposal.execution_layer_reward`, with the same windows as above; 💎 365 days needs a custom range.

Epochs and Slots

V1	V2	Notes
`GET /api/v1/epoch/{epoch}`	`POST /api/v2/ethereum/epoch`	Amounts are in wei. `participation_rate` and `attesting_balance` are `null` until the epoch is finalized; V1 returns them for recent epochs too. `blockscount` and `rewards_exported` have no V2 field.
`GET /api/v1/slot/{slotOrHash}`	`POST /api/v2/ethereum/slot`	Select by slot number, block root, `latest`, or `finalized`. The execution payload details are in `block`, and the fee recipient is in `block/rewards`. V1 `attestationscount` is `included_aggregate_count`, and `graffiti_text` is `null` instead of empty when there is no graffiti. Eth1 data votes, the sync aggregate bits and signature, the logs bloom, and `votes` (the number of validator votes that name the block as head, added up over every block that included them) are not returned.
`GET .../epoch/{epoch}/slots`	`POST /api/v2/ethereum/epoch`, then `POST /api/v2/ethereum/slot`	`slots.start` and `slots.end` give the epoch’s slot range; request `slot` for each of its slots. The fields that `slot` does not return are listed in the row above.
`GET .../slot/{slot}/deposits`	`POST .../slot/deposits`	Since Electra, deposits are reported at the slot where they were processed.
`GET .../slot/{slot}/withdrawals`	`POST .../slot/withdrawals`	Amounts are in wei. The withdrawal index is not returned.

Sync Committees

V1	V2	Notes
`GET /api/v1/sync_committee/{period}`	`POST /api/v2/ethereum/sync-committee/validators`	Lists each member once, ordered by validator index, with its positions in the committee in `sync_committee_indices`. To rebuild V1’s `validators` array in committee order, put each validator at each of its positions: a validator selected more than once appears once per position. The committee spans several pages: get the period number for `latest` or `next` from `sync-committee` first and request every page by that number, because `latest` and `next` move to the following period at a period boundary. `range` holds the start and end epochs.

Network Statistics

V1	V2	Notes
`GET /api/v1/ethstore/{day}`	`POST /api/v2/ethereum/eth-store`	V2 returns a paginated time series that covers V1’s single-day and `latest` lookups. See the differences below.

The V2 endpoint reads the same source data as V1 and applies the same ETH.STORE® methodology. 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, most recent day first). Scale and Enterprise plans can also request an arbitrary range by timestamp, epoch, or slot.
Precision. V2 returns APR values as single-precision floats, so they can differ from V1 in the last digits.

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.

V1 Endpoints Partially Covered by V2

These V1 endpoints stay in the V1 API reference because part of their use case has no V2 equivalent yet. Use V2 for the part it covers.

V1	Covered in V2	Not covered in V2
`GET .../validator/{indexOrPubkey}/deposits`	`validators/deposit-slots`, then `slot/deposits`, for validators that have an index. For public keys without an index yet, `validators/queues` returns the deposit count, balance, and estimated wait	The deposit transaction hash, signature, and withdrawal credentials of a public key without an index yet
`GET .../validator/{indexOrPubkey}/blsChange`	The current `withdrawal_credentials` in `validators`	The change record: slot, signature, and previous credentials
`GET .../execution/{addressIndexOrPubkey}/produced`	By proposer index or public key: `validators/proposal-slots`, then `block/rewards` for each block	Lookup by fee recipient address or ENS name

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 .../validators/proposalLuck`	Proposal luck metrics
Validators	`GET .../eth1deposit/{txhash}`	Deposits by execution transaction hash
Slots	`GET .../slot/{slot}/attestations`	Attestations included in a block. V2 `slot/attestation-duties` lists the duties scheduled for a slot instead
Slots	`GET .../slot/{slot}/attesterslashings`	Attester slashings. V2 `slot` returns only counts
Slots	`GET .../slot/{slot}/proposerslashings`	Proposer slashings. V2 `slot` returns only counts
Slots	`GET .../slot/{slot}/voluntaryexits`	Voluntary exits. V2 `slot` returns only counts
Other	`POST /api/v1/client/metrics`	Pushes machine metrics. V2 `machine-metrics` reads them back

Unlisted V1 Endpoints Without a Full V2 Equivalent

The following V1 endpoints are no longer listed in the V1 API reference, although V2 does not fully replace them. They still respond, but receive no new development. Where V2 has a close equivalent, it is listed.

V1	Closest V2	Notes
`GET /api/v1/latestState`	`state`: head, justified, and finalized slots, and how far the explorer’s data lags the chain	ETH prices in fiat currencies, `gasPriceGwei`, `lastProposedSlot`, and the node `syncing` flag are not available
`GET /api/v1/execution/block/{blockNumber}`	`block` and `block/rewards`, and `slot` for the proposer	One block per request instead of up to 100. The relay and builder are in `block/mev-timing` for mainnet blocks from 2024-06-03 on
`GET /api/v1/validator/leaderboard`	`entities`	V2 ranks staking entities, not single validators
`GET /api/v1/rocketpool/stats` and `GET /api/v1/rocketpool/validator/{indexOrPubkey}`	—	Rocket Pool data is not offered in V2
`GET /api/v1/execution/address/{address}`, `GET /api/v1/execution/address/{address}/erc20tokens`, `GET /api/v1/execution/gasnow`, and `GET /api/v1/ens/lookup/{domain}`	—	Execution layer address, token, gas price, and ENS data are not offered in V2
`GET /api/v1/graffitiwall`	—	The graffiti wall is not offered in V2
`GET /api/v1/chart/{chart}`	—	Its chart images are no longer updated

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, including entity and sub-entity
Validator Metrics	`POST .../validators/apy-roi`	APY and ROI calculations
Validator Metrics	`POST .../validators/mev-timing-aggregate`	MEV timing of a validator set
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
Validator Duties	`POST .../slot/sync-committee-duties`	Sync committee duty status and rewards for a slot
Validator Duties	`POST .../validators/ptc-slots` and `POST .../slot/ptc-duties`	Payload Timeliness Committee duties, see Glamsterdam API
Queues	`POST .../validators/queues`	Queue positions and estimated wait times of your validators
Queues	`POST .../validators/queues/consolidations` and `POST .../validators/queues/compounding-switches`	Consolidation and compounding switch requests of your validators
Queues	`POST /api/v2/ethereum/queues/history`	Staking queue sizes over time
Queues	`POST .../queues/request-fees` and `POST .../queues/request-fees/current`	Withdrawal and consolidation request fees
Network	`POST .../state/validator-statuses`	Distribution of validator statuses
Network	`POST /api/v2/ethereum/performance-aggregate`	Network-wide performance aggregate
Network	`POST .../slot/consolidations`	Consolidation and compounding switch requests in a block
Network	`POST /api/v2/ethereum/config`	Pending API: the beaconcha.in team is working on this API.
MEV	`POST /api/v2/ethereum/mev-timing`	Network-wide MEV timing per day
MEV	`POST .../block/mev-timing`	MEV timing outcome of a block
MEV	`POST .../block/mev-bids`	💎 All relay bids for a block
Entities	`POST /api/v2/ethereum/entities`	💎 Staking entities overview
Entities	`POST .../entity/sub-entities`	💎 Entity sub-entities
Entities	`POST .../entity/mev-timing`	💎 MEV timing of an entity
Machine Metrics	`POST /api/v2/machine-metrics` and `POST .../machine-metrics/machine-names`	Reads the metrics your machines push to `POST /api/v1/client/metrics`

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
The chain field selects the network (mainnet by default)

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]},
    "epoch": 413950,
    "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 accepts the same methods, but we recommend the Bearer token header:

# V2 - Bearer token (recommended)
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. On history endpoints such as balancehistory, offset and limit step through epochs:

# 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. Per-epoch endpoints such as validators/balances take one epoch per request, and the cursor pages through the validators of that epoch, at most 10 per page. To build a history, send one request per epoch. 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]},
    "epoch": 413950,
    "page_size": 10
  }'

# 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]},
    "epoch": 413950,
    "page_size": 10,
    "cursor": "eyJlcG9jaCI6MzQ3NTY2fQ=="
  }'

See the Pagination Guide for full details on cursor-based pagination.

Rate Limit Considerations

A single V1 history request can take many V2 requests, because V2 returns at most 10 items per page and per-epoch endpoints take one epoch per request. Your rate limit behavior also 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. V2 requests are limited to 1 request per second and 1,000 requests per month, and V2 selectors accept up to 20 validators.
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

Validators

Rewards

Epochs and Slots

Sync Committees

Network Statistics

V1 Endpoints Partially Covered by V2

V1-Only Endpoints (No V2 Equivalent Yet)

Unlisted V1 Endpoints Without a Full V2 Equivalent

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

​Why Migrate?

​Need Help?

Use Cases

Error Handling

AI Integration

Discord

​Key Differences

​Endpoint Mapping

​Validators

​Rewards

​Epochs and Slots

​Sync Committees

​Network Statistics

​V1 Endpoints Partially Covered by V2

​V1-Only Endpoints (No V2 Equivalent Yet)

​Unlisted V1 Endpoints Without a Full V2 Equivalent

​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

Validators

Rewards

Epochs and Slots

Sync Committees

Network Statistics

V1 Endpoints Partially Covered by V2

V1-Only Endpoints (No V2 Equivalent Yet)

Unlisted V1 Endpoints Without a Full V2 Equivalent

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