# ERC-20 token balances for an address Source: https://docs.beaconcha.in/api-reference/addresses/erc-20-token-balances-for-an-address /api/v1/bundled.yaml get /api/v1/execution/address/{address}/erc20tokens Retrieve a paginated list of ERC-20 token balances for a specific Ethereum address. Use this endpoint to list all token balances when the number of tokens exceeds the 200-token limit returned by the summary endpoint `/api/v1/execution/address/{address}`. Use the `offset` and `limit` query parameters to paginate through the complete set. # Execution address balances Source: https://docs.beaconcha.in/api-reference/addresses/execution-address-balances /api/v1/bundled.yaml get /api/v1/execution/address/{address} Retrieve the native ETH balance and ERC-20 token balances for an Ethereum address. The response includes at most 200 distinct ERC-20 tokens. To fetch all tokens beyond this limit, call `/api/v1/execution/address/{address}/erc20tokens`. # Execution block overview Source: https://docs.beaconcha.in/api-reference/blocks/execution-block-overview /api/v1/bundled.yaml get /api/v1/execution/block/{blockNumber} Retrieve one or more execution-layer blocks by block number. Provide block numbers as a comma-separated list in the `blockNumber` path segment (up to 100 values). The response includes per-block metadata, rewards, consensus linkage, and relay information when available. # Execution blocks produced by fee recipient, proposer index, or pubkey Source: https://docs.beaconcha.in/api-reference/blocks/execution-blocks-produced-by-fee-recipient-proposer-index-or-pubkey /api/v1/bundled.yaml get /api/v1/execution/{addressIndexOrPubkey}/produced Retrieve execution-layer blocks attributed to one or more producers. You can filter by fee recipient address (execution coinbase), beacon-chain proposer index, or validator public key. Provide one or more identifiers as a comma-separated list in the `addressIndexOrPubkey` path segment. You may mix identifiers, but mixing with a non-zero `offset` can skip items because pagination is applied after merging results. Limits: up to 20 fee recipient addresses and up to 100 proposer indices or pubkeys per request. ENS names are supported for addresses. # Resolve ens name or address Source: https://docs.beaconcha.in/api-reference/ens/resolve-ens-name-or-address /api/v1/bundled.yaml get /api/v1/ens/lookup/{domain} Get the address for an ens name and vice versa. Returns and object with the ens name and address - if found. # Epoch overview Source: https://docs.beaconcha.in/api-reference/epochs/epoch-overview /api/v1/bundled.yaml get /api/v1/epoch/{epoch} Retrieve aggregate metrics and status for a beacon chain epoch. You can specify the epoch by number, or use the keywords `latest` (most recently processed epoch) or `finalized` (most recent epoch finalized by the consensus). # Epoch slots Source: https://docs.beaconcha.in/api-reference/epochs/epoch-slots /api/v1/bundled.yaml get /api/v1/epoch/{epoch}/slots Retrieve all slots within a specific epoch, including per-slot block metadata such as proposer, roots, operation counts, sync committee participation, and execution payload details when available. You can specify the epoch by number, or use the keywords `latest` (most recently processed epoch) or `finalized` (most recent finalized epoch). # šŸ’Ž MEV Bids Source: https://docs.beaconcha.in/api-reference/ethereum/block/mev-bids /v3/bundled.yaml post /api/v2/ethereum/block/mev-bids Returns the full per-relay bid ladder for a single block's slot ā€” every recorded relay bid with its value, arrival time, relay, builder, and source. Intended for research and auditing. **Use case guide:** [Investigate a Block](/use-cases/investigate-mev-block) shows how to filter, paginate, and audit the relay bid ladder. **Data provenance:** The bid ladder is collected from offchain relay APIs and streams. Relay-reported timestamps, identities, and bids are not independently verifiable from onchain data, and coverage gaps or inconsistent reporting can make the recorded ladder incomplete. Verify included block fields separately. Results are ordered by arrival time and paginated. An optional `slot_offset_ms_range` filters bids by their slot offset. **Note:** MEV relay and timing data is only available on mainnet at this time. **History:** Relay bid collection began on 2024-06-03 (UTC). No bids are recorded for slots before that date ā€” including all pre-Merge blocks ā€” so the bid ladder is empty for them. Data freshness: per-slot relay statistics lag the chain head by roughly 4 hours. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. # MEV Timing Source: https://docs.beaconcha.in/api-reference/ethereum/block/mev-timing /v3/bundled.yaml post /api/v2/ethereum/block/mev-timing Returns the MEV timing-game outcome for a single block: the winning relay bid, the earliest later bid that would have beaten it (`first_better_bid`), the highest-value later bid (`best_later_bid`), the value left on the table, and the winning relay and builder. **Use case guide:** [Investigate a Block](/use-cases/investigate-mev-block) shows how to interpret the winning bid, later alternatives, and missed value. **Protocol caveat:** The 1200 ms and 2600 ms timing bands apply to pre-Glamsterdam slots. [Glamsterdam](https://ethereum.org/roadmap/glamsterdam/) introduces ePBS and restructures slot production, so post-fork classifications may change. **Data provenance:** Timing and bid fields are derived from offchain relay APIs and streams. Relay-reported timestamps, identities, and bid coverage are not independently verifiable from onchain data; verify included block fields separately. Resolve a block by number or the keywords "latest" / "finalized". Pair this with [/api/v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots) to drill into a specific proposal. **Note:** MEV relay and timing data is only available on mainnet at this time. **History:** Relay bid collection began on 2024-06-03 (UTC). Blocks before that date ā€” including all pre-Merge blocks ā€” return status `unknown`, since the absence of relay data means the timing outcome is not known rather than that no MEV occurred. Data freshness: per-slot relay statistics lag the chain head by roughly 4 hours. A block newer than the latest aggregated slot returns status `pending` until the data catches up. # Block Source: https://docs.beaconcha.in/api-reference/ethereum/block/overview /v3/bundled.yaml post /api/v2/ethereum/block Provides comprehensive details about a specific execution layer block, excluding rewards. For reward details, refer to [v2/ethereum/block/rewards](/api-reference/ethereum/block/rewards). Execution layer blocks contain transactions and state changes, while consensus layer slots manage validator duties and finality. Since the Merge (Proof-of-Stake transition), each execution layer block corresponds to a consensus layer slot, though their numbers differ. This endpoint delivers an overview of the requested block, including its slot reference (if applicable), block hash, timestamp, gas usage, transaction counts, and other key metrics. For pre-Merge blocks, consensus layer references will be null. Query options include block number or keywords like "latest" and "finalized" for the most recent or finalized block. # Details Source: https://docs.beaconcha.in/api-reference/ethereum/block/rewards /v3/bundled.yaml post /api/v2/ethereum/block/rewards Offers detailed insights into the execution layer rewards for a specific block, including transaction fees and MEV (Maximal Extractable Value). You can query using a block number or the keywords "latest" / "finalized". # Consolidations Source: https://docs.beaconcha.in/api-reference/ethereum/consolidations /v3/bundled.yaml post /api/v2/ethereum/slot/consolidations Returns the EIP-7251 requests carried by the block at the specified slot: validator consolidations and switches to compounding withdrawal credentials. Both kinds arrive through the same execution-layer contract with the same fields, including a source and a target public key. The consensus layer distinguishes them by whether those keys are equal: - `consolidation` ā€” the keys differ. The source validator exits and its balance moves to the target, which must already have compounding (`0x02`) withdrawal credentials. - `compounding_switch` ā€” the keys are identical. Nothing exits and no balance moves; the request only changes that validator's withdrawal credentials from `0x01` to `0x02`. The `type` field reports which kind an entry is, so you do not have to compare public keys yourself. Use `type_filter` to narrow the response to one kind. Results are anchored to the slot whose block body carried the request. For a consolidation the resulting balance transfer settles later, when the pending consolidation queue drains to it; that settlement slot is reported in `stage_history.consensus_layer_processed` and is not used for filtering. A compounding switch is applied at inclusion, so both slots are the same. Consolidations settle at the epoch transition and are reported at the last slot of the epoch, also when that slot was missed or its block was orphaned. For such a slot, `stage_history.consensus_layer_processed.block_root` is null. Rejected requests are included. A request rejected at inclusion reached a block but changed no state, so `stage_history.consensus_layer_processed` is null and, for consolidations, a `reject_reason` is set. Because of that delay a past slot's response is **not** immutable straight away: a `queued` consolidation keeps its inclusion slot but gains `amount` and `stage_history.consensus_layer_processed`, and flips to `completed`, long after the slot itself finalized. Cache a slot's response indefinitely only once no entry in it is `queued`; entries that are `completed` or `rejected` are terminal. Data is available from the Pectra fork (epoch 364032, first slot 11649024, 7 May 2025) onwards. On mainnet the earliest request observed is in slot 11649029. Slots before Pectra, and slots that carried no such request, return `200` with an empty `data` array. The validator filter is optional; if omitted, results include every request in the slot. A validator matches when it is either the source or the target of the request. You can combine this endpoint with: - Track consolidations for your own validators across all slots: [/api/v2/ethereum/validators/queues/consolidations](/api-reference/ethereum/validators/queues/consolidations) - Track compounding switches for your own validators: [/api/v2/ethereum/validators/queues/compounding-switches](/api-reference/ethereum/validators/queues/compounding-switches) - Compare the fee in `request.fee` against every other request submitted in the same execution layer block: [/api/v2/ethereum/queues/request-fees](/api-reference/ethereum/queues/request-fees) # Deposits Source: https://docs.beaconcha.in/api-reference/ethereum/deposits /v3/bundled.yaml post /api/v2/ethereum/slot/deposits Returns comprehensive details about all validator deposits processed in the specified slot. The validator filter is optional; if omitted, results include all deposits processed in the slot. Results may include *system deposits* ā€” protocol-generated deposits that are not initiated by a user, such as the deposit created when a validator switches to compounding. See [System deposits and withdrawals](/faqs/system-deposits-and-withdrawals) for details. Since Electra, pending deposits are processed at the epoch transition and reported at the last slot of the epoch, also when that slot was missed or its block was orphaned. For such a slot, `stage_history.consensus_layer_processed.block_root` is null. Before Electra, deposits are processed in the block that includes them, so a slot whose block was orphaned has none. You can combine this endpoint with: - Find deposits associated with your validators: [v2/ethereum/validators/deposit-slots](/api-reference/ethereum/validators/deposit-slots) # šŸ’Ž Overview Source: https://docs.beaconcha.in/api-reference/ethereum/entities/overview /v3/bundled.yaml post /api/v2/ethereum/entities Returns an overview of all entities with their validator count, BeaconScoreĀ®, and net share. **Use case guide:** [Entity benchmarking](/use-cases/entity-benchmarking-overview) explains how to rank entities and compare an operator with the network baseline. Results can be sorted by `beaconscore`, `net_share`, `validator_count`, or `sub_entity_count` in ascending or descending order. By default, results are sorted by `net_share` in descending order. **Note:** The underlying data is precomputed and updated hourly. `all_time` evaluation window is not supported for this endpoint. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. **Attribution Required:** If you display BeaconScoreĀ® data publicly, you must include appropriate attribution. See our [BeaconScoreĀ® License](/legal/beaconscore-license) and [License Materials](/legal/license-materials) for badges and usage guidelines. # šŸ’Ž MEV Timing Source: https://docs.beaconcha.in/api-reference/ethereum/entity/mev-timing /v3/bundled.yaml post /api/v2/ethereum/entity/mev-timing Returns an entity's MEV timing-game statistics as a per-day series. Optionally scope to a sub-entity; omit `sub_entity` for the entity-level rows. **Use case guide:** [Compare MEV Timing](/use-cases/compare-mev-timing) shows how to benchmark an entity or sub-entity against the network. **Protocol caveat:** The 1200 ms and 2600 ms timing bands apply to pre-Glamsterdam slots. [Glamsterdam](https://ethereum.org/roadmap/glamsterdam/) introduces ePBS and restructures slot production, so post-fork classifications may change. **Data provenance:** Timing statistics are derived from offchain relay APIs and streams. Relay-reported timestamps, identities, and bid coverage are not independently verifiable from onchain data; coverage gaps or inconsistent reporting can affect results. Results can be filtered by a time range (bucketed to whole UTC days) and are paginated. For an aggregated posture and histogram over an entity (rather than a daily series), use [/api/v2/ethereum/validators/mev-timing-aggregate](/api-reference/ethereum/validators/mev-timing-aggregate) with its entity selector. **Note:** MEV relay and timing data is only available on mainnet at this time. **History:** Relay bid collection began on 2024-06-03 (UTC). The series contains no days before that date; a time range that falls entirely before it returns an empty result. Data freshness: the most recent ~3 days of daily aggregates are reprocessed and may still change. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. # šŸ’Ž Sub Entities Source: https://docs.beaconcha.in/api-reference/ethereum/entity/sub-entities /v3/bundled.yaml post /api/v2/ethereum/entity/sub-entities Returns an overview of all sub-entities associated with a given entity, including their validator count, BeaconScoreĀ®, and net share. **Use case guide:** [Entity benchmarking](/use-cases/entity-benchmarking-overview) explains how to drill from a public entity into its sub-entities and compare them with the network. Results can be sorted by `beaconscore`, `net_share`, or `validator_count` in ascending or descending order. By default, results are sorted by `net_share` in descending order. **Note:** The underlying data is precomputed and updated hourly. `all_time` evaluation window is not supported for this endpoint. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. **Attribution Required:** If you display BeaconScoreĀ® data publicly, you must include appropriate attribution. See our [BeaconScoreĀ® License](/legal/beaconscore-license) and [License Materials](/legal/license-materials) for badges and usage guidelines. # Epoch Source: https://docs.beaconcha.in/api-reference/ethereum/epoch/overview /v3/bundled.yaml post /api/v2/ethereum/epoch Returns a rolled-up overview of a single consensus layer epoch. In Ethereum, an epoch is a fixed window of consensus layer slots (32 on Ethereum Mainnet) over which validator attestations are aggregated and finality is determined. This endpoint summarizes network-wide activity for the epoch: validator participation, balances, block proposal outcomes, and the protocol events (deposits, withdrawals, exits, slashings) included across its slots. Think of it as a per-epoch starting point: the `slots` range tells you which slots belong to the epoch so you can drill into per-slot detail via [v2/ethereum/slot](/api-reference/ethereum/slot/overview), and the counts point you to the more specific endpoints for each topic. You can query by epoch number, or use "latest" / "finalized" for the most recent or finalized epoch. The "finalized" view can lag the chain's latest finalized epoch by up to one epoch so that every metric of the returned epoch is fully populated. Note: for an epoch whose duties have not yet been fully aggregated (the most recent epochs, whether not-yet-finalized or queried by number just after finalization) the participation- and performance-based fields (`attesting_balance`, `participation_rate`, `attestation_participation`, `sync_participation`, `beaconscore`) are `null` ā€” check `finality` to tell an in-progress epoch apart, and query "finalized" for a complete, stable response. # ETH.STOREĀ® Source: https://docs.beaconcha.in/api-reference/ethereum/eth-store /v3/bundled.yaml post /api/v2/ethereum/eth-store Returns ETH.STOREĀ® ā€” the staking benchmark measuring the average return that validators on the Ethereum network achieved over each 24-hour period. Each datapoint covers one beaconchain-day (a fixed window of `86400 Ć· seconds_per_slot Ć· slots_per_epoch` epochs, indexed by the number of whole days elapsed since genesis) and aggregates every validator that was active for the full day. Each datapoint reports the effective, start, and end balances, the deposits credited during the day, and the rewards split into consensus-layer (attestation, sync-committee, proposal) and execution-layer (priority transaction fees and MEV) components. The annualized rate of return (APR) is given for each layer and combined, together with 7-day and 31-day trailing averages that smooth out day-to-day variance. Results are returned one datapoint per day, most recent first. Free plans select a trailing evaluation window (`24h` for the latest datapoint, up to `all_time` with pagination for the full history). [Scale and Enterprise plans](https://beaconcha.in/pricing) can additionally request an arbitrary range by Unix timestamp, epoch, or slot. Because a datapoint is computed only after its day has finalized, every returned value is immutable and safe to cache indefinitely. ETH.STOREĀ® is not made available for use as a benchmark, whether in relation to a financial instrument, financial contract or to measure the performance of an investment fund, or otherwise in a way that would require it to be administered by a benchmark administrator pursuant to the EU Benchmarks Regulation. Currently Bitfly does not grant any right to access or use ETH.STOREĀ® for such purpose. # Network MEV Timing Source: https://docs.beaconcha.in/api-reference/ethereum/mev-timing /v3/bundled.yaml post /api/v2/ethereum/mev-timing Returns network-wide MEV timing-game statistics as a per-day series. Each day carries the slot counts, a timing breakdown, the median slot offset, and the full histogram. **Use case guide:** [Compare MEV Timing](/use-cases/compare-mev-timing) shows how to compare daily network, entity, and validator-set behavior. **Protocol caveat:** The 1200 ms and 2600 ms timing bands apply to pre-Glamsterdam slots. [Glamsterdam](https://ethereum.org/roadmap/glamsterdam/) introduces ePBS and restructures slot production, so post-fork classifications may change. **Data provenance:** Timing statistics are derived from offchain relay APIs and streams. Relay-reported timestamps, identities, and bid coverage are not independently verifiable from onchain data; coverage gaps or inconsistent reporting can affect results. Results can be filtered by a time range (bucketed to whole UTC days) and are paginated. Use `min_slots_per_day` to exclude sparsely-covered days. **Note:** MEV relay and timing data is only available on mainnet at this time. **History:** Relay bid collection began on 2024-06-03 (UTC). The series contains no days before that date; a time range that falls entirely before it returns an empty result. Data freshness: the most recent ~3 days of daily aggregates are reprocessed and may still change. # Network Performance Source: https://docs.beaconcha.in/api-reference/ethereum/performance-aggregate /v3/bundled.yaml post /api/v2/ethereum/performance-aggregate Returns aggregated performance metrics for the entire network in the given time range. **Use case guide:** [Entity benchmarking](/use-cases/entity-benchmarking-overview) uses this endpoint as the network baseline for public and private validator-set comparisons. Must provide either start + end times or epochs **Custom time ranges:** Query arbitrary time ranges using Unix timestamps, epochs, or slots ā€” exclusively for [Scale and Enterprise plans](https://beaconcha.in/pricing). Custom ranges are served at whole-UTC-day granularity (partial days are rounded outward), and the response `range` reports the actual covered range. # Network Queue Overview Source: https://docs.beaconcha.in/api-reference/ethereum/queues /v3/bundled.yaml post /api/v2/ethereum/queues Returns information about the various staking-related queues (deposit, exit, full withdrawal, consolidation, compounding switch) and how long the expected wait time is. **Use case guide:** [Queue tracking](/use-cases/queue-tracking) explains how to choose between network and validator queue views, estimate wait times, and measure staking flows. The `estimated_processed_at` field in each queue always refers to the very last item in the network queue (i.e. when the entire queue will be fully processed). For per-validator queue details, use: - [/api/v2/ethereum/validators/queues](/api-reference/ethereum/validators/queues) ā€” overview per validator ### Deprecation Notice This notice only affects you if your requests do **not** send the `Accept: application/vnd.beaconcha.in.v2.1+json` header ā€” such requests currently receive the legacy v2 schema. The legacy schema is deprecated and will be sunset on 02.07.2026 23:59:59 UTC. After that date, all requests receive the new v2.1 schema regardless of the `Accept` header, which will break your response parsing if you have not migrated. To migrate, send the `Accept: application/vnd.beaconcha.in.v2.1+json` header and adapt your parsing to the v2.1 schema shown in the response section below. To review the legacy schema you are currently receiving, select v2 from the **Content-Type dropdown** in the top-right corner of the response section. # Staking Queues History Source: https://docs.beaconcha.in/api-reference/ethereum/queues/history /v3/bundled.yaml post /api/v2/ethereum/queues/history Returns a history of the staking queue sizes ā€” how much ETH is waiting to enter and leave staking over time. Each entry is a snapshot of the staking queues at one epoch. History begins at the Pectra fork (7 May 2025), which is where the queues themselves begin: the pending deposit, consolidation and partial-withdrawal queues are Pectra state fields, so there is nothing to report before it. How far back a given request reaches also depends on `granularity` ā€” `epoch` resolution is currently available for a shorter, more recent span than `daily`. See that field for the exact start points and how out-of-range requests are handled. An epoch with no usable snapshot is omitted from the series rather than returned as an empty entry, so entries are not guaranteed to be evenly spaced. Read `epoch` and `timestamp` on each entry rather than inferring them from position. Each entry covers the four queues the snapshot records. The `withdrawal_sweep` and `compounding_switch_queue` entries of the live endpoint have no historical counterpart and are not returned here. For the current point-in-time queue state, see [/api/v2/ethereum/queues](/api-reference/ethereum/queues). # Withdrawal & Consolidation Request Fees Source: https://docs.beaconcha.in/api-reference/ethereum/queues/request-fees /v3/bundled.yaml post /api/v2/ethereum/queues/request-fees Returns what it costs to submit a withdrawal or consolidation request to the execution layer, as observed history: one entry per execution layer block that saw at least one request, most recent block first. Two contracts charge such a fee, and `type_filter` selects between them ā€” the EIP-7002 contract for execution-layer triggered partial withdrawals and full exits, and the EIP-7251 contract for consolidations and compounding switches. Deposits are free, so they do not appear here. Every request that a validator queue endpoint reports as `pending` paid one of these fees. Both contracts price requests with an EIP-1559 style mechanism: the fee starts at a floor of 1 wei and climbs exponentially while submissions exceed the per-block target, then decays back toward the floor once demand drops. A mass exit or mass consolidation event therefore lifts the fee well above the floor for as long as it lasts. Operators batching many exits or consolidations can use this history to judge whether they are submitting into such a period. ### What these numbers are, and what they are not This endpoint reports **fees actually paid**, derived from the value sent with each request transaction. It is not a fee oracle and does not read the contracts' current fee. - `fee_min` is the best available estimate of the protocol-required fee in that block, because no submitter can pay less than the contract demands. - `fee_max` may exceed it. The contracts do not refund an overpayment, and some tooling deliberately overpays so the transaction still succeeds if the fee rises between signing and inclusion. - Blocks with no requests are absent from the response. A gap does not mean the fee is unknown: with no submissions the fee decays deterministically toward the 1 wei floor, so a long gap implies the fee has returned to the floor. This endpoint reports historic state only and must not be used as a fee oracle. Its most recent entry is a fee that was already paid in a past block, not the fee your own submission has to pay. For the fee that applies to the next block, use [/api/v2/ethereum/queues/request-fees/current](/api-reference/ethereum/queues/request-fees/current). To obtain the exact fee for a request you are about to submit, call the contract itself with empty calldata ā€” that is the only authoritative source. Results can be filtered by a time range and are paginated. Omit `range` to cover the whole available history starting at the most recent block; this endpoint is network-wide, so no validator selection is involved. Supply a `range` to reach a past congestion event instead of paging back to it. The `range` in the response reports the span the returned entries actually cover, not the span you asked for. You can combine this endpoint with: - Inspect the individual requests that paid these fees, and the fee each one paid: [/api/v2/ethereum/slot/consolidations](/api-reference/ethereum/consolidations) and [/api/v2/ethereum/slot/withdrawals](/api-reference/ethereum/withdrawals) - Check the fee environment your own validators' requests were submitted into, using the execution layer block from their `stage_history`: [/api/v2/ethereum/validators/queues/consolidations](/api-reference/ethereum/validators/queues/consolidations) Data is available from the Pectra fork (7 May 2025) onwards. On mainnet the first consolidation request was submitted in execution layer block 22431119 and the first withdrawal request in block 22431159, both on 7 May 2025. A range that falls entirely before Pectra returns `200` with an empty `data` array. # Withdrawal & Consolidation Request Fees (Current) Source: https://docs.beaconcha.in/api-reference/ethereum/queues/request-fees/current /v3/bundled.yaml post /api/v2/ethereum/queues/request-fees/current Returns what it costs to submit a withdrawal or consolidation request to the execution layer right now: one entry per request type. The value is the fee that applies to the next block, so it is what your submission pays if it is included immediately. Two request types carry such a fee, and `request_type` tells the entries apart ā€” EIP-7002 requests, which are execution-layer triggered partial withdrawals and full exits, and EIP-7251 requests, which are consolidations and compounding switches. Deposits are free, so they do not appear here. Both types are priced with an EIP-1559 style mechanism: the fee starts at a floor of 1 wei and climbs exponentially while submissions exceed the per-block target, then decays back toward the floor once demand drops. The climb has no per-block ceiling, so a single busy block can raise the fee by orders of magnitude. The fee reported here is not guaranteed to be sufficient by submission time, because it can still change in the block your transaction lands in. An overpayment is not refunded, and an underpayment makes the call revert. No fixed margin is safe in all conditions, so you must decide your own trade between paying above the reported value and risking a revert. Read the fee immediately before you submit, and during a congestion period read it again as close to submission as possible. To obtain the exact fee for a request you are about to submit, call the contract itself with empty calldata ā€” that is the only authoritative source. ### Freshness The fee is read approximately every 4 seconds, so a new execution layer block is normally picked up within a few seconds of it landing. Every entry carries the execution layer `block` and `timestamp` it was read at, so you can compare `timestamp` to the current time to judge its age. Because `timestamp` is the block's own time, a normal age is anywhere inside the current slot, and a missed slot adds a further slot to it. This endpoint does not serve a fee it knows to be stale. If the underlying data stops advancing, it returns `503` instead of a `200` that carries an out-of-date value, because a fee that is too low makes your submission revert. Treat `503` as retryable, and do not fall back to a cached fee without a new age check. The response always carries one entry per request type. It is never `200` with an empty `data` array: either both fees are known, or the endpoint answers `503`. This endpoint describes only the present. For the fee history, see [/api/v2/ethereum/queues/request-fees](/api-reference/ethereum/queues/request-fees). # Rewards Source: https://docs.beaconcha.in/api-reference/ethereum/slot/attestation-duties /v3/bundled.yaml post /api/v2/ethereum/slot/attestation-duties Provides detailed status and reward information about attestation duties assigned to validators for a specific slot. The validator filter is optional; if omitted, results include all validators assigned attestation duties for the slot. The response only includes attestation duties scheduled for the specified slot, not attestations included in this slot. Use the reward endpoints for epoch based attestation rewards information. You can combine this endpoint with: - Find attestations slots your validators were assigned to: [v2/ethereum/validators/attestation-slots](/api-reference/ethereum/validators/attestation-slots) # Slot Source: https://docs.beaconcha.in/api-reference/ethereum/slot/overview /v3/bundled.yaml post /api/v2/ethereum/slot Returns detailed information about a specific consensus layer slot. In Ethereum, "slots" are data containers on the consensus layer where validator duties are scheduled and blocks may be proposed. Each slot may reference a block, but a slot can also be missed. This endpoint provides an overview of the requested slot, including its status (proposed, missed, scheduled), assigned proposer, participation metrics, protocol events (deposits, withdrawals, slashings), and other relevant details. You can query by slot number, block root hash, or use "latest" / "finalized" for the most recent or finalized slot. # Rewards Source: https://docs.beaconcha.in/api-reference/ethereum/slot/sync-committee-duties /v3/bundled.yaml post /api/v2/ethereum/slot/sync-committee-duties Provides status and reward information about sync committee duties for a specific slot for each validator. The validator filter is optional; if omitted, results include all validators assigned sync duties for the slot. This endpoint currently only supports finalized data. Use the reward endpoints for epoch based attestation rewards information. You can combine this endpoint with: - Find periods your validators were part in: [v2/ethereum/validators/sync-committee-periods](/api-reference/ethereum/validators/sync-committee-periods) - Sync committee overview: [v2/ethereum/sync-committee](/api-reference/ethereum/sync-committee/overview) # Explorer State Source: https://docs.beaconcha.in/api-reference/ethereum/state /v3/bundled.yaml post /api/v2/ethereum/state Returns the explorer's current view of the Ethereum chain, including network health, validator counts, balances, and finality status. Unlike most API endpoints where processing lag is invisible, this endpoint explicitly exposes how far behind the explorer is relative to the actual chain head (see `data_freshness`). Use it to determine whether the data you're querying from other endpoints is sufficiently up-to-date for your use case. # Validator Statuses Source: https://docs.beaconcha.in/api-reference/ethereum/state/validator-statuses /v3/bundled.yaml post /api/v2/ethereum/state/validator-statuses Returns the distribution of validator states across the network or a given validator filter. By default it returns the network distribution, but you might pass the optional validator filter to get a breakdown of states for a specific set of validators (e.g. your own). # Sync Committee Periods Source: https://docs.beaconcha.in/api-reference/ethereum/sync-committee/overview /v3/bundled.yaml post /api/v2/ethereum/sync-committee Returns basic sync committee information for a particular sync period. Use this to determine the range of epochs a given sync period entails. You can combine this endpoint with: - Validators in sync committee period: [v2/ethereum/sync-committee/validators](/api-reference/ethereum/sync-committee/validators) # Validators Source: https://docs.beaconcha.in/api-reference/ethereum/sync-committee/validators /v3/bundled.yaml post /api/v2/ethereum/sync-committee/validators Returns the validators in the sync committee for a particular sync period. You can combine this endpoint with: - Sync Committee Period Overview: [v2/ethereum/sync-committee](/api-reference/ethereum/sync-committee) Response can be filtered to a specific set of validators by providing optional **validator** identifiers in the request body. # Validator Source: https://docs.beaconcha.in/api-reference/ethereum/validators /v3/bundled.yaml post /api/v2/ethereum/validators Returns basic information about a set of validators at the current epoch. Data returned by the endpoint is based on the latest completed epoch of the beacon chain (not finalized). Use `status_filter` to return only validators in the listed lifecycle statuses, for example `["active"]` for the currently active validators of an entity or a withdrawal address. Statuses are evaluated at the same epoch as the rest of the response. When the selected validators exist but none of them has a matching status, the response is `200` with an empty `data` array. The filter reads lifecycle data that is refreshed after each epoch, so a validator that was just deposited or slashed can take up to about one epoch to match it; the returned `status` always matches the filter. For the same reason a filtered page can hold fewer entries than `page_size`, even none, while `next_cursor` is set; keep paging until `next_cursor` is empty. # APY & ROI Source: https://docs.beaconcha.in/api-reference/ethereum/validators/apy-roi /v3/bundled.yaml post /api/v2/ethereum/validators/apy-roi Returns the annual percentage yield (APY) and return on investment (ROI) for a known collection or group of validators. Known collections are referenced by index, public key, deposit address, or withdrawal address. **Use case guide:** [APY & ROI metrics](/use-cases/apy-roi) explains how to choose a window, interpret return metrics, and decide when BeaconScoreĀ® is the better comparison. For comparing performance across different staking providers, we recommend using the BeaconScoreĀ® from the Performance Aggregated endpoints instead of APY or ROI, as BeaconScoreĀ® normalizes for luck and provides a fairer comparison. Note that some residual luck factors outside a validator's control can still influence BeaconScoreĀ®, especially over short evaluation windows. See the Residual Luck Factors section in the BeaconScoreĀ® documentation for details. **Custom time ranges:** Query arbitrary time ranges using Unix timestamps, epochs, or slots ā€” exclusively for [Scale and Enterprise plans](https://beaconcha.in/pricing). Custom ranges are served at whole-UTC-day granularity (partial days are rounded outward), and the response `range` reports the actual covered range. # Attestation Slots Source: https://docs.beaconcha.in/api-reference/ethereum/validators/attestation-slots /v3/bundled.yaml post /api/v2/ethereum/validators/attestation-slots Returns all slot numbers where the specified validators were assigned attestation duties, grouped by slot. Each result shows a slot number and the count of your validators that attested in that slot. This is useful for tracking when your validators attested and identifying slots where they may have missed attestations. For example, querying one epoch with 200 validators returns up to 32 results (one per slot in the epoch) rather than 200 individual validator-slot pairs. Combine this endpoint with others for deeper insights: - Consensus slot information: [v2/ethereum/slot](/api-reference/ethereum/slot/overview) This endpoint serves as a high-level overview, while other endpoints provide detailed data for specific slots or validators. Results can be filtered by a time range. Validators that were never assigned an attestation duty ā€” a deposit still in the entry queue, for example ā€” return an empty result rather than an error. Note: This endpoint supports **only finalized** data at this time. # Validator Balance Source: https://docs.beaconcha.in/api-reference/ethereum/validators/balances /v3/bundled.yaml post /api/v2/ethereum/validators/balances Returns the balances for a set of validators at a particular epoch. Use `status_filter` to return only validators in the listed status groups at the requested `epoch`, for example `["active"]` to leave out validators that were not active yet or had already exited at that epoch. When the selected validators have data for the epoch but none of them is in a listed group, the response is `200` with an empty `data` array. For exact statuses such as `active_exiting`, use [Validator](/api-reference/ethereum/validators), which reports the current status of each validator. # Deposit Slots Source: https://docs.beaconcha.in/api-reference/ethereum/validators/deposit-slots /v3/bundled.yaml post /api/v2/ethereum/validators/deposit-slots Returns a list of deposit events for your selected validators. Use this endpoint to quickly identify all relevant deposits for your validator set. You can combine this endpoint with: - Deposit detail from slot: [v2/ethereum/slot/deposits](/api-reference/ethereum/slot/deposits) - Consensus slot information: [v2/ethereum/slot](/api-reference/ethereum/slot/overview) Note: [v2/ethereum/slot/deposits](/api-reference/ethereum/slot/deposits) returns deposits by the slot they were **processed** in. Rows whose `observed_stages` do not include `consensus_layer_processed` describe a deposit that was still queued at that slot and cannot be looked up there. To get only rows with detail available, set `stage_filter: ["consensus_layer_processed"]`. Results can be filtered by a time range. # šŸ’Ž Validator Metadata Source: https://docs.beaconcha.in/api-reference/ethereum/validators/metadata /v3/bundled.yaml post /api/v2/ethereum/validators/metadata Returns metadata for a set of validators, including their index, public key, deposit address, withdrawal address, entity, and sub-entity. **Use case guide:** [Entity benchmarking](/use-cases/entity-benchmarking-overview) uses validator metadata to map validators to public entities and sub-entities. Results are paginated with a default and maximum page size of 10. Ideal for discovering validator associations; use the results to supply filters in other endpoints via the validator selector. **Note:** Entity and sub-entity assignments are updated once per day. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. # MEV Timing Aggregate Source: https://docs.beaconcha.in/api-reference/ethereum/validators/mev-timing-aggregate /v3/bundled.yaml post /api/v2/ethereum/validators/mev-timing-aggregate Returns the overall MEV timing posture and histogram for a set of validators over a fixed evaluation window. The validator set may be selected by identifiers, dashboard, withdrawal/deposit address, or entity/sub-entity. **Use case guide:** [Compare MEV Timing](/use-cases/compare-mev-timing) shows how to profile validator cohorts and interpret their timing distribution. **Protocol caveat:** The 1200 ms and 2600 ms timing bands apply to pre-Glamsterdam slots. [Glamsterdam](https://ethereum.org/roadmap/glamsterdam/) introduces ePBS and restructures slot production, so post-fork classifications may change. **Data provenance:** Timing statistics are derived from offchain relay APIs and streams. Relay-reported timestamps, identities, and bid coverage are not independently verifiable from onchain data; coverage gaps or inconsistent reporting can affect results. Currently only the `180d` rolling window is available (see `range.evaluation_window`). Omit `range` to use it. **Note:** MEV relay and timing data is only available on mainnet at this time. **History:** Relay bid collection began on 2024-06-03 (UTC). The evaluation window only reflects data from that date onward. Data freshness: validator timing profiles are rebuilt nightly over a rolling 180-day window. # Performance Aggregated Source: https://docs.beaconcha.in/api-reference/ethereum/validators/performance-aggregate /v3/bundled.yaml post /api/v2/ethereum/validators/performance-aggregate Returns aggregated performance metrics for a known collection or group of validators. Known collections are referenced by index, public key, deposit address, or withdrawal address. **Use case guide:** [Validator performance](/use-cases/performance-introduction) explains how to monitor BeaconScoreĀ®, select evaluation windows, and compare validator sets. This endpoint includes the **BeaconScoreĀ®** metric, which measures how well validators perform their duties. Learn more about [how BeaconScoreĀ® is calculated](/beaconscore/introduction). **Custom time ranges:** Query arbitrary time ranges using Unix timestamps, epochs, or slots ā€” exclusively for [Scale and Enterprise plans](https://beaconcha.in/pricing). Custom ranges are served at whole-UTC-day granularity (partial days are rounded outward), and the response `range` reports the actual covered range. # Performance Source: https://docs.beaconcha.in/api-reference/ethereum/validators/performance-list /v3/bundled.yaml post /api/v2/ethereum/validators/performance-list Returns a list of a validator's performance for a specific epoch for a set of validators. **Use case guide:** [Validator performance](/use-cases/performance-introduction) explains when to use per-epoch performance and how it complements the aggregate endpoint. This endpoint includes the **BeaconScoreĀ®** metric, which measures how well validators perform their duties. Learn more about [how BeaconScoreĀ® is calculated](/beaconscore/introduction). Use `status_filter` to return only validators in the listed status groups at the requested `epoch`, for example `["active"]` to leave out validators that were not active yet or had already exited at that epoch. When the selected validators have data for the epoch but none of them is in a listed group, the response is `200` with an empty `data` array. For exact statuses such as `active_exiting`, use [Validator](/api-reference/ethereum/validators), which reports the current status of each validator. # Proposal Slots Source: https://docs.beaconcha.in/api-reference/ethereum/validators/proposal-slots /v3/bundled.yaml post /api/v2/ethereum/validators/proposal-slots Returns a list of block proposal slots during which one or more of your selected validators were assigned a proposal duty. Use this endpoint to quickly identify all relevant proposals for your validator set, making it easier to explore proposal performance and related activity. You can combine this endpoint with: - Reward: [v2/ethereum/block/rewards](/api-reference/ethereum/block/rewards) - Consensus slot information: [v2/ethereum/slot](/api-reference/ethereum/slot/overview) - Execution block information: [v2/ethereum/block](/api-reference/ethereum/block/overview) or use it alongside reward and performance endpoints for deeper analysis, depending on your needs. Results can be filtered by a time range. Note: This endpoint supports **only finalized** data at this time. # Validator Queue ETA Source: https://docs.beaconcha.in/api-reference/ethereum/validators/queues /v3/bundled.yaml post /api/v2/ethereum/validators/queues Provides a rough overview of staking-related queue positions (deposit, exit, full withdrawal, consolidation, compounding switch) and estimated wait times for the selected set of validators. **Use case guide:** [Queue tracking](/use-cases/queue-tracking) explains when to use per-validator ETAs and how they complement the network queue view. Uses the same unified schema as the network-level queue endpoint The `estimated_processed_at` field in each queue always refers to the very last item for that validator. For example, if a validator has multiple pending deposits, `estimated_processed_at` in `deposit_queue` refers to when the last deposit will be processed. `compounding_switch_queue` is the exception: it refers to the validator's **earliest** pending switch request, because the switch takes effect when the first one is processed and any later request is a no-op. For network-wide queue statistics across all validators, see [/api/v2/ethereum/queues](/api-reference/ethereum/queues). # Validator Queue Compounding Switch Details Source: https://docs.beaconcha.in/api-reference/ethereum/validators/queues/compounding-switches /v3/bundled.yaml post /api/v2/ethereum/validators/queues/compounding-switches Returns a paginated list of compounding switch requests for the selected validators. A compounding switch changes a validator's withdrawal credential prefix from `0x01` to `0x02`, unlocking effective balances above 32 ETH (up to 2048 ETH). Unlike a consolidation, the validator stays active throughout ā€” no exit, no balance transfer. This endpoint covers **self-consolidation requests only** (source pubkey equals target pubkey). For cross-validator consolidations where one validator's balance is merged into another, use [/api/v2/ethereum/validators/queues/consolidations](/api-reference/ethereum/validators/queues/consolidations). A `pending` entry becomes `completed` or `rejected` once the consensus layer picks the request up out of the execution-layer contract, which releases at most two requests per block. Unlike consolidations, switches have no intermediate queued phase ā€” they are accepted or rejected immediately at consensus-layer inclusion. Pending entries appear first. Completed and rejected entries follow, ordered by submission time (most recent first). Use `status_filter` to narrow the response to a single status, e.g. only `rejected` entries. Use this endpoint alongside the queue overview at [/api/v2/ethereum/validators/queues](/api-reference/ethereum/validators/queues) for a complete picture. **Temporary restriction:** the validator selector must resolve to no more than 50,000 validators. A larger selection returns `400`. Narrow the selection ā€” for example, select a sub-entity instead of a whole entity ā€” or page through it with a set of validator indices. This limit will be raised. # Validator Queue Consolidation Details Source: https://docs.beaconcha.in/api-reference/ethereum/validators/queues/consolidations /v3/bundled.yaml post /api/v2/ethereum/validators/queues/consolidations Returns a flat, paginated list of consolidation requests involving the selected validators, whether as source (balance being merged away) or as target (balance being received). The response is not limited to requests that are still in flight: it covers the complete history of consolidations for the selected validators, back to the Pectra fork (7 May 2025). Pass `status_filter: completed` to retrieve only consolidations that have already settled. Each entry pairs a source validator with a target validator. A single validator may appear in multiple entries across both roles. Use `role_filter` to keep only the entries where a selected validator is the source, or only those where it is the target ā€” for example, to list every validator that was ever merged into a given target validator. Which fields an entry carries depends on its `status`: | `status` | Fields set | |---|---| | `pending` | `execution_layer` ā€” the submitting transaction | | `queued` | `source_exit_at`, `estimated_processed_at` | | `completed` | `amount`, `processed_slot` | | `rejected` | `reject_reason` | A `pending` entry becomes `queued` once the consensus layer picks the request up out of the execution-layer contract, which releases at most two consolidation requests per block. Pending and queued entries appear first, ordered by queue position (soonest processed first). Completed and rejected entries follow, ordered by submission time (most recent first). Use `status_filter` to narrow the response to a single status, e.g. only `rejected` entries. A rejected entry whose `reject_reason` is `source_equals_target` is not a failed consolidation ā€” it is a failed switch to compounding credentials, which the consensus layer reports through the consolidation path because both requests share one contract and one structure. A common cause is asking a validator that already has `0x02` credentials to switch again. Use [/api/v2/ethereum/validators/queues/compounding-switches](/api-reference/ethereum/validators/queues/compounding-switches) to retrieve those entries as switches. Use this endpoint in combination with the queue overview at [/api/v2/ethereum/validators/queues](/api-reference/ethereum/validators/queues) for a complete picture. **Temporary restriction:** the validator selector must resolve to no more than 50,000 validators. A larger selection returns `400`. Narrow the selection ā€” for example, select a sub-entity instead of a whole entity ā€” or page through it with a set of validator indices. This limit will be raised. # Rewards Aggregated Source: https://docs.beaconcha.in/api-reference/ethereum/validators/rewards-aggregate /v3/bundled.yaml post /api/v2/ethereum/validators/rewards-aggregate Returns the cumulative rewards for a set for a known collection or group of validators. Known collections are referenced by index, public key, deposit address, or withdrawal address. **Use case guide:** [Validator rewards](/use-cases/rewards-introduction) explains when to use aggregate rewards and how to turn the response into reports and comparisons. Use [Rewards](/api-reference/ethereum/validators/rewards-list) for a rewards breakdown of each validator. Note: Only finalized epochs are supported for rewards data. **Attribution Required:** If you display BeaconScoreĀ® data publicly, you must include appropriate attribution. See our [BeaconScoreĀ® License](/legal/beaconscore-license) and [License Materials](/legal/license-materials) for badges and usage guidelines. **Custom time ranges:** Query arbitrary time ranges using Unix timestamps, epochs, or slots ā€” exclusively for [Scale and Enterprise plans](https://beaconcha.in/pricing). Custom ranges are served at whole-UTC-day granularity (partial days are rounded outward), and the response `range` reports the actual covered range. # Rewards Source: https://docs.beaconcha.in/api-reference/ethereum/validators/rewards-list /v3/bundled.yaml post /api/v2/ethereum/validators/rewards-list Returns a breakdown of rewards for each validator for a given epoch. **Use case guide:** [Validator rewards](/use-cases/rewards-introduction) explains when to use per-epoch rewards and links to custom-range, tax, and missed-reward workflows. Use [Rewards Aggregated](/api-reference/ethereum/validators/rewards-aggregate) for a cumulative view of all validator rewards combined. Note: Only finalized epochs are supported for rewards data. Use `status_filter` to return only validators in the listed status groups at the requested `epoch`, for example `["active"]` to leave out validators that were not active yet or had already exited at that epoch. When the selected validators have data for the epoch but none of them is in a listed group, the response is `200` with an empty `data` array. For exact statuses such as `active_exiting`, use [Validator](/api-reference/ethereum/validators), which reports the current status of each validator. **Attribution Required:** If you display BeaconScoreĀ® data publicly, you must include appropriate attribution. See our [BeaconScoreĀ® License](/legal/beaconscore-license) and [License Materials](/legal/license-materials) for badges and usage guidelines. # Sync Committee Periods Source: https://docs.beaconcha.in/api-reference/ethereum/validators/sync-committee-periods /v3/bundled.yaml post /api/v2/ethereum/validators/sync-committee-periods Returns a deduplicated list of sync committee periods during which one or more of your selected validators were assigned sync committee duties. Use this endpoint to quickly identify all relevant periods for your validator set, making it easier to explore sync committee participation and related activity. You can combine this endpoint with: - Resolve to slots/epochs: [v2/ethereum/sync-committee](/api-reference/ethereum/sync-committee/overview) - Sync Duties at slot: [v2/ethereum/slot/sync-committee-duties](/api-reference/ethereum/slot/sync-committee-duties) or use it alongside reward and performance endpoints for deeper analysis, depending on your needs. Results can be filtered by a time range. Note: The `range` in the response spans only the first to the last sync committee period your validators were assigned to ā€” not the full chain history. A validator assigned during periods 370ā€“1218, for example, returns a range covering just those periods. Note: This endpoint supports **only finalized** data at this time. # Withdrawal Slots Source: https://docs.beaconcha.in/api-reference/ethereum/validators/withdrawal-slots /v3/bundled.yaml post /api/v2/ethereum/validators/withdrawal-slots Returns a list of withdrawal events for your selected validators. Use this endpoint to quickly identify all relevant withdrawals for your validator set. You can combine this endpoint with: - Withdrawal detail from slot: [v2/ethereum/slot/withdrawals](/api-reference/ethereum/slot/withdrawals) - Consensus slot information: [v2/ethereum/slot](/api-reference/ethereum/slot/overview) Note: [v2/ethereum/slot/withdrawals](/api-reference/ethereum/slot/withdrawals) returns withdrawals by the slot they were **processed** in. Rows whose `observed_stages` do not include `consensus_layer_processed` describe a withdrawal request that was still queued at that slot and cannot be looked up there. To get only rows with detail available, set `stage_filter: ["consensus_layer_processed"]`. Results can be filtered by a time range. # Withdrawals Source: https://docs.beaconcha.in/api-reference/ethereum/withdrawals /v3/bundled.yaml post /api/v2/ethereum/slot/withdrawals Returns comprehensive details about all validator withdrawals processed in the specified slot. The validator filter is optional; if omitted, results include all withdrawals processed in the slot. Results may include *system withdrawals* ā€” protocol-generated withdrawals that are not initiated by a user, such as the withdrawal created when a validator switches to compounding. See [System deposits and withdrawals](/faqs/system-deposits-and-withdrawals) for details. Use this endpoint to quickly identify all relevant withdrawals for a slot. You can combine this endpoint with: - Find withdrawals associated with your validators: [v2/ethereum/validators/withdrawal-slots](/api-reference/ethereum/validators/withdrawal-slots) # ETH.Store daily aggregates Source: https://docs.beaconcha.in/api-reference/ethstoreĀ®/ethstore-daily-aggregates /api/v1/bundled.yaml get /api/v1/ethstore/{day} Retrieve ETH.StoreĀ® daily aggregate metrics that represent the average financial return validators achieved over a 24-hour period. A "beaconchain-day" is defined as the number of full days elapsed since chain genesis, computed as blocks grouped into periods of `(24 * 60 * 60) // SlotsPerEpoch // SecondsPerSlot` epochs. Use this endpoint to analyze validator returns, moving averages, and reward composition (consensus-layer vs. execution-layer fees) on a per-day basis. See https://github.com/gobitfly/eth.store for additional context. # Current gas price recommendations Source: https://docs.beaconcha.in/api-reference/gas/current-gas-price-recommendations /api/v1/bundled.yaml get /api/v1/execution/gasnow Retrieve current execution-layer fee recommendations and ETH price snapshot. The response provides four fee tiers expressed as wei per gas, each corresponding to a target inclusion time: rapid (ā‰ˆ15 seconds), fast (ā‰ˆ1 minute), standard (ā‰ˆ3 minutes), and slow (>10 minutes). The payload also includes a Unix millisecond timestamp and an ETH/USD price snapshot. # Machine Metrics Source: https://docs.beaconcha.in/api-reference/machine-metrics /v3/bundled.yaml post /api/v2/machine-metrics Retrieve machine monitoring metrics for the authenticated user. Returns system, validator client, and beacon node metrics that were previously pushed via the `--monitoring-endpoint` flag and set up via https://beaconcha.in/user/settings#app. Users can only access metrics belonging to their own API key. Optionally filter by one or more machine names. Provide a time range via unix timestamps to query a specific historical window (maximum 31 days, limited by data retention). Each array is ordered newest first, then paginated toward older data. Pagination uses an opaque continuation token that tracks the last emitted `(timestamp, machine)` tuple separately for `system_metrics`, `validator_metrics`, and `node_metrics`. Clients must treat `paging.next_cursor` as opaque. # Machine Names Source: https://docs.beaconcha.in/api-reference/machine-metrics/machine-names /v3/bundled.yaml post /api/v2/machine-metrics/machine-names List all known machine names for the authenticated user. These are the names that were provided when pushing metrics via the `--monitoring-endpoint` flag. # Chart Source: https://docs.beaconcha.in/api-reference/misc/chart /api/v1/bundled.yaml get /api/v1/chart/{chart} Returns charts from the page https://beaconcha.in/charts as PNG # Explorer Availability Source: https://docs.beaconcha.in/api-reference/misc/explorer-availability /api/v1/bundled.yaml get /api/healthz-loadbalancer Health endpoint to monitor the operational status of the explorer (used for load balancer health checks) # Explorer Health Source: https://docs.beaconcha.in/api-reference/misc/explorer-health /api/v1/bundled.yaml get /api/healthz Provides the health status of all modules of the explorer. This endpoint is useful for monitoring the availability and functionality of the explorer's components. - **Modules Monitored:** Includes monitoring of services such as `monitoring_app`, `monitoring_el_data`, `monitoring_services`, `monitoring_cl_data`, `monitoring_api`, `monitoring_redis`. - **Response Details:** Returns the status of each module. If all modules are operational, the response will indicate success. Otherwise, it will return an error with details about the failing modules. # Graffiti wall pixels Source: https://docs.beaconcha.in/api-reference/misc/graffiti-wall-pixels /api/v1/bundled.yaml get /api/v1/graffitiwall Retrieve pixels painted on the community graffiti wall within a rectangular area and a slot range. Coordinates are expressed in pixels with the origin at the top-left corner (x = 0, y = 0). Boundary coordinates are inclusive. If you do not provide a slot, the service returns pixels from the most recent 10,000 slots. You can expand the time window by setting `slot` (end of range) and optionally `startSlot` (start of range). When `startSlot` is omitted, it defaults to `slot - 10000`. Use `summarize=true` to receive only the final color per pixel within the requested slot range (end state). When `summarize=false` or omitted, the API returns the full sequence of changes within the range. # Latest consensus and execution state Source: https://docs.beaconcha.in/api-reference/network/latest-consensus-and-execution-state /api/v1/bundled.yaml get /api/v1/latestState Retrieve the latest known network state as observed by the explorer backend. The payload includes current slot and epoch numbers, the most recent finalized epoch, a finality delay indicator, a syncing flag, and display rates used for price conversions in the UI. # Consensus-layer rewards Source: https://docs.beaconcha.in/api-reference/rewards/consensus-layer-rewards /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/performance Retrieve consensus-layer rewards for one or more validators over multiple lookback windows. Provide validator identifiers as a comma-separated list in the path parameter. The service accepts validator indices and 0x-prefixed BLS pubkeys (up to the server-enforced limit; default 100). Amounts are returned in gwei. # Execution layer rewards Source: https://docs.beaconcha.in/api-reference/rewards/execution-layer-rewards /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/execution/performance Retrieve execution-layer rewards (priority fees and MEV payments) for one or more validators over multiple lookback windows. Provide validator identifiers as a comma-separated list in the path parameter. The service accepts validator indices and 0x-prefixed BLS pubkeys (up to the server-enforced limit; default 100). Values are reported in wei. # Validator performance leaderboard Source: https://docs.beaconcha.in/api-reference/rewards/validator-performance-leaderboard /api/v1/bundled.yaml get /api/v1/validator/leaderboard Retrieve the current top 100 validators ranked by 7-day consensus-layer rewards. This endpoint does not accept query parameters. # Get Rocket Pool validator metadata by index or pubkey Source: https://docs.beaconcha.in/api-reference/rocketpool/get-rocket-pool-validator-metadata-by-index-or-pubkey /api/v1/bundled.yaml get /api/v1/rocketpool/validator/{indexOrPubkey} Retrieve Rocket Poolā€“specific metadata for one or more Ethereum consensus validators. You provide a comma-separated list of validator identifiers in the path parameter. The server resolves each identifier to a validator index and returns the corresponding Rocket Pool minipool and node data. Response shape: - If you request a single validator, the response data field is a single object. - If you request multiple validators, the data field is an array of objects in no guaranteed order. Use this endpoint to answer questions such as: - What is the current minipool status and node fee for a validator? - Has the node opted into the smoothing pool, and how much has been claimed or remains unclaimed? - What are the nodeā€™s RPL stake metrics (effective, min, max)? # Rocket Pool network statistics Source: https://docs.beaconcha.in/api-reference/rocketpool/rocket-pool-network-statistics /api/v1/bundled.yaml get /api/v1/rocketpool/stats Retrieve current Rocket Pool protocol statistics as observed by the explorer backend. Use this endpoint to monitor network-level metrics including node and minipool counts, rETH supply, rETH exchange rate and APR, claim interval timing, and protocol balances. Responses are cached for one minute and subject to the API's standard rate limits. You do not provide any request parameters for this endpoint. # Attestations for a slot Source: https://docs.beaconcha.in/api-reference/slots/attestations-for-a-slot /api/v1/bundled.yaml get /api/v1/slot/{slot}/attestations Retrieve all attestations included in the beacon block for a specific slot. You can provide a slot number or the keyword `latest` to fetch attestations from the most recently processed slot. The response lists each aggregated attestation with its source/target checkpoints, committee index, and the participating validators. # Attester slashings for a slot Source: https://docs.beaconcha.in/api-reference/slots/attester-slashings-for-a-slot /api/v1/bundled.yaml get /api/v1/slot/{slot}/attesterslashings Retrieve all attester slashing operations included in the beacon block for a specific slot. You can provide a slot number or the keyword `latest` to fetch from the most recently processed slot. Each item contains the two conflicting attestations that triggered the slashing and the block inclusion metadata. # Deposits for a slot Source: https://docs.beaconcha.in/api-reference/slots/deposits-for-a-slot /api/v1/bundled.yaml get /api/v1/slot/{slot}/deposits Retrieve all validator deposit operations included in the beacon block for a specific slot. Deposits include the validator public key, withdrawal credentials, amount (gwei), and signature. Use pagination parameters to page through results when many deposits are present. # Proposer slashings Source: https://docs.beaconcha.in/api-reference/slots/proposer-slashings /api/v1/bundled.yaml get /api/v1/slot/{slot}/proposerslashings Returns the proposer slashings included in a specific slot # Slot overview Source: https://docs.beaconcha.in/api-reference/slots/slot-overview /api/v1/bundled.yaml get /api/v1/slot/{slotOrHash} Retrieve a beacon chain slot by slot number or block root. You can also use the keywords `latest` (most recently processed slot) or `head` (slot of the current head block). # Voluntary exits for a slot Source: https://docs.beaconcha.in/api-reference/slots/voluntary-exits-for-a-slot /api/v1/bundled.yaml get /api/v1/slot/{slot}/voluntaryexits Retrieve all voluntary exit operations included in the beacon block for a specific slot. A voluntary exit is a signed message from a validator indicating the epoch at which they choose to exit the active set. Provide a slot number or use the keyword `latest` to fetch from the most recently processed slot. The response lists each voluntary exit along with block inclusion metadata. # Withdrawals for a slot Source: https://docs.beaconcha.in/api-reference/slots/withdrawals-for-a-slot /api/v1/bundled.yaml get /api/v1/slot/{slot}/withdrawals Retrieve all withdrawal operations included in the execution payload of the beacon block for a specific slot. A withdrawal moves ETH from the beacon chain to an execution-layer address after a validator has eligible balance. Provide a slot number or use the keyword `latest` to fetch from the most recently processed slot. The response lists each withdrawal with the recipient address, amount in gwei, the originating validator index, and the global withdrawal index. # Sync committee for a period Source: https://docs.beaconcha.in/api-reference/sync-committees/sync-committee-for-a-period /api/v1/bundled.yaml get /api/v1/sync_committee/{period} Retrieve the sync committee membership for a given sync period. The sync committee contains 512 validator indices that participate in light-client finality via sync committee signatures. The validators in the response are ordered by the sync-committee index (the position used when interpreting syncaggregate_bits in blocks). A sync period spans 256 consecutive epochs. Sync committees were introduced with the Altair upgrade. Requests for periods before Altair return an error because no sync committee exists for those periods. On Ethereum mainnet, Altair activated at epoch 74240 (period 290). # Submit Machine Metrics Source: https://docs.beaconcha.in/api-reference/v1/client/metrics api/v1/bundled.yaml POST /api/v1/client/metrics Submits monitoring metrics from a consensus-layer client, validator client, or host machine to the authenticated beaconcha.in account. The endpoint is the target of the consensus-client `--monitoring-endpoint` flag (Lighthouse, Lodestar, Teku) and of the standalone [eth2-client-metrics-exporter](https://github.com/gobitfly/eth2-client-metrics-exporter). Submitted data appears in the **Machines** view of the beaconcha.in mobile app and can be read back via [POST /api/v2/machine-metrics](/api-reference/machine-metrics). The request body is either a single metrics object or an array of up to **10** objects. Each object must include a `process` discriminator that selects one of three payload schemas: * `system` ā€” host CPU, memory, disk, network, OS * `beaconnode` ā€” consensus-layer client process and sync state * `validator` ā€” validator-client process and managed-validator counts Submissions are rate-limited to **1 request per user per machine per process**. The maximum number of distinct machines is determined by your subscription tier (see [pricing](https://beaconcha.in/pricing)). See [`gobitfly/eth2-client-metrics`](https://github.com/gobitfly/eth2-client-metrics) for the canonical protobuf specification. # Deposits by execution transaction hash Source: https://docs.beaconcha.in/api-reference/validator-deposits/deposits-by-execution-transaction-hash /api/v1/bundled.yaml get /api/v1/eth1deposit/{txhash} Retrieve all beacon chain validator deposit events associated with a specific execution-layer transaction hash. This endpoint returns every deposit log decoded from the transaction, including deposit amount, validator public key, withdrawal credentials, and signature verification status. # Attestation efficiency Source: https://docs.beaconcha.in/api-reference/validators/attestation-efficiency /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/attestationefficiency Retrieve normalized attestation inclusion effectiveness for one or more validators. Provide a comma-separated list of validator indices or 0x-prefixed BLS pubkeys (up to the server-enforced limit; default 100). The score is computed for the most recently completed epoch and defined as: `score = 1 + (1 āˆ’ percentage/100) = 2 āˆ’ percentage/100`. A score of 1.0 indicates perfect effectiveness (100% inclusion); scores approach 2.0 as effectiveness worsens (0% inclusion). # BLS-to-execution credential changes Source: https://docs.beaconcha.in/api-reference/validators/bls-to-execution-credential-changes /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/blsChange Retrieve on-chain BLS-to-execution credential change messages (EIP-4881 style) for one or more validators. Each item includes the slot and epoch of inclusion, the canonical block root, the validatorā€™s BLS pubkey and signature over the change message, the original 0x00 withdrawal credentials, and the resulting 0x01 credentials (derived from the execution address). Provide validator identifiers as a comma-separated list in the path. The service accepts validator indices and 0x-prefixed BLS pubkeys (up to the server-enforced limit; default 100). If a provided pubkey does not resolve to a known validator index, the request fails with HTTP 400. # Daily validator statistics Source: https://docs.beaconcha.in/api-reference/validators/daily-validator-statistics /api/v1/bundled.yaml get /api/v1/validator/stats/{index} Retrieve per-day statistics for a single validator by index. Use this endpoint to obtain balance snapshots (in gwei), duty counts (attestations, block proposals, sync committee), and deposit/withdrawal activity aggregated per beaconchain-day. When `start_day` is omitted, the API returns all days up to `end_day` (which defaults to the latest exported day). # Proposal luck Source: https://docs.beaconcha.in/api-reference/validators/proposal-luck /api/v1/bundled.yaml get /api/v1/validators/proposalLuck Returns the proposal luck of a validator or a list of validators # Validator activation and exit queue Source: https://docs.beaconcha.in/api-reference/validators/validator-activation-and-exit-queue /api/v1/bundled.yaml get /api/v1/validators/queue Retrieve current queue metrics for validators awaiting activation (entering) and validators scheduled to exit (exiting). The response includes the number of validators in each queue, the total effective balance in gwei for each queue, and the total validator count known to the explorer. No parameters are required. # Validator attestations history Source: https://docs.beaconcha.in/api-reference/validators/validator-attestations-history /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/attestations Retrieve attestations observed for one or more validators within a bounded epoch window. By default, the service returns data for the last 100 epochs ending at the latest processed epoch. You can narrow the range with `startEpoch` and `endEpoch`, which must lie within `[latest-99, latest]` and satisfy `startEpoch <= endEpoch`. Each item represents a scheduled attestation duty for a validator and includes the slot attested to, the inclusion slot when observed, a status flag, and convenience week boundaries for grouping in UI charts. When `slim=true`, the response omits the `week`, `week_start`, `week_end`, and `committeeindex` properties from each item to reduce payload size. # Validator balance history Source: https://docs.beaconcha.in/api-reference/validators/validator-balance-history /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/balancehistory Retrieve per-epoch balance history for one or more validators. Provide a comma-separated list of validator indices or 0x-prefixed BLS pubkeys in the path parameter (up to the server-enforced limit; default 100). Use the optional query parameters to control the time window: - latest_epoch: the most recent epoch to include (defaults to the latest processed epoch) - offset: number of epochs to step back from latest_epoch before starting the window - limit: number of epochs to return (1..100, defaults to 100) The response contains one item per validator per epoch within the window, including the balance and effective balance in gwei, and week grouping metadata for downstream charting. # Validator deposits (execution layer) Source: https://docs.beaconcha.in/api-reference/validators/validator-deposits-execution-layer /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/deposits Retrieve execution-layer deposit events associated with one or more validators. Provide a comma-separated list of validator indices or 0x-prefixed BLS pubkeys (up to the server-enforced limit; default 100). The response lists every DepositContract event observed for the specified validators, including deposit amount (gwei), validator public key, withdrawal credentials, and signature verification status. Use this endpoint to audit funding transactions for validators. # Validator income detail history Source: https://docs.beaconcha.in/api-reference/validators/validator-income-detail-history /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/incomedetailhistory Retrieve a per-epoch income breakdown for one or more validators over a bounded epoch window. Provide validator identifiers as a comma-separated list in the path parameter (indices or 0x-prefixed BLS pubkeys, up to the server-enforced limit; default 100). The window ends at `latest_epoch` (defaults to the latest finalized epoch) and spans `limit` epochs backwards. You can shift the window back in time by setting `offset`, which reduces `latest_epoch` by the given number of epochs. The response includes consensus-layer rewards/penalties in gwei and execution tips in wei (`tx_fee_reward_wei`). # Validator proposed blocks Source: https://docs.beaconcha.in/api-reference/validators/validator-proposed-blocks /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/proposals Retrieve beacon chain blocks proposed by one or more validators within a bounded epoch window. By default, the service returns proposals from the last 100 epochs ending at the latest processed epoch. You can page the window by setting the optional `epoch` query parameter to an upper bound (inclusive). The response includes per-block consensus metadata (roots, proposer, counts) and execution payload details when available. Execution fields are null for pre-Merge slots or blocks without an execution payload. # Validator withdrawal history Source: https://docs.beaconcha.in/api-reference/validators/validator-withdrawal-history /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/withdrawals Retrieve withdrawal operations attributed to one or more validators within a bounded epoch window. By default, the service returns data for the last 100 epochs ending at the latest processed epoch. You can set the optional `epoch` query parameter to move the 100-epoch window back in time (the window becomes `[epoch-99, epoch]`, clamped at 0 when `epoch < 99`). Each item includes the epoch and slot of inclusion, the canonical block root, the global withdrawal index, the validator index, the recipient execution address, and the amount in gwei. # Validators by deposit address Source: https://docs.beaconcha.in/api-reference/validators/validators-by-deposit-address /api/v1/bundled.yaml get /api/v1/validator/eth1/{eth1address} Retrieve validators that have made deposits from a specific execution-layer address. The service inspects DepositContract events where the `from_address` equals the provided address and groups results by validator public key. Use this endpoint to identify validators funded by an address. ENS names are supported for the path parameter when they resolve to a 0x-prefixed address at request time. # Validators by withdrawal credentials or address Source: https://docs.beaconcha.in/api-reference/validators/validators-by-withdrawal-credentials-or-address /api/v1/bundled.yaml get /api/v1/validator/withdrawalCredentials/{withdrawalCredentialsOrEth1address} Retrieve validators whose withdrawal credentials match the provided value, or whose credentials correspond to the provided execution-layer address. You can specify either a 32-byte withdrawal credentials value or a 0x-prefixed Ethereum address. When you provide an address, the service derives the corresponding withdrawal credentials (prefix 0x01) and returns validators whose credentials equal that value. ENS names are accepted for the address form when they resolve to a 0x-prefixed address at request time. The lookup is case-insensitive and accepts inputs with or without the 0x prefix. # Validators overview Source: https://docs.beaconcha.in/api-reference/validators/validators-overview /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey} Retrieve validator information by index or public key using a comma-separated list in the path parameter. Provide up to 100 identifiers (higher limits may apply to authenticated premium users). Each identifier must be either a validator index (base-10 integer) or a 48-byte BLS public key as 0x-prefixed hex (96 hex characters after 0x) or without the 0x prefix. Use the POST variant (`/api/v1/validator`) when the list is too long for a URL. # Validators overview (POST) Source: https://docs.beaconcha.in/api-reference/validators/validators-overview-post /api/v1/bundled.yaml post /api/v1/validator Retrieve validator information by index or public key using a JSON request body. Use this endpoint when the list of identifiers is too long for the GET path parameter. Provide up to 100 identifiers (higher limits may apply to authenticated premium users) as a comma-separated string in the `indicesOrPubkey` field. Each identifier must be either a validator index (base-10 integer) or a 48-byte BLS public key as 0x-prefixed hex (96 hex characters after 0x) or without the 0x prefix. # Account Management FAQ Source: https://docs.beaconcha.in/api/account-management Answers to common questions about managing your beaconcha.in API account, including plan upgrades, multiple accounts, and email changes # Account Management FAQ Answers to common questions about managing your beaconcha.in API subscription, upgrading plans, and working with multiple accounts. ## Can I change the email address associated with my account? **No, email addresses cannot be changed after account creation.** This is due to technical limitations with our payment processor (Stripe), where accounts are permanently linked to the email used during registration. ### What should I do instead? If you need to use a different email address: 1. Create a new account with your preferred email address 2. Subscribe to your desired plan on the new account 3. Cancel your old subscription via the [pricing page](https://beaconcha.in/pricing) by clicking **Manage Billing** Your API usage history and statistics will not transfer to the new account. ## Can I merge multiple accounts into one? **No, accounts cannot be merged or consolidated.** Each beaconcha.in account is treated as an independent subscription and cannot be combined with other accounts. ### Why do organizations sometimes have multiple accounts? Organizations often create multiple accounts to: * Separate API keys for different projects or environments (development, staging, production) * Provide independent rate limits for different teams * Track usage separately for billing purposes ### The better solution: Enterprise Plan If your organization needs higher rate limits or more API keys than your plan includes, the **Enterprise plan** is designed specifically for you. Instead of managing multiple separate accounts, Enterprise provides: | Need | Multiple Accounts | Enterprise Plan | | - | - | - | | Multiple API keys | āœ… Up to 10 keys per account (Hobbyist 2, Business 5, Scale 10) | āœ… Custom key allowance, one account | | Higher rate limits | āŒ Limited by plan tier | āœ… Custom rate limits | | Centralized billing | āŒ Separate invoices | āœ… Single invoice | | Account management | āŒ Multiple logins | āœ… One dashboard | | Support | Standard | Priority support | | Attribution requirement | Required | Exempt | Contact us for custom rate limits, multiple API keys, and priority support ā€” all under one account. ## How do I upgrade my plan? You can upgrade your plan at any time through your account settings: 1. Log in to [beaconcha.in](https://beaconcha.in) 2. Go to **User Settings** ā†’ **API Key Management** 3. Select your desired plan and complete the upgrade For Enterprise plans, [contact us](https://beaconcha.in/pricing) to discuss your requirements. ## What happens to my existing subscription when I upgrade? When you upgrade: * Your new plan takes effect immediately * You'll be charged the prorated difference for the current billing period * Your rate limits increase instantly ## I need more than what my current plan offers. What are my options? | If you need... | Recommended action | | - | - | | Higher rate limits | Upgrade to a higher tier or Enterprise | | More API keys | Upgrade to a higher tier (Hobbyist 2, Business 5, Scale 10) or Enterprise for a custom allowance | | Pro šŸ’Ž features | Upgrade to Scale or Enterprise | | Custom requirements | Contact us for Enterprise | ## How do I cancel my subscription? To cancel your subscription: 1. Log in to [beaconcha.in](https://beaconcha.in) 2. Go to the [pricing page](https://beaconcha.in/pricing) and click **Manage Billing** 3. Cancel your subscription from the billing portal Your access will continue until the end of your current billing period. Cancellation is permanent. After your billing period ends, your API key will lose API access. To regain access, start a new subscription. ## How do I access my invoices? Where to find your invoices depends on how you purchased your subscription. ### Purchased through beaconcha.in (Stripe) If you subscribed directly on the beaconcha.in website, your payments are processed by Stripe and your invoices are available in the billing portal: 1. Log in to [beaconcha.in](https://beaconcha.in) 2. Go to the [pricing page](https://beaconcha.in/pricing) and click **Manage Billing** 3. Download your invoices from the billing portal ### Purchased through the Apple App Store or Google Play Store If you subscribed through one of our mobile apps, the purchase was processed by the app store, and beaconcha.in has no access to those invoices. Request them directly from the store: * **Apple App Store**: See [View your purchase history for the App Store](https://support.apple.com/en-us/118212), or request an invoice at [reportaproblem.apple.com](https://reportaproblem.apple.com). * **Google Play Store**: See [Review your order history](https://support.google.com/googleplay/answer/2850369) to find and download your receipts. Invoices for App Store and Google Play purchases can only be obtained from Apple or Google ā€” they are not available in the beaconcha.in billing portal. ## I have multiple accounts and want to consolidate. What should I do? If you're currently managing multiple accounts and want to simplify: 1. **Evaluate your needs**: Determine your total rate limit requirements and number of API keys needed 2. **Contact us**: Reach out to [support@beaconcha.in](mailto:support@beaconcha.in) to discuss Enterprise options 3. **Migrate**: We'll help you transition to a single Enterprise account that meets all your needs 4. **Cancel old accounts**: Once migrated, cancel your individual subscriptions Let us help you find the right plan for your organization's needs. ## Still have questions? * Join our [Discord community](https://dsc.gg/beaconchain) for quick answers * Email [support@beaconcha.in](mailto:support@beaconcha.in) for account-specific questions * Visit our [pricing page](https://beaconcha.in/pricing) to compare plans # AI Integration Source: https://docs.beaconcha.in/api/ai-integration Connect AI assistants and LLMs to beaconcha.in documentation for accurate, up-to-date answers about Ethereum staking and our API. Connect your AI assistant to beaconcha.in documentation for accurate, contextual answers about Ethereum staking, validators, and our API. ## llms.txt (Universal) For any AI agent or LLM that follows the [llms.txt standard](https://llmstxt.org/), fetch our complete documentation index: ``` https://docs.beaconcha.in/llms.txt ``` This file is auto-generated and contains links to all documentation pages with descriptions, including: * **V1 & V2 API Reference** ā€” All endpoints with parameter descriptions and usage notes * **API Guides** ā€” Authentication, pagination, rate limits, and dashboard management * **Use Cases** ā€” Rewards calculations, performance monitoring, queue tracking * **Validator Dashboard** ā€” Configuration, groups, slot visualization, BeaconScoreĀ® * **FAQs** ā€” Deposits, withdrawals, validator queues, and staking concepts * **Legal** ā€” Terms, privacy, and BeaconScoreĀ® license Use `llms.txt` when your AI tool doesn't support MCP, or when you need to provide your AI assistant with a complete list of available documentation. *** ## skill.md (For AI Agents) For AI agents and assistants that support skill files or need comprehensive capability documentation: ``` https://docs.beaconcha.in/skill.md ``` This file provides a complete reference designed specifically for AI agents, including: * **Capabilities** ā€” Overview of all beaconcha.in APIs and monitoring features * **Skills** ā€” Detailed instructions for validator lookups, rewards calculations, performance monitoring, and more * **Workflows** ā€” Step-by-step guides for common tasks like tax reporting and validator monitoring * **Integration** ā€” Connections with Lido, Rocket Pool, MEV-Boost, and Ethereum clients * **Context** ā€” Important background on Ethereum staking architecture and BeaconScoreĀ® metrics The skill.md format is ideal for AI agents in development environments (like Cursor) that can read and follow structured capability documentation to assist with beaconcha.in integration tasks. *** ## MCP Server (For Supported Tools) For AI tools that support Model Context Protocol (MCP), connect directly to our documentation server for richer integration: ``` https://docs.beaconcha.in/mcp ``` ### What is MCP? Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. By using our MCP server, you can give your AI assistant direct access to beaconcha.in documentation, enabling it to provide more accurate and contextual answers. ### Setting Up MCP Add the following to your Cursor MCP configuration (`.cursor/mcp.json`): ```json theme={null} { "mcpServers": { "beaconchain-docs": { "url": "https://docs.beaconcha.in/mcp" } } } ``` Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "beaconchain-docs": { "url": "https://docs.beaconcha.in/mcp" } } } ``` Edit `%APPDATA%\Claude\claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "beaconchain-docs": { "url": "https://docs.beaconcha.in/mcp" } } } ``` For other MCP-compatible tools, use the server URL `https://docs.beaconcha.in/mcp` and follow your tool's specific configuration instructions. ### Available via MCP Once connected, the MCP server provides access to: * **API Documentation** ā€” Complete reference for the beaconcha.in API v1 and v2 * **Validator Dashboard Guides** ā€” How to use and configure validator dashboards * **FAQs** ā€” Common questions about deposits, withdrawals, and validator operations * **Notifications & Monitoring** ā€” Setting up alerts and monitoring for your validators *** ## Example Use Cases Ask your AI assistant to help you integrate the beaconcha.in API into your application with accurate, up-to-date documentation. Get guidance on setting up notifications and monitoring for your validators directly in your development environment. Learn how to configure and customize your validator dashboard with contextual assistance. Diagnose issues with deposits, withdrawals, or validator performance using documentation-backed answers. *** ## Need Help? If you have questions about AI integration or encounter any issues, reach out to us on [Discord](https://dsc.gg/beaconchain) or [X](https://x.com/beaconcha_in). # Dashboard management and data API Source: https://docs.beaconcha.in/api/dashboard Learn how to manage the validators on your beaconcha.in dashboard and query your dashboard data onā€‘demand using the V2 API and validator selectors. This guide shows you how to: * Manage the validators on your beaconcha.in dashboard via API (add/move and remove) * Access your dashboardā€™s data onā€‘demand using the V2 API and its validator dashboard selectors ## Prerequisites * API key: You need a beaconcha.in API key and must send it in the Authorization header. See Getting Started and how to obtain an API key in the [API Overview](/api/overview). * Orca subscription: To manage your dashboard (add/move/remove validators) via API, you need an Orca subscription. See plans: [https://beaconcha.in/premium](https://beaconcha.in/premium) * Higher rate limits: If you need more than 1 req/sec and 1000 req/month, you will need an additional API subscription: [https://beaconcha.in/pricing](https://beaconcha.in/pricing) * Dashboard ID: Your dashboard\_id is visible in your validator dashboard URL on beaconcha.in. Authenticate with: `Authorization: Bearer YOUR_API_KEY` and `Content-Type: application/json`. *** ## Manage validators on your dashboard Use the validator dashboard management endpoints to add or remove validators from your dashboard and groups. ### Add or move validators to a dashboard (optionally to a specific group) Reference: [/api/v2/validator-dashboards//validators](/validator-dashboard/manage-validators-api-endpoints/validators_post) This endpoint accepts several input modes. The simplest is to send a list of validator indices or public keys. Optionally include `group_id` to add/move them into a specific group. Group IDs are visible in the dashboard UI. If you don't pass a `group_id` to the add endpoint, validators are added to your default group. Example ā€” add indices to dashboard 123, default group: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/validator-dashboards/123/validators \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "validators": [1, 2, 3] } ' ``` Example ā€” move validators into group 456: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/validator-dashboards/123/validators \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "group_id": 456, "validators": [ "0xa94f5374fce5edbc64b...", 42 ] } ' ``` Bulkā€‘add by deposit/withdrawal/graffiti (availability depends on subscription tier): ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/validator-dashboards/123/validators \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "group_id": 456, "deposit_address": "0x1234567890abcdef1234567890abcdef12345678" } ' ``` This endpoint always adds as many validators as possible, even if you provide more than allowed by your plan. The response includes the list that were actually added. ### Remove specific validators from a dashboard Reference: [/api/v2/validator-dashboards//validators/bulk-deletions](/validator-dashboard/manage-validators-api-endpoints/validators_bulk_delete_post) ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/validator-dashboards/123/validators/bulk-deletions \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "validators": [1, "0x8fe...public_key...e1"] } ' ``` ### Clear all validators from a specific group Reference: [/api/v2/validator-dashboards//groups//validators](/validator-dashboard/manage-validators-api-endpoints/groups_delete) ```bash theme={null} curl --request DELETE \ --url https://beaconcha.in/api/v2/validator-dashboards/123/groups/456/validators \ --header 'Authorization: Bearer ' ``` *** ## Access your dashboard data via the V2 API The V2 API supports a flexible validator selector (validatorsSelector) that lets you query data for: * A whole dashboard: `{ "dashboard_id": 123 }` * A specific group in a dashboard: `{ "dashboard_id": 123, "group_id": 456 }` Below are a few common examples using your dashboard\_id. ### Example: APY & ROI for your dashboard Endpoint: `POST /api/v2/ethereum/validators/apy-roi` ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/apy-roi \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "30d" } } ' ``` ### Example: Aggregated rewards for your dashboard (fixed window) Endpoint: `POST /api/v2/ethereum/validators/rewards-aggregate` ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123, "group_id": 456 }, "range": { "evaluation_window": "all_time" } } ' ``` ### Example: Validator overview with pagination Endpoint: `POST /api/v2/ethereum/validators` ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "page_size": 10, "validator": { "dashboard_id": 123 } } ' ``` If the response includes `paging.next_cursor`, pass it back in the next request to continue. See the [Pagination guide](/api/pagination). You can always restrict to a subset by switching to `validator_identifiers` or target a single group with `group_id`. *** ## Rate limits and access * Managing your dashboard via API requires an Orca subscription: [https://beaconcha.in/premium](https://beaconcha.in/premium) * If you need more than 1 req/sec and 1000 req/month, get an API subscription: [https://beaconcha.in/pricing](https://beaconcha.in/pricing) * For API key setup and basics, see the [API Overview](/api/overview). # API Error Messages Source: https://docs.beaconcha.in/api/error-handling Complete reference for beaconcha.in API error messages, what they mean, and how to handle them. ## Overview All API errors use this shape unless otherwise noted: ```json theme={null} { "error": "message text" } ``` Use the HTTP status code as the primary signal. Treat the `error` string as human-readable context that may vary by endpoint. In rare panic-recovery cases, the server may return a plain-text `500 Internal Server Error` body instead of JSON. ## Errors shown in API Reference examples These are the shared examples shown across API Reference response tabs: | HTTP | Example message | Meaning | Recommended action | | - | - | - | - | | `400` | `Bad request. Please check your input and try again.` | Request payload/params are invalid. | Validate request shape and values against the endpoint schema. | | `401` | `Unauthorized. Please provide a valid API key.` | Authentication failed. | Send `Authorization: Bearer ` with a valid key. | | `403` | `endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing.` | Authenticated, but plan/permissions do not allow this endpoint or selector. | Upgrade plan, reduce selector scope, or switch to an allowed endpoint. | | `404` | `The requested resource was not found.` | Requested resource/data was not found. | Check identifiers/ranges and retry with existing data. | | `429` | `Rate limit exceeded. Please try again later.` | Request limit exceeded. | Back off and retry after `ratelimit-reset`. | | `default` | `An unexpected error occurred.` | Generic fallback example. | Retry with backoff; if persistent, contact support with request details. | ## Complete Runtime Error Catalog (Public v2 API) The following messages are returned by the current backend implementation for public **v2 API** endpoints and may be more specific than the shared examples above. This guide is for public **v2 API** behavior. Public **v1 API** endpoints may return different status codes and message texts. ### `401 Unauthorized` | Message | Common causes | Recommended user action | | - | - | - | | `API key missing from authorization header. You can obtain a free API key at https://beaconcha.in/register` | Missing `Authorization` header. | Send `Authorization: Bearer `. | | `invalid authorization format` | Header is not `Bearer `, malformed token, extra spaces/prefix. | Use exact Bearer format and a raw API key. | | `invalid API key` | Unknown/revoked key, key/user not found. | Regenerate key in user settings and update your client secret store. | Internal API (session-based) also returns: | Message | Common causes | Recommended user action | | - | - | - | | `Missing session cookie` | Session cookie is absent on internal API call. | Authenticate in the app first and send the required session cookie. | | `Invalid session ID` | Session is expired, malformed, or unknown. | Re-authenticate and retry with a fresh session. | ### `403 Forbidden` | Message | Common causes | Recommended user action | | - | - | - | | `endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing.` | Your current plan does not include the requested capability. | Upgrade plan or use a capability available on your tier. | | `number of validator identifiers exceeds allowed limit of for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing.` | Too many validator IDs/public keys in one request for your tier. | Reduce selector size, split into smaller batches, or upgrade. | | `validator selector type not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing.` | Using premium selector types (`deposit_address`, `withdrawal`, etc.) on non-premium tier. | Use allowed selector types or upgrade. | | `maximum number of API keys () reached` | Internal API key-management quota reached. | Delete unused keys or increase allowed limit via plan/support. | ### `404 Not Found` | Message | Common causes | Recommended user action | | - | - | - | | `block root not found` | Unknown consensus block root. | Verify root format/network and retry with an existing root. | | `dashboard or group not found for your user account` | Dashboard/group ID does not exist or is not accessible to this API key's user. | Confirm ownership/permissions and IDs. | | `no sub-entities found for entity ''` | Entity has no sub-entities for requested window/filters. | Check entity spelling/window and try broader range. | | `slot not found` | Slot is outside indexed/available data. | Re-check chain/slot and query an existing slot. | | `requested slot is before the earliest available slot with sync committee duties ` | Requested slot predates available sync committee duties data. | Query a later slot at or after ``. | | `requested slot is greater than latest slot ` | Requested slot is beyond the latest known slot for the selected view (`head`/`finalized`). | Retry with a lower slot or use `head`/`finalized` selectors. | | `requested sync committee period is before the earliest available period ` | Requested period predates available history. | Use a period `>= `. | | `requested sync committee period is beyond the latest available period ` | Requested period is too far in the future. | Query `latest`/`next` or a lower explicit period. | | `requested sync committee period is beyond the latest available and finalized period ` | Requested period exceeds the range of finalized periods for that endpoint. | Query `latest` or a lower finalized period. | | `requested sync committee period not found` | No committee data exists for that period. | Verify period value and retry with a known available period. | | `Requesting the 'next' sync committee period is currently not supported by this endpoint. This feature may soon be available in a future update.` | Endpoint does not support `next` for this operation. | Use an explicit existing period or `latest` where supported. | | `no indexed data found for block ` | Block exists but indexed data for that endpoint is unavailable. | Try another block or retry later after indexing catches up. | | `no validators found` | Validator selector resolved to no records. | Check validator IDs/public keys/entity input. | | `no validators found for the provided validator selector` | Selector is syntactically valid but empty in data. | Confirm selector and chain, then retry. | | `no validators found for the provided selector` | Selector did not resolve to any validators. | Confirm selector values and chain context, then retry. | | `no APY & ROI data available for the requested range and validators` | No ROI dataset for requested validators/window. | Use a different window or selector with active validators. | | `no attestation assignment data available for the requested validators` | No attestation history for selected validators. | Check validator activity and query a different range. | | `no validator balances available for the requested epoch ` | No balances for that epoch/selector. | Verify epoch/finality and retry with available epoch. | | `no validator performance data available for the requested epoch ` | No performance row for that epoch/selector. | Check epoch/selector and try adjacent epoch. | | `no validator performance data available for the requested range and validators` | No performance data in selected window. | Expand range or adjust validator set. | | `no validator rewards data available for the requested epoch ` | No rewards row for that epoch/selector. | Verify epoch/selector and retry with available epoch. | | `no validator rewards data available for the requested range and validators` | No rewards in selected window. | Expand range or adjust validator set. | | `no validator metadata available for the requested validators` | Metadata missing for selected validators. | Check selector and ensure validators exist on target chain. | | `API key not found: ` | Internal API key-management request referenced a non-existent key name. | Verify key name or list keys before update/delete operations. | | `resource not found` | Domain-level not found fallback. | Re-check target resource identifiers and retry. | | `path not found: ` | Route does not exist. | Fix URL path; use API Reference path exactly. | ### `400 Bad Request` | Message | Common causes | Recommended user action | | - | - | - | | `empty request body` | Missing JSON body on required POST endpoint. | Send `Content-Type: application/json` and valid body. | | `parameter "cursor" is invalid` | Cursor is malformed, stale, or from another endpoint/query. | Use `paging.next_cursor` from the same endpoint and unchanged filters/sorting. | | `evaluation_window 'all_time' is not supported for this endpoint` | `all_time` used where endpoint supports only bounded windows. | Use `24h`, `7d`, `30d`, or `90d` as documented. | | `sort_by and sort_order must not change between paginated requests; start a new query without a cursor to change sorting` | Changed sort options mid-pagination. | Keep sort stable while using a cursor, or restart without cursor. | | `entity must be provided` | Missing `entity` field for sub-entity queries. | Provide `entity` in request body. | | `invalid block root hex` | Block root is not valid hex. | Send `0x`-prefixed valid hex root. | | `invalid time range: start epoch is after end epoch ` | Inverted epoch range. | Swap/fix boundaries so start is not greater than end. | | `invalid time range: start slot is after end slot ` | Inverted slot range. | Swap/fix boundaries so start is not greater than end. | | `invalid time range: start time is after end time ` | Inverted timestamp range. | Swap/fix boundaries so start is not greater than end. | ### `405 Method Not Allowed` | Message | Common causes | Recommended user action | | - | - | - | | `method not allowed: ` | Wrong HTTP method (for example `GET` instead of `POST`). | Use the method defined in API Reference. | ### `409 Conflict` | Message | Common causes | Recommended user action | | - | - | - | | `API key with name '' already exists` | Creating an API key with a duplicate name (internal API key management). | Use a unique key name or rename existing key. | ### `429 Too Many Requests` | Message | Common causes | Recommended user action | | - | - | - | | `rate limit exceeded` | Per-second/minute/hour/day/month bucket exhausted. | Pause and retry after `ratelimit-reset`; implement backoff/jitter. | ### `500 Internal Server Error` | Message | Common causes | Recommended user action | | - | - | - | | `internal server error. please try again later.` | Unexpected server-side error. | Retry with exponential backoff; contact support if persistent. | | `Internal Server Error` | Panic recovery fallback response. | Retry once; if persistent, report with timestamp and request ID details. | | `failed to encode response` | Rare server-side serialization failure (health/operational handlers). | Retry once; if repeated, report with timestamp and endpoint. | ## Dynamic validation error format For schema/validation failures, the API can return structured, field-level messages generated at runtime (for example missing required fields or enum/type mismatch). Typical patterns: * `request body: : is missing` * `request body: : input must be one of ` * `request body: : input must not be null` * `request body: : doesn't match expected schema due to one of the following reasons: {...}` Recommended handling: 1. Treat all `400` as non-retryable until request is fixed. 2. Surface the raw `error` text in logs for faster debugging. 3. Add client-side schema validation for high-volume paths. ## Client handling checklist 1. Parse JSON body and capture `status`, `error`, and rate-limit headers. 2. Retry only retryable statuses (`429`, and selected `5xx`) with backoff. 3. Do not retry `400`, `401`, `403`, `404`, `405` blindly. 4. Keep pagination inputs stable (`cursor`, filters, sort options). 5. Include endpoint, request payload hash, timestamp, and error text in logs. # Machine Metrics Source: https://docs.beaconcha.in/api/machine-metrics-overview Push consensus-layer node, validator, and host metrics to your beaconcha.in account The Machine Metrics endpoint accepts monitoring metrics from your staking infrastructure and stores them against your beaconcha.in account. The data shows up under **Machines** in the [beaconcha.in mobile app](https://beaconcha.in/mobile) and can be used to power alerts and dashboards. It is the same endpoint targeted by the consensus client `--monitoring-endpoint` flag (Lighthouse, Lodestar, Teku) and by the standalone metrics exporter for clients that don't expose a push integration natively (Prysm, Nimbus). For step-by-step client setup (Lighthouse, Prysm, Nimbus, Teku, Lodestar, Rocket Pool), follow the [Mobile App Node Monitoring tutorial](/notifications-monitoring/mobile-app-beacon-node). This page covers the API contract for direct integrations. ## Three payload shapes Every request carries a `process` field that selects one of three payload schemas: | `process` | What it represents | Sent by | | - | - | - | | `system` | Host machine ā€” CPU, memory, disk, network, OS | Standalone exporter | | `beaconnode` | Consensus-layer client ā€” sync state, peers, libp2p I/O | CL client or exporter | | `validator` | Validator client ā€” managed validators, fallback config | VC or exporter | A single request body may be one object or an array of up to **10** objects. Each object is rate-limited to **1 request per user, per machine, per process**. The full field-by-field schema is documented on the [POST /api/v1/client/metrics](/api-reference/v1/client/metrics) reference page. The protobuf source of truth lives at [`gobitfly/eth2-client-metrics`](https://github.com/gobitfly/eth2-client-metrics). ## Two ways to push data ### 1. Native `--monitoring-endpoint` flag Lighthouse, Lodestar, and Teku ship with a flag that posts metrics directly to this endpoint. Each client uses a slightly different flag spelling: ```bash theme={null} # Lighthouse / Lodestar (validator and beacon node) --monitoring-endpoint 'https://beaconcha.in/api/v1/client/metrics?apikey=YOUR_API_KEY' # Teku (beacon node) --metrics-publish-endpoint 'https://beaconcha.in/api/v1/client/metrics?apikey=YOUR_API_KEY' ``` Find your API key at [beaconcha.in/api/key-management](https://beaconcha.in/api/key-management). ### 2. Standalone metrics exporter For clients without a native flag (Prysm, Nimbus, custom setups), use [`gobitfly/eth2-client-metrics-exporter`](https://github.com/gobitfly/eth2-client-metrics-exporter). It scrapes Prometheus-format metrics from your client and pushes them in the expected shape: ```bash theme={null} ./eth2-client-metrics-exporter-linux-amd64 \ --server.address='https://beaconcha.in/api/v1/client/metrics?apikey=YOUR_API_KEY' \ --beaconnode.type=prysm \ --beaconnode.address=http://localhost:8080/metrics \ --validator.type=prysm \ --validator.address=http://localhost:8081/metrics ``` Replace `prysm` with `nimbus`, `lighthouse`, etc. as appropriate for your client. See the exporter README for the full flag reference. ## Authentication and limits * **API key:** required as the `apikey` query parameter. Get one at [beaconcha.in/api/key-management](https://beaconcha.in/api/key-management). * **Optional `machine` query parameter:** name a device when you monitor more than one host on the same account. * **Rate limit:** 1 request per user per machine per process. Bursts beyond this return `429`. * **Machine count:** capped by your subscription tier. Exceeding the cap returns `402`. Upgrade at [beaconcha.in/pricing](https://beaconcha.in/pricing). * **Privacy:** beaconcha.in does not store the source IP address of metrics submissions. ## Reading the data back The mobile app surfaces this data under **Machines**. There is no public read endpoint for the V1 API; the V2 [POST /api/v2/machine-metrics](/api-reference/machine-metrics) endpoint exposes the same underlying data and is the recommended integration target for new dashboards. Full request/response schema for `POST /api/v1/client/metrics`. Per-client setup walkthroughs and mobile app login. # Getting Started Source: https://docs.beaconcha.in/api/overview Learn how to authenticate, make your first request, and understand responses using the beaconcha.in V2 API ā€” the recommended API for all new integrations. The **V2 API** is the recommended API for all new integrations. It offers richer data, flexible validator selectors, cursor-based pagination, and exclusive features like [BeaconScoreĀ®](/use-cases/performance-introduction) and [entity benchmarking](/use-cases/rank-and-compare-entities). The [V1 API](/api/v1-overview) remains available but no new features will be added to V1. ## Pricing | Plan | Price | Features | Ratelimit | Requests | API keys | | - | - | - | - | - | - | | Free Trial | 0ā‚¬ (30 days) | Basic | 1/sec | 1000 | 1 | | Hobbyist | 59ā‚¬/mo\* | Basic | 1/sec | Unlimited | 2 | | Business | 99ā‚¬/mo\* | Basic | 2/sec | Unlimited | 5 | | Scale | 399ā‚¬/mo\* | Basic & Pro šŸ’Ž | 5/sec | Unlimited | 10 | | Enterprise | [Contact us](https://beaconcha.in/api/pricing#contact-sales) | Basic & Pro šŸ’Ž | [Contact us](https://beaconcha.in/api/pricing#contact-sales) | Unlimited | [Contact us](https://beaconcha.in/api/pricing#contact-sales) | \*Prices shown are for annual billing, excluding VAT * **Free Trial:** Test the API with a 30-day free trial. The trial does not auto-renew; access ends after 30 days unless you upgrade. [Start your free trial and create an API key](https://beaconcha.in/user/api-key-management). * **Access:** API endpoints require an API key. Free Trial and paid users have access to both V1 and V2 APIs. * **Pro šŸ’Ž features:** available for users on the Scale and Enterprise plans. * **Attribution:** See [API Terms and Conditions](/legal/api-terms) for details. **Building with AI?** Connect your AI assistant to our documentation via [AI Integration](/api/ai-integration). Get accurate, up-to-date answers about the beaconcha.in API directly in your development environment. ## Attribution Requirements If you use beaconcha.in API data in your application or website, please follow these attribution guidelines: ### BeaconScoreĀ® After an agreement the BeaconScoreĀ® badge may be required. See [API Terms and Conditions](/legal/api-terms) for details. BeaconScoreĀ® ### Powered by beaconcha.in After an agreement the "Powered by beaconcha.in" logo may be required. See [API Terms and Conditions](/legal/api-terms) for details. Powered by beaconcha.in Download official BeaconScoreĀ® and "Powered by beaconcha.in" badges in SVG and PNG formats For full terms and conditions, see our [BeaconScoreĀ® License](/legal/beaconscore-license). ## API Keys API keys can be obtained in the [user portal](https://beaconcha.in/user/api-key-management) and must be included in requests either as a query string parameter or in the request header. V1 and V2 APIs use the same authentication method. A single API key is valid for all endpoints. ## Quick Start ā€” Your First Request The simplest V2 API call is the [Chain State](/api-reference/ethereum/state) endpoint, which returns the current state of the Ethereum network with a single field in the request body: ```bash theme={null} curl -X POST 'https://beaconcha.in/api/v2/ethereum/state' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"chain": "mainnet"}' ``` ```python theme={null} import requests response = requests.post( "https://beaconcha.in/api/v2/ethereum/state", headers={ "Authorization": "Bearer ", "Content-Type": "application/json" }, json={"chain": "mainnet"} ) print(response.json()) ``` ```typescript theme={null} const response = await fetch("https://beaconcha.in/api/v2/ethereum/state", { method: "POST", headers: { "Authorization": "Bearer ", "Content-Type": "application/json" }, body: JSON.stringify({ chain: "mainnet" }) }); const data: { data: { current_epoch: number; total_validators: number } } = await response.json(); console.log(data); ``` ```javascript theme={null} const response = await fetch("https://beaconcha.in/api/v2/ethereum/state", { method: "POST", headers: { "Authorization": "Bearer ", "Content-Type": "application/json" }, body: JSON.stringify({ chain: "mainnet" }) }); const data = await response.json(); console.log(data); ``` All V2 API endpoints use the `POST` method with a JSON request body. The `chain` field (`"mainnet"` or `"hoodi"`) is required in every request. ## Full Example ā€” Validator Rewards This example uses the [Rewards](/api-reference/ethereum/validators/rewards-list) endpoint to get validator rewards data. ### Request ```bash theme={null} curl -X POST 'https://beaconcha.in/api/v2/ethereum/validators/rewards-list' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "validator": { "validator_identifiers": [1] }, "chain": "mainnet", "page_size": 10, "epoch": 347566 }' ``` ```python theme={null} import requests API_KEY = "" BASE_URL = "https://beaconcha.in" response = requests.post( f"{BASE_URL}/api/v2/ethereum/validators/rewards-list", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }, json={ "validator": {"validator_identifiers": [1]}, "chain": "mainnet", "page_size": 10, "epoch": 347566 } ) if response.status_code == 200: data = response.json() print(data) else: print(f"Error {response.status_code}: {response.json()}") ``` ```typescript theme={null} const API_KEY = ""; const BASE_URL = "https://beaconcha.in"; interface RewardsResponse { data: Array<{ validator: { index: number; public_key: string }; total: string; total_reward: string; total_penalty: string; }>; paging: { next_cursor?: string }; } async function getValidatorRewards(): Promise { const response = await fetch( `${BASE_URL}/api/v2/ethereum/validators/rewards-list`, { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ validator: { validator_identifiers: [1] }, chain: "mainnet", page_size: 10, epoch: 347566 }) } ); if (!response.ok) { const error = await response.json(); throw new Error(`API error ${response.status}: ${error.error}`); } return response.json(); } ``` ```javascript theme={null} const API_KEY = ""; const BASE_URL = "https://beaconcha.in"; async function getValidatorRewards() { const response = await fetch( `${BASE_URL}/api/v2/ethereum/validators/rewards-list`, { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ validator: { validator_identifiers: [1] }, chain: "mainnet", page_size: 10, epoch: 347566 }) } ); if (!response.ok) { const error = await response.json(); throw new Error(`API error ${response.status}: ${error.error}`); } return response.json(); } ``` ### Response ```json theme={null} { "data": [ { "total": "80660680222696592", "validator": { "index": 1, "public_key": "0xa1d1ad0714035353258038e964ae9675dc0252ee22cea896825c01458e1807bfad2f9969338798548d9858a571f7425c" }, "total_reward": "80660680222696592", "total_penalty": "0", "total_missed": "132644000000000", "attestation": { "total": "9371000000000", "head": { "total": "2408000000000", "reward": "2408000000000", "penalty": "0", "missed_reward": "0" }, "source": { "total": "2437000000000", "reward": "2437000000000", "penalty": "0", "missed_reward": "0" }, "target": { "total": "4526000000000", "reward": "4526000000000", "penalty": "0", "missed_reward": "0" }, "inactivity_leak_penalty": "0", "inclusion_delay": null }, "sync_committee": { "total": "0", "reward": "0", "penalty": "0", "missed_reward": "0" }, "proposal": { "total": "80651309222696592", "execution_layer_reward": "35087332222696592", "attestation_inclusion_reward": "43946801000000000", "sync_inclusion_reward": "1617176000000000", "slashing_inclusion_reward": "0", "missed_cl_reward": "132644000000000", "missed_el_reward": "0" }, "finality": "finalized" } ], "paging": {}, "range": { "slot": { "start": 11122112, "end": 11122143 }, "epoch": { "start": 347566, "end": 347566 }, "timestamp": { "start": 1740289367, "end": 1740289750 } } } ``` See all parameters, response fields, and try the Rewards endpoint # Pagination Source: https://docs.beaconcha.in/api/pagination Learn how cursor and page_size work together to paginate list endpoints in the v2 API ## Why cursor-based pagination Cursor-based pagination returns a small, ordered slice of results plus an opaque token you pass back to get the next slice. Compared to offset-based pagination, cursors are typically more consistent and performant under concurrent writes and large datasets. Use the `cursor` returned by the API as-is. Do not build or parse cursors on the client. ## How it works * Request parameters * `page_size` ā€” number of items per page. Typical range is 1ā€“100 with default 10. Some endpoints may enforce different bounds; check the API Reference for specifics. * `cursor` ā€” pass the string returned in `paging.next_cursor` from the previous response to load the next page. * Response fields * `paging.next_cursor` ā€” present only when there is more data to fetch. If itā€™s missing or empty, youā€™ve reached the end. Keep all filters and sort parameters identical for every page in a pagination sequence. Changing them mid-stream can lead to duplicates or gaps. ## Example: Validators list First page (no `cursor`): ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "page_size": 10, "validator": { "validator_identifiers": [ 1 ] } } ' ``` Response (excerpt): ```json theme={null} { "data": [ { /* validator item */ }, { /* validator item */ }, { /* validator item */ } ], "paging": { "next_cursor": "eyJfc2FtcGxlX2N1cnNvciI6MTIzNDU2Nzg5MH0" // truncated } } ``` Next page (use `paging.next_cursor` from the previous response): ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "page_size": 10, "cursor": "eyJfc2FtcGxlX2N1cnNvciI6MTIzNDU2Nzg5MH0", "validator": { "validator_identifiers": [ 1 ] } } ' ``` Response (excerpt): ```json theme={null} { "data": [ /* next 3 validators */ ], "paging": { "next_cursor": "eyJfc2FtcGxlX2N1cnNvciI6OTg3NjU0MzIxMH0" // if more data remains } } ``` Some endpoints require additional filters (e.g., validator selectors or time ranges). Include the same filters on every paginated request. Refer to the API Reference for each endpointā€™s required and optional parameters. ## Complete Pagination Examples ```python theme={null} import requests from typing import Iterator, Any API_KEY = "" BASE_URL = "https://beaconcha.in" def paginate_all(endpoint: str, payload: dict, page_size: int = 100) -> Iterator[dict]: """ Generator that yields all items across all pages. Args: endpoint: API endpoint path payload: Request payload (without cursor) page_size: Items per page (max 100) Yields: Individual items from each page """ cursor = None payload = {**payload, "page_size": page_size} while True: if cursor: payload["cursor"] = cursor response = requests.post( f"{BASE_URL}{endpoint}", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }, json=payload ) response.raise_for_status() result = response.json() # Yield each item for item in result.get("data", []): yield item # Check for next page cursor = result.get("paging", {}).get("next_cursor") if not cursor: break # No more pages # Usage: Get all rewards for validators all_rewards = list(paginate_all( "/api/v2/ethereum/validators/rewards-list", { "chain": "mainnet", "validator": {"validator_identifiers": [1, 2, 3]}, "epoch": 347566 } )) print(f"Retrieved {len(all_rewards)} reward records") ``` ```typescript theme={null} const API_KEY = ""; const BASE_URL = "https://beaconcha.in"; interface PaginatedResponse { data: T[]; paging: { next_cursor?: string }; } async function* paginateAll( endpoint: string, payload: Record, pageSize: number = 100 ): AsyncGenerator { let cursor: string | undefined; const requestPayload = { ...payload, page_size: pageSize }; while (true) { if (cursor) { requestPayload.cursor = cursor; } const response = await fetch(`${BASE_URL}${endpoint}`, { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify(requestPayload) }); if (!response.ok) { const error = await response.json(); throw new Error(`API error ${response.status}: ${error.error}`); } const result: PaginatedResponse = await response.json(); // Yield each item for (const item of result.data) { yield item; } // Check for next page cursor = result.paging?.next_cursor; if (!cursor) break; } } // Usage: Get all rewards for validators async function getAllRewards() { const rewards = []; for await (const reward of paginateAll( "/api/v2/ethereum/validators/rewards-list", { chain: "mainnet", validator: { validator_identifiers: [1, 2, 3] }, epoch: 347566 } )) { rewards.push(reward); } console.log(`Retrieved ${rewards.length} reward records`); return rewards; } ``` ```javascript theme={null} const API_KEY = ""; const BASE_URL = "https://beaconcha.in"; async function* paginateAll(endpoint, payload, pageSize = 100) { let cursor = undefined; const requestPayload = { ...payload, page_size: pageSize }; while (true) { if (cursor) { requestPayload.cursor = cursor; } const response = await fetch(`${BASE_URL}${endpoint}`, { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify(requestPayload) }); if (!response.ok) { const error = await response.json(); throw new Error(`API error ${response.status}: ${error.error}`); } const result = await response.json(); // Yield each item for (const item of result.data) { yield item; } // Check for next page cursor = result.paging?.next_cursor; if (!cursor) break; } } // Usage: Get all rewards for validators async function getAllRewards() { const rewards = []; for await (const reward of paginateAll( "/api/v2/ethereum/validators/rewards-list", { chain: "mainnet", validator: { validator_identifiers: [1, 2, 3] }, epoch: 347566 } )) { rewards.push(reward); } console.log(`Retrieved ${rewards.length} reward records`); return rewards; } ``` ## Endpoint-specific limits While many endpoints accept `page_size` values between 1 and 100 (default 10), some may enforce different limits or include additional paging fields. Always check the API Reference for the exact bounds and response schema of each endpoint. If you need a stable snapshot across many pages, keep your filters constant and paginate in one continuous session. # Understanding Rate Limits Source: https://docs.beaconcha.in/api/rate-limits Learn how to monitor and work within API rate limits ## Overview The beaconcha.in API uses rate limiting to ensure fair usage and maintain service quality for all users. Rate limits vary by subscription tier and are enforced across multiple time windows. *** ## Rate Limit Headers Every API response includes headers that show your current rate limit status: ### Primary Headers | Header | Description | Example | | - | - | - | | `ratelimit-limit` | Requests allowed per window | `1` | | `ratelimit-remaining` | Requests remaining in current window | `0` | | `ratelimit-reset` | Seconds until the window resets | `1` | | `ratelimit-window` | The time window type | `second` | | `ratelimit-bucket` | The rate limit bucket for this endpoint | `default` | | `ratelimit-validapikey` | Whether your API key is valid | `true` | ### Extended Headers The API also returns detailed limits for each time window: | Header | Description | | - | - | | `x-ratelimit-limit-second` | Requests allowed per second | | `x-ratelimit-limit-minute` | Requests allowed per minute | | `x-ratelimit-limit-hour` | Requests allowed per hour | | `x-ratelimit-limit-day` | Requests allowed per day | | `x-ratelimit-limit-month` | Requests allowed per month | | `x-ratelimit-remaining-second` | Remaining requests this second | | `x-ratelimit-remaining-minute` | Remaining requests this minute | | `x-ratelimit-remaining-hour` | Remaining requests this hour | | `x-ratelimit-remaining-day` | Remaining requests today | | `x-ratelimit-remaining-month` | Remaining requests this month | *** ## Checking Your Rate Limits Make any API request and inspect the response headers to see your current limits: ```bash theme={null} curl -s -D - -o /dev/null --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "validator_identifiers": [1] }, "range": { "evaluation_window": "24h" } }' ``` **Example Response Headers:** ``` ratelimit-limit: 1 ratelimit-remaining: 0 ratelimit-reset: 1 ratelimit-window: second ratelimit-bucket: default ratelimit-validapikey: true x-ratelimit-limit-second: 1 x-ratelimit-limit-minute: 1000 x-ratelimit-limit-hour: 1000 x-ratelimit-limit-day: 1000 x-ratelimit-limit-month: 1000 x-ratelimit-remaining-second: 0 x-ratelimit-remaining-minute: 972 x-ratelimit-remaining-hour: 972 x-ratelimit-remaining-day: 972 x-ratelimit-remaining-month: 972 ``` *** ## Handling Rate Limit Errors When the rate limit is exceeded, the API returns a `429 Too Many Requests` status code. To handle this correctly, implement retry logic with a dynamic delay: immediately pause outgoing requests and wait for the duration specified in the `ratelimit-reset` header before attempting the request again. ### Code Examples ```python theme={null} import requests import time API_KEY = "" BASE_URL = "https://beaconcha.in" def make_request_with_retry(endpoint: str, payload: dict, max_retries: int = 5) -> dict: """Make API request with automatic retry on rate limit.""" for attempt in range(max_retries): response = requests.post( f"{BASE_URL}{endpoint}", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }, json=payload ) if response.status_code == 200: return response.json() if response.status_code == 429: # Read the reset time from header reset_seconds = int(response.headers.get("ratelimit-reset", 1)) print(f"Rate limited. Waiting {reset_seconds}s before retry...") time.sleep(reset_seconds) continue # Other errors - raise exception error_data = response.json() raise Exception(f"API error {response.status_code}: {error_data.get('error', 'Unknown error')}") raise Exception(f"Max retries ({max_retries}) exceeded") # Usage data = make_request_with_retry( "/api/v2/ethereum/validators/rewards-aggregate", { "chain": "mainnet", "validator": {"validator_identifiers": [1, 2, 3]}, "range": {"evaluation_window": "7d"} } ) ``` ```typescript theme={null} const API_KEY = ""; const BASE_URL = "https://beaconcha.in"; async function makeRequestWithRetry( endpoint: string, payload: object, maxRetries: number = 5 ): Promise { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(`${BASE_URL}${endpoint}`, { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify(payload) }); if (response.ok) { return response.json(); } if (response.status === 429) { // Read the reset time from header const resetSeconds = parseInt(response.headers.get("ratelimit-reset") || "1", 10); console.log(`Rate limited. Waiting ${resetSeconds}s before retry...`); await new Promise(resolve => setTimeout(resolve, resetSeconds * 1000)); continue; } // Other errors - throw exception const errorData = await response.json(); throw new Error(`API error ${response.status}: ${errorData.error || "Unknown error"}`); } throw new Error(`Max retries (${maxRetries}) exceeded`); } // Usage const data = await makeRequestWithRetry( "/api/v2/ethereum/validators/rewards-aggregate", { chain: "mainnet", validator: { validator_identifiers: [1, 2, 3] }, range: { evaluation_window: "7d" } } ); ``` ```javascript theme={null} const API_KEY = ""; const BASE_URL = "https://beaconcha.in"; async function makeRequestWithRetry(endpoint, payload, maxRetries = 5) { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(`${BASE_URL}${endpoint}`, { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify(payload) }); if (response.ok) { return response.json(); } if (response.status === 429) { // Read the reset time from header const resetSeconds = parseInt(response.headers.get("ratelimit-reset") || "1", 10); console.log(`Rate limited. Waiting ${resetSeconds}s before retry...`); await new Promise(resolve => setTimeout(resolve, resetSeconds * 1000)); continue; } // Other errors - throw exception const errorData = await response.json(); throw new Error(`API error ${response.status}: ${errorData.error || "Unknown error"}`); } throw new Error(`Max retries (${maxRetries}) exceeded`); } // Usage const data = await makeRequestWithRetry( "/api/v2/ethereum/validators/rewards-aggregate", { chain: "mainnet", validator: { validator_identifiers: [1, 2, 3] }, range: { evaluation_window: "7d" } } ); ``` *** ## Revoked Access A `429` response does not always mean a temporary rate limit. If your free trial has expired or your subscription has been cancelled, all limit headers will be `0`: ``` x-ratelimit-limit-second: 0 x-ratelimit-limit-minute: 0 x-ratelimit-limit-hour: 0 x-ratelimit-limit-day: 0 x-ratelimit-limit-month: 0 ``` In this case, **do not retry** ā€” waiting will not help. The `ratelimit-reset` and `retry-after` headers are present but do not reflect a real reset time. Upgrade your plan at [beaconcha.in/api/pricing](https://beaconcha.in/api/pricing) to restore access. *** ## Rate Limits by Plan Rate limits vary by subscription tier: | Plan | Price | Features | Ratelimit | Requests | API keys | | - | - | - | - | - | - | | Free Trial | 0ā‚¬ (30 days) | Basic | 1/sec | 1000 | 1 | | Hobbyist | 59ā‚¬/mo\* | Basic | 1/sec | Unlimited | 2 | | Business | 99ā‚¬/mo\* | Basic | 2/sec | Unlimited | 5 | | Scale | 399ā‚¬/mo\* | Basic & Pro šŸ’Ž | 5/sec | Unlimited | 10 | | Enterprise | [Contact us](https://beaconcha.in/api/pricing#contact-sales) | Basic & Pro šŸ’Ž | [Contact us](https://beaconcha.in/api/pricing#contact-sales) | Unlimited | [Contact us](https://beaconcha.in/api/pricing#contact-sales) | \*Prices shown are for annual billing, excluding VAT **Pro šŸ’Ž features** include premium validator selectors (`withdrawal` address, `deposit_address`) and are available on Scale and Enterprise plans. *** ## Rate Limit Buckets A **rate limit bucket** is an independent counter that tracks API usage separately from other buckets. Think of each bucket as its own quota system with its own limits and usage tracking. When you make API requests, the system checks which bucket(s) your requests count against and decrements the appropriate counter(s). Once a bucket is exhausted, requests that count against that bucket will be rate limited until the bucket resets. ### Key Concepts * **Separate buckets** mean usage in one bucket doesn't affect the limits in another bucket * **Shared buckets** mean all requests count against the same quota, regardless of which API version you're using * Your subscription type determines whether V1 and V2 API requests use separate or shared buckets ### Endpoint Buckets Different endpoints are assigned to specific buckets. You can see which bucket your request counted against in the `ratelimit-bucket` response header. | Bucket | Endpoints | | - | - | | `default` | All endpoints not listed below | | `app` | `/api/v1/dashboard/widget`, `/api/v2/validator-dashboards/*` | | `machine` | `/api/v1/client/metrics` | | `oldsubnewapi` | `/api/v2/*` (only for legacy subscription users) | The `oldsubnewapi` bucket applies when a user with a legacy subscription (Sapphire, Emerald, Diamond) accesses V2 endpoints. This keeps V2 usage separate from their V1 quota. ## How V1 and V2 rate limits work ### API keys There is only **one kind of API key**. All keys work for both **V1** and **V2** endpoints. ### Rate limits depend on your subscription type #### Legacy subscriptions If you are on a legacy plan (**Sapphire**, **Emerald**, or **Diamond**): * **V1 endpoints:** you get your **legacy plan rate limits**. * **V2 endpoints:** included with **1 call/s, 1000 requests/month**. * **Separate buckets:** V1 and V2 usage are tracked in **separate rate limit buckets**. This means: * Requests to V1 API endpoints do **not** count towards your V2 API rate limit * Requests to V2 API endpoints do **not** count towards your V1 API rate limit * You can fully utilize both V1 and V2 limits independently * **Limit types:** legacy plans enforce **per-second** and **per-month** limits. #### Current subscriptions If you are on a current plans (**Hobbyist**, **Business**, or **Scale**): * **V1 + V2 endpoints:** you get the **same rate limits** on both versions. * **Same bucket:** V1 and V2 usage share **one combined rate limit bucket**. * **Limit types:** current plans enforce **per-second** limits only (no monthly limits). ### Enterprise Enterprise customers are handled case-by-case. View current pricing at [beaconcha.in/pricing](https://beaconcha.in/pricing). Your actual limits are always available in the response headers. *** ## Best Practices Check `x-ratelimit-remaining-*` headers before making bulk requests to avoid hitting limits. Implement exponential backoff when receiving 429 errors to gracefully handle rate limits. Use `dashboard_id` to query multiple validators in a single request instead of individual calls. *** ## Related Resources * [Pagination Guide](/api/pagination) ā€” Efficient data fetching * [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets) ā€” Batch validator queries * [Custom Range Rewards](/use-cases/rewards-custom-range) ā€” Performance considerations for bulk operations # V1 API Overview Source: https://docs.beaconcha.in/api/v1-overview We recommend using the V2 API for all new integrations. No new features or endpoints will be added to V1. We strongly recommend the [V2 API](/api/overview) for all new projects. The V1 API uses `GET` requests with path parameters and query-string authentication. It remains available for existing integrations but receives no new development. ## Key Differences from V2 | Aspect | V1 (this section) | V2 (recommended) | | - | - | - | | HTTP method | `GET` with path params | `POST` with JSON body | | Authentication | `?apikey=` or `apikey:` header | `Authorization: Bearer` | | Pagination | Offset-based | Cursor-based | | Validator selection | Single index or pubkey in URL path | Batch selectors (index, pubkey, deposit address, withdrawal address, entity, dashboard) | | BeaconScoreĀ® | Not available | Available | | Entity benchmarking | Not available | Available | | Dashboard management | Not available | Available | Step-by-step instructions to migrate from V1 to V2, with endpoint mappings and code examples. Get started with the V2 API ā€” authentication, pricing, and your first request. # Migrating from V1 to V2 API Source: https://docs.beaconcha.in/api/v1-to-v2-migration 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. # BeaconScoreĀ® vs. 3rd Party Metrics Source: https://docs.beaconcha.in/beaconscore/BeaconScore-vs-3rd-party-metrics Understanding how BeaconScoreĀ® differs from externally weighted validator performance metrics # Methodology: BeaconScoreĀ® vs. 3rd Party Metrics The primary distinction between **BeaconScoreĀ®** and other ecosystem ratings is that **BeaconScoreĀ® avoids arbitrary weightings** for validator duties. Instead, it utilizes the native weighting defined by the actual Ethereum Consensus Layer (CL) specification. ## Why Protocol-Native Weighting Matters The Ethereum protocol already performs internal weighting through its reward structure. Different duties carry different levels of importance to the network's security and finality, and the protocol incentivizes them accordingly. Adding external weighting on top of these values introduces **redundant variance and "statistical noise."** By adhering strictly to the protocol's internal logic, BeaconScoreĀ® provides: * **Dynamic Adaptation:** The score automatically updates if a protocol upgrade (e.g., a hard fork) modifies duty rewards. * **Historical Reproducibility:** Metrics remain consistent and verifiable for any specific historic epoch. * **Economic Alignment:** The score reflects the actual financial impact of validator performance. *** ## Case Study: The "Weighting Problem" in Attestations The importance of native weighting is most visible in **Attestation duties**. In the Ethereum specification, an attestation is not a single "pass/fail" event; it consists of three distinct components with different protocol weights: | Attestation Component | Protocol Weight | % of Attestation Reward | | - | - | - | | **Source Vote** | 14 | \~26% | | **Target Vote** | 26 | **\~48%** | | **Head Vote** | 14 | \~26% | **The Conflict with Arbitrary Scoring:** Many external scoring models treat an attestation as a single binary event or apply a flat 33/33/33% weight to these components. If a validator misses a **Target vote** (the most critical component for finality), the Ethereum protocol penalizes the validator nearly **twice as heavily** as if they had missed a Head vote. * **Arbitrary Scores:** Might treat both misses as equal "missed duties," failing to reflect the actual severity of the performance drop. * **BeaconScoreĀ®:** Correctly reflects the 48% reward loss, ensuring the metric stays synchronized with the validator's actual economic standing and network impact. *** ## The Mental Model BeaconScoreĀ® moves away from subjective "performance ratings" toward an objective financial truth. It follows a transparent formula: > **"The ratio of rewards actually received versus the maximum potential rewards available."** By using the protocol as the "source of truth," BeaconScoreĀ® ensures that if the network considers a duty important enough to pay more for it, your score will reflect that importance naturally. # Introduction Source: https://docs.beaconcha.in/beaconscore/introduction BeaconScoreĀ®, a metric to measure validator performance # šŸ“ˆ BeaconScoreĀ® **BeaconScoreĀ®** is a comprehensive measure of validator performance, integrating multiple components: 1. [**Attestation Efficiency**](#attestation-efficiency) 2. [**Proposal Efficiency**](#proposal-efficiency) 3. [**Sync Efficiency**](#sync-efficiency) This metric is designed to provide a holistic view of a validator's effectiveness. BeaconScoreĀ® can be calculated over an arbitrary timeframe. The longer the timeframe, the closer it is expected to approach the duty weighting as defined in the consensus layer specification. For shorter timeframes however (down to a single epoch), these values can vary significantly: A block proposal or sync committee participation can completely dominate the resulting score in these cases. In order to calculate BeaconScoreĀ® over multiple epochs correctly, the respective effective balance has to be factored in. To accomplish this, each individual value gets aggregated before calculating the percentage, instead of calculating the percentage for each epoch and averaging that. *** ## Components of BeaconScoreĀ® ### **Attestation Efficiency** 84.4% (= 54/64) of validators' rewards come from attestations. Every epoch (\~6.4 minutes), a validator publishes an attestation (vote) to the network. These attestations contain valuable information about the consensus layer and are rewarded based on their correctness and inclusion delay. An attestation consists of three votes: \- Head vote \- Source vote \- Target vote If a validator votes correctly on all three and is included in the block with the best inclusion delay (1), the reward will be 100%, as good as it can be. Conveniently, the [beacon API](https://ethereum.github.io/beacon-APIs/#/Rewards/getAttestationsRewards) returns the `idealReward` for a given epoch. The `idealReward` represents the maximum potential rewards based on optimal performance, which allows us to calculate attestation efficiency. Negative rewards (penalties) from any of the 3 attestation components do not count towards `attester_actualReward`. ``` attester_efficiency = attester_actualReward / attester_idealReward ``` *** ### Proposal Efficiency Block proposals are purely luck-based, but over the long run, 12.5% (8/64) of validators' rewards come from block proposals. Blocks include execution rewards (transaction rewards + MEV rewards) and scale with the number of attestations and sync committee outputs included in a block. Comparing validator performance based on MEV rewards (which highly depend on market volatility) would not provide meaningful context. Thus, proposal efficiency solely depends on CL rewards. To remove some volatility from the result, the received proposal-related rewards are compared to the median proposal-related reward of surrounding proposals. Specifically, the surrounding 32 proposals (missing skipped, 0 if none) of each proposal are considered to be the median proposal reward. Primary reasons for using median instead of a calculated max: * Proposals can include attestations originally meant for other proposers, so the actual max reward attainable through attestation inclusion is higher than the one attainable during normal operation (which would be including attestations only meant for your slot) * It prevents offline/slashed validators from influencing proposal efficiency. Long term (multi-block) sync committee or attester participation is mostly out of the control of the proposer, and by using the median we effectively remove participants that fail to vote more than 50% of the time. \ This leads to the following formula: ``` proposer_idealReward = max(proposer_actualReward, medianReward([x-16 ... x+16])) proposer_efficiency = proposer_actualReward / proposer_idealReward ``` *** ### Sync Efficiency Every 256 epochs, 512 validators are elected to be part of the sync committee. Like block proposals, being part of a sync committee is purely luck-based. However, over the long run, 3.1% (2/64) of validators' rewards come from sync committee duties. With 500,000 validators, the expected time between being selected for sync committee duty is approximately 37 months. During this period, the rewards for sync committee members are significantly higher. Compared to attestations, which occur once per epoch, sync duties occur in every slot for 256 epochs, totaling 8192 duties per sync committee member. Since sync duties need to be included in a block by the block proposer, we ignore missed blocks that occurred during this period to avoid penalizing the sync committee member. Penalties from missed sync participation are also not counted towards `sync_actualReward`. Note: The second slot of each epoch often shows low sync committee participation, likely due to increased resource usage during the epoch transition. As a result, you may see a slight decrease in sync efficiency. This affects all validators equally, though some operators may handle it more effectively than others. This leads to the following formula ``` sync_efficiency = sync_actualReward / sync_idealReward ``` *** ### Example BeaconScoreĀ® Calculation When a validator has **attestations, block proposals, and sync committees**, BeaconScoreĀ® is calculated as: ``` BeaconScore = (attester_actualReward + proposer_actualReward + sync_actualReward) / (attester_idealReward + proposer_idealReward + sync_idealReward) ``` When a validator did not participate in a sync committee and/or did not propose a block, the respective rewards & ideal rewards are set to 0. *** ## Benchmark values Target a BeaconScoreĀ® of at least 99% on Ethereum mainnet. Performance above 99.5% is considered exceptional. Scores below 98% generally indicate an underlying issue and warrant further investigation. *** ## Residual Luck Factors BeaconScoreĀ® normalizes for the randomness of block proposal and sync committee **assignments** ā€” validators are not penalized for receiving fewer or more duties than expected. However, several external factors outside a validator's control can still influence the resulting score: * **Missed slots delaying attestation inclusion.** A validator can attest correctly, but if the next block proposer misses their slot, the attestation is delayed or excluded entirely. This increases the inclusion delay and reduces attester efficiency even though the attesting validator did nothing wrong. * **Non-finality events.** If more than one-third of the network goes offline, the chain enters a non-finality state. During this period, correctly performing validators still receive reduced rewards compared to normal operation. * **Timing games by large operators.** Some large staking pools delay publishing their blocks to capture additional MEV. Validators that follow the protocol as intended may not see the correct chain head in time, leading to incorrect head votes and lower attester efficiency. * **Sync committee during missed blocks.** If a validator is elected to a sync committee during a period when many block proposers miss their slots, their sync participation cannot be included in a block, reducing sync efficiency. * **Proposer reward variance.** Proposer efficiency only considers CL rewards (EL rewards are excluded) and is measured against the median CL reward of the 32 surrounding proposals. If a validator proposes a block during a low-activity period while surrounding proposals happen to be high-value, the comparison will understate their proposer efficiency ā€” and vice versa. ### How the duty mix shapes the aggregate score The bullets above describe factors that can lower an *individual* per-duty efficiency. A separate, often-confused effect comes from how those per-duty efficiencies are combined into the overall BeaconScoreĀ®. The BeaconScoreĀ® is **reward-weighted** ā€” equivalently, a weighted average of the three duty efficiencies, where the weight on each is the share of total ideal reward that duty type contributed during the window. Over a long horizon those weights match the protocol's per-epoch reward budget: * **\~84%** from attestation duties (54/64) * **\~13%** from block proposals (8/64) * **\~3%** from sync committee duties (2/64) On shorter windows the realised mix wanders away from this split: * Every active validator attests once per epoch ā€” the attestation share is very stable. * Block proposals are randomly assigned per slot ā€” a small entity may end up with a handful more or fewer than expected on any given day. * Sync committees are reselected every \~27 hours and pick only 512 validators network-wide ā€” a small entity may have zero sync members one day and several the next. A window that happens to give your validators a higher-than-typical share of sync-committee or proposal duties will give those (typically lower) efficiencies more weight in your BeaconScoreĀ® for that period. **Worked example.** Consider two pools, A and B, whose validators have *identical* per-duty performance: | Duty type | Efficiency | | - | -: | | Attestation | 99.88% | | Proposal | 99.30% | | Sync | 99.70% | On a "typical" day each pool's reward mix lands close to the protocol-canonical 84% / 13% / 3% split, and both pools score the same: ``` BeaconScore = 99.88 Ɨ 0.84 + 99.30 Ɨ 0.13 + 99.70 Ɨ 0.03 = 83.90 + 12.91 + 2.99 = 99.80% ``` Now suppose Pool A's validators are assigned more proposals and sync duties than statistically expected on this particular day, while Pool B has a typical day. Pool A's realised mix shifts to roughly 78% / 16% / 6%. The same per-duty numbers now produce: ``` Pool A: 99.88 Ɨ 0.78 + 99.30 Ɨ 0.16 + 99.70 Ɨ 0.06 = 99.78% Pool B: 99.88 Ɨ 0.84 + 99.30 Ɨ 0.13 + 99.70 Ɨ 0.03 = 99.80% ``` Pool A's BeaconScoreĀ® drops by \~0.02 percentage points ā€” purely because more of its score came from the duty types where its validators perform slightly worse. **No validator in Pool A performed any differently from any validator in Pool B; only the *weights* on the three numbers changed.** Smaller entities feel this more strongly: with fewer validators the realised mix has more room to deviate from the protocol-canonical 84/13/3 split before the law of large numbers smooths it out. One last subtlety to be aware of: the three duty efficiencies on the dashboard are rounded to two decimal places. Both `99.835%` and `99.844%` display as `99.84%`. Because attestation efficiency carries \~84% of the BeaconScoreĀ® weight, a sub-rounding difference there can move the BeaconScoreĀ® by \~0.008 percentage points ā€” sometimes enough to flip the ordering between two entities whose duty cards look identical. These residual factors are stochastic and tend to even out over longer evaluation windows. Use 30-day or longer windows for meaningful performance comparisons. Short windows (24h, 7d) can be significantly influenced by these effects. *** Huge thanks to [Ben Edington](https://x.com/benjaminion_xyz) for providing [https://eth2book.info/capella/](https://eth2book.info/capella/) # Product Updates Source: https://docs.beaconcha.in/changelog/product-updates # Release 26.40: On-Chain ether.fi Tagging Release 26.40 * **Validator queues redesigned** ā€” [Validator queues](https://beaconcha.in/validators/queues) charts each queue's history and wait time, and lists who is next, newest and largest. * **ether.fi tagged on chain** ā€” [ether.fi](https://beaconcha.in/entity/ether.fi/-) validators are now tagged from ether.fi's own contracts, with their operator as sub-entity. * **Cleaner entity labels** ā€” Validator pages show a validator's entity once, by name. * **Improved color scheme** ā€” Text meets WCAG AA contrast in light and dark mode across the explorer. * **Branded account emails** ā€” Sign-up, email change, password reset and sign-in security emails arrive in a clean card layout with a plain-text version. * **Menus stay on top** ā€” Sidebar menus now open above date pickers, dropdowns and banners. # Release 26.39: Filter Validators by Status Release 26.39 * **Filter validators by status** ā€” [Validators](/api-reference/ethereum/validators) and the per-epoch [balances](/api-reference/ethereum/validators/balances), [performance](/api-reference/ethereum/validators/performance-list) and [rewards](/api-reference/ethereum/validators/rewards-list) lists accept a `status_filter`, so you can list only an entity's active validators. * **Entity credential breakdown** ā€” [Consolidations](https://beaconcha.in/validators/consolidations) now lists the 25 largest staking entities with their validators and balance per withdrawal credential type. * **Clearer Block Space breakdown** ā€” The Block Space tooltip on [entities](https://beaconcha.in/entities) shows blocks and relay reports in separate tables. * **Disconnected devices flagged** ā€” [Notification settings](https://beaconcha.in/notifications) warn when push alerts can no longer reach a paired device, and we email you about it. * **Lido Curated Module v2** ā€” Its validators are now tagged Lido, with their node operator as sub-entity, on [entities](https://beaconcha.in/entities). * **Faster home dashboard card** ā€” The dashboard card on [home](https://beaconcha.in/home) loads faster for large dashboards, with a retry if a request fails. * **Missed slots shown right away** ā€” The [slot visualization](https://beaconcha.in/charts/slotviz) marks a missed slot as missed immediately. * **Link previews for every page** ā€” Every page now shares a card with its title, logo and a QR code; testnet cards are badged, dashboards stay anonymous. # Release 26.38: Charts in Search Release 26.38 * **Charts in search** ā€” Every chart on [charts](https://beaconcha.in/charts) is now searchable by name, and Charts has its own sidebar row. * **Two compounding charts** ā€” Staked ETH per withdrawal credential type, plus compounding validators' average and median balance, weekly since Pectra, on [consolidations](https://beaconcha.in/validators/consolidations). * **Attestation slots without attestations** ā€” [Attestation slots](/api-reference/ethereum/validators/attestation-slots) now returns assignment history for validators that never attested, and an empty list for queued ones. * **ETH.STOREĀ® exclusions documented** ā€” [ETH.STOREĀ®](https://beaconcha.in/ethstore) now states that validators whose effective balance changed during the day are excluded, and why. * **API key allowance corrected** ā€” The [API docs](/api/account-management) now match [pricing](https://beaconcha.in/api/pricing): Hobbyist 2, Business 5, Scale 10, custom on Enterprise. # Release 26.37: Custom Time Ranges for APY & ROI Release 26.37 Our latest release opens the APY & ROI endpoint to any time range you ask for, carries your display currency across the whole site, names Ethereum's system contracts wherever they appear, and puts the logo back on the path home: * **Custom time ranges for APY and ROI** ā€” The [APY & ROI](/api-reference/ethereum/validators/apy-roi) endpoint only accepted one of a few named windows. It now takes any range you ask for, by Unix timestamp, epoch or slot, on [Scale and Enterprise plans](https://beaconcha.in/pricing) ā€” the same custom ranges the network performance, validator performance and validator rewards endpoints already accept. Custom ranges are served at whole-UTC-day granularity, and the response reports the range it actually covered. * **Your display currency now follows you across the whole site** ā€” The currency you pick in the top bar used to apply only to the part of the site you picked it on: the newer pages and the classic explorer each remembered their own choice, so the same balance could read in dollars on one page and in euros on the next. There is now one selection for the whole site, and it is remembered between visits on every page. * **Ethereum's system contracts are shown by name** ā€” The beacon roots, block hash history, withdrawal request, consolidation request and CREATE2 factory contracts appeared as raw addresses everywhere they turned up. They are now labelled by name on the address page and on the [transactions](https://beaconcha.in/transactions) that call them. * **The logo takes you home again** ā€” In the new sidebar the logo led back out to the marketing page, which is the one thing a logo is not expected to do. It now takes you to [your home page](https://beaconcha.in/home), and the marketing page has a Products row of its own in the sidebar. The cards and charts on the home page also got a layout pass for narrow screens. * **Searching for a number finds the validator first** ā€” A number can be a block, an epoch, a slot or a validator index all at once, and the search results did not lead with the validator. On a validator explorer that is almost always the one you mean, so validator results now come first. * **Block pages load again** ā€” Opening a block from the [blocks](https://beaconcha.in/blocks) list briefly returned an error page instead of the block's details, for every block produced since the Merge. Pre-Merge blocks and the matching slot pages were never affected. They all load again. # Release 26.36: The New Sidebar Release 26.36 Our latest release replaces the top navigation with a sidebar that follows you across the whole site, gives you a home page of your own, lets you chart how the staking queues change over time, and ends the timeouts when you search for a block's graffiti: * **A sidebar that follows you across the whole site** ā€” The product navigation moves from the top of the page into a sidebar on the left, with the full site map grouped into sections that open and close. The pages you star, the ones you visited recently, which sections you left open, whether the sidebar is expanded or collapsed to icons and your theme follow you across every page on the site. It collapses to a narrow icon rail on smaller screens and expands on wide ones, and you can override that yourself ā€” your choice is remembered. On a phone or tablet it becomes a drawer behind the menu button. Above it a bar carries the current slot, epoch, finality, gas price and ETH price, the currency switch, and a star to add the page you are reading to your favourites. Your dashboards are listed by name, and the account menu now shows your full email address, your plan per product, and new Send feedback and Report a bug entries. * **A home page of your own** ā€” Signed in, [beaconcha.in](https://beaconcha.in) now takes you to [your home page](https://beaconcha.in/home) instead of the marketing page. It greets you, puts a search field front and centre, and leads with your dashboard: how many of your validators are online, your BeaconScoreĀ® over the last day, your rewards and APR over the last 30 days, each with a small chart over exactly that period. Narrow the whole card to a single validator group, or switch to another of your dashboards, and every figure follows. Below that: your latest notification, a strip of network figures, the validator queue and current wait time, the recent epochs and slots tables, and the top staking operators. Signed out, the marketing page is unchanged. * **Chart how the staking queues change over time** ā€” The new [staking queues history](/api-reference/ethereum/queues/history) endpoint returns the deposit, exit, manual withdrawal and consolidation queue sizes as a time series, so you can chart how much ETH is waiting to enter and leave staking rather than only reading today's figure. Ask for a range by timestamp, epoch or slot, daily or per epoch, or leave the range out for the last 30 days. Daily figures reach back to the Pectra fork; per-epoch figures reach back as far as the records can be trusted, and a request for anything earlier is answered from that point rather than with gaps. * **Turn product emails on and off** ā€” A new "Product News & Offers" switch on the Account tab of your [settings](https://beaconcha.in/user/settings) controls whether you receive product news, and takes effect immediately. Every such email also carries a working unsubscribe link, including the one-click kind your mail app offers at the top of the message. Until now consent was only recorded when you registered, with no way to change your mind. * **A realistic wait for a switch to compounding** ā€” The queue position and estimated wait shown for a switch to compounding withdrawal credentials were counted only among your own requests, not among everyone's, so the estimate said the switch was seconds away no matter how long the real queue was. Both are now counted against the whole queue, and the figures shown for your validator and for the network as a whole agree with each other. Requests submitted through a contract rather than directly are no longer left out. * **Searching for a block's graffiti no longer times out** ā€” Searching for the text a validator writes into the blocks it proposes could hang for over a minute and end on an error page instead of a result, and a common value such as "Lido" did so every time. Those searches now answer in well under a second. # Release 26.35: Block Space by Relay Release 26.35 Our latest release shows which relays deliver each staking operator's blocks, adds a section navigation to long pages, tells you when a manual withdrawal request will be paid out, makes tooltips that carry more than one figure readable, and hardens account sign-in: * **Which relays deliver each operator's blocks** ā€” [Entities](https://beaconcha.in/entities) and each entity's sub-entities table gain a Block Space column: a stacked bar of the MEV-Boost relays that delivered that operator's blocks over the selected period, with blocks built without a relay as a gray remainder and the MEV-Boost share below it. Hover the bar for the split per relay. The column also sorts on the Entities table, so an ascending sort brings up the operators that propose most of their blocks without a relay ā€” usually a sign that a relay, or the monitoring of it, is misconfigured. * **Tooltips with more than one figure are now readable** ā€” Tooltips that carry several figures, on charts and in tables across the site, packed them into a single line separated by pipes or line breaks. They now lay the figures out as a small table: a heading, one row per value with the numbers lined up on the right, and the total set apart. Their colours were rebuilt for the dark tooltip background as well, so values that were hard to make out against it now stand out. * **Search results no longer open a new tab** ā€” Picking a page from the search dialog opened it in a new browser tab, even when it was a page on beaconcha.in, and the same happened in the header search on explorer pages and in some links in the [notification centre](https://beaconcha.in/monitoring/notifications). Those now open in the tab you are already in. Only genuinely external links still open a new one ā€” the [documentation](https://docs.beaconcha.in) and Chainabuse. * **Jump around long pages** ā€” Long pages now carry a section navigation: a rail beside the content on a wide screen, and a sheet you can open on a phone. It follows along as you scroll, marks the sections currently on your screen, and takes you straight to any of them. You will find it on each validator's own page (reachable from [Validators](https://beaconcha.in/validators)), on [Validator Queues](https://beaconcha.in/validators/queues) and [Withdrawals](https://beaconcha.in/validators/withdrawals), and on the [home page](https://beaconcha.in), the [API page](https://beaconcha.in/api) and [BeaconScoreĀ®](https://beaconcha.in/beaconscore). * **See when a manual withdrawal request will be paid out** ā€” A manual partial withdrawal now shows when it is expected to settle: a countdown on each request already queued, and an estimate of the wait if you were to request one now. Both appear on each validator's own page, in the table labels and their tooltips. * **Execution payload status on slot pages** ā€” After the upcoming Gloas upgrade, a block can be proposed without its execution payload ever being revealed. [Slot pages](https://beaconcha.in/slots) now show that as a status of its own beside the proposal status ā€” full, empty or still pending ā€” and name the reason an empty one is empty: the builder withheld the payload, or the next block was built on an earlier one. The [slot endpoint](/api-reference/ethereum/slot/overview) returns the same two fields. Slots from before the upgrade show nothing, since the distinction does not exist for them. * **The mobile app's status and navigation bars follow your theme again** ā€” On Android 16 the bars at the top and bottom of the app stopped picking up the theme and stayed white. They follow it again, including the colour set by the validator you have selected. * **Account sign-in hardened** ā€” Several fixes to signing in: a two-factor code can no longer be used a second time, your session is replaced part-way through a two-factor sign-in rather than carried over, and two accounts can no longer be created for the same email address at the same moment. Nothing is needed from you. # Release 26.34: Entity Search & Explorer Fixes Release 26.34 Our latest release lets you search for staking entities, and fixes the tables on the address and token pages and the colours of the MEV timing map: * **Search for staking entities and their operators** ā€” The search bar now finds staking entities and their operators by name, so you can go straight to one instead of looking it up in the [Entities](https://beaconcha.in/entities) table. They appear in their own Staking Entities and Staking Sub-Entities groups, each with the entity's logo, and a filter chip shows only those. A search also no longer waits on its slowest part: every kind of result now has its own time limit, so a slow one is left out rather than holding up everything else. * **Table headers no longer cover the search results** ā€” On the [address](https://beaconcha.in/address/0x00000000219ab540356cbb839cbe05303d7705fa) and token pages, the column headers of the tables stayed on top of the search dialog when you searched from those pages, hiding the first results behind them. They now stay within their own table. * **MEV timing colours now agree with the label beside them** ā€” On [Entities](https://beaconcha.in/entities), the MEV timing map coloured every operator on a single scale that ran across all three timing categories, so an operator close to a category boundary took the neighbouring category's colour ā€” one labelled "Timing Games" could be drawn in the red of the aggressive band. Each category now has its own colour range, so a tile's colour always matches its label, and the map reads the same way as the BeaconScoreĀ® map beside it. # Release 26.33: Machine Monitoring on the Web Release 26.33 Our latest release brings your machine and client metrics to the website, with alerts you can set per machine, a clearer view of MEV timing across the network, and two new endpoints for the consolidation queue: * **Your machines on the website** ā€” Machine and client metrics were only visible in the mobile app. The new [Machines](https://beaconcha.in/monitoring/machines) page, in the Monitoring menu, charts cpu, memory, disk, disk i/o, network, libp2p traffic, peers and validators for each of your machines, grouped into a card per domain. An online/offline dot beside every machine shows at a glance which one stopped reporting. Time windows run from 1 hour to 30 days, with 3 hours on the free plan. * **Machine alerts, on the web for the first time** ā€” Alerts for an offline machine and for cpu, memory and storage usage can now be configured in the [notification centre](https://beaconcha.in/monitoring/notifications)'s Machines tab, either for every machine at once or per machine. Until now they could not be set anywhere on the website. Machines that have no alerts of their own are named rather than left to look covered. * **Every consolidation your validators took part in** ā€” The new [validator queue consolidation details](/api-reference/ethereum/validators/queues/consolidations) endpoint lists each consolidation request your validators are involved in, as the source whose balance is merged away or as the target that receives it, back to the Pectra fork. Every entry carries its status: waiting in the execution-layer contract, queued with an estimated processing time, completed with the amount moved, or rejected with the reason. Filter by status, or by role to list every validator ever merged into one target. A selection of up to 50,000 validators is supported for now. * **Switches to compounding withdrawal credentials** ā€” The new [validator queue compounding switch details](/api-reference/ethereum/validators/queues/compounding-switches) endpoint lists the requests that raise a validator's limit from 32 to 2048 ETH, each with its status. The consensus layer reports these through the same contract as consolidations, so a rejected switch is easy to mistake for a failed consolidation; this endpoint returns them as the switches they are. * **MEV timing across the whole network, not just its middle** ā€” The network timing chart on [MEV](https://beaconcha.in/mev) plotted a single line, the daily median. The largest staking pools win most slots and propose promptly, so that line barely moves and tells you nothing about what the rest of the network does. The card now shows the spread instead: the middle half of proposals as a shaded band, with the promptest tenth and the slowest tenth as their own lines, and every value in the tooltip. A short explainer says what to watch ā€” the gap between the outer lines, which is how far apart operators behave. # Release 26.32: Custom Time Ranges & Pectra Execution Requests Release 26.32 Our latest release brings custom time ranges for aggregated data, new endpoints for Pectra execution requests and the fee you need to pay to submit one, and staking returns on the entity pages: * **What it costs to submit a withdrawal or consolidation right now** ā€” The new [current request fee](/api-reference/ethereum/queues/request-fees/current) endpoint reports the fee each request contract demands at this moment, so you can decide whether to submit now or wait. The fee is not readable from a block explorer, and underpaying makes your own submission fail. * **Request fee history** ā€” The new [request fees](/api-reference/ethereum/queues/request-fees) endpoint reports the lowest and highest fee seen per block for withdrawal and consolidation requests, over any time range. * **Consolidations in a slot** ā€” The new [slot consolidations](/api-reference/ethereum/consolidations) endpoint lists the consolidation requests a slot's block carried, covering both consolidations between validators and switches to compounding withdrawal credentials, each with its status and rejection reason. * **Custom time ranges for aggregated data** ā€” [Network performance](/api-reference/ethereum/performance-aggregate), [validator performance](/api-reference/ethereum/validators/performance-aggregate) and [validator rewards](/api-reference/ethereum/validators/rewards-aggregate) accept arbitrary time ranges by Unix timestamp, epoch, or slot, on [Scale and Enterprise plans](https://beaconcha.in/pricing). Ranges are returned in whole UTC days, and each response reports the range it actually covers. * **Staking returns on the entity pages** ā€” [Entities](https://beaconcha.in/entities) gains a sortable APR column, and each entity's own page now leads with APR and the period ROI instead of a plain income figure. The earned-rewards box gains the missing execution (MEV + tips) row, and both boxes close with their APR and ROI. The figures come from the same data as the [validator APY/ROI](/api-reference/ethereum/validators/apy-roi) endpoint, so the explorer and the API agree. * **Each operator's APR in the sub-entities table** ā€” An entity's sub-entities table now shows the APR of every operator beside its BeaconScoreĀ® and net share, so you can compare returns without opening each one. * **Webhook and Discord notifications are delivered again** ā€” Webhook and Discord [notifications](https://beaconcha.in/monitoring/notifications) were silently dropped for any period in which no user had turned the webhook channel off, which in practice meant most of them. They are now sent as configured. * **Time ranges starting before the chain existed** ā€” Endpoints that take a custom time range returned a negative slot and epoch when the range started before genesis, which their own contract does not allow. Such a range is now reported as starting at genesis ([request fees](/api-reference/ethereum/queues/request-fees) and every other endpoint with a time range). * **Better activation estimates for pending validators** ā€” The [dashboard](https://beaconcha.in/dashboard) estimated when a pending validator would activate using the queue rules that applied before Pectra, which no longer describe how a validator enters the chain. The estimate now follows the current rules, so a validator that already holds a registry entry is no longer told to wait behind the whole activation queue. * **MEV timing rejects a time range it cannot serve** ā€” [Validator MEV timing](/api-reference/ethereum/validators/mev-timing-aggregate) accepted a time range, ignored it, and answered over the default 180-day window, so you could not tell that your range had no effect. Such a request is now rejected. The rolling 180-day window is still the only one available, and it stays the default when you omit the range. * **Layout fix** ā€” The period badge in an entity page's headline figures is no longer clipped on narrow screens. # Release 26.31: Unified Pricing & Subscriptions Release 26.31 Our latest release brings a single pricing page, a subscriptions overview, a new ETH.STOREĀ® endpoint, and a withdrawal-estimate fix: * **One pricing page** ā€” API and Monitoring plans now live together on [pricing](https://beaconcha.in/pricing) with a product switcher; the old API and Premium pricing links redirect there with the right product preselected. * **Your subscriptions in one place** ā€” A new [Subscriptions](https://beaconcha.in/user/subscriptions) page lists your API and Monitoring subscriptions with direct access to billing management. * **Accurate next-withdrawal estimates** ā€” Queued withdrawal requests are now included in the next-withdrawal estimate on [validator](https://beaconcha.in/validators) pages and the [dashboard](https://beaconcha.in/dashboard), which previously showed a near-zero amount for a validator with a large request already queued. * **ETH.STOREĀ® as a daily time series** ā€” The new [ETH.STORE](/api-reference/ethereum/eth-store) endpoint returns the network-wide daily staking yield as a paginated series with 7-day and 31-day moving averages. * **Adding exited validators to a dashboard works again** ā€” Adding validators by deposit address no longer fails outright when one of them has already exited, on the [dashboard](https://beaconcha.in/dashboard). * **Validator index on the deposits page** ā€” The [deposits](https://beaconcha.in/validators/deposits) table now shows each deposit's validator index, so you no longer have to open a deposit to find it. * **ether.fi in the staking services directory** ā€” [Staking services](https://beaconcha.in/stakingServices) now lists ether.fi alongside the other liquid-staking providers. * **Machine metrics API works again** ā€” The [machine metrics](/api-reference/machine-metrics) endpoints returned an error instead of your monitoring data. They now serve it again, with correct "last seen" timestamps and correct ordering and paging for machines whose exporter reported time in milliseconds. * **Mobile fix** ā€” The landing page's API cards no longer overflow the page padding on narrow screens. # Release 26.30: New API Endpoints & Income Report Fixes Release 26.30 Our latest release brings new API endpoints, income report accuracy fixes, and validator data corrections: * **New API endpoints** ā€” [Epoch overview](/api-reference/ethereum/epoch), [slot deposits](/api-reference/ethereum/deposits), and [validator lifecycle states](/api-reference/ethereum/state/validator-statuses) are now available, alongside newly-published docs for the [deposits](/api-reference/ethereum/validators/deposit-slots) and [withdrawals](/api-reference/ethereum/validators/withdrawal-slots) endpoints. * **Income report accuracy** ā€” System deposits/withdrawals (protocol-internal balance movements) no longer count toward payouts or income, and networks with Electra active from genesis no longer double-count deposits, in the [income report](https://beaconcha.in/monitoring/income-report). Both CSV exports are now versioned so external tools can detect format changes. * **Validator data corrections** ā€” Fixed a cross-chain cache bug that could show one chain's validator key on another chain's same-numbered validator, corrected contract categorization on block overview/rewards/withdrawals pages, and fixed incorrect checkpoint reporting on the network state endpoint. * **Faster custom date-range queries** ā€” Rewards and network views over a custom date range load faster thanks to smarter query planning. * **Protocol-generated deposits are now typed `system`** ā€” The deposit type previously returned as `network` is now `system`, matching the wording used for [system deposits and withdrawals](/faqs/system-deposits-and-withdrawals) ([slot deposits](/api-reference/ethereum/deposits)). * **Correct sender on direct deposits** ā€” Deposits sent straight to the deposit contract now report the depositing address instead of an empty one ([slot deposits](/api-reference/ethereum/deposits)). * **Queued deposits and withdrawals clarified** ā€” The [deposit](/api-reference/ethereum/validators/deposit-slots) and [withdrawal](/api-reference/ethereum/validators/withdrawal-slots) endpoints now explain that entries still waiting in the queue have no per-slot detail yet, and how to filter for the ones that do. # Release 26.29: Validator Page Refresh & MEV Guides Release 26.29 Our latest release brings a validator-page refresh, a one-click income report, and new MEV guides: * **Validator page refresh** ā€” Cleaner heading labels on [validator](https://beaconcha.in/validators) pages, a new BeaconScoreĀ® percentile badge ("Top X%"), and ā€” on mobile ā€” the edit, follow, and API-links actions tucked into a single menu. * **One-click Income Report** ā€” A "Generate Income Report" button on the [validator](https://beaconcha.in/validators) page takes you straight to a tax-grade [income report](https://beaconcha.in/monitoring/income-report) pre-filled with that validator. * **MEV analysis guides** ā€” New how-to guides for MEV timing analysis: an [introduction](/use-cases/mev-analysis-introduction), plus walkthroughs for [comparing timing across entities](/use-cases/compare-mev-timing) and [investigating a block](/use-cases/investigate-mev-block). * **Dashboard updates instantly** ā€” The validator summary now refreshes right after you add or remove validators, instead of showing stale rows for up to \~15 seconds; the add-validator search also accepts a trailing comma. * **Faster slot pages** ā€” [Slot](https://beaconcha.in/slots) pages load noticeably faster, and the Transactions tab on busy blocks now loads in pages instead of resolving every transaction up front. * **Mobile fixes** ā€” Recent-slots cards no longer overlap on the landing page, and the Expert-mode Daily Income chart legend no longer swallows the plot on phones. # Release 26.28: Validator Income & Tax Report Release 26.28 Our latest release brings the income report and navigation polish: * **Validator income & tax report** ā€” New [income report](https://beaconcha.in/monitoring/income-report) with time-weighted APR and a tax-grade CSV export of your validators' rewards, priced in your fiat currency; non-premium users can explore a demo with sample data. * **Redesigned Daily Income chart** ā€” The [validator](https://beaconcha.in/validators) page's Daily Income chart is rebuilt with Simple, Advanced, and Expert detail levels, a per-component reward breakdown, clearer missed-reward bands, and an expandable full-history view ā€” with the header income figures and chart now guaranteed to agree. * **Explorer menu refined** ā€” The [Explorer](https://beaconcha.in/explorer) menu's Network Overview now has labelled Chain and Validators sections, and Relays and Entities join the Staking Hub. # Release 26.27: MEV Timing API, Navigation & Explorer Redesign Release 26.27 Our latest release brings a new API, a redesigned navigation, a tools gateway, and MEV polish: * **MEV timing games API** ā€” Five new endpoints expose relay bid ladders and timing-game outcomes for blocks, entities, validators, and the whole network ([docs](/mev-timing-games/introduction)), now linked from the API pill on every page that shows the same data. * **Redesigned navigation** ā€” New mega menus with gateway cards and a restructured [Explorer](https://beaconcha.in/explorer) menu (Staking Hub, Network Overview, Performance), plus a rebuilt mobile menu. * **Tools Hub** ā€” A new [tools gateway page](https://beaconcha.in/tools) presenting every explorer tool in one place, with a spotlight carousel. * **Explorer landing page redesign** ā€” The [explorer](https://beaconcha.in/explorer) landing page is rebuilt on the new design system, with reworked slot and epoch cards, a validator-status breakdown, and network-vitals tiles. * **System deposits & withdrawals** ā€” New [explainer](/faqs/system-deposits-and-withdrawals) covering protocol-internal balance movements that are re-queued as pending deposits. * **MEV timing accuracy** ā€” On the [entities](https://beaconcha.in/entities) pages, a day that has not finished aggregating now shows an "Unknown" badge instead of a misleading "No MEV". * **Entity & MEV polish** ā€” Touch-device treemap tooltips with a working "View details" link, plus mobile tab cutoff, card alignment, a colored MEV median with vs-average delta, and MEV sub-tab deep-linking on [validator](https://beaconcha.in/validators) pages. * **Withdrawal & consolidation status** ā€” On the [dashboard](https://beaconcha.in/dashboard), completed execution-layer withdrawal and consolidation requests now show the correct processed status instead of staying stuck on "queued". # Release 26.26: Large-Dashboard Fixes Release 26.26 Our latest release brings several fixes: * **Large dashboards: Blocks tab** ā€” The [dashboard](https://beaconcha.in/dashboard) Blocks tab now loads for very large dashboards (tens of thousands of validators) that previously timed out. * **Large dashboards: MEV tab** ā€” The [dashboard](https://beaconcha.in/dashboard) MEV tab now loads for very large dashboards instead of failing. * **Entities treemap consistency** ā€” The [entities](https://beaconcha.in/entities) treemap now shows the same BeaconScoreĀ® as the matching entity detail page. # Release 26.25: MEV Timing Games & Entities Redesign Release 26.25 Our latest release brings major new analysis tools: * **MEV timing games** ā€” New [MEV analysis](https://beaconcha.in/mev) with heatmap, treemap, and bar charts, plus MEV insights on slot, validator, and entity pages and a dashboard MEV tab. * **Entities redesign** ā€” Rebuilt [entities hub](https://beaconcha.in/entities) and detail pages with a period switcher, KPI trend chips, treemap / BeaconScoreĀ® charts, and searchable tables. * **Validator queue accuracy** ā€” Balance-derived churn, correct live consolidation balance, and 0x01/0x02 address matching in the [queue API](/use-cases/queue-wait-times). * **Staking queue guides** ā€” New [queue-tracking guides](/use-cases/queue-tracking) for wait times and staking flows; the v2.1 schema is now the default (legacy deprecated, sunset 2026-07-02). * **Validators sorting** ā€” Restored column sorting on the [validators overview](https://beaconcha.in/validators). * **Top-up deposit clarity** ā€” Top-up deposits now show a "Top-up" badge instead of confusing all-zero values on the [deposits page](https://beaconcha.in/validators/deposits). * **Consolidation vs. exit queues** ā€” The [validator queues page](https://beaconcha.in/validators/queues) now separates consolidation sources from voluntary exits. # Release 26.24: New Clients, GasNow Fix, Withdrawal Epoch Release 26.24 Our latest release brings several updates: * **ethrex & Grandine** ā€” Two new Ethereum clients (ethrex execution layer, Grandine consensus layer) are now tracked in the clients overview and available for update notifications. * **GasNow decimal precision** ā€” Gas price tiers now show 3-decimal precision. Previously any value below 1 gwei showed "\< 1 GWei" on all four tiers; you can now see actual values like "0.042 Gwei". * **Validator withdrawal epoch** ā€” The lifecycle timeline now shows the withdrawal epoch on the "Withdrawn" step ā€” estimated for validators still in the sweep queue, confirmed once fully withdrawn. * **Withdrawal slots API** ā€” New endpoint returns all slots in which a validator received a withdrawal sweep payment. * **Currency switch fix** ā€” Switching the display currency now immediately reloads server-rendered values (balances, income cards, charts, tables). Previously required a manual page refresh. * **Consolidation banner accuracy** ā€” The "Consolidation in progress" banner no longer shows for validators with rejected consolidations, and no longer renders twice. # Release 26.23: Reward Accuracy & Bug Fixes Release 26.23 Our latest release brings several fixes: * **Slots reward accuracy** ā€” The burned base fee is now correctly subtracted from EL proposer rewards for non-MEV blocks on the slots list. Values were previously overstated by baseFee Ɨ gasUsed. * **Exit queue 404 fixed** ā€” An empty validator exit queue no longer returns a 404 error. * **Exit queue estimate accuracy** ā€” Estimated withdrawal queue epochs are accurate again (were up to \~11.6 hours too early due to a missing MAX() aggregate). * **Mobile pricing table** ā€” Row backgrounds now paint across all columns when scrolling horizontally on mobile. # Release 26.22: Slots Reward Bars, Validator Lifecycle, Bug Fixes Release 26.22 Our latest release brings several updates: * **Slots: EL/CL reward bars** ā€” The slots list shows inline bar charts for Execution Layer (priority fees / MEV) and Consensus Layer proposer rewards, normalised per page. The activity column is compacted with icon + count pairs. * **Validator lifecycle** ā€” The lifecycle timeline gains a Withdrawn step. "Consolidation in progress" now surfaces in the overview card and is suppressed when the latest request is rejected. EL consolidation, withdrawal, and exit tables show a Status column with consensus-layer rejection reasons. * **Post-Pectra deposits** ā€” Post-Pectra CL deposit events are now included on validator and address pages, so deposits submitted after Pectra are no longer missing. * **Cookie consent unified** ā€” A single consent choice now covers both v1 and v2 pages. * **Bug fixes** ā€” Withdrawals chart values corrected (was 10ā¹ too small), non-default currency on withdrawals page fixed, contact form 404 resolved, and more. # Release 26.21: Gas Price, Validator Self-Reporting, UI Polish Release 26.21 Our latest release brings several updates: * **Validator chart deep links** ā€” Sub-tabs on validator pages (#income, #proposals, #beaconscore) are now bookmarkable URLs that update as you navigate. * **Validator self-reporting** ā€” Validators can now claim their entity tag directly via the API, making it easier for staking operators to associate validators with their organisation. * **Mobile slot visualization** ā€” Slot category icons now render correctly on mobile without needing to open the filter panel first. * **CL reward pending status** ā€” Slot and block pages now show "Pending (waiting for epoch finality)" instead of a blank dash for proposer rewards that haven't been processed yet. * **Withdrawal sweep timestamps** ā€” Corrected the staking queue estimation timestamps (slot time was being computed as epoch time, inflating values by 32Ɨ). * **Copy & UI polish** ā€” 13 text and copy fixes across the site (EIP-1559, Rocket Pool, footer, and more), BeaconScoreĀ® button spacing fixed, card rounded corners no longer clipped. # Release 26.20: TOTP 2FA, Consolidations UI, Entity Selector Release 26.20 Our latest release brings three updates: * **TOTP two-factor authentication** ā€” Secure your account with a TOTP authenticator app (Google Authenticator, Authy, etc.). Enable it from user settings. * **Consolidations UI** ā€” Ethereum Pectra consolidation requests are now visible in the explorer. Track on-chain consolidations from the Eth1 address page. * **Entity selector live** ā€” The entity selector API is fully deployed. The "Coming Soon" label is gone. # Release 26.19: Page Search, Validator EL/CL Rewards, BeaconScoreĀ® Simulator Fix Release 26.19 Our latest release brings four updates: * **Cmd+K page search** ā€” The search dialog now surfaces internal pages alongside chain entities. Find any page ā€” dashboard, explorer, API docs, settings ā€” instantly. * **EL/CL reward split** ā€” Proposer rewards on slot and block pages are now broken out into Execution Layer and Consensus Layer components. Relay-built blocks show a MEV badge with the MEV recipient. The validator history table gains duty icons for attestation, proposal, and sync duties. * **BeaconScoreĀ® simulator** ā€” The simulator math now matches the API's reward identity with correct Altair weighting and realistic defaults. Sliders extend to 0ā€“100 % with a red-zone gradient on the track. * **Machine Metrics API (POST)** ā€” `POST /api/v1/client/metrics` is now fully documented in the API docs sidebar with all three process variants. # Release 26.18: Machine Metrics API Docs, UI Fixes Release 26.18 Our latest release brings a documentation update and several UI fixes: * **Machine Metrics API** is now fully documented at [docs.beaconcha.in](https://docs.beaconcha.in) ā€” endpoints, cursor pagination, and example responses. * **Tab navigation** no longer scrolls the page when switching between tab panels. * **Cookie banner** button layout is fixed for mobile screens. * **Maximum stake exceeded banner** is now correctly centered. # Release 26.17: BeaconScoreĀ® Hub, Pubkey Prefix Search, Machine Metrics API Release 26.17 Our latest release brings four updates: * **[BeaconScoreĀ®](https://beaconcha.in/beaconscore)** now has a dedicated landing page covering methodology, leaderboard, simulator, and comparison. * **Pubkey prefix search** lets you find validators by the first few hex characters (up to 10 matches). * **Machine Metrics API** adds two new endpoints with cursor pagination to pull your own node, system, and validator metrics ā€” making it easier to correlate hardware issues with on-chain events like missed blocks or finality drops. * **Themed scrollbars** ā€” thin theme-aware scroll bars with scroll shadows. # Free API Tier Replaced with a 30-Day Trial The free API tier is being replaced with a **30-day full-access trial**. Existing free API keys will stop working on **Tue May 26, 2026 at 13:00 GMT+0200**. The trial gives you full access for 30 days with no automatic upgrade to a paid plan after the trial ends. Existing free users should migrate before the cutoff at [beaconcha.in/api/pricing](https://beaconcha.in/api/pricing). # V1 ā†’ V2 API Migration Guide Still on our V1 API? V2 is worth the switch: * All new features ship on V2 only. * Query by index, pubkey, deposit address, withdrawal address, entity, or dashboard. * Cursor-based pagination for cleaner data flows. Step-by-step instructions are in the [V1 to V2 migration guide](/api/v1-to-v2-migration). # Website Redesign and Navigation Update We redesigned the website and reorganized the main navigation around a search-first landing page and four primary sections: [API](https://beaconcha.in/api), Monitoring, [Explorer](https://beaconcha.in/explorer), and Resources. The new landing page puts search first so you can find chain entities faster, while still giving you a quick overview of our core products at [beaconcha.in](https://beaconcha.in). Technical endpoints and documentation now live under the [API menu](https://beaconcha.in/api). Dashboards and notification settings are grouped under [Monitoring](https://beaconcha.in/monitoring/dashboard/). Chain data such as epochs, validators, slots, and blocks now sits under the [Explorer menu](https://beaconcha.in/explorer), while tools like GasNow have moved under Resources. Website Redesign # New v2 API Endpoints for Network and Validator Insights We added new v2 API endpoints focused on three areas: Entity Performance, Network Insights, and Validator Duty History. These updates make it easier to monitor staking entities, query network-level data for blocks, slots, sync committees, and validator metadata, and review validator duty history across attestations, proposals, and sync committees. Explore the updated API documentation at [docs.beaconcha.in](https://docs.beaconcha.in/api/overview). v2 API Updates # Introducing new API Key Management Now you can generate & manage keys directly in our new api key management page. Increased key limits based on your subscription plan. API Key Management # Our new v2 API is live! You can now: * Monitor your validators' performance with BeaconScoreĀ® * Access consensus layer data in real-time * Analyze validator rewards and queues * Free tier users have access to v1 & v2 API with a rate limit of 1K/per month v2 API Release # Validator Queue Dashboard We've added a new [Validator Queue Dashboard](https://beaconcha.in/validators/queues) that gives you real-time visibility into Ethereum's validator queues. Track the Deposit, Consolidation, and Withdrawal queues ā€” each showing the number of pending requests, total queued ETH, estimated wait time, churn limit per epoch, and a 30-day historical trend chart. Validator Queue Dashboard # API Docs We made improvements to help you understand and use the API to the fullest. Find them in our [docs portal](/api/overview). You can now access the API quickly from the updated homepage banner or from the new dropdown menu. API Docs # BeaconScoreĀ® + Entity Dashboards Weā€™ve just rolled out a set of updates on beaconcha.in: Weā€™ve rebranded our validator efficiency metric to BeaconScoreĀ® ā€” same reliable calculation, now with a clearer name. Learn how it works [here](/beaconscore/introduction) A new [Entities Page](https://beaconcha.in/entities) : A high-level view of major staking providers, showing net validator share and BeaconScoreĀ® ā€” all in one interactive visualization. Shout out to to [Hildoby](https://x.com/hildobby) for providing the data. Entities Page Detailed [Entity Dashboards](https://beaconcha.in/entity/Lido/-): Dive into each entityā€™s performance, see rewards, validator breakdowns, and sub-entities ā€” all in one place. Entity Detail Page # Deposit process Source: https://docs.beaconcha.in/faqs/deposit-process This guide explains the different validator statuses shown on Beaconcha.in and how validators transition between them. # Ethereum Validator Lifecycle and Status (Post-Pectra) ## Introduction This guide explains the different validator statuses shown on Beaconcha.in (Unknown, Deposited, Pending, Active, Exiting, Slashed, and Exited) along with what each status means, how validators transition between them, and how the queue system works. In addition to these Ethereum protocol-specific statuses, Beaconcha.in also labels validators as Online or Offline, indicating whether they are currently performing their assigned duties. ## Unknown (Transaction still in mempool) Every validator deposit, like any Ethereum transaction, first enters the Mempool, which acts as a waiting room for transactions. While in the Mempool, the transaction status is pending. At this stage, the deposit has not yet been added to the canonical blockchain, so the validator appears as Unknown on Beaconcha.in. Each transaction pays a Base Fee, which is set algorithmically and burned, plus an optional Priority Fee that goes to the block builder including the transaction. Block builders typically prioritize transactions offering the highest Priority Fee. When the network is congested, the Base Fee rises dynamically. Transactions with low Base Fees or low Priority Fees may face unpredictable delays. You can speed up a pending transaction by increasing the network fees. ## Deposited At this stage, the deposit transaction has been included in a block. Beaconcha.in will show the validator status as Deposited until the deposit has been fully processed by the deposit queue. A validator must have a minimum effective balance of 32 ETH to become eligible for activation. Note that there can be a difference between a validator's balance and effective balance. The effective balance only increases if the balance is at least 1.25 ETH higher than the current effective balance. For example, if a validator has an effective balance of 31 ETH and receives an additional 1 ETH deposit, the validator's balance becomes 32 ETH, but the effective balance remains 31 ETH. Deposit Queue ## Pending Once a validator's effective balance has reached at least 32 ETH, it enters the Pending state and stays there for 5 epochs (32 minutes) before becoming Active. See [process\_registry\_updates](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/beacon-chain.md#modified-process_registry_updates) for details. Pending ## Active Active validators have at least one attestation duty in every epoch and may also be randomly selected to propose blocks or participate in sync committee duties. At this stage, the validator begins earning staking rewards for helping secure the network. Active Validator ## Exiting (Exit in Progress) The validator is currently Exiting the network, either because its effective balance fell below 16 ETH (a forced exit) or due to a Voluntary Exit requested by the owner or operator. The validator will continue to receive new duties and is expected to fulfill them. Exiting a validator takes at least 5 epochs (32 minutes), but there is also a queue with a dynamic per-epoch limit. As a result, completing an exit can take anywhere from minutes to weeks, depending on how many other validators are exiting at the same time. Note that a validator must remain in the Active state for at least 256 epochs (\~27 hours) before it can be exited. See [process\_voluntary\_exit](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/beacon-chain.md#modified-process_voluntary_exit), [process\_withdrawal\_request](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/beacon-chain.md#execution-layer-withdrawal-requests) and [compute\_exit\_epoch\_and\_update\_churn](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/beacon-chain.md#new-compute_exit_epoch_and_update_churn) for details. Exiting Validator ## Exited The validator has Exited the network and will no longer be assigned new duties. However, in rare cases, the validator may still have sync committee duties! Note that an exited validator can still have a balance. Exit and Withdrawal are two separate events. See [How Ethereum validator withdrawals work](https://docs.beaconcha.in/faqs/how-withdrawals-work) and [process\_withdrawals](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/beacon-chain.md#modified-process_withdrawals) for more details about withdrawals. Exited Validator ## Slashed (Forced Exit due to Slashing) A Slashed validator violated network rules, usually by acting maliciously or negligently, such as signing conflicting blocks or attestations, resulting in a loss of a portion of their stake. The funds will be withdrawable after 8192 epochs (\~36 days). See [slash\_validator](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/beacon-chain.md#modified-slash_validator) for details. Slashed Validator ## Invalid Deposit The transaction contains an invalid BLS signature. This often occurs when the deposit was accidentally signed for the wrong network. Invalid Deposit ## Online / Offline We consider a validator that missed the latest 3 finalized attestations as Offline. Missing duties results in missed rewards and may also incur penalties. # How Ethereum validator withdrawals work Source: https://docs.beaconcha.in/faqs/how-withdrawals-work Understand the lifecycle, credentials, timing, and verification of validator withdrawals. If you have exited your validator and are waiting for your ETH, this guide explains what happens next, how long it can take, and how to confirm progress on beaconcha.in. ## TL;DR * There are two kinds of withdrawals: * Partial withdrawals: automatically skim any balance above your validatorā€™s effective balance (typically 32 ETH unless you opted for a higher cap after Pectra; see below) to your withdrawal address. * Full withdrawals: after you exit and become withdrawable, the protocol pays out your validatorā€™s full effective balance to your withdrawal address. * You must have 0x01 or 0x02 withdrawal credentials (execution address) to receive either partial or full withdrawals. * Payouts are processed by the protocol in the background, at a limited rate per slot. This can take from minutes to multiple days depending on global queues. * You can verify status and payouts on beaconcha.in: use your validator page (status, epochs) and your withdrawal address page ā†’ Withdrawals tab. ## The withdrawal lifecycle 1. Active ā†’ Exiting * You (or an authorized party) submit a voluntary exit for your validator. * Your validator stays active until the exit is processed by the consensus layer (subject to churn limits). 2. Exited ā†’ Withdrawable * After the exit is finalized, the validator becomes withdrawable at a specific epoch (withdrawable\_epoch). 3. Withdrawable ā†’ Paid * The consensus layer includes your validator in the withdrawal queue. * The execution layer credits your withdrawal address in the block/slot where your withdrawal is processed. * Credits appear as ā€œWithdrawalsā€ in the block, not as normal transactions. ## Credential requirements (critical) * 0x01 or 0x02 withdrawal credentials (to an execution address) are required for both partial and full withdrawals to be paid. * If you still have 0x00 (BLS) credentials, you must perform a credential update to 0x01 first. Until then, the protocol cannot pay out to your execution address. ## Partial vs full withdrawals * Partial withdrawals * Trigger: Your validatorā€™s actual balance exceeds its effective balance. * Amount: Only the excess above effective balance is skimmed to your withdrawal address. * Timing: Processed automatically and continuously by the protocol when eligible; batched at a limited rate per slot. * Full withdrawals * Trigger: Your validator is exited, and has reached its withdrawable epoch. * Amount: Your entire effective balance is paid to your withdrawal address in a withdrawal entry when processed; if a block hits its withdrawal limit, your entry is included in a later block. * Timing: Subject to the same per-slot processing limits; can take up to several days. ## How long will my payout take after exit? Timing depends on: * Exit churn: How many validators are exiting around the same time (there is a limit per epoch). * Withdrawal throughput: The protocol processes only a limited number of withdrawals each slot. * Your place in the queue. ## FAQ * I exited but donā€™t see my ETH yet. Whatā€™s happening? * Check your validator page: are you withdrawable yet? If yes, the payout is waiting for its turn in the withdrawal queue. * Will partial withdrawals continue after I exit? * After you exit and become withdrawable, your full withdrawal is paid. Partial withdrawals are a mechanism for active validators; once fully withdrawn, the validator no longer receives partial skims. * Do withdrawals cost gas or require me to send a transaction? * No. Withdrawals are protocol-driven credits included in blocks as part of the consensus process. * I still have 0x00 credentialsā€”can I get paid? * Not until you update to 0x01 credentials. Perform the credential change first; then partial/full withdrawals can be processed to your execution address. ## Troubleshooting * My validator shows ā€œexitedā€ but not ā€œwithdrawableā€ * Wait for finality and the withdrawable epoch. Large exit waves can add delay due to churn limits. * beaconcha.in shows a withdrawal to my address, but my wallet balance looks unchanged * Some wallets cache balancesā€”refresh and wait a few confirmations. Confirm the credit in the addressā€™s Withdrawals tab and on the slot page. ## Related resources * [Why validator withdrawals donā€™t show up as wallet transactions](./validator-withdrawals-execution-layer.md) * [beaconcha.in explorer](https://beaconcha.in/) Tip: Keep your withdrawal address secure. Anyone with control of that address controls the withdrawn ETH. # Optimal Inclusion Distance Source: https://docs.beaconcha.in/faqs/optimal-inclusion-distance Explains why inclusion distance can appear as 0 despite later block inclusion. The attestation for `slot 156508` was included in `slot 156510` but why is the inclusion distance 0?\ If were to use the formula from above and set the inclusion delay to 0, the rewards would be 0 for a proposed attestation Missed blocks are **not added** to the inclusion distance, but since the attestant is not responsible for the block proposal, and to only warn the user about its faults (e.g. slow internet connection, power failure etc.), the [beaconcha.in explorer](https://beaconcha.in/) displays the distance as 0 # System deposits and withdrawals Source: https://docs.beaconcha.in/faqs/system-deposits-and-withdrawals You may see deposits and withdrawals on your validator that you never initiated. These are protocol-generated balance movements. This page explains what they are, how the protocol creates them, how to recognize them, and why they don't affect your rewards or your net balance. ## TL;DR * After the **Pectra (Electra)** upgrade, the protocol can move a validator's balance **internally**. These movements are recorded as deposits and withdrawals even though **you never initiated them** and **no ETH left or entered your wallet**. * They usually occur in a **pair**: the protocol removes the balance above 32 ETH from your validator (shown as a **withdrawal**) and re-queues that same amount as a **deposit** back into the same validator. * They are **net-zero** for you and **do not affect your rewards or APR**. Don't treat them as real payouts or income (for example, for tax accounting). * You'll see them in **two situations**: a **one-time bulk batch at the Pectra fork**, and then **individually** afterwards whenever a validator **switches to compounding**. * How to spot them: * Both system **deposits** and **withdrawals** are flagged with **`type: system`** in the API. * System **withdrawals** also have an **empty recipient** (the explorer shows `SYSTEM`); system **deposits** also carry a **placeholder signature** instead of a real one. ## Why these appear Pectra introduced compounding (`0x02`) withdrawal credentials and a deposit queue ([EIP-7251](https://eips.ethereum.org/EIPS/eip-7251)). The core operation is the consensus-spec `queue_excess_active_balance` function: for a validator whose balance is above 32 ETH (`MIN_ACTIVATION_BALANCE`), the protocol resets the active balance to 32 ETH and appends a pending deposit for the excess. beaconcha.in shows **both halves** of this internal move ā€” the balance leaving as a **withdrawal**, and the re-queued amount as a **deposit** ā€” even though no execution-layer transaction happened and no funds left your control. The amount is added back afterwards: it is an internal re-deposit of your own balance. This happens in **two situations** ā€” one historical, one ongoing: ### 1. The one-time Pectra activation ā€” `upgrade_to_electra` At the transition into Pectra (epoch 364032), the consensus-layer [`upgrade_to_electra`](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/fork.md) routine applied this across the **entire validator set in a single state transition**, producing two kinds of protocol-generated entries: * **Excess re-queue for early compounding adopters.** Every validator that already carried `0x02` credentials at the fork had its balance above 32 ETH re-queued via `queue_excess_active_balance` ā€” a **system withdrawal** (the balance leaving) paired with a **system deposit** (the same amount queued back). * **Activation-queue migration.** Pectra replaced the old eth1 activation queue with the deposit queue, so every validator still waiting to activate (`activation_epoch == FAR_FUTURE_EPOCH`) had its staked balance moved into the new queue ā€” recorded as a **system deposit** for its full balance. Because it all happened at once, this shows up as a **large one-time batch** dated to the activation slot, [slot 11649023](https://beaconcha.in/slot/11649023#withdrawals), whose Withdrawals tab is dominated by system withdrawals. It is historical and **does not repeat**. ### 2. When a validator switches to compounding ā€” `switch_to_compounding_validator` Going forward, the **same excess re-queue happens individually** whenever a validator switches to compounding, by submitting an execution-layer consolidation request to itself. `switch_to_compounding_validator` changes the credentials to `0x02` and then calls `queue_excess_active_balance`, so any balance above 32 ETH is moved into the deposit queue: again a **system withdrawal** paired with a **system deposit** for that validator. ## Identifying them in the API In the API, system deposits and withdrawals are both flagged with **`type: system`** ā€” the category for entries the protocol generates automatically, rather than ones a user initiated. Beyond that flag, deposits and withdrawals each carry an additional distinguishing field. **Deposits** * `type: system` ā€” as opposed to `deposit` (a new validator) or `top_up` (funds added to an existing one). * The `signature` is a **placeholder**: the "point at infinity" value, `0xc0` followed by all zero bytes, never a real 96-byte BLS signature. The protocol uses this because it generated the deposit itself. **Withdrawals** * `type: system` ā€” as opposed to `manual`, `partial_sweep`, or `full_exit_sweep` for real withdrawals. * The `recipient` field is **empty** ā€” there is no execution-layer payout address, because this is the internal balance reduction that pairs with a system deposit. The consensus spec sets these markers deliberately; from `queue_excess_active_balance`: > Use `bls.G2_POINT_AT_INFINITY` as a signature field placeholder and `GENESIS_SLOT` to distinguish from a pending deposit request. ## Not the same as a partial withdrawal or a consolidation A normal **partial withdrawal** skims the balance above your validator's *maximum effective balance* ā€” 32 ETH for `0x01`, or **2048 ETH** for `0x02` compounding validators ā€” and pays it **to your withdrawal address** (a real recipient). See [How withdrawals work](/faqs/how-withdrawals-work). A **system** deposit/withdrawal is different: it's the protocol moving balance above **32 ETH** into the deposit queue for compounding validators ā€” in bulk at the Pectra fork, and individually as validators switch to compounding. It stays inside your validator and has no execution-layer recipient. A **consolidation** (moving one validator's balance into another) is tracked separately ā€” as a *consolidation*, not as a deposit or withdrawal. The protocol transfers the source's balance to the target directly, and the source validator exits with any remaining balance paid out by a **normal sweep to its withdrawal address**. So an ordinary consolidation produces **neither** a system deposit **nor** a system withdrawal. ## What this means for you * **Net balance:** unchanged. The balance stays inside your validator ā€” a withdrawal and its matching deposit cancel out. * **Rewards / APR:** unaffected. These movements are excluded from reward calculations. * **Accounting / tax:** these are **not** real withdrawals or deposits of your funds ā€” they are the protocol re-depositing your own balance ā€” so they should not be counted as income or payouts. * **On-chain vs. explorer counts:** because a system withdrawal isn't an execution-layer withdrawal object, a block's on-chain withdrawal count can be lower than the number of withdrawal entries beaconcha.in shows for that slot. This is most visible at the Pectra activation slot, but applies to any slot containing a system withdrawal. ## Where to see them on beaconcha.in * **Validator page ā†’ Deposits / Withdrawals tabs** ā€” system entries appear alongside your normal ones; a system withdrawal shows `SYSTEM` as its recipient. * **Slot page** ā€” any slot that processed system entries lists them. The Pectra activation slot, [slot 11649023](https://beaconcha.in/slot/11649023#withdrawals), shows the large one-time batch; individual system deposits and withdrawals also appear on ordinary slots as validators switch to compounding. ## References * [EIP-7251: Increase the MAX\_EFFECTIVE\_BALANCE](https://eips.ethereum.org/EIPS/eip-7251) * [Electra consensus specs ā€” beacon chain](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/beacon-chain.md) (`queue_excess_active_balance`, `switch_to_compounding_validator`, `apply_pending_deposit`) * [Electra consensus specs ā€” fork](https://github.com/ethereum/consensus-specs/blob/master/specs/electra/fork.md) (`upgrade_to_electra`) # Understanding Ethereum's Validator Queues Source: https://docs.beaconcha.in/faqs/understanding-validator-queues Learn how Ethereum manages validator entry, exit, and withdrawal queues # Understanding Ethereum's Validator Queues Validator Queue Diagram View real-time queue data and statistics on [beaconcha.in Validator Queues](https://beaconcha.in/validators/queues) Ethereum uses several distinct queues to manage the flow of validators and funds in and out of the staking system. Here's how they work: ## Entry Queue & Deposit Requirements To create a validator, you need a minimum deposit of 1 ETH, and you can use any 0x credential type. However, your validator won't activate until it reaches 32 ETH. Once you deposit, you join the Entry Queue, which processes up to 256 ETH per epoch ([validator churn limit](https://github.com/ethereum/consensus-specs/blob/69d34dc4ee3d026ca437d1b6875b218e8aaf3a5c/specs/phase0/beacon-chain.md#get_validator_churn_limit)). During high demand periods, new validators may wait days or weeks before activating. After clearing the queue, activation itself takes about 4-5 epochs. The entry queue processing rate was capped by [EIP-7514](https://eips.ethereum.org/EIPS/eip-7514) to limit the growth of the validator set during periods of high demand. You can also top up an existing validator's balance at any time (subject to entry queue limits). When topped up, if the [effective balance](https://eth2book.info/latest/part2/incentives/balances/#hysteresis) is N, it becomes N+1 once the actual balance reaches N+1.25 ETH. ## Exit Queue Validators wanting to leave the network enter a shared Exit Queue, also capped at 256 ETH per epoch ([validator churn limit](https://github.com/ethereum/consensus-specs/blob/69d34dc4ee3d026ca437d1b6875b218e8aaf3a5c/specs/phase0/beacon-chain.md#get_validator_churn_limit)). This queue handles: * CL voluntary exits (free to initiate) * EL full exit requests (requires tx fee, 0x01/0x02 credentials only) * EL partial withdrawal requests (0x02 only) All exit types share this same queue capacity, so heavy exit demand affects everyone. Validators must have been active for at least 27 hours before requesting an exit. ## Consolidation Queue There's a separate queue for consolidations (merging one validator's balance into another). This also processes 256 ETH per epoch but importantly does not compete with the exit queue. After about 256 epochs (\~27 hours), the source validator's balance merges into the target validator, which remains active. ## Withdrawal Sweep After exiting, funds don't arrive instantly. There's a waiting period of approximately 256 epochs (\~27 hours) before becoming withdrawable. The protocol then performs a withdrawal sweep processing up to 16 validators per block for full withdrawals. The time to receive your funds depends on the total number of active 0x01 validators in the system, as the sweep must cycle through all of them. Partial withdrawals for 0x02 credentials skip the sweep and process up to 8 per block. ## Automatic Withdrawals The protocol handles excess balance withdrawals differently depending on your credential type: * **0x01 credentials**: Excess balance above 32 ETH is swept automatically without any action required * **0x02 credentials**: Automatic withdrawals only trigger for excess above 2048 ETH. For smaller amounts, you must submit a manual EL partial withdrawal request ## Slashed Validators Validators that misbehave get slashed and automatically ejected from the network. Slashed validators bypass the normal voluntary exit process. They're forcibly removed and enter the exit queue automatically, eventually reaching the exited validator state with penalties applied to their balance. ## Withdrawal Credential Considerations Your credential type determines when you receive funds: * **0x00 credentials**: Funds remain stuck on the consensus layer until you upgrade to 0x01 or 0x02 * **0x01/0x02 credentials**: Funds arrive at your designated withdrawal address after the sweep processes your validator # Why validator withdrawals donā€™t show up as wallet transactions Source: https://docs.beaconcha.in/faqs/validator-withdrawals-execution-layer Understand why withdrawals appear as balance credits on the EL and how to verify them. When your validator withdraws ETH, you usually wonā€™t see an incoming transaction in your wallet. Instead, your balance on the execution layer increases silently. This behavior is expected and by design. This page explains why, what kinds of withdrawals exist, and how you can verify them on beaconcha.in. ## Key takeaways * Withdrawals are system-level balance credits on the execution layer (EL), not user-initiated transfers. * They donā€™t originate from an externally owned account (EOA), so most wallets donā€™t display a ā€œreceived transaction.ā€ * Partial withdrawals (excess above 32 ETH) credit automatically to your withdrawal address once eligible. * Full withdrawals (validator exited) credit the entire effective balance to your withdrawal address. * You can verify credits on beaconcha.in via the Withdrawals tab on the address page and on the slot/block page. ## How withdrawals flow: consensus vs. execution layers Ethereum staking operates across two layers: * Consensus layer (CL): Manages validators, attestations, and withdrawal eligibility. The CL determines when a validator can withdraw and includes withdrawal instructions in the payload. * Execution layer (EL): Manages ETH balances, transactions, and smart contracts. The EL applies the withdrawal list by directly increasing the specified withdrawal address balance. During block processing, the CL passes a list of withdrawals to the EL. The EL applies these as balance changes, not as regular EOA-to-EOA transactions. Result: Your wallet balance at the withdrawal address increases, but there is no sender account or ā€œtransactionā€ to show in the walletā€™s history. ## Types of withdrawals * Partial withdrawals * What it is: Automatic skimming of any ETH above 32 ETH effective balance from an active validator. * When it happens: Periodically, once the validator has a valid withdrawal credential set to an Ethereum address (0x01 prefix) and becomes eligible in the withdrawal queue. * What you will see: Balance at the withdrawal address increases by the skimmed amount. No incoming transaction appears in most wallets. * Full withdrawals * What it is: Payout of the validatorā€™s entire effective balance after a successful voluntary exit (or forced exit) and eligibility in the withdrawal queue. * When it happens: After exit finalization and once the validator is processed by the withdrawal queue. * What you will see: A one-time balance increase at the withdrawal address, again typically without an inbound transaction entry. ## Why your wallet doesnā€™t show an inbound transaction Most wallet UIs list transfers initiated by accounts (EOAs) or contractsā€”events they can attribute to a sender and a transaction hash. Withdrawals are neither: * They are protocol-applied balance updates recorded in the blockā€™s withdrawals list. * There is no sender address, no ERC-20 Transfer event, and often no typical EOA transaction hash tied to the credit. * On beaconcha.in, withdrawals are visible in the Withdrawals tab on the execution address page and on the slot/block page, separate from normal transactions. Because the wallet canā€™t attribute a familiar transfer, it simply reflects the new balance without an itemized incoming tx. ## Prerequisites Before expecting withdrawals to appear: * Your validator must use 0x01 withdrawal credentials that point to your intended execution address. * Your validator must be eligible in the withdrawal queue (partial: above 32 ETH; full: exited and finalized). * You must wait for the network to process withdrawals, which occurs continuously but is rate-limited per block. ## How to verify your withdrawal Use beaconcha.in to confirm credits and timing. 1. Open your withdrawal execution address on beaconcha.in and select the Withdrawals tab. * You will see all credits to this address and the slot they were included in. * Example address page: [https://beaconcha.in/address/0xb720fbd903ffcd40e63def20f3321a483bf00bb2#withdrawals](https://beaconcha.in/address/0xb720fbd903ffcd40e63def20f3321a483bf00bb2#withdrawals) 2. From any withdrawal row, open the linked slot and select the Withdrawals tab to view all withdrawals included in that slot/block. * Example slot page: [https://beaconcha.in/slot/12800471#withdrawals](https://beaconcha.in/slot/12800471#withdrawals) 3. Optionally, open your validator page on beaconcha.in and review its Withdrawals section to see which slots credited your withdrawal address. 4. Compare your wallet balance around that slot; expect a net increase without a normal inbound transaction entry. Expected outcome: You can identify the block that included your withdrawal and confirm the credited amount to your withdrawal address, even though no inbound transaction appears in your wallet history. ## Common questions * Can I make withdrawals show as transactions in my wallet? * No. These are protocol-level balance credits. On beaconcha.in, they appear under the Withdrawals tab, but your wallet will typically not show a normal incoming transaction. * Why havenā€™t I received my partial withdrawal yet? * Ensure you have 0x01 withdrawal credentials set to an execution address. If you still have 0x00 (BLS) credentials, you must perform a credential update first. Then wait for the queue to process. * Where can I see the exact credit? * On beaconcha.in: Address page ā†’ Withdrawals tab, and Slot/Block page ā†’ Withdrawals tab. Your address balance will reflect the credit once the slot is processed. * Do withdrawals cost gas? * No. They are system-applied and do not require you to submit a transaction or pay gas. ## Troubleshooting * Balance didnā€™t change but beaconcha.in shows a withdrawal * Re-check the specific block and confirm you are looking at the correct withdrawal address. * Wait for a few confirmations and refresh your wallet; some UIs cache balances. * Verify that your wallet shows the updated native balance for the address; if not, confirm the credit on the beaconcha.in address page (Withdrawals tab) and allow time for your wallet to refresh cached data. * Still have 0x00 credentials * You must update to 0x01 credentials to enable partial withdrawals. Follow official steps to generate and broadcast the credential update message. After confirmation on CL, partial withdrawals can start when eligible. * Expecting full withdrawal but not credited yet * Confirm the validator is fully exited and finalized. Then wait for the withdrawal queue to process your index. Timing depends on network throughput and queue length. ## Related resources * [How Ethereum validator withdrawals work](./how-withdrawals-work) * [beaconcha.in explorer](https://beaconcha.in/) (validator view and block view) Tip: Keep your withdrawal address secure. Anyone with control of that address controls the withdrawn ETH. # API Terms and Conditions of License and Use Source: https://docs.beaconcha.in/legal/api-terms bitfly explorer gmbh, Wiedner GĆ¼rtel 9, 1100 Vienna Last updated: 22.09.2026 ## Introduction (A) The provider operates an application programming interface ("API service") which registered customers are able to access via the website. The API service is provided for the purposes set out in these Terms and Conditions of License and Use. (B) By accessing the API service described below in this document, the customer declares with binding effect that it accepts and will comply with both the [General Terms and Conditions](/legal/terms) and these API Terms and Conditions of License and Use. (C) The latest version of these Terms and Conditions of License and Use is available on the website [https://beaconcha.in/](https://beaconcha.in/). (D) The API service is intended exclusively for business customers as defined by the Austrian Business Code (UGB). Consumers are excluded from entering into contracts. The customer warrants that it is not a consumer within the meaning of the Austrian Consumer Protection Act (KSchG) and that this is therefore a business transaction for both parties. ## 1. Registration (1) The customer must have an account in accordance with section 1 of the General Terms and Conditions in order to access and use the provider's API service. (2) The customer shall provide accurate and complete registration and company information and shall promptly update such information for the entire duration of the contractual relationship. (3) A valid API key is required to use the API service. The customer can access API keys via the user area on the website [https://beaconcha.in/](https://beaconcha.in/). The API key must be stated in the request header with each request in accordance with the provider's technical API documentation. (4) The customer is under an obligation to protect the API key from unauthorised access by third parties and to use it exclusively within the scope of the agreed use. ## 2. API service (1) The provider currently operates multiple API services: **beaconcha.in v1-API** as well as **beaconcha.in v2-API**. (2) The customer can order the API service via the website [https://beaconcha.in/pricing](https://beaconcha.in/pricing) based on the service packages and prices offered there. The service packages include in each case access to the v1-API as well as the v2-API. (3) The content and scope of the API service are set out in the service specifications for the respective service packages. (4) The provider may offer a free tier for the API service. Unless otherwise stated in the pricing information, any free tier is granted exclusively as a one-time trial per customer (sole proprietor or legal entity) regardless of the number of employees or representatives for a period of up to 30 consecutive days starting with the first activation of the relevant API key. (5) The customer shall not attempt to obtain multiple free trials or otherwise circumvent the limitations of the free trial. The use of multiple accounts or identities per customer for the purpose of obtaining additional free trials is prohibited. (6) For the purpose of enforcing this restriction, the provider may determine whether multiple registrations relate to the same customer on the basis of objective indicators, including but not limited to email domain, billing details, legal entity identifiers, affiliated entities, responsible contact persons, technical usage patterns and other reasonably available evidence. (7) The provider may refuse, suspend, or revoke free-tier access, API keys or the associated account at any time if it reasonably suspects that the customer attempts to obtain multiple free trials or otherwise circumvents the limitations set out in sections 2 (5) and 2 (6). (8) The provider reserves the right to adjust the scope of the service packages on offer to technological developments, new functions or changes in market conditions at any time. Existing service packages will be assigned to the new service packages that have the corresponding functions. The provider shall be entitled to adjust prices if the cost factors relevant for the provision of services change (in particular staff, infrastructure, energy or license costs). Price adjustments will be communicated to the customer at least 30 days before these come into effect. The customer will be entitled to terminate the contractual relationship extraordinarily until the increase comes into effect (special right of termination). If the customer does not terminate the contract, the new prices and service content will be deemed to have been agreed. (9) The customer may only access the API within the scope of the usage limits and functions provided in the service package. The provider's record of the API access performed under the respective customer account will be deemed binding unless there is an obvious and demonstrable error in recording this by the provider. (10) Once the usage limit recorded in the service package has been reached or the functional restrictions specified are exhausted, use of the API service will be suspended automatically. The customer may purchase an expanded service package (upgrade) at any time for additional API queries. ## 3. API documentation (1) The provider will provide the API service specified in the latest applicable API documentation to the customer exclusively for the functionalities specified there, whereby the provider shall be entitled to change and/or adapt the API service at any time. (2) Amendments to the API documentation will be announced on the provider's website [https://docs.beaconcha.in/api/overview](https://docs.beaconcha.in/api/overview) and will be considered to be binding from that point onwards. The customer is under an obligation to read the latest applicable version of the published API documentation carefully and apply the same. (3) The provider assumes no responsibility for ensuring that the API documentation provided is compatible with the hardware and software used by the customer. ## 4. API license (1) Subject to the provider's property and exploitation rights to intellectual property in accordance with section 10 of the General Terms and Conditions, the provider grants the customer a non-exclusive, non-transferable, non-sublicensable right that may be revoked at any time to use the API data and/or content provided via the respective API service using an assigned API key. (2) The customer may use the API Data and/or content solely for the following internal business purposes: internal archival, compliance, audit, and historical analysis. The customer may retain API Data already lawfully received and store internal copies of such data after receipt for the purposes mentioned. Any use of API Data or retained data for customer-facing, third-party-facing, or publicly accessible products, services, or outputs is strictly prohibited unless expressly permitted under a separate written license agreement with the provider. (3) It is prohibited for any customer, whether a sole proprietor or a legal entity, to create, maintain, or operate multiple accounts, directly or indirectly (including via affiliates, subsidiaries, employees, contractors, or other related persons), for the purpose of circumventing rate limits, quotas, pricing tiers, or any other usage restrictions instead of upgrading to a higher service package. (4) Any transfer, distribution, publication, sub-licensing, commercial exploitation or other use outside of the purpose of use agreed in accordance with section 4 (2) is prohibited. The customer is prohibited in particular from, * feeding the API data or parts thereof into third-party databases or setting up an independent database for third-party-facing, customer-facing or public use; * making the API Data, or any output derived from or combined with it, available to any third party, whether free of charge or for payment, including where the API Data is merged or processed together with other data and only the resulting output is shared; * operating any third-party accessible dashboard, feed, report, score, interface, analytics, aggregation, transformation, or other output based on API Data, unless expressly permitted in an enterprise subscription and separate written license agreement with the provider; * removing or modifying references to the origin, copyright or trademark notices. (5) In the event of a breach of this provision, the provider shall be entitled to block access to the API service at any time with immediate effect and without prior notice. (6) If the customer wishes to use the API data and/or content over and above the usage purpose agreed contractually in accordance with section 4 (2) (in particular integration into external systems, commercial exploitation or use in relation to third parties), a separate written Enterprise agreement must be entered into with the provider beforehand. Any extended use shall be expressly prohibited until such an agreement has been entered into. Upon request, the provider may submit a corresponding offer to the customer for the extended scope of use. (7) If the customer is granted a license for transfer or for commercial exploitation of the API data and/or content by means of a separate written agreement in accordance with section 4 (6), then with every use, presentation or transfer of the API data it will be under an obligation to affix a clearly visible designation with the notice **"Powered by beaconcha.in"** and the logo provided by the provider in accordance with the branding guidelines. The provider shall be entitled to review compliance with these labelling requirements at any time. The provider may require the customer, under a separate written agreement, to ensure that its customers and other recipients of the API Data or any derived outputs are subject to equivalent contractual obligations and restrictions. (8) Any use of the API content that exceeds the license and usage rights expressly granted herein is prohibited. (9) The customer will retain its property rights to the data content that it makes available to the provider for use in connection with providing the API service. The customer will grant the provider in this regard a non-exclusive, non-transferable right to use the data content made available by the customer exclusively for the customer's benefit for fulfilment of the provider's obligations under these Terms and Conditions of License and Use. ## 5. Unauthorised use (1) The customer makes the following undertakings in connection with the use of the API service: * not to use the API service in any way that violates applicable law, including but not limited to the intellectual property rights, unfair competition rights and personal rights of third parties; * not to use the API service for unlawful, abusive or fraudulent purposes; * to present its own identity truthfully and not to conceal the same; * not to transfer the API keys to third parties or make them available to the public; * to keep its access data and API keys secret; * not to reproduce, replicate, modify or redesign API content, transfer it to third parties, make it available to the public or create derivative works from it, including by way of transformed, aggregated or otherwise derived outputs made accessible to third parties; not to use API content to operate competing or proxy API services; * to refrain from having reverse engineering operations implemented, scraping data or attempting to circumvent rate limitations or authentication systems, free trial restrictions or any other technical or contractual usage controls imposed by the provider; * not to implement any measures that could adversely affect the API service or infrastructure of Bitfly or other users. (2) The customer will be under an obligation to notify the provider without delay of any suspicion that its access data, API keys and/or other confidential information in connection with the use of the API service could have become known to unauthorised third parties. (3) The provider shall be entitled to block access to the API service in the event of a breach of these Terms and Conditions of License and Use by the customer or third parties attributable to it. The access will only then be restored once the breach has been permanently remedied or the risk of recurrence has been eliminated through submission of a corresponding declaration to cease and desist. ## 6. Payment terms (1) Use of the API service is subscription-based. The prices applicable in each case for the service packages are available on the provider's website at [https://beaconcha.in/pricing](https://beaconcha.in/pricing). All prices are quoted in euros, plus statutory VAT, unless otherwise stated. (2) The provider uses the external payment service provider "Stripe" (Stripe, Inc., 354 Oyster Point Blvd, South San Francisco, CA 94080, USA) for billing of subscriptions. By using the services, the customer agrees that payment details will be processed in accordance with Stripe's terms and conditions of use and privacy policy. The payment details entered will be processed directly by Stripe and not be stored by the provider. (3) Payments can only be made by credit card or via another payment method supported by Stripe. The provider will not be liable for failures or errors in the payment processing by Stripe unless these are attributable to gross negligence or wilful intent on the part of the provider. (4) Customers may change their requested service package at any time within their account: * Upgrade: the difference is calculated immediately and the new plan will apply from the time of the change. * Downgrade: a downgrade in the subscription will take effect from the start of the next billing period. If there is a credit balance remaining in the assigned Stripe account following the downgrade, this balance will automatically be offset against future charges until it has been consumed in its entirety. Any payments already made will not be reimbursed. (5) The subscription will start as of the date that the customer selects the requested service package and billing period, and will renew automatically until it is cancelled. The subscription fee will be debited automatically from the credit card stored in the customer's Stripe account in each case on the payment date shown in the customer's Stripe account. (6) In the event that the contractual relationship is terminated by the customer (see section 9), there will be no pro rata refund of amounts already paid for the relevant service period. (7) Post-Licensing: The provider shall be entitled to verify whether the provided data is being used in accordance with these API Terms and Conditions of License and Use. If the customer uses the provided data, contrary to Section 4(2), for commercial purposes without a valid Enterprise Agreement ("External Use"), in particular for public display, commercial use or redistribution, the provider shall be entitled to charge post-licensing fees for such use in accordance with this Section. (8) The post-licensing fee shall correspond to the Enterprise fee applicable to the relevant type and scope of External Use during the relevant period of use. The relevant categories of commercial use are Public Display, Commercial Use and Redistribution. The applicable fee shall be no less than EUR 1,000 and no more than EUR 10,000 per month. The specific amount of the post-licensing fee shall be determined by the provider, acting reasonably and at its equitable discretion, based on the nature and scope of the customer's External Use. (9) Notice Procedure: If the provider determines, on the basis of justified and objective indications, that unauthorized External Use has occurred, the provider shall notify the customer in writing at the email address stored in the customer's account, stating the applicable post-licensing fee and any contractual penalty that may be charged. Within 30 days of receipt of the notice, the customer shall: * (a) provide reasonable and verifiable evidence demonstrating that the use concerned does not violate these API Terms and Conditions of License and Use; * (b) cease the External Use; or * (c) enter into an Enterprise Agreement with the provider corresponding to the customer's actual use. (10) If the customer fails to respond within the 30-day period and continues the External Use after expiry of that period, the provider shall be entitled to charge the post-licensing fee pursuant to Section 6.8 and the contractual penalty pursuant to Section 6.14 and to collect the amounts invoiced using the payment method stored in the customer's Stripe account. (11) The customer authorizes the provider to collect the determined post-licensing amount and any contractual penalty using the payment method stored in the customer's Stripe payment profile. Such collection shall take place no earlier than two business days after expiry of the 30-day period. (12) If the customer demonstrably ceases the External Use within the 30-day period, the provider shall be entitled to charge the post-licensing fee up to and including the date on which the External Use ceased. In such case, the one-off contractual penalty pursuant to Section 6.14 shall not apply. (13) Continuing Effect: Following completion of the notice procedure, the applicable post-licensing fee shall automatically accrue for each additional billing month during which the customer continues the unauthorized External Use. No further notice or request by the provider shall be required. Further charges shall cease upon the earliest of the following: * (a) cessation of the External Use; * (b) evidence that the relevant use complies with the Agreement; or * (c) conclusion of an Enterprise Agreement permitting the relevant use. (14) If the customer continues the unauthorized External Use after expiry of the 30-day period provided for in Section 6.9 and has neither provided a substantively adequate response, demonstrated that the use has ceased, nor entered into a corresponding Enterprise Agreement, the provider shall be entitled to charge a one-off contractual penalty in the amount of EUR 1,000.00 net. (15) If the customer demonstrates, by means of reasonable and objectively verifiable evidence, that the use concerned was fully compliant with the Agreement during the relevant period, the provider shall immediately discontinue all measures taken in connection with the relevant compliance case and shall refund in full the post-licensing fees charged and any contractual penalty. The contractual penalty shall also be refunded if the customer demonstrates that it had ceased the External Use before expiry of the 30-day period provided for in Section 6.9. (16) The provider shall be entitled to suspend the customer's access to the API Service if the customer continues the unauthorized External Use after expiry of the period provided for in Section 6.9, fails to enter into a corresponding Enterprise Agreement or fails to pay any amount due under this section. (17) The provider's right to terminate ordinarily or for cause, as well as its right to assert claims for injunctive relief, damages, restitution, unjust enrichment and any other statutory or contractual remedies, shall remain unaffected. ## 7. Exclusion of liability (1) The provider does not warrant that the API service will be fully functional at all times and without interruptions. The provider therefore does not provide any warranties, guarantees and/or assurances of success of any kind whatsoever with regard to the API service, particularly with respect to the particular suitability of the API service and/or the API content for a specific purpose; the API content is provided to the customer "as is" without any express or implied warranty. The provider is in particular under no obligation to review the results (API data and/or content) from the use of the API service for legality, accuracy or completeness. (2) Furthermore, the provider assumes no responsibility for circumstances that are within the customer's sphere of influence, particularly with respect to its hardware, software or internet connection. (3) In the event of a separate agreement regarding the availability of the API service (Service Level Agreement, "SLA"), the service levels guaranteed there with respect to guaranteed availability and response times will apply. If no such agreement is in place, the provider will assume no warranty for uninterrupted availability of the API service. Where a Service Level Agreement applies, any service credits granted thereunder shall, unless expressly stated otherwise, be the customer's sole and exclusive remedy for failure to meet the agreed service levels. ## 8. Compensation and limitation of liability (1) Use of the API is at the customer's own responsibility and at its own risk. The customer will be responsible exclusively for any damage resulting from the use of the API service, including any damage to the customer's own IT system or loss of data. (2) The provider will be liable in accordance with the statutory provisions exclusively for damage caused intentionally or through gross negligence by the provider and its vicarious agents. The provider's liability is excluded for damage that is not typical for this type of contract, for consequential damage, in particular lost profits and lost savings, and for pure financial losses, except in cases involving wilful intent on the part of the provider. The customer's claims will expire within six months of becoming aware of the damage and of the party at fault. ## 9. Duration of the API service (1) The customer shall be entitled to cancel the subscription directly at any time via the Stripe customer portal. In this case, the subscription will end automatically at the end of the current billing period. Any payments already made for the current billing period will not be reimbursed. (2) If the customer downgrades to a cheaper tariff during a current billing period, a pro-rata credit note for the amount already paid will be issued to the assigned Stripe account (see section 6 (4)). (3) The provider will be entitled to suspend or block access to the API service for cause, particularly if the customer * has provided false customer details or access to the API service has been obtained by other fraudulent means; * has disclosed the access details to unauthorised persons and/or the API service is used in breach of the agreement; * fails to comply with any other essential provision in these Terms and Conditions of License and Use for the purposes of section 5 and fails to comply with these despite being requested to remedy the breach of contract or defaulting situation within a grace period of seven calendar days; (4) The contracting parties will be entitled to terminate the API service immediately if the API service is unavailable for more than 90 days due to force majeure. Any amounts already paid for services not rendered will not be reimbursed unless otherwise agreed. (5) Upon termination or expiry of the API Service, all rights granted to the customer to access, call, refresh, update, redistribute, use or otherwise exploit the API Data, whether under these API Terms and Conditions of License and Use or any separate Enterprise Agreement, shall immediately terminate, except to the extent that the relevant Enterprise Agreement expressly provides for such rights to survive termination or expiry. Historical API Data lawfully received by the customer before termination or expiry may be retained and used solely for internal archival, compliance, audit and historical analysis purposes, unless broader retention rights or post-termination use are expressly permitted under a separate written agreement. ## 10. General provisions (1) These API Terms and Conditions of License and Use shall take precedence over the provider's General Terms and Conditions. Unless specified otherwise in these API Terms and Conditions of License and Use, the provider's General Terms and Conditions shall apply. (2) We may update, change or replace these Terms at any time. We will notify you via email if we update, change or replace these Terms. You have a period of 14 days after notice has been provided to you to object to any update, change or replacement. If you do not object within this period, you shall be deemed having agreed to the update, change or replacement. We will remind you in our notice email that continuing to use our services after the objection period shall be deemed as expressing consent. ## Document History Previous version effective until September 22, 2026 # BeaconScoreĀ® License Terms Source: https://docs.beaconcha.in/legal/beaconscore-license bitfly explorer gmbh, Wiedner GĆ¼rtel 9, 1100 Vienna Last updated: 22.09.2026 ## Introduction (1) The licensor, bitfly explorer gmbh, with registered company number FN 623067a, Wiedner GĆ¼rtel 9, 1100 Vienna, is the owner of all copyrights to the subject matter of protection "BeaconScoreĀ®" (referred to in the following as the "work"). Trademark rights in "BeaconScoreĀ®" are addressed separately in Section 6. (2) "BeaconScoreĀ®" is a metric developed by the licensor to measure the efficiency of blockchain validators. The licensor places the work under the licensing terms of the **Creative Commons Attribution ā€“ Non-Commercial ā€“ ShareAlike 4.0 International License ([CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/))**, which is intended to enable worldwide and free use of "BeaconScoreĀ®". These License Terms explain the content of this license. ## 1. Granting of the license (1) The licensor grants the licensees a worldwide, free-of-charge, non-sublicensable, non-exclusive and irrevocable right to use the work in accordance with the Creative Commons License [CC BY-NC-SA 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/). (2) The license [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) grants the licensee the right to reproduce and redistribute the work in whole or in part in any format or medium exclusively for non-commercial purposes, with the work expressly attributed to the licensor. The licensee may also remix, modify and build upon the work ("derivative work") under the conditions specified in section 2 (3). ## 2. Terms of use (1) **Attribution (BY):** The licensee shall be under an obligation to name the licensor as the creator by means of a clearly visible designation with the trademark **"BeaconScoreĀ®"** each time that the work is used. The information must also include a reference to the license used ([CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)) and a link or URL to the licensor's BeaconScoreĀ® documentation [https://docs.beaconcha.in/beaconscore/introduction](https://docs.beaconcha.in/beaconscore/introduction). The attribution applies to both the use of the original work and derivative works. (2) To comply with the requirements of section 2 (1) the licensee is required to follow the guidelines provided in this link [https://docs.beaconcha.in/legal/license-materials](https://docs.beaconcha.in/legal/license-materials). (3) **Non-commercial (NC):** The work or derivative work may only be used for non-commercial purposes. Non-commercial purposes include e.g.: * free-of-charge distribution in blockchain communities * use for internal presentations, analyses, training courses, workshops or for research purposes (e.g. citations in scientific articles, statistics, etc.) * use for non-commercial public relations activities (e.g. information brochures, awareness campaigns, publication on non-commercial websites) * use in white papers, blogs or YouTube videos with no revenue (4) Any use of the work within the scope of services provided in return for payment or for generating a profit is excluded. This includes e.g.: * transfer of the work in whole or in part in return for payment * use of the work or parts of it as the main component of a commercial offering * derivation of products or services that are based directly on the work and are intended for further distribution in return for payment ("derivative works") * use for commercial marketing purposes, in particular in advertising, product campaigns or other measures aimed directly at increasing sales revenues. (5) **ShareAlike (SA):** Adaptations or transformations of the work or other derivative works may only be distributed under the same license ([CC BY-NC-SA 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/)) as the original work. Any distribution under different or more restrictive conditions is not permitted. ## 3. Prohibition of additional restrictions (1) The licensee is not entitled to apply technical protection measures or additional legal terms that would restrict the freedoms granted to third parties by this license. ## 4. Term of the license and reservation of rights (1) The license granted will terminate automatically in the event of a breach of these terms of use. (2) In all other respects, the licensor reserves all rights not expressly granted by this license. ## 5. Applicable law (1) Unless governed by the CC license, Austrian law shall apply to these BeaconScoreĀ® License Terms. ## 6. Trademark (1) BeaconScoreĀ® is a registered trademark of bitfly explorer gmbh in Austria. The use of the Ā® symbol on our website, within our API, or in associated documentation refers to our registered trademark status in Austria. BeaconScoreĀ® may also be subject to trademark rights, registrations, or pending applications in other jurisdictions. ## Document History Previous version effective until September 22, 2026 # Imprint Source: https://docs.beaconcha.in/legal/imprint ## Disclosure Disclosure in accordance with the Austrian E-Commerce Act, the Commercial Code, the Media Act as well as the Regulation on Online Dispute Resolution for Consumer Disputes: ## Company Details **bitfly explorer gmbh**\ Wiedner GĆ¼rtel 9\ 1100 Vienna | Austria ## Contact Email: [support@beaconcha.in](mailto:support@beaconcha.in) ## Commercial Register Court: Handelsgericht Wien\ Register: FN 623067 a\ Registered Office: Vienna, Austria\ Field of Interest: Our aim: providing information about the companies goods and services ## Business Purpose The business purpose of the company is services in the automated data processing; information technology; trading with goods of all kinds, especially software as well as consulting services. Chamber: Vienna Chamber of Economics ([www.wko.at](http://www.wko.at)). Regulatory Authority: Municipal District Office for the 3rd District of Vienna. Scope of the Companies Activities: Commercial Business not including regulated cases of Commercial Business and Commercial Agent. Form of Business: Free Trade. Legal and Professional Law Provisions: E-Commerce Act ([www.ris.bka.gv.at](http://www.ris.bka.gv.at)); Trade Regulation Code ([www.ris.bka.gv.at](http://www.ris.bka.gv.at)); Media Act ([www.ris.bka.gv.at](http://www.ris.bka.gv.at)); Commercial Code ([www.ris.bka.gv.at](http://www.ris.bka.gv.at)). ## Online Dispute Resolution The European Commission is providing a platform for Online Dispute Resolution (ODR) under [http://ec.europa.eu/consumers/odr/](http://ec.europa.eu/consumers/odr/). We are not obliged nor willing to participate in a dispute settlement procedure before a consumer arbitration board. # License Materials Source: https://docs.beaconcha.in/legal/license-materials Download BeaconScoreĀ® and beaconcha.in branding assets for use on your website # License Materials This page provides official branding assets that you can download and use on your website to display BeaconScoreĀ® ratings or to indicate that your service is powered by beaconcha.in. By downloading and using these materials, you agree to use them in accordance with our [BeaconScoreĀ® License Terms](/legal/beaconscore-license). ## Usage Guidelines 1. **Do not modify** the logos or badges beyond resizing 2. **Maintain aspect ratio** when resizing 3. **Use appropriate contrast** - use dark badges on light backgrounds and light badges on dark backgrounds 4. **Do not use** these materials to imply endorsement without permission 5. **Use of the "Powered by [beaconcha.in](https://beaconcha.in)", "BeaconScoreĀ®"** badge and/or any other branding materials does not itself grant any license or additional rights beyond those expressly permitted under the [API Terms and Conditions of License and Use](/legal/api-terms). In particular, branding usage does not permit any external use of our API [beaconcha.in](https://beaconcha.in) data, including but not limited to publication, commercial use, redistribution or any form of third-party access. Any such use requires a separate Enterprise Agreement with Bitfly. 6. **BeaconScoreĀ® is a registered trademark of Bitfly** in Austria and made available under the Creative Commons Attribution ā€“ Non-Commercial ā€“ ShareAlike 4.0 International License ([CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)) and the [BeaconScoreĀ® License Terms](/legal/beaconscore-license). Use of branding materials does not grant any rights beyond this license and may not be used to imply commercial use rights, endorsement, partnership, or other approval unless expressly agreed in a separate Enterprise Agreement with Bitfly. 7. **Using BeaconScoreĀ® content?** Please add the following attribution at the bottom of your page to meet the requirements of Section 2(1) of our [BeaconScoreĀ® License Terms](/legal/beaconscore-license): > *"Some content on this page is used under the **BeaconScoreĀ®** trademark and licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). For further information, please refer to the [BeaconScoreĀ® documentation](/beaconscore/introduction)."* 8. **All trademarks and other proprietary rights** in and to "beaconcha.in", "BeaconScoreĀ®", logos, and related branding remain the exclusive property of the provider. For questions regarding licensing or usage, please contact us at [support@beaconcha.in](mailto:support@beaconcha.in). *** ## BeaconScoreĀ® Use these badges to display [BeaconScoreĀ®](/beaconscore/introduction) ratings on your website. ### Dark Theme (for light backgrounds) BeaconScoreĀ® Dark Vector format, scalable to any size ### Light Theme (for dark backgrounds) BeaconScoreĀ® Light Vector format, scalable to any size *** ## Powered by beaconcha.in Use these badges to indicate that your service uses beaconcha.in data or infrastructure. ### Dark Theme (for light backgrounds) Powered by beaconcha.in Dark Vector format, scalable to any size ### Light Theme (for dark backgrounds) Powered by beaconcha.in Light Vector format, scalable to any size # Data Protection Declaration Source: https://docs.beaconcha.in/legal/privacy 22.09.2026 Data Protection Declaration of bitfly explorer gmbh, Wiedner GĆ¼rtel 9, 1100 Vienna, Austria ("**bitfly**"; "**We**") concerning the website beaconcha.in and all available subdomains. Thank you for your interest in the services of bitfly. The protection of your privacy and thus the protection of your (personal) data is Our highest priority. The following declaration is intended to provide you with comprehensive information on (i) what data We collect, (ii) how We deal with it, and (iii) what rights you have. At the same time, We therewith fulfil Our duties imposed by the (Austrian) Data Protection Act 2000 and other statutory data protection regulations. This Data Protection Declaration applies to the use of Our website beaconcha.in ("**Website**"). Data protection laws are generally relevant in case any processing of personal data is concerned. The terms used within the scope of this data protection declaration are defined in and by the General Data Protection Regulation of the European Union. As such, the wide definition of "processing" of personal data means any operation or set of operations performed on personal data, such as, but not excluded to, recording, organization, storage, alteration, and transmission of personal data. Any information allowing Us or third parties to potentially identify you in person can be considered personal data. This terminology may also apply to IP addresses as long as they allow e.g. Internet Service Providers such identification. ## 1. Processing of Data By accessing Our Website the external IP address of your computer as well as http specific information will be stored and logged for statistical, verification and organizational purposes (Art 6 para 1 lit f GDPR, legitimate interests of bitfly: technical website review and market research). Our services are designed to be used without indication of any additional personal data. IP addresses are stored for a period of 1 year, after which the data shall be deleted unless a longer time period is necessary for compliance with legal obligations. Customers may register for the service and voluntarily provide personal data, including their email address, in order to access and use the API and related services. In this context, we process personal data such as registration data, company information, email domains, billing data, support correspondence, contractual data, and information relating to API usage. This processing is carried out for the purposes of providing and maintaining the services, initiating and performing the contractual relationship, and enabling service-related communications, including automated notifications regarding the availability, performance, and security of the services and potential technical issues. We also process such data for the purpose of verifying eligibility for specific service packages, enforcing usage limitations (including trial and promotional allowances), preventing and investigating misuse and fraud, examining suspected unauthorized use, and ensuring compliance with these Terms of Use. The legal bases for this processing are Art. 6(1)(b) GDPR and Art. 6(1)(f) GDPR, whereby our legitimate interests include, in particular, ensuring the secure, proper, and abuse-free operation of the API services. Users may delete their account at any time via the user interface, subject to any applicable legal retention obligations. In case you need any support regarding Our services, you may also submit support tickets. Therefore, you need to indicate your full name as well as your email address by sending an email to [support@beaconcha.in](mailto:support@beaconcha.in). ## 2. Rights of the Data Subject A central aspect of data protection regulations is the implementation of adequate opportunities to allow for the disposition of personal data, even after the processing of said personal data has occurred. For this purpose, a series of rights of the data subject are set in place. Bitfly shall comply with your corresponding requests to exercise your rights without undue delay and in any event within one month of receipt of the request. To ensure the exercise of your rights, we maintain a dedicated Email contact address at [privacy@bitfly.at](mailto:privacy@bitfly.at) where all requests should be addressed to. Specifically, the following rights are entailed: * (a) **Right to information and access to personal data:** should you exercise your right to information, We shall provide you with all relevant information regarding the processing of your personal data by bitfly, permitted to the extent of the law. As We are processing very little personal data in order to provide Our services, We may not be able to identify your person by any means. Thus, We may only be able to provide information by requesting additional data to verify your status. This may apply to the other rights of the data subject as well. * (b) **Right to rectification:** with this right you may request the rectification of inaccurate or incomplete personal data (e.g. email addresses). * (c) **Right to erasure:** We are obliged to delete personal data (e.g. name, email address) upon your request to the extent no legal retention duties or other overriding legitimate interests under GDPR apply. * (d) **Right to restriction of processing:** restriction may be requested (i) for a verification period if the accuracy of the data is contested, (ii) if the processing is unlawful. * (e) **Right to lodge a complaint with a supervisory authority.** ## 3. Data Security Bitfly will protect processed data adequately against unauthorized access (of third parties) in accordance with the provisions of the legal framework of Austria as well as the European Union. We will only process data which are essential to provide Our services. Measures are taken with regard to (i) the quantity of data collected, (ii) the extent of data processing, (iii) the storage time as well as (iv) the accessibility of data. Data will not be used or stored by other means than set out in this Data Protection Declaration and are made accessible only to a restricted and necessary number of persons. All employees of bitfly have been informed about applicable data protection provisions as well as data security measures and are bound to Our privacy practices. Our web presence and other systems are adequately protected by a variety of security mechanisms. We do not transfer any personal data to third parties without prior explicit consent of the data subject. ## 4. Cookies Cookies are small key-value text files that are stored by the users browser. These are used by bitfly to provide a more user-friendly and secure service. Cookies allow bitfly to provide the user with more functionality, and helps us communicate securely with the browser. Cookies do not contain any personal information. The user has the option to refuse cookies at any time by selecting the appropriate option in the browser settings. However, it should be noted that the deactivation of cookies may reduce the services that we can offer and reduce user experience. ### What different types of cookies are there? To better understand why cookies are so important, we provide a brief overview of what types of cookies exist: * **Cookies, which are absolutely necessary** help with the basic navigation on a website and the display of certain functions. Without this type of cookie, the core functionality and security of a website is not available. No consent is required for this type of cookie. * **Function and analysis cookies** are used primarily for learning and analysis purposes to improve the comfort and experience of the website. This may also include the additional use of cookies from third parties such as Google Analytics. * **Advertising and social media cookies** support the use of information collected on the website for the best possible user comfort and also for additional marketing purposes. As a result, this type of cookie is also called a "targeting cookie". The second type of cookie, which falls into this category, is suitable for performance purposes as it makes use more enjoyable in general and improves marketing messages. Finally, there are ways to share content with a community, such as blog posts, or interact between a website and a social media channel. These cookies are called "interaction cookies". ### What cookies do we use? * **Necessary Cookies:** We use cookies to store settings made by the user, and to protect users from malicious actors. To display the correct currency we use a cookie named **currency**. We set a session cookie to authenticate users named **auth**. To prevent CSRF attacks we use a **\_gorilla\_csrf** cookie that stores a token sent with any POST request. * **Functional Cookies:** We use functional cookies to improve our service over time. For statistics we use google analytics and cloudflare that sets cookies such as **\_gid**, **\_ga** and **\_cfduid** to anonymously identify user behaviour. * **Marketing:** To understand user conversion we use google analytics cookies such as **\_gat\_gtag\_UA\_\***. Further, we set cookies when users interact with our advertisements. The **OAID** cookie is set by our revive server to measure our advertisement ratios. We do not share our marketing data directly with third parties, only aggregated reports and ratios are shared. ## 5. Third Party Providers The following section describes the third party software used by our website. ### 5.1 Google Analytics This website also uses Google Analytics, a web analysis service provided by Google Inc. ("Google"). Google Inc. is an enterprise of the holding company Alphabet Inc., domiciled in the USA. The information generated by the cookie about your use of the websites (including your IP address) will be transmitted to and stored by Google on servers in the United States. Google will use this information for the purpose of evaluating your use of the website, compiling reports on websites activity and providing other services relating to websites activity and internet usage. Google may also transfer this information to third parties if this is required by law or if third parties process this data on behalf of Google. Generally, before the data is transmitted to the provider, the IP address will be abbreviated by activating IP anonymization (anonymizeIP) on this website, within the member states of the European Union or in other contracting states of the agreement on the European Economic Area. Only in exceptional cases will the full IP address be sent to a Google server in the USA and abbreviated there. In these cases, we provide contractual guarantees to ensure that Google Inc. maintains a sufficient level of data protection. According to Google Inc., under no circumstances will the IP address be associated with any other user-related data. More information about the web analytics service used is available at the websites of Google Analytics: [https://www.google.ch/policies/privacy/partners](https://www.google.ch/policies/privacy/partners) We may receive the following information of Google Analytics: * Navigation path * Length of stay on the website * Returning or new user * End device We do not use the information and personal data collected by Google Analytics to identify individuals unless we become aware of specific indications of illegal use. ### 5.2 Payment Processing (Stripe) When you make a purchase, any credit card information you provide as part of your Payment Information is collected and processed directly by our payment processor Stripe through their Stripe Checkout service. We at no time receive or store your full credit card information. Stripe commits to complying with the Payment Card Industry Data Security Standard (PCI-DSS) and using industry standard security. Stripe may use your Payment Information in accordance with their own Privacy Policy here: [https://stripe.com/checkout/legal](https://stripe.com/checkout/legal). ### 5.3 Google Recaptcha To protect our services from bots bitfly uses the reCAPTCHA service of Google Inc. (Google). The IP address transmitted by your browser within the scope of reCaptcha and the data required for this are transmitted to Google. The data protection regulations of google apply in this case. [http://www.google.com/policies/privacy/](http://www.google.com/policies/privacy/). ### 5.4 Mailgun Bitfly also uses "Mailgun", an email delivery service provided by Mailgun Technologies Inc., 112 E Pecan St #1135, San Antonio, TX 78205, USA. The information required to send contractual or service-related emails (including your email address, IP address, and the content of the respective message) is transmitted to and processed by Mailgun on servers that may be located in the United States. Mailgun processes this data on our behalf solely for the purpose of sending emails that are necessary to fulfill our contractual obligations or provide essential service notifications. Emails sent for marketing or promotional purposes are only sent if you have given your prior consent, in accordance with applicable data protection laws. Mailgun may share your personal data with third parties only as necessary to provide the service and in accordance with its privacy policy. More information about Mailgun's privacy practices can be found at: [https://www.mailgun.com/legal/privacy-policy/](https://www.mailgun.com/legal/privacy-policy/). ## 6. Links to websites of third parties As far as the Websites contains external links, we hereby indicate that these third-party websites are not subject to the influence and control of bitfly. We disclaim all liability for losses or obligations related to the use of these third-party websites. We are not responsible for the contents, availability, correctness, or accuracy of these websites, nor for their offerings, links, or advertisements. ## 7. Contact Details Regarding Data Protection Issues In case you have any questions concerning bitfly's Data Protection Declaration or if you would like to exercise your right of information, rectification or deletion, please send us a written request outlining your desire to: bitfly explorer gmbh\ Wiedner GĆ¼rtel 9\ 1100 Vienna\ Austria\ E-mail: [privacy@bitfly.at](mailto:privacy@bitfly.at) ## Document History Previous version effective until September 22, 2026 Previous version effective until December 10, 2025 # General Terms and Conditions Source: https://docs.beaconcha.in/legal/terms bitfly explorer gmbh, Wiedner GĆ¼rtel 9, 1100 Vienna Last updated: 22.09.2026 ## Preamble (A) These General Terms and Conditions ("**Terms**") govern your access to and use of the Services provided on the website beaconcha.in (the "**Website**"). The Website is owned and operated by bitfly explorer gmbh ("**Bitfly**", "**we**", "**us**" and "**our**"), an Austrian limited liability company registered in the commercial register of the Vienna Commercial Court under FN 623067 a, with its seat in Vienna and its business address at Wiedner GĆ¼rtel 9, 1100 Vienna, Austria. The Services provided by us on the Website (the "**Services**") include, but are not limited to, (1) blockchain explorer, (2) API, (3) advertising, and (4) Mobile Application (the "**App**"). (B) You agree to be bound by these Terms by accessing the Website or using the Services. These Terms are available in their most current form on the Website. ## Ā§ 1. Account Registration (1) **Account.** You must create an account to make use of some of the Services. To create an account you must provide an email address and a password. To complete the registration you must verify your email address by clicking on a link in the verification email sent to you. (2) **Privacy.** Data provided by you is handled according to our Privacy Policy. (3) **Access.** You are responsible for safeguarding access to your account. Do not share your password with anyone. If you have any reason to believe that a third party has obtained knowledge of your password or is using your password in an unauthorized manner, you must notify us immediately. (4) **Violations.** We may, in our sole discretion and without notice, suspend, delete, disable or terminate any account that we suspect is in violation of these Terms. ## Ā§ 2. Blockchain Explorer (1) **License.** We grant you a limited, non-exclusive, non-transferable license to access and use the blockchain explorer on the Websites. The blockchain explorers are open source and subject to the GNU General Public License v3.0. The blockchain explorer is under development and subject to interruption without notice at any time. If you notice any errors, please contact us at [support@beaconcha.in](mailto:support@beaconcha.in). (2) **Notifications.** Email subscriptions may be configured in the 'Watchlist' section of your account. We reserve the right to limit the number of emails that are sent to you. ## Ā§ 3. API (1) **License.** We grant you a limited, non-exclusive, non-transferable, and revocable license to access and use the API through the Website for its intended purpose, provided that you continue to comply with both the General Terms and Conditions and these [API Terms and Conditions of License and Use](/legal/api-terms). (2) You can view the API Terms and Conditions of License and Use at the following link: [API Terms and Conditions of License and Use](/legal/api-terms). (3) By using the API, you explicitly agree to comply with the [API Terms and Conditions of License and Use](/legal/api-terms). (4) We may terminate or suspend your access to the API immediately if you breach any provision of the General Terms and Conditions or the [API Terms and Conditions of License and Use](/legal/api-terms). Free, trial, or promotional access to the API is subject to the eligibility criteria, time limitations, and anti-circumvention rules set out in the API Terms and Conditions of License and Use. Where we reasonably suspect misuse ā€” including, in particular, repeated use of trial access or attempts to bypass applicable restrictions ā€” we reserve the right to suspend, revoke, or terminate API access, API keys, or the associated account, on a temporary or permanent basis. ## Ā§ 4. Mobile Application (App) (1) If you access our Services via the mobile application, you are granted a revocable, non-exclusive, non-transferable, and limited license to install and use the application on wireless electronic devices owned or controlled by you for personal, non-commercial purposes only. (2) This license is limited to devices operating on the Apple iOS or Google Android operating systems and is subject to (a) these General Terms and Conditions and (b) the applicable Terms of Service of the respective App Distributor. The Application can be obtained through the Apple App Store or the Google Play Store (each individually referred to as an "**App Distributor**"). (3) The contract for the use of the App is concluded solely between the user and Bitfly. Apple Inc. and Google LLC are not responsible for maintenance, support, error correction, warranty, or liability regarding the App. Any claims arising from or in connection with the use of this App must be directed solely to Bitfly. In such cases, please contact us at [support@beaconcha.in](mailto:support@beaconcha.in). (4) Pricing plans for extended use of our App are available at [https://beaconcha.in/premium](https://beaconcha.in/premium). Payments are processed via the Apple App Store or Google Play Store under their respective terms of service. (5) **Monthly Subscription.** Your subscription starts on the date you choose your plan and will renew automatically on the first of each month until cancelled. Unless agreed otherwise, all fees are non-refundable. ## Ā§ 5. Advertising (1) **Authorization.** By purchasing advertising space from us, you authorize us to place your advertising materials on our Website. (2) **Pricing.** We typically sell advertising on a CPM basis. Custom pricing plans are available. Advertising inquiries may be made by filling out the form available at [https://beaconcha.in/advertisewithus](https://beaconcha.in/advertisewithus). (3) **No Malicious Code.** You shall not provide advertisements containing malware, spyware or any other malicious code. (4) **Cancellation.** To cancel an advertisement, please contact us at [support@beaconcha.in](mailto:support@beaconcha.in). We will remove the advertisement from the Website as soon as reasonably possible but in any case within three business days after receiving actual notice of the cancellation. You will remain obligated to pay all fees accrued between the time of cancellation and removal of the advertisement from the Website. ## Ā§ 6. Third-Party Content (1) In using the Website, you may view content provided by third parties, including links to web pages of such parties ("**Third-Party Content**"). We do not vet or endorse, nor shall we be responsible for, any Third-Party Content. Your business dealings or correspondence with such third parties are solely between you and the third parties. We disclaim any responsibility for any harm resulting from any Third-Party Content. You understand that your use of Third-Party Content, and your interactions with third parties, is at your own risk. ## Ā§ 7. Representations and Warranties (1) You represent and warrant that: * (a) you are of legal age and are legally competent to form a binding contract; * (b) you are authorized to access the Website and use the Services in the jurisdiction in which you are a citizen or resident, incorporated or established; * (c) if you are accessing the Website or using the Services on behalf of a legal entity, * (i) you have the authority to act on behalf of such legal entity, and * (ii) such legal entity is duly organized, validly existing and in good standing under the laws of the jurisdiction of its organization. (2) If you purchase extended use of the API, advertising or App you further represent and warrant that you are not a consumer as defined in the Austrian Consumer Protection Act (Konsumentenschutzgesetz; KSchG). ## Ā§ 8. Disclaimer of Warranties (1) To the extent permitted under applicable law, the Website and the Services provided by us under these Terms and the API License Terms and Conditions are provided on an "as is" basis. We disclaim any warranty, either express or implied, in connection with the Website and the Services, including without limitation any warranty of merchantability or fitness for any particular purpose. We do not guarantee that the Website is available uninterruptedly or that all data are correct, complete, accurate and current or that the Services meet your or any third party's requirements or expectations. (2) Before entering into a contract related to the Services with any third party, you must provide notice of these Terms and the API License Terms and Conditions to the third party, in particular our disclaimer of warranties under this section. ## Ā§ 9. Indemnification You agree to indemnify us and hold us harmless from any and all third party claims, demands, actions, damages, losses, costs or expenses, including reasonable legal fees, arising out of or relating to use of the Website or the Services. ## Ā§ 10. Intellectual Property (1) Notwithstanding anything to the contrary, any and all copyrights, trademark rights, patents, the right to concepts and ideas (as far as protected by intellectual property rights) related to the Website and the Services shall remain with us. (2) We grant you a limited, non-exclusive, non-transferable license to access and use the Website, subject to these Terms. You may use the Website only as permitted by law. The license granted herein terminates if you do not comply with these Terms. This license does not grant you any rights to the data made available through the Website. Any use of such data is subject to the applicable data use restrictions set out in section Ā§ 10 (3). (3) All data, content, and information made available by us, whether via API, website, user interface, export, or any other means (collectively, "Data"), may be used solely for your internal business purposes. Any use beyond such internal purposes ā€” including, in particular, the reproduction, aggregation, extraction, scraping, redistribution, publication, or commercial exploitation of the data, or its use for the benefit of third parties ā€” requires the prior conclusion of a separate Enterprise Agreement with us. ## Ā§ 11. Miscellaneous (1) **Changes.** We may update, change or replace these Terms at any time. We will notify you via email if we update, change or replace these Terms. You have a period of 14 days after notice has been provided to you to object to any update, change or replacement. If you do not object within this period, you shall be deemed having agreed to the update, change or replacement. We will remind you in our notice email that continuing to use our Services after the objection period shall be deemed as expressing consent. (2) **Survival.** If a provision of these Terms is invalid, contestable or enforceable, the validity of these Terms remains unaffected, provided that this corresponds to the intention of the parties as can be seen from the provisions of these Terms in their context. (3) **Governing Law.** These Terms and any non-contractual obligations arising out of or in relation to it shall be governed by and construed in all respects in accordance with Austrian law, excluding the Austrian conflict of laws rules. (4) **Disputes.** All disputes arising out of the Website or related to the violation, termination or nullity of these Terms shall be brought before the competent court in commercial matters (Handelsgericht) in Vienna, Austria. ## Document History Previous version effective until September 22, 2026 Previous version effective until December 10, 2025 # MEV Timing Games Source: https://docs.beaconcha.in/mev-timing-games/introduction What MEV timing games are, what the timing thresholds mean, how the bids are compared, and what changes with Glamsterdam. # ā±ļø MEV Timing Games **MEV timing games** are a deliberate strategy where Ethereum validators delay their block proposals to capture higher rewards from the relay market. beaconcha.in tracks this behaviour per-block and per-validator so you can see exactly where on the spectrum each proposal falls. This page covers: 1. [What MEV Timing Games Are](#what-are-mev-timing-games) 2. [Can You Play Them by Accident?](#can-you-play-them-by-accident) 3. [The Timing Spectrum](#the-timing-spectrum) 4. [Understanding the Bids](#understanding-the-bids) 5. [The Timing Histogram](#the-timing-histogram) 6. [Risk vs. Reward](#risk-vs-reward) 7. [Network Effects](#network-effects) 8. [Exploring MEV Data on beaconcha.in](#exploring-mev-data-on-beaconchain) 9. [What's Coming: Glamsterdam](#whats-coming-glamsterdam) *** ## What Are MEV Timing Games? ### The Ethereum slot clock Every Ethereum slot is exactly **12 seconds** long. When a validator is scheduled to propose a block, the sequence looks like this: | Time into slot | Event | | - | - | | **t = 0 s** | Slot begins; the validator calls `get_header` via MEV-boost to request bids from relays | | **t ā‰ˆ 1 s** | MEV-boost hard deadline ā€” the relay bid must be signed and committed to | | **t = 4 s** | Attesters broadcast their votes; any block not yet seen by attesters is voted *against* | | **t = 12 s** | Slot ends; next slot begins | The **t = 4 s attestation deadline** is the critical boundary. Attesters vote for whichever block they have seen at that moment. A block that arrives after 4 s risks being ignored by a large fraction of the committee, increasing the chance it is orphaned from the canonical chain entirely. ### Where MEV fits in Most validators don't build their own blocks. Instead they use **MEV-boost**, which queries multiple **relays** (trusted intermediaries between block builders and validators). Each relay returns the highest-value sealed block it has received from competing builders. At **t = 0**, the validator's consensus client calls `get_header`. MEV-boost queries all connected relays simultaneously, selects the highest bid, and must return a signed header back to the validator within roughly **1 second** (the default MEV-boost timeout is 950 ms, leaving a small buffer before the hard protocol limit). ### What a timing game is A **timing game** is the deliberate decision to *delay* calling `get_header` ā€” or to wait for a higher bid to arrive before committing ā€” beyond the time that would be needed for a timely proposal. The reasoning: builders need time to collect and order transactions. Waiting an extra second or two gives builders more profitable transactions to include, which lifts their bids. The tradeoff is that the later the block arrives at the network, the fewer attesters will have seen it by t = 4 s. Timing games are legal within the protocol ā€” no slashing risk ā€” but part of the cost is borne by *other* validators who lose attestation rewards through no fault of their own. The [Risk vs. Reward](#risk-vs-reward) and [Network Effects](#network-effects) sections cover this in detail. *** ## Can You Play Them by Accident? **Yes ā€” and it is more common than most validators realise.** A block arriving at 1.3 s registers as "Timing Games" in our classification, even if the operator had no intention of delaying. Real-world sources of accidental delay include: * **Relay response latency** ā€” a relay being slow to respond can push the `get_header` call past the 950 ms window, causing the next available slot to be chosen later than intended. * **Network propagation** ā€” a block signed at 1.0 s still needs time to propagate; by the time it is seen by remote nodes, the clock has moved forward. * **Validator client processing** ā€” signing and broadcasting adds a few hundred milliseconds on modest hardware. * **Geographic distance to relays** ā€” validators far from relay infrastructure experience higher round-trip latency on every `get_header` call. The classification thresholds (1.2 s / 2.6 s) are therefore not a binary "cheating" indicator. Low timing values are often noise. Only consistent patterns towards the aggressive end of the scale are a reliable signal of intentional behaviour. *** ## The Timing Spectrum beaconcha.in measures `slot_t_ms` ā€” the number of milliseconds from the **start of the slot** to the moment the winning relay bid was committed to (as reported by relay data archives). Each proposal is assigned one of four categories: | Category | Range | Colour | | - | - | - | | **No MEV** | No relay used | Gray | | **On-Time MEV** | ā‰¤ 1,200 ms | šŸŸ¢ Green | | **Timing Games** | 1,201 ā€“ 2,600 ms | šŸŸ” Yellow ā†’ šŸŸ  Orange | | **Aggressive Timing Games** | > 2,600 ms | šŸ”“ Red (deepening towards 3,500 ms) | The colour is not a step function ā€” it is a **continuous gradient** interpolated across six anchor points (0 ms ā†’ deep green, 1,100 ms ā†’ healthy green, 1,200 ms ā†’ yellow, 2,400 ms ā†’ orange, 2,600 ms ā†’ bright red, 3,500 ms ā†’ deep red). Values above 3,500 ms are clamped to the deepest red. ### On-Time MEV The block was proposed promptly. The relay bid arrived and was signed within the \~1 s window that MEV-boost is designed for. No deliberate delay is evident. MEV extraction is happening, but transparently and without network cost. ### Timing Games The block was proposed more than 1.2 s into the slot. This covers a wide range: modest delays (1.2ā€“2 s) that may be partially accidental, through to clearly intentional delays approaching 2.6 s. Higher values within this band increase the fraction of attesters that will not have seen the block by t = 4 s. ### Aggressive Timing Games The block was proposed more than 2.6 s into the slot. At this point the validator is taking a significant risk of missing attestations. Empirically, blocks arriving near 3.5 s or later have almost no network-propagation buffer before the attestation deadline, and operators proposing consistently in this range are sacrificing network health for marginal extra MEV. The 4 s mark displayed on the slot timeline is the **attestation deadline** ā€” the point at which attesters commit their votes regardless of whether they have seen your block. The 3.5 s colour ceiling reflects that practical network propagation time leaves little to no room between 3.5 s and the 4 s deadline. *** ## Understanding the Bids The slot page shows up to three bid markers on a timing timeline for each MEV block: ### Winning Bid **Green circle** ā€” the relay bid the validator actually selected and signed. This determines both the ETH reward and the `slot_t_ms` timing used for classification. ### First Better Bid **Blue square** ā€” the *earliest* bid that arrived after the winning bid and offered a higher value. Because the horizontal axis is **time, not reward**, this marker shows *how much longer the proposer would have had to wait* to capture a better bid. If it sits close to the winning bid, only a small timing-game delay ā€” with little added orphan risk ā€” would have captured that extra value. The further to the right it sits, the more aggressive the timing game required, and the more orphan risk the proposer would have taken on to reach it. The First Better Bid is only shown when it differs from the Best Possible Bid. ### Best Possible Bid **Purple diamond** ā€” the *highest* value bid that arrived after the winning bid. This is the **theoretical maximum**: what the validator *could* have earned had they waited until that exact moment and then committed. The difference between the Winning Bid and the Best Possible Bid represents the maximum amount left uncaptured. A large gap between the Winning Bid and the Best Possible Bid does not automatically mean the validator made a bad decision. Waiting for the Best Possible Bid requires accepting the full orphan risk of proposing that late. The validator cannot know in advance which bid will turn out to be the best; they can only observe the bids as they arrive. *** ## The Timing Histogram The validator dashboard MEV tab shows a **histogram** of `slot_t_ms` values across all MEV blocks proposed by the validators in your dashboard. * The chart spans from **\< 0 ms** (bids committed before the slot officially started) to **ā‰„ 4,000 ms**, split into **22 buckets of 200 ms each**. * Each bar is coloured using the same continuous gradient as the individual block badges ā€” green on the left, red on the right. * The **overall timing label** shown above the histogram is determined by the **median** `slot_t_ms` across all relay-winner proposals, giving a representative single number for the validator set. * Blocks with no relay participation (No MEV) and blocks where the relay reported no winner are excluded from the histogram and timing label ā€” they are accounted for separately. Reading the histogram: * A distribution concentrated in the 0ā€“1,200 ms range indicates prompt, on-time proposals. * A distribution spread across 1,201ā€“2,600 ms suggests mild to moderate timing games, possibly a mix of intentional and accidental delay. * Any significant bar at or beyond 2,600 ms ā€” especially towards 3,500 ms ā€” is a strong signal of intentional aggressive timing game behaviour. *** ## Risk vs. Reward The economic logic of timing games is straightforward: the longer builders have to observe pending transactions, the more profitable blocks they can construct. Research has estimated that optimal timing can improve overall validator APR by roughly **1ā€“2%** for sophisticated operators. The risk is also straightforward: the later a block arrives at the network, the fewer attesters will have seen it by the t = 4 s deadline. Empirical data from testnet observations shows that blocks arriving near 3ā€“3.5 s can lose \~10% of attestations to wrong-head votes, directly reducing the CL reward. In extreme cases, a block arriving after 4 s may be entirely skipped by attesters, resulting in the slot being treated as missed ā€” losing the entire block reward. The risk is therefore asymmetric and non-linear: modest timing (1.2ā€“1.8 s) carries limited risk, but delays approaching 3.5 s carry a substantially higher chance of orphaning the block and turning a reward into a missed slot. If your histogram shows a consistent pattern of proposals beyond 2.6 s, the orphan risk may be material. Monitor your actual CL rewards relative to the network median and watch for missed attestation patterns in neighbouring slots. *** ## Network Effects Timing games are not purely a private risk ā€” they have externalities that fall on other validators. **A direct financial cost to innocent attesters:** This is the most concrete harm. Consider a simple example: you propose a late block at t = 2.5 s. Alice is randomly assigned to attest in your slot. She polls the network at t = 4 s and has not yet seen your block, so she votes for the previous block ā€” a *wrong-head vote*. Meanwhile, the majority of attesters *did* receive your block in time and vote correctly. The network accepts your block as canonical. The result: Alice loses the **head vote component** of her attestation reward for that slot, through no fault of her own. She voted correctly for what she could observe. The cost of your timing game was partly shifted onto her. This is a negative externality in the economic sense: you capture extra MEV, but a portion of the cost is borne by validators who had no part in the decision. **Attestation quality and fork-choice stability:** Beyond the per-validator penalty, a high rate of wrong-head votes degrades the overall quality of consensus information. Fork-choice becomes noisier, and in edge cases the split can be exploited to mount certain fork-choice attacks. A network where many proposers consistently play aggressive timing games is structurally weaker than one where blocks arrive promptly. **Orphan propagation:** A block that is not seen by enough attesters in time may trigger a re-org, forcing the next proposer to build on a different parent. This disrupts any validators who built on the orphaned tip, potentially invalidating their attestations as well. **Centralisation pressure:** Effective timing games require fast, low-latency connections to multiple relay endpoints. Large staking pools with dedicated relay infrastructure and co-located validators can execute timing games more safely than solo stakers on commodity hardware at home. This creates an unequal playing field ā€” operators with better infrastructure can capture more MEV at lower orphan risk. The academic literature frames timing games as *"honest-but-rational"* behaviour: validators are acting within the rules of the protocol while extracting value that could otherwise belong to the network as a whole. There is no community consensus on whether they are unethical, but they are widely viewed as a network health concern, particularly at the aggressive end of the scale. *** ## Exploring MEV Data on beaconcha.in The same underlying timing data is surfaced at six levels of granularity, from a single block all the way to a network-wide 30-day view. Each answers a different question. ### Individual block ā€” Slot page **[beaconcha.in/slot/\{slot}](https://beaconcha.in/slot/14607081)** The most granular view. For every MEV block it shows: * A **timing badge** on the Proposer Reward line, colour-coded by `slot_t_ms` and labelled with the timing category. Hover the badge for the exact millisecond value and a link to the [timing spectrum](#the-timing-spectrum) explainer. * A **MEV Bid Analysis section** plotting all three [bid markers](#understanding-the-bids) ā€” Winning Bid, First Better Bid, and Best Possible Bid ā€” on a timeline against the slot clock. This lets you see exactly how much value the proposer captured, what was left on the table, and how close to the attestation deadline the block arrived. Use this when you want to understand a specific proposal in full detail. ### Individual validator ā€” Validator page **[beaconcha.in/validator/\{index}](https://beaconcha.in/validator/1)** The validator detail page adds a **MEV tab** showing: * A **timing label** summarising the validator's overall timing posture. * A **180-day MEV distribution chart** ā€” a histogram of `slot_t_ms` values across all proposals in the past 180 days, coloured with the same gradient as the timing badges. This reveals whether timing patterns are consistent or episodic, and whether they are drifting over time. Use this when you want to profile a single validator's timing behaviour over a longer window. ### Your validator set ā€” Dashboard **[beaconcha.in/monitoring/dashboard](https://beaconcha.in/monitoring/dashboard)** The validator dashboard surfaces MEV data in two places: **Blocks table** ā€” every proposed block row includes a MEV status badge and bid insight details: the winning bid value, timing, relay and bid counts, and the best alternative bid that was available. This gives you a running log of MEV outcomes across your entire set without needing to visit each slot individually. **MEV tab** ā€” an aggregated view across all validators in the dashboard showing: * An **overall timing label** (based on the median `slot_t_ms` across all relay-winner proposals), with a link to the [timing spectrum](#the-timing-spectrum) explainer. * A **bid timing histogram** across all 22 buckets. See the [histogram section](#the-timing-histogram) for how to read it. Use this when you want to answer "how are my validators performing on timing, in aggregate?" ### Staking operator ā€” Entity detail page **[beaconcha.in/entities](https://beaconcha.in/entities)** ā†’ click any entity ā†’ **[beaconcha.in/entity/\{name}](https://beaconcha.in/entity/Lido/-)** The entity detail page aggregates MEV data across every validator operated by a staking entity (e.g. Lido, Coinbase, solo stakers). It shows: * A **180-day MEV distribution chart** ā€” the same histogram format as the individual validator page, but representing thousands of proposals aggregated by operator. Overlaid on the chart is the **max bid value** in ETH, showing whether higher-timing proposals actually capture higher rewards. * A **MEV trend chart** ā€” a time-series of the entity's median `slot_t_ms` over the past 180 days, with reference lines at 1,200 ms and 2,600 ms marking the [spectrum](#the-timing-spectrum) thresholds. This makes sustained timing game behaviour or gradual drift clearly visible. * **Sub-entity timing labels** in the sub-entities table, showing the MEV posture for each sub-entity (e.g. individual node operators within a liquid staking protocol). Use this when you want to assess whether a large staking operator is systematically playing timing games, and how the behaviour compares across their sub-entities. ### All operators at a glance ā€” Entities overview **[beaconcha.in/entities](https://beaconcha.in/entities)** The entities overview page lets you compare all major staking operators side-by-side. Two MEV features are available: * **MEV timing column** in the entities table ā€” a timing label badge per operator showing their overall MEV posture at a glance. * **MEV heatmap treemap** ā€” toggle the treemap from *Performance* mode to *MEV Timing* mode to see the entire staking landscape coloured by timing behaviour. Larger squares represent more stake; deeper red indicates more aggressive timing games. Use this when you want to identify which large operators are the most active timing game players across the network. ### Network-wide trends ā€” MEV Analysis **[beaconcha.in/mev](https://beaconcha.in/mev)** The broadest view. A **30-day stacked bar chart** of daily slot counts broken down by all five timing categories: No MEV, Unknown Timings, On-Time MEV, Timing Games, and Aggressive Timing Games. The 7-day summary cards at the top give an at-a-glance percentage for each category. Use this to track whether timing game behaviour is growing or shrinking across Ethereum as a whole ā€” useful context for interpreting what you see at any of the more granular views above. Timing games by large operators can lower [BeaconScoreĀ®](/beaconscore/introduction#residual-luck-factors) for innocent validators through missed head votes, even when those validators are performing perfectly. The BeaconScoreĀ® explainer covers this under *Residual Luck Factors*. *** ## What's Coming: Glamsterdam The current timing game dynamic is a consequence of the **relay architecture**: relays sit outside the protocol, creating the gap between the 1 s MEV-boost deadline and the 4 s attestation deadline that validators can exploit. **Glamsterdam**, the next Ethereum protocol upgrade, will introduce **enshrined Proposer-Builder Separation (ePBS)** ā€” moving the builder auction mechanism directly into the consensus layer. Relays as they exist today will be replaced by a protocol-native mechanism, and the timing game landscape will change significantly as a result. We will share a detailed breakdown of what ePBS means for timing game metrics on beaconcha.in as the hardfork approaches. Follow [@beaconcha\_in](https://x.com/beaconcha_in) and our [Changelog](/changelog/product-updates) for updates on Glamsterdam support. *** Thanks to the researchers who documented timing games on Ethereum: [Caspar Schwarz-Schilling, Fahad Saleh, Thomas Thiery, Jennifer Pan, Nihar Shah, and BarnabĆ© Monnot](https://arxiv.org/abs/2305.09032) ā€” *Time is Money: Strategic Timing Games in Proof-of-Stake Protocols* (AFT 2023). # Legacy notifications Source: https://docs.beaconcha.in/notifications-monitoring/legacy-notifications How to configure beaconcha.in notifications # Notification configuration ## Configuration This article provides a tutorial on setting up and debugging notifications using beaconcha.in's web and mobile platforms. It's worth noting that the current notification center will undergo an upgrade in late 2023 to upgrade its user-friendliness #### Enabling notifications via web 1. Head over to [https://beaconcha.in/user/notifications](https://beaconcha.in/user/notifications) and log in with your e-mail address. 2. Click on "Notifications Channels" and make sure the desired channels are active Notification channels settings on beaconcha.in 3. Scroll down to the **Validators** table and add your validators. Once added you can *select all* and bulk edit the notifications by clicking *Manage selected*. Validators table and Manage selected actions 4. Enable the desired notification(s) and press *Save*. Enable desired notifications and save 5. Verify that the subscriptions are enabled Subscriptions enabled verification in validator table 6. If a notification was triggered it will show up in the Most recent column Most recent notification column showing a triggered alert 7. Done! You may have noticed that the Notification Center allows you to configure push notifications for the mobile app. This is crucial since some users may not receive any push notifications if it is disabled. #### Mobile app 1. Download the app for iOS and Android here [https://beaconcha.in/mobile](https://beaconcha.in/mobile) 2. Create an account and log in with your e-mail address\ \ ***Note**: If you added validators to your Notification center through* [*https://beaconcha.in/user/notifications*](https://beaconcha.in/user/notifications) *they will **not** appear in your mobile app automatically.*\ *If push notifications were enabled in the web notification center, the mobile app push the notifications through even if the validators are not visible in your app.*\ \ *This UX issue will be part of the improvements later this year.* 3. Add validators to your mobile app dashboard 4. Head over to the settings and enable the desired notifications Mobile app notification settings screen 5. Click the "Sync" button in the Validator section Sync button in validator section 6. Done!\ \ Verify that the notifications were added successfully by logging in at [https://beaconcha.in/user/notifications](https://beaconcha.in/user/notifications) and scrolling to the Validator table at the bottom of the page Validator table showing added notifications You may have noticed that the Notification Center allows you to configure push notifications for the mobile app. This is crucial since some users may not receive any push notifications if it is disabled. #### Webhooks 1. Follow the steps as described [above](#enabling-notifications-via-web) in "Enabling notifications via web". 2. Double-check that webhooks are enabled Webhooks settings showing webhook enabled 3. Add a webhook via [https://beaconcha.in/user/webhooks](https://beaconcha.in/user/webhooks) 4. Enable the same notification types as on the notification center and enable "discord" if the notifications should be sent to a discord channel Webhook configuration with Discord option 5. Done # Mobile App <> Cl Node Monitoring Source: https://docs.beaconcha.in/notifications-monitoring/mobile-app-beacon-node A step-by-step tutorial on how to monitor your staking device and consensus layer node on the beaconcha.in mobile app # Mobile App Node Monitoring ## General This is a free monitoring tool provided by [beaconcha.in](https://beaconcha.in/) to enhance the solo staking experience. The user specifies the monitoring endpoint on its consensus layer and validator node. Screenshot: Mobile app and node monitoring overview *By using this endpoint, beaconcha.in will be allowed and is required to store the given data to display it in the beaconcha.in the mobile application. To protect user privacy, the IP address will **never** be stored* ### **Requirements** * beaconcha.in [Account](https://beaconcha.in/register) * beaconcha.in [Mobile App](https://beaconcha.in/mobile) * **Lighthouse** [**v.1.4.0**](https://github.com/sigp/lighthouse/releases) or higher * **Prysm** [**v1.3.10**](https://github.com/prysmaticlabs/prysm/releases) or higher * **Nimbus** [**v1.4.1**](https://github.com/status-im/nimbus-eth2/releases) **or higher** * **Teku v22.3.0 or higher** * **Lodestar** [**v1.6.0**](https://github.com/ChainSafe/lodestar/releases) **or higher** * Staking on Linux (No windows support by clients yet!) Please adjust the network on the beaconcha.in browser and mobile app accordingly. Both the beaconcha.in [explorer](https://github.com/gobitfly/eth2-beaconchain-explorer) and the [mobile app](https://github.com/gobitfly/eth2-beaconchain-explorer-app) are open source! ## Lighthouse *A step-by-step guide on the Prater Testnet. Please adjust the network for your own needs.* 1. Open the [**Mobile App** ](https://beaconcha.in/user/settings#app)Tab and enter a name for your staking setup.\ Use the same worker name even if your consensus layer node runs on a separate machine than your validator node.\ Copy the generated flag and paste it to your **beacon & validator node** Screenshot: Lighthouse mobile app flag in settings Screenshot: Lighthouse command line flags *If your consensus layer node or execution layer node is not in sync yet, you will see some warning in the logs!* \ 2\. Open the [beaconcha.in mobile app](https://beaconcha.in/mobile) and login with your account under *Preferences.*\ Your staking device will appear under *Machines*! Screenshot: Mobile app Machines view ## Prysm 1. Head over to the [beaconcha.in settings](https://beaconcha.in/user/settings#app) and open the prysm section: Screenshot: Prysm section in beaconcha.in settings 2\. Open a **new Terminal** and copy and paste the commands Screenshot: Prysm exporter configuration 3\. Make sure your Prysm client (consensus layer node and validator client) is already up and running. The exporter will now send the data to your mobile app! Screenshot: Prysm exporter sending data 4\. Wait a few minutes and open the [beaconcha.in mobile app](https://beaconcha.in/mobile) and login with your account under *Preferences.*\ \ Your staking device will appear under *Machines*! Screenshot: Mobile app Machines view ## Nimbus 1. Head over to the [beaconcha.in settings](https://beaconcha.in/user/settings#app) and open the nimbus section: Screenshot: Nimbus section in beaconcha.in settings 2\. Add `--metrics --metrics-port=8008` to your nimbus client! Otherwise, the exporter will not be able to get any data from your client. Screenshot: Nimbus client metrics flags 3\. Wait a few minutes and open the [beaconcha.in mobile app](https://beaconcha.in/mobile) and login with your account under *Preferences.*\ \ Your staking device will appear under *Machines*! Screenshot: Mobile app Machines view ## Teku Add the following endpoint to your teku node `--metrics-publish-endpoint https://beaconcha.in/api/v1/client/metrics?apikey=YOUR_API_KEY` You can find your API Key here: [https://beaconcha.in/user/settings#app](https://beaconcha.in/user/settings#app) ## Lodestar Add the following CLI flag to your Lodestar validator and consensus layer node `--monitoring.endpoint 'https://beaconcha.in/api/v1/client/metrics?apikey=YOUR_API_KEY'` You can find your API Key in the [account settings](https://beaconcha.in/user/settings#api). Check out the Lodestar documentation about [client monitoring](https://chainsafe.github.io/lodestar/run/logging-and-metrics/client-monitoring) for further details. ## Monitoring with Rocket Pool Works with Lighthouse, Lodestar, Teku and Nimbus only. ### Lighthouse, Lodestar and Teku Add Your [beaconcha.in API key ](https://beaconcha.in/user/settings#app)in Monitoring/Metrics (service config) Screenshot: Rocket Pool service config Monitoring/Metrics API key *** ### Nimbus Nimbus does not expose all tracked data, some metrics such as validators are not visible in the app. Guide: [https://gist.github.com/jshufro/89e32d417801bf3dfb02c32a983b63cf](https://gist.github.com/jshufro/89e32d417801bf3dfb02c32a983b63cf) # Notifications Source: https://docs.beaconcha.in/notifications-monitoring/notifications Manage notifications in the v2 dashboard # ā° Notifications v2 ## Requirements * beaconcha.in account * Register [here](https://beaconcha.in/register) * Login [here](https://beaconcha.in/login) * Configure notifications [here](https://beaconcha.in/notifications) ## Overview * **A**: Shows whether email notifications are enabled. * **B**: Daily email limit. The limit resets at 00:00 UTC. Upgrading to a higher [premium](https://beaconcha.in/pricing) tier increases this limit. * **C**: Indicates whether push notifications for the mobile app are enabled. * **D**: Notification history. Notifications for dashboards, machines, clients, and network events will appear in dedicated tabs. * **E**: Set up or manage your notifications in this section. ## Setting up v2 notifications via web ### Validator notifications V2 notifications are group-based, meaning you can set validator notifications for each [group](../validator-dashboard/validator-groups) configured on the [validator dashboard](https://beaconcha.in/dashboard). To set up notifications: 1. Make sure you have created a [validator dashboard](https://beaconcha.in/dashboard) first. 2. Go to [https://beaconcha.in/notifications#dashboards](https://beaconcha.in/notifications#dashboards). 3. Click on `Manage Notifications`. 4. Ensure email and push notifications are **enabled**. 5. Send a test notification to confirm you receive notifications. 6. Go to the Dashboard tab, select the group, and edit the subscription column. ### Validator notifications via webhook 1. Follow the steps in [Validator Notifications](#validator-notifications) 2. Click the Edit icon in the webhook column. 3. Add your webhook URL. 1. Check the 'Send via Discord' box if notifications should be sent to a [Discord channel](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks). 4. Send a test notification to ensure everything is working. 5. Click Save. ### Client notifications To set up notifications for EL and CL clients like Geth, Nimbus, or Erigon, go to the Clients tab. ### Network notifications To set up notifications for Gas prices, Rocket Pool reward round or Participation rate of the network, go to the Networks tab. ## Migrating from v1 notification to v2 NOTE: This method works for up to 100 validators for free users and up to 280 for premium users! Users exceeding this limit, please continue from 4. 1. Head over to [https://beaconcha.in/user/notifications](https://beaconcha.in/user/notifications) 2. Scroll down and click "View Stats" 3. Copy the validator indices from the URL of the website that opens:\ e.g `1,2641,2642,2643,2645,3288,3292,3400,3401,3402,3403,3404` 4. Login on [https://beaconcha.in/login](https://beaconcha.in/login), and create a v2 dashboard here: [https://beaconcha.in/dashboard](https://beaconcha.in/dashboard)\\ 5. Click on `Manage Validators`and add your validators as a comma-separated list or use other methods as described in [#bulk-adding-to-the-validator-dashboard](../validator-dashboard/manage-validators#bulk-adding-to-the-validator-dashboard "mention"): With the dashboard successfully set up, you can configure notifications. :relaxed: 6. Go to [https://beaconcha.in/notifications#dashboards](https://beaconcha.in/notifications#dashboards). 7. Click on `Manage Notifications`. 8. Ensure email and push notifications are **enabled**. 9. Send a test notification to confirm you receive notifications. 10. Go to the Dashboard tab, select the group, and edit the subscription column. # APY & ROI Metrics Source: https://docs.beaconcha.in/use-cases/apy-roi Calculate annual percentage yield and return on investment for validators ## Overview The APY & ROI endpoint provides standardized return metrics for your validators, broken down by execution layer (EL) and consensus layer (CL) contributions. **API Endpoint:** This guide uses [`/api/v2/ethereum/validators/apy-roi`](/api-reference/ethereum/validators/apy-roi) for aggregated return metrics. **When to use APY/ROI vs BeaconScoreĀ®:** APY and ROI measure absolute returns in ETH/percentage terms. BeaconScoreĀ® measures relative efficiency normalized for luck (see [residual luck factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors)). For comparing validator performance across operators, BeaconScoreĀ® is recommended. **See Also:** For detailed per-epoch missed reward analysis (which duty types are causing losses), see [Analyze Missed Rewards](/use-cases/missed-rewards). This endpoint focuses on aggregated return metrics. *** ## Understanding the Metrics This guide focuses on choosing a window and interpreting the metrics in an operational comparison. See the [APY & ROI API reference](/api-reference/ethereum/validators/apy-roi). APY is an extrapolation based on the selected evaluation window. Past performance does not guarantee future results, especially for execution layer rewards which are highly variable. *** ## Quick Start: Fetch APY & ROI ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/apy-roi \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "30d" } } ' ``` ### Response ```json theme={null} { "data": { "execution_layer": { "roi": "0.00125", "apy": "0.0152" }, "consensus_layer": { "roi": "0.00285", "apy": "0.0347" }, "combined": { "roi": "0.0041", "apy": "0.0499" }, "finality": "finalized" }, "range": { "epoch": { "start": 407453, "end": 414202 }, "timestamp": { "start": 1763285975, "end": 1765877974 } } } ``` ## Evaluation Windows Choose a window that matches the reporting period, and use the same value for every comparison. See the [APY & ROI API reference](/api-reference/ethereum/validators/apy-roi). Longer evaluation windows provide more stable APY estimates. Short windows are heavily influenced by luck (block proposals, MEV). *** ## APY vs BeaconScoreĀ® | Metric | Use Case | Affected By | | - | - | - | | **APY** | Absolute return calculation | Luck (proposals, MEV), network conditions | | **BeaconScoreĀ®** | Performance comparison | Primarily validator behavior (normalized for luck; some [residual factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors) remain) | A validator with lower APY might still have a higher BeaconScoreĀ® if they were unlucky with block proposals. BeaconScoreĀ® largely removes luck from the equation, making it ideal for comparing operator performance. Some [residual luck factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors) can still influence scores over short windows. *** ## Best Practices Short windows are noisy. Use 30 days or longer for meaningful APY estimates. EL rewards (MEV) are highly variable. Track them separately from CL rewards. When comparing validators, ensure they use the same MEV-boost configuration. For comparing validator quality, BeaconScoreĀ® is more reliable than APY. *** ## Related Resources * [Monitor Validator Performance](/use-cases/performance-introduction) ā€” BeaconScoreĀ® metrics * [Analyze Missed Rewards](/use-cases/missed-rewards) ā€” Quantify lost earnings * [Calculate Validator Rewards](/use-cases/rewards-introduction) ā€” Detailed reward breakdowns # Benchmark Entity vs Network Source: https://docs.beaconcha.in/use-cases/benchmark-entity-vs-network Compare one staking entity against the network baseline for BeaconScoreĀ®, APY, missed rewards, and sub-entity drill-down ## Overview Compare a single staking entity against the network average across BeaconScoreĀ®, APY, missed rewards, and sub-entity performance. **API Endpoints:** This guide uses [`entities`](/api-reference/ethereum/entities/overview), [`performance-aggregate`](/api-reference/ethereum/performance-aggregate), [`validators/apy-roi`](/api-reference/ethereum/validators/apy-roi), [`validators/rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate), [`entity/sub-entities`](/api-reference/ethereum/entity/sub-entities), and [`validators/metadata`](/api-reference/ethereum/validators/metadata). **Premium access:** `entities`, `entity/sub-entities`, `validators/apy-roi` (with entity selector), `validators/rewards-aggregate` (with entity selector), and `validators/metadata` require a Scale or Enterprise plan. `performance-aggregate` (network baseline) is available on all plans. **Attribution required:** If you display BeaconScoreĀ® publicly, follow the [BeaconScoreĀ® License](/legal/beaconscore-license) and [License Materials](/legal/license-materials). **Configurable evaluation window:** All examples below use `30d`, but you can change `evaluation_window` to `24h`, `7d`, `30d`, or `90d` depending on your use case. Use consistent windows across all calls in the same comparison. See [Evaluation Windows](/use-cases/entity-benchmarking-overview#evaluation-windows) for guidance. *** ## Why Benchmark vs Network? A BeaconScoreĀ® of 99.5% is only meaningful in context. Comparing to the network average reveals whether that score represents outperformance, peer performance, or lagging performance. If an entity's score drops, compare against the network delta first. A simultaneous network-wide drop indicates an external event; an entity-only drop points to operational issues. Produce clear entity-vs-network deltas for customer SLAs, quarterly reports, or public transparency disclosures. When a parent entity score changes, drill into sub-entities (node operators) to identify which operators are driving the change. | Metric | Luck-normalized? | Best use | | - | - | - | | BeaconScoreĀ® | Yes (see [residual factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors)) | Performance comparison across entities | | APY / ROI | No | Absolute return reporting | | Missed rewards | Yes (% of earned) | Operational efficiency | For the full BeaconScoreĀ® methodology, see [BeaconScoreĀ® vs. 3rd Party Metrics](/beaconscore/BeaconScore-vs-3rd-party-metrics). *** ## Step 1: Get the Entity BeaconScoreĀ® Fetch the entity list and select your target: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/entities \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "range": { "evaluation_window": "30d" } }' ``` From the response, use the target entity's `beaconscore` field (decimal, e.g. `0.9947`). *** ## Step 2: Get the Network Baseline Fetch the network-wide performance aggregate over the **same** evaluation window: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/performance-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "range": { "evaluation_window": "30d" } }' ``` **Known behavior:** This endpoint does not filter by entity. Any entity parameter is silently ignored. The response always represents the full network. This is the intended behavior for computing the baseline. Use the total and component scores as the benchmark values. See [Network Performance Aggregate](/api-reference/ethereum/performance-aggregate). *** ## Step 3: Compute BeaconScoreĀ® Delta ```python theme={null} delta_total = entity_beaconscore - network_beaconscore ``` ### Threshold Reference | šŸŸ¢ Green | šŸŸ” Yellow | šŸ”“ Red | | - | - | - | | `delta >= +0.0025` (+0.25pp above network) | `-0.0025 < delta < +0.0025` (within Ā±0.25pp) | `delta <= -0.0025` (0.25pp+ below network) | These same thresholds apply to all three component deltas (attestation, sync committee, proposal). *** ## Step 4: Fetch APY and Compare vs Network Fetch APY for the target entity: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/apy-roi \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "entity": "Lido" }, "range": { "evaluation_window": "30d" } }' ``` Then fetch APY for the network baseline (no entity selector): ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/apy-roi \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "range": { "evaluation_window": "30d" } }' ``` Compare the combined, consensus-layer, and execution-layer APY totals. Use the same Ā±0.25pp thresholds for coloring. See [APY & ROI](/api-reference/ethereum/validators/apy-roi). **Interpreting EL APY:** A high EL APY vs the network in short windows typically reflects proposal luck (favorable MEV), not operational efficiency. Always check whether EL outperformance aligns with an above-average proposal count before attributing it to operator quality. *** ## Step 5: Fetch Missed Rewards and Compute Efficiency Fetch missed rewards for the entity: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "entity": "Lido" }, "range": { "evaluation_window": "30d" } }' ``` **Wei values are JSON strings.** All reward values are returned as strings representing large integers. Always cast with `int(str(v))` before dividing by `1e18`. Compute per-component efficiency and total missed: ```python theme={null} def w(v): return int(str(v)) if v is not None else 0 d = response["data"] att = d["attestation"] sc = d["sync_committee"] prop = d["proposal"] # Component efficiency att_eff = (w(att["head"]["reward"]) + w(att["source"]["reward"]) + w(att["target"]["reward"])) / \ (w(att["head"]["reward"]) + w(att["source"]["reward"]) + w(att["target"]["reward"]) + w(att["head"]["missed_reward"]) + w(att["source"]["missed_reward"]) + w(att["target"]["missed_reward"])) sync_eff = w(sc["reward"]) / (w(sc["reward"]) + w(sc["missed_reward"])) prop_cl_earned = w(prop["attestation_inclusion_reward"]) + w(prop["sync_inclusion_reward"]) + w(prop["slashing_inclusion_reward"]) prop_eff = prop_cl_earned / (prop_cl_earned + w(prop["missed_cl_reward"])) # Deltas vs network baseline components d_att = att_eff - NET_attestation d_sync = sync_eff - NET_sync_committee d_prop = prop_eff - NET_proposal # Missed totals m_cl_eth = (w(att["head"]["missed_reward"]) + w(att["source"]["missed_reward"]) + w(att["target"]["missed_reward"]) + w(sc["missed_reward"]) + w(prop["missed_cl_reward"])) / 1e18 m_el_eth = w(prop["missed_el_reward"]) / 1e18 m_total_eth = m_cl_eth + m_el_eth earned_eth = w(d["total_reward"]) / 1e18 # gross, not net pct_missed = m_total_eth / (m_total_eth + earned_eth) * 100 ``` ### Missed % of Earned Thresholds (lower = better) | šŸŸ¢ Green | šŸŸ” Yellow | šŸ”“ Red | | - | - | - | | `< 0.40%` | `0.40% ā€“ 0.60%` | `> 0.60%` | Absolute ETH missed scales with validator count. Use `% of earned` for fair cross-entity comparisons. *** ## Step 6: Drill Into Sub-Entities When parent performance changes, identify which operators are driving it: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/entity/sub-entities \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "entity": "Lido", "range": { "evaluation_window": "30d" }, "sort_by": "beaconscore", "sort_order": "desc" }' ``` Compare each sub-entity's `beaconscore` against the network baseline. Sub-entities with `delta <= -0.0025` warrant investigation. Sortable fields: `beaconscore`, `net_share`, `validator_count`. *** ## Step 7: Map Validators to Entities (Optional) If you start from validator indices rather than an entity name, resolve entity assignments first: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/metadata \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "validator_identifiers": [1, 2, 3] }, "page_size": 10 }' ``` Use the assignment to route validators to the correct entity benchmarking queries. See [Validator Metadata](/api-reference/ethereum/validators/metadata). *** ## Example: Full Entity Benchmark Script (Python) ```python theme={null} import requests import time API_KEY = "" BASE = "https://beaconcha.in" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} WINDOW = "30d" ENTITY_NAME = "Lido" def post(endpoint, payload): r = requests.post(f"{BASE}{endpoint}", headers=HEADERS, json=payload, timeout=30) r.raise_for_status() return r.json() def w(v): return int(str(v)) if v is not None else 0 # Entity BeaconScore entities = post("/api/v2/ethereum/entities", { "chain": "mainnet", "range": {"evaluation_window": WINDOW}, }) entity = next((e for e in entities["data"] if e["entity"] == ENTITY_NAME), None) if not entity: raise ValueError(f"Entity not found: {ENTITY_NAME}") # Network baseline net = post("/api/v2/ethereum/performance-aggregate", { "chain": "mainnet", "range": {"evaluation_window": WINDOW}, }) NET = net["data"]["beaconscore"] delta = entity["beaconscore"] - NET["total"] print(f"BeaconScore: {entity['beaconscore']*100:.4f}% | Network: {NET['total']*100:.4f}% | Delta: {delta*100:+.2f}pp") # APY time.sleep(1) apy_r = post("/api/v2/ethereum/validators/apy-roi", { "chain": "mainnet", "validator": {"entity": ENTITY_NAME}, "range": {"evaluation_window": WINDOW}, }) apy = apy_r["data"]["combined"]["apy"]["total"] print(f"APY: {apy*100:.2f}% CL: {apy_r['data']['consensus_layer']['apy']['total']*100:.2f}% EL: {apy_r['data']['execution_layer']['apy']['total']*100:.2f}%") # Missed rewards time.sleep(1) rw = post("/api/v2/ethereum/validators/rewards-aggregate", { "chain": "mainnet", "validator": {"entity": ENTITY_NAME}, "range": {"evaluation_window": WINDOW}, }) d = rw["data"] att = d["attestation"] sc = d["sync_committee"] prop = d["proposal"] m_cl_eth = (w(att["head"]["missed_reward"]) + w(att["source"]["missed_reward"]) + w(att["target"]["missed_reward"]) + w(sc["missed_reward"]) + w(prop["missed_cl_reward"])) / 1e18 m_el_eth = w(prop["missed_el_reward"]) / 1e18 m_total_eth = m_cl_eth + m_el_eth earned_eth = w(d["total_reward"]) / 1e18 pct_missed = m_total_eth / (m_total_eth + earned_eth) * 100 print(f"Missed: {m_total_eth:.2f} ETH ({pct_missed:.3f}% of earned)") # Sub-entity drill-down time.sleep(1) subs = post("/api/v2/ethereum/entity/sub-entities", { "chain": "mainnet", "entity": ENTITY_NAME, "range": {"evaluation_window": WINDOW}, "sort_by": "beaconscore", "sort_order": "desc", }) print(f"\nSub-entities for {ENTITY_NAME}:") for row in subs["data"][:10]: sub_delta = row["beaconscore"] - NET["total"] flag = "šŸŸ¢" if sub_delta >= 0.0025 else ("šŸ”“" if sub_delta <= -0.0025 else "šŸŸ”") print(f" {flag} {row['sub_entity']:<25} {row['beaconscore']*100:.4f}% ({sub_delta*100:+.2f}pp)") ``` *** ## Best Practices Short windows introduce noise from proposal luck. Use 30d minimum for stable benchmarking. Store `entity - network` deltas over time to distinguish persistent underperformance from temporary variance. A parent-level score change can mask improvement in some operators and degradation in others. When APY diverges from peers, check whether the gap is in CL APY (operational) or EL APY (proposal luck). CL APY differences are operationally significant; EL APY differences in short windows often are not. *** ## Related Resources * [Entity Benchmarking Overview](/use-cases/entity-benchmarking-overview) * [Rank and Compare Entities](/use-cases/rank-and-compare-entities) * [Private Entity Benchmarking with Dashboards](/use-cases/private-entity-benchmarking-with-dashboard) * [APY & ROI Metrics](/use-cases/apy-roi) * [Analyze Missed Rewards](/use-cases/missed-rewards) * [BeaconScoreĀ® vs. 3rd Party Metrics](/beaconscore/BeaconScore-vs-3rd-party-metrics) * [Supported Entities List](https://beaconcha.in/entities) * [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets#dashboard-as-private-sets) * [Validator Tagging](/validator-tagging/overview) # Compare MEV Timing Source: https://docs.beaconcha.in/use-cases/compare-mev-timing Compare MEV timing behavior across the network, staking entities, sub-entities, and your validator sets ## Overview MEV timing is most useful as a comparison. A single late proposal may be noise, but a sustained difference from the network can reveal deliberate timing behavior, relay latency, or a configuration change. This guide shows two complementary workflows: 1. Compare an entity's daily timing trend with the network over the same UTC dates. 2. Profile your own validator set with a rolling 180-day timing label and histogram. **API Endpoints:** This guide uses [`/api/v2/ethereum/mev-timing`](/api-reference/ethereum/mev-timing), [`/api/v2/ethereum/entity/mev-timing`](/api-reference/ethereum/entity/mev-timing), and [`/api/v2/ethereum/validators/mev-timing-aggregate`](/api-reference/ethereum/validators/mev-timing-aggregate). The entity daily endpoint requires a Scale or Enterprise plan. You can query the validator aggregate with explicit validator identifiers or your dashboard on free plans. *** ## Comparison Strategy Use the daily network and entity series for like-for-like date comparisons, and use the validator aggregate when its rolling 180-day window matches your question. Report sample size and relay coverage with every result; inspect the distribution when a median could hide mixed behavior or long tails. API references: [Network timing](/api-reference/ethereum/mev-timing), [entity timing](/api-reference/ethereum/entity/mev-timing), and [validator aggregate](/api-reference/ethereum/validators/mev-timing-aggregate). Do not average daily medians to create a period median. Medians are not additive. Aggregate the histogram for an approximate period distribution, or use the validator aggregate when its rolling 180-day window matches your question. The timing bands describe pre-Glamsterdam slots and may change when Glamsterdam restructures slot production with ePBS. Relay timing is also offchain observation data, not independently verifiable onchain. Compare like-for-like protocol eras, report relay-data coverage, and treat missing observations as an uncertainty rather than evidence that no timing game occurred. *** ## Compare an Entity with the Network Request both daily series with the same timestamp range. The example uses June 2026 and a page size large enough to return all 30 days in one request. ### Network Request ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/mev-timing \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "range": { "timestamp": { "start": 1780272000, "end": 1782863999 } }, "min_slots_per_day": 100, "page_size": 100 } ' ``` ### Entity Request ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/entity/mev-timing \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "entity": "Lido", "range": { "timestamp": { "start": 1780272000, "end": 1782863999 } }, "page_size": 100 } ' ``` Entity and sub-entity names are case-sensitive. Get the canonical spelling from the [`entities`](/api-reference/ethereum/entities/overview) and [`entity/sub-entities`](/api-reference/ethereum/entity/sub-entities) endpoints. Add `"sub_entity": ""` to scope the second request. ### Calculate Daily Deltas with Python ```python theme={null} import os import requests BASE_URL = "https://beaconcha.in/api/v2/ethereum" HEADERS = { "Authorization": f"Bearer {os.environ['BEACONCHAIN_API_KEY']}", "Content-Type": "application/json", } RANGE = { "timestamp": { "start": 1780272000, "end": 1782863999, } } def post(path, payload): response = requests.post( f"{BASE_URL}/{path}", headers=HEADERS, json=payload, timeout=30 ) response.raise_for_status() return response.json()["data"] def timing_game_share(row): denominator = row["slots_with_relay_winners"] if denominator == 0: return None breakdown = row["timing_breakdown"] delayed = breakdown["timing_games"] + breakdown["aggressive_tg"] return delayed / denominator network_rows = post( "mev-timing", { "chain": "mainnet", "range": RANGE, "min_slots_per_day": 100, "page_size": 100, }, ) entity_rows = post( "entity/mev-timing", { "chain": "mainnet", "entity": "Lido", "range": RANGE, "page_size": 100, }, ) network_by_date = {row["date"]: row for row in network_rows} for entity_row in sorted(entity_rows, key=lambda row: row["date"]): network_row = network_by_date.get(entity_row["date"]) if network_row is None: continue entity_share = timing_game_share(entity_row) network_share = timing_game_share(network_row) if ( entity_share is None or network_share is None or entity_row["median_slot_offset_ms"] is None or network_row["median_slot_offset_ms"] is None ): continue median_delta = ( entity_row["median_slot_offset_ms"] - network_row["median_slot_offset_ms"] ) share_delta = entity_share - network_share print( entity_row["date"], f"median delta: {median_delta:+.0f} ms", f"timing-game share delta: {share_delta:+.2%}", f"entity sample: {entity_row['slots_with_relay_winners']}", ) ``` ### Calculate Daily Deltas with JavaScript This example uses the built-in `fetch` available in Node.js 18 and later. ```javascript theme={null} const baseUrl = 'https://beaconcha.in/api/v2/ethereum' const headers = { Authorization: `Bearer ${process.env.BEACONCHAIN_API_KEY}`, 'Content-Type': 'application/json', } const range = { timestamp: { start: 1780272000, end: 1782863999, }, } async function post(path, payload) { const response = await fetch(`${baseUrl}/${path}`, { method: 'POST', headers, body: JSON.stringify(payload), }) if (!response.ok) { throw new Error(`${response.status} ${await response.text()}`) } return (await response.json()).data } function timingGameShare(row) { const denominator = row.slots_with_relay_winners if (denominator === 0) return null const delayed = row.timing_breakdown.timing_games + row.timing_breakdown.aggressive_tg return delayed / denominator } const [networkRows, entityRows] = await Promise.all([ post('mev-timing', { chain: 'mainnet', range, min_slots_per_day: 100, page_size: 100, }), post('entity/mev-timing', { chain: 'mainnet', entity: 'Lido', range, page_size: 100, }), ]) const networkByDate = new Map(networkRows.map(row => [row.date, row])) for (const entityRow of entityRows.sort((a, b) => a.date.localeCompare(b.date))) { const networkRow = networkByDate.get(entityRow.date) if (!networkRow) continue const entityShare = timingGameShare(entityRow) const networkShare = timingGameShare(networkRow) if ( entityShare === null || networkShare === null || entityRow.median_slot_offset_ms === null || networkRow.median_slot_offset_ms === null ) continue const medianDelta = entityRow.median_slot_offset_ms - networkRow.median_slot_offset_ms const shareDelta = entityShare - networkShare console.log({ date: entityRow.date, median_delta_ms: medianDelta, timing_game_share_delta: shareDelta, entity_sample: entityRow.slots_with_relay_winners, }) } ``` Daily rows can have `median_slot_offset_ms: null` when there are no identified relay winners. The examples skip those rows before calculating deltas. *** ## Profile Your Validator Set Use the validator aggregate to summarize a validator list, dashboard, dashboard group, withdrawal credential, deposit address, entity, or sub-entity. Currently, the only supported evaluation window is `180d`. ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/mev-timing-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123, "group_id": 7 }, "evaluation_window": "180d" } ' ``` The following shortened response illustrates the comparison workflow. See the [validator timing aggregate reference](/api-reference/ethereum/validators/mev-timing-aggregate). ```json theme={null} { "data": { "timing_label": { "status": "timing_games", "median_slot_offset_ms": 1376, "total_count": 284 }, "histogram": [ { "slot_offset_ms_min": 1200, "slot_offset_ms_max": 1400, "count": 31, "max_value": "194000000000000000" } ], "evaluation_window": "180d" } } ``` Use the complete distribution to check whether the median reflects a tight cluster or hides a long aggressive tail. Create dashboard groups for infrastructure cohorts such as client, region, node, or relay configuration. Query each `group_id` separately to isolate where a timing shift originates. *** ## Comparison Checklist Compare daily rows only when their `date` values match. Do not compare a partial day with a complete day. Always show `slots_with_relay_winners` or `total_count` next to a median or percentage. A healthy median can coexist with aggressive outliers. Review histogram counts beyond 2,600 ms. Exclude the newest three daily buckets from finalized reports because they may still change. *** ## Related Resources * [MEV Analysis Introduction](/use-cases/mev-analysis-introduction) ā€” Endpoint selection, timing bands, and data freshness * [Investigate a Block](/use-cases/investigate-mev-block) ā€” Drill from an aggregate outlier into one proposal * [MEV Timing Games](/mev-timing-games/introduction) ā€” Why operators delay and what the thresholds mean * [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets) ā€” Organize validators into reusable groups # Embed BeaconScoreĀ® in Your Product Source: https://docs.beaconcha.in/use-cases/embed-beaconscore Integrate BeaconScoreĀ® metrics into your staking platform or application ## Overview BeaconScoreĀ® provides an independent, trusted metric for validator performance. By embedding BeaconScoreĀ® in your product, you can offer your users transparent performance data while keeping them in your ecosystem. **API Endpoint:** This guide uses [`/api/v2/ethereum/validators/performance-aggregate`](/api-reference/ethereum/validators/performance-aggregate) to fetch BeaconScoreĀ® metrics. BeaconScoreĀ® is a proprietary metric developed by beaconcha.in. Attribution is required when displaying BeaconScoreĀ® publicly. Enterprise plan users may be exempt from attribution requirements. *** ## Why Embed BeaconScoreĀ®? Provide users with trusted, third-party performance metrics that validate your operational quality. Use our robust API to build real-time visualizations without building your own indexing infrastructure. Keep customers in your platform by offering independent data within your UI. Differentiate your product with transparent performance reporting. *** ## Quick Start ### 1. Fetch BeaconScoreĀ® Data ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "validator_identifiers": [1, 2, 3] }, "range": { "evaluation_window": "30d" } } ' ``` ### 2. Display in Your UI ```json theme={null} { "data": { "beaconscore": { "total": 0.9945, "attestation": 0.9952, "proposal": 0.9876, "sync_committee": 0.9991 }, "duties": { "proposal": { "successful": 3, "missed": 0 } } } } ``` ### 3. Add Attribution Include the BeaconScoreĀ® badge when displaying the metric publicly: BeaconScoreĀ® *** ## Attribution Requirements **Required:** When displaying BeaconScoreĀ® data publicly in your application, website, or reports, you must include appropriate attribution using our official badges. ### BeaconScoreĀ® Badge Use when displaying BeaconScoreĀ® metrics: | Format | Light Mode | Dark Mode | | - | - | - | | SVG | `beaconscore_black.svg` | `beaconscore_white.svg` | | PNG | `beaconscore_black.png` | `beaconscore_white.png` | ### Powered by beaconcha.in Badge Use when your product uses any beaconcha.in API data: | Format | Light Mode | Dark Mode | | - | - | - | | SVG | `poweredby_black.svg` | `poweredby_white.svg` | | PNG | `poweredby_black.png` | `poweredby_white.png` | Download official badges in SVG and PNG formats **Enterprise Exemption:** Enterprise API plan users are exempt from attribution requirements. [Contact sales](https://beaconcha.in/pricing) for details. *** ## API Plans for Integration | Plan | Best For | BeaconScoreĀ® Access | | - | - | - | | **Scale** | Production integrations | Full access, attribution required | | **Enterprise** | White-label solutions | Full access, attribution optional | For high-volume integrations or white-label requirements, [contact our sales team](https://beaconcha.in/pricing). *** ## Related Resources * [Monitor Validator Performance](/use-cases/performance-introduction) ā€” BeaconScoreĀ® deep dive * [BeaconScoreĀ® Calculation](/beaconscore/introduction) ā€” How the metric is calculated * [License Materials](/legal/license-materials) ā€” Download official badges * [BeaconScoreĀ® License](/legal/beaconscore-license) ā€” Full terms and conditions # Introduction Source: https://docs.beaconcha.in/use-cases/entity-benchmarking-overview Rank, compare, and benchmark Ethereum staking entities using BeaconScoreĀ®, APY, and missed rewards ## Overview Compare recognized Ethereum staking entities by operational performance, returns, and missed rewards. Reproduce the metrics published on [beaconcha.in/entities](https://beaconcha.in/entities). **What is an entity?** An entity is a named staking operator (e.g. Lido, Coinbase, Figment) whose validators are publicly labeled in the beaconcha.in dataset. The Entity Benchmarking APIs let you query performance, APY, missed rewards, and network-relative standing for any labeled entity, or for your own private validator set. *** ## Guides in This Section Rank all public entities by BeaconScoreĀ®, net share, APY, or missed rewards. Includes pagination, filtering Unknown, and multi-window comparison. Compare one entity against the network baseline. Compute BeaconScoreĀ® deltas, APY vs network, missed reward efficiency, and drill into sub-entities. Use a validator dashboard as a private entity. Benchmark any unlabeled or custom validator set against the network baseline using the same methodology. *** ## Key Metrics The leaderboard and benchmarking guides use four metric families. Each is fetched from a different endpoint: | Metric | Endpoint | What it measures | Used in | | - | - | - | - | | **BeaconScoreĀ®** | [`entities`](/api-reference/ethereum/entities/overview) / [`performance-aggregate`](/api-reference/ethereum/performance-aggregate) | Attestation, proposal, sync committee efficiency (luck-normalized; see [residual factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors)) | [Rank entities](/use-cases/rank-and-compare-entities#step-1-fetch-ranked-entities), [Benchmark vs network](/use-cases/benchmark-entity-vs-network#step-1-get-the-entity-beaconscore), [Private benchmarking](/use-cases/private-entity-benchmarking-with-dashboard#step-2-fetch-private-entity-beaconscore) | | **APY / ROI** | [`validators/apy-roi`](/api-reference/ethereum/validators/apy-roi) | Annualized return, split by CL and EL | [Rank entities](/use-cases/rank-and-compare-entities#step-2-fetch-apy--roi-per-entity), [Benchmark vs network](/use-cases/benchmark-entity-vs-network#step-4-fetch-apy-and-compare-vs-network), [Private benchmarking](/use-cases/private-entity-benchmarking-with-dashboard#step-5-fetch-apy--roi-for-the-private-set) | | **Missed rewards** | [`validators/rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate) | ETH opportunity cost by duty type | [Rank entities](/use-cases/rank-and-compare-entities#step-3-fetch-missed-rewards-per-entity), [Benchmark vs network](/use-cases/benchmark-entity-vs-network#step-5-fetch-missed-rewards-and-compute-efficiency), [Private benchmarking](/use-cases/private-entity-benchmarking-with-dashboard#step-6-fetch-missed-rewards-for-the-private-set) | | **Network baseline** | [`performance-aggregate`](/api-reference/ethereum/performance-aggregate) (no entity filter) | Network-wide BeaconScoreĀ® for delta computation | [Rank entities](/use-cases/rank-and-compare-entities#step-4-fetch-the-network-baseline), [Benchmark vs network](/use-cases/benchmark-entity-vs-network#step-2-get-the-network-baseline), [Private benchmarking](/use-cases/private-entity-benchmarking-with-dashboard#step-3-fetch-network-baseline) | *** ## BeaconScoreĀ® Components BeaconScoreĀ® integrates three validator duty types weighted by their contribution to rewards: | Component | Weight | | - | - | | Attestation efficiency | 84.4% | | Proposal efficiency | 12.5% | | Sync committee efficiency | 3.1% | API references: [`entities`](/api-reference/ethereum/entities/overview) and [`performance-aggregate`](/api-reference/ethereum/performance-aggregate). Per-component efficiency can also be derived from [`rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate) earned/missed ratios. See [Rank entities: Step 5](/use-cases/rank-and-compare-entities#step-5-compute-derived-metrics) and [Benchmark vs network: Step 5](/use-cases/benchmark-entity-vs-network#step-5-fetch-missed-rewards-and-compute-efficiency) for the calculation. BeaconScoreĀ® and APY measure fundamentally different things. BeaconScoreĀ® is a **duty efficiency** metric (0-100%): a score of 100% means the validator earned the maximum possible rewards for every assigned duty. APY is a **financial return** metric that expresses the annualized yield on staked ETH (e.g., 3%). A validator can have a perfect BeaconScoreĀ® of 100% and an APY of 3% at the same time; these are not contradictory. BeaconScoreĀ® normalizes for proposal luck (though some [residual luck factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors) remain), making it the recommended metric for cross-entity performance comparison. APY is better suited for reporting absolute returns. See [BeaconScoreĀ® Calculation](/beaconscore/introduction) for the full formula and [BeaconScoreĀ® vs. 3rd Party Metrics](/beaconscore/BeaconScore-vs-3rd-party-metrics) for how BeaconScoreĀ® compares to other metrics. *** ## Missed Rewards Methodology Missed rewards quantify the **opportunity cost** of a validator failing a duty, not a balance penalty. All missed reward data comes from the [`rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate) endpoint. The leaderboard uses: ``` CL missed = attestation missed (head + source + target) + sync committee missed + proposal missed (CL portion) EL missed = proposal missed (EL portion, foregone MEV + tips) Total missed = CL missed + EL missed % of earned = total_missed / (total_missed + earned_gross) x 100 ``` `earned_gross` is `data.total_reward` from `rewards-aggregate` (gross, before penalties). Do **not** use `data.total` (net) for this calculation. All wei values returned by `rewards-aggregate` are JSON strings. Cast with `int(str(v))` before dividing by `1e18`. For step-by-step implementation, see [Rank entities: Step 3](/use-cases/rank-and-compare-entities#step-3-fetch-missed-rewards-per-entity), [Benchmark vs network: Step 5](/use-cases/benchmark-entity-vs-network#step-5-fetch-missed-rewards-and-compute-efficiency), or [Private benchmarking: Step 6](/use-cases/private-entity-benchmarking-with-dashboard#step-6-fetch-missed-rewards-for-the-private-set). For per-validator missed reward analysis, see [Analyze Missed Rewards](/use-cases/missed-rewards). *** ## vs Average Thresholds The leaderboard uses the following thresholds consistently across all comparisons (BeaconScoreĀ® total, all three components, and APY deltas). See these applied in [Rank entities: Step 5](/use-cases/rank-and-compare-entities#step-5-compute-derived-metrics), [Benchmark vs network: Step 3](/use-cases/benchmark-entity-vs-network#step-3-compute-beaconscore-delta), and [Private benchmarking: Step 4](/use-cases/private-entity-benchmarking-with-dashboard#step-4-compute-beaconscore-delta): | Color | Condition | | - | - | | šŸŸ¢ Green | `delta >= +0.0025` (+0.25 percentage points above network) | | šŸŸ” Yellow | `-0.0025 < delta < +0.0025` (within Ā±0.25pp of network) | | šŸ”“ Red | `delta <= -0.0025` (more than 0.25pp below network) | For missed reward efficiency (lower = better): | Color | Condition | | - | - | | šŸŸ¢ Green | `< 0.40%` of earned | | šŸŸ” Yellow | `0.40% ā€“ 0.60%` of earned | | šŸ”“ Red | `> 0.60%` of earned | *** ## Evaluation Windows All benchmarking endpoints support the same rolling windows: | Window | Typical use | | - | - | | `24h` | Incident detection | | `7d` | Weekly review | | `30d` | Monthly leaderboard (recommended) | | `90d` | Long-term trend analysis | Use consistent windows when comparing entities. `all_time` is not supported for entity endpoints. *** ## API Plan Requirements | Endpoint | Minimum plan | | - | - | | [`entities`](/api-reference/ethereum/entities/overview) | Scale | | [`entity/sub-entities`](/api-reference/ethereum/entity/sub-entities) | Scale | | [`validators/apy-roi`](/api-reference/ethereum/validators/apy-roi) with `entity` selector | Scale | | [`validators/rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate) with `entity` selector | Scale | | [`performance-aggregate`](/api-reference/ethereum/performance-aggregate) (network baseline) | Any | | [`validators/performance-aggregate`](/api-reference/ethereum/validators/performance-aggregate) with `dashboard_id` | Any | See [API Pricing](https://beaconcha.in/pricing) for plan details. *** ## Attribution If you display BeaconScoreĀ® publicly, follow the [BeaconScoreĀ® License](/legal/beaconscore-license) and [License Materials](/legal/license-materials). *** ## Related Resources * [Supported Entities List](https://beaconcha.in/entities) * [BeaconScoreĀ® vs. 3rd Party Metrics](/beaconscore/BeaconScore-vs-3rd-party-metrics) * [BeaconScoreĀ® Calculation](/beaconscore/introduction) * [APY & ROI Metrics](/use-cases/apy-roi) * [Analyze Missed Rewards](/use-cases/missed-rewards) * [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets#dashboard-as-private-sets) * [Validator Tagging](/validator-tagging/overview) # Overview Source: https://docs.beaconcha.in/use-cases/introduction Practical guides for common validator operations using the beaconcha.in V2 API ## Overview This section provides step-by-step guides for common validator operations. Each guide includes code examples, best practices, and links to the relevant API endpoints. Use-case guides focus on choosing endpoints, sequencing requests, and turning responses into operational decisions. *** ## Calculate Validator Rewards Track and calculate validator earnings across consensus and execution layers. Overview of reward endpoints, when to use aggregate vs. list APIs, and quick start examples. Get rewards for any date range ā€” a single aggregated call on Scale/Enterprise, or by iterating epochs for per-epoch detail. Get per-epoch rewards for tax reporting with fiat conversion guidance. Organize validators into groups and query by `dashboard_id` or `group_id`. Convert between epochs, timestamps, and local time zones. *** ## Monitor Validator Performance Track efficiency, identify issues, and measure returns. Understand BeaconScoreĀ® components and how to fetch performance metrics. Rank staking entities by BeaconScoreĀ®, validator count, network share, and distribution. Benchmark a selected entity against the network baseline and inspect sub-entities. Use dashboards as private entity definitions and benchmark them against network performance. Integrate BeaconScoreĀ® into your product with attribution guidelines. Identify lost rewards by duty type and quantify downtime costs. Calculate annual returns with execution/consensus layer breakdown. *** ## MEV Analysis Measure relay bid timing, compare operators and validator sets, and investigate individual proposals. Choose the right MEV timing endpoint and understand timing bands, histograms, and data freshness. Benchmark daily entity behavior against the network and profile your validator sets. Audit the winning bid, later alternatives, value left on the table, and full relay bid ladder. *** ## Track Queues & Operations Monitor network queues and plan validator operations. Overview of the Queue APIs, the staking queues, and how to choose an endpoint. Turn queue lengths and churn rates into activation and exit ETAs. Measure pending ETH in transit ā€” deposits awaiting activation and exits awaiting redemption. *** ## Quick Reference | Use Case | Best Endpoint | Description | | - | - | - | | Daily/weekly rewards summary | `rewards-aggregate` | Rolling periods (24h, 7d, 30d, 90d) | | Tax reporting | `rewards-list` | Per-epoch data for fiat conversion | | Performance comparison | `performance-aggregate` | BeaconScoreĀ® across groups | | Rank entities | `entities` | Compare staking entities by BeaconScoreĀ®, size, and network share | | Benchmark entity vs network | `entities`, `performance-aggregate` | Compare selected providers to network baseline and drill into sub-entities | | Benchmark private entities | `validators/performance-aggregate`, `performance-aggregate` | Use dashboard/group sets as private entities and compare against network | | Missed rewards analysis | `rewards-list` | Per-epoch missed reward breakdown | | APY/ROI calculation | `apy-roi` | Annualized return metrics | | Network MEV timing trends | `ethereum/mev-timing` | Daily timing breakdown and histogram | | Entity and validator MEV comparison | `entity/mev-timing`, `validators/mev-timing-aggregate` | Daily entity trends and 180-day validator profiles | | Block MEV investigation | `block/mev-timing`, `block/mev-bids` | Winning bid outcome and complete relay bid ladder | | Queue wait times | `ethereum/queues` | Network-wide queue statistics | | Pending ETH in transit | `ethereum/queues`, `validators/queues` | Deposit, exit, and withdrawal queue balances with ETAs | Each guide includes Python and JavaScript code examples. Look for the **API Endpoint** note at the top of each document to find the relevant API. # Investigate a Block Source: https://docs.beaconcha.in/use-cases/investigate-mev-block Audit the winning MEV bid, later alternatives, and complete relay bid ladder for an Ethereum block ## Overview Block-level MEV analysis answers two different questions: 1. **What was the outcome?** The block timing endpoint summarizes the selected bid and the best alternatives that arrived later. 2. **What did the proposer have available?** The bid endpoint returns every recorded relay bid in arrival order for research and auditing. **API Endpoints:** This guide uses [`/api/v2/ethereum/block/mev-timing`](/api-reference/ethereum/block/mev-timing) and [`/api/v2/ethereum/block/mev-bids`](/api-reference/ethereum/block/mev-bids). The timing summary is available to all API plans. The full bid ladder requires a Scale or Enterprise plan. The bid ladder is collected from offchain relay APIs and streams. Relay-reported arrival times, identities, and bids cannot be independently verified from onchain data, and missing or inconsistent relay observations can make the recorded ladder incomplete. Verify onchain fields such as the included block hash separately. *** ## Step 1: Fetch the Timing Outcome Resolve a block by execution-layer block number, or use the `latest` or `finalized` view. A recent `latest` block will usually return `pending` because per-slot MEV aggregates lag the chain head by about 4 hours. ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/block/mev-timing \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "block": { "number": 25378998 } } ' ``` An identified relay winner produces a response like this: ```json theme={null} { "data": { "status": "timing_games", "winning_bid": { "value": "118000000000000000", "slot_offset_ms": 2460, "relays": ["example-relay"], "builder_pubkey": null }, "first_better_bid": { "value": "121000000000000000", "slot_offset_ms": 2518, "status": "timing_games" }, "best_later_bid": { "value": "139000000000000000", "slot_offset_ms": 2784, "status": "aggressive_tg" }, "missed_value": "21000000000000000", "relay_count": 8, "bid_count": 436 } } ``` This is an illustrative response. Bid values, relay names, counts, and builder keys depend on the selected block. *** ## Interpret the Outcome See the [block timing API reference](/api-reference/ethereum/block/mev-timing). In this workflow, compare the included winner with the earliest better bid and the best later bid to distinguish the minimum additional wait from the maximum later opportunity observed. `missed_value` is hindsight, not guaranteed revenue. The proposer could not know which future bid would be best, and waiting for it would have increased propagation and orphan risk. *** For non-classified outcomes, follow the status-specific behavior in the API reference. Retry provisional results, and do not reinterpret unknown coverage as a non-MEV outcome. *** ## Step 2: Fetch the Bid Ladder The full bid ladder is ordered by arrival time and can contain many thousands of rows. Filter to the timing window you need, request up to 200 bids per page, and follow `paging.next_cursor` until it is empty. ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/block/mev-bids \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "block": { "number": 25378998 }, "slot_offset_ms_range": { "min": 2400, "max": 4000 }, "page_size": 200 } ' ``` See the [block MEV bids API reference](/api-reference/ethereum/block/mev-bids). *** ## Audit the Alternatives with Python This script fetches the summary, retrieves every later bid, and independently checks the earliest better and best later values. It keeps wei as integers until formatting the final ETH amounts. ```python theme={null} import os from decimal import Decimal import requests BASE_URL = "https://beaconcha.in/api/v2/ethereum" BLOCK_NUMBER = 25378998 HEADERS = { "Authorization": f"Bearer {os.environ['BEACONCHAIN_API_KEY']}", "Content-Type": "application/json", } def post(path, payload): response = requests.post( f"{BASE_URL}/{path}", headers=HEADERS, json=payload, timeout=30 ) response.raise_for_status() return response.json() selector = {"chain": "mainnet", "block": {"number": BLOCK_NUMBER}} summary = post("block/mev-timing", selector)["data"] winner = summary["winning_bid"] if winner is None: raise SystemExit(f"No identified winner: {summary['status']}") cursor = "" bids = [] while True: payload = { **selector, "slot_offset_ms_range": { "min": winner["slot_offset_ms"], "max": 4000, }, "page_size": 200, } if cursor: payload["cursor"] = cursor page = post("block/mev-bids", payload) if not page["ready"]: raise SystemExit("Bid data is still processing; retry later") bids.extend(page["data"]) cursor = page.get("paging", {}).get("next_cursor", "") if not cursor: break later_bids = [ bid for bid in bids if bid["slot_offset_ms"] is not None and bid["slot_offset_ms"] > winner["slot_offset_ms"] ] winning_value = int(winner["value"]) better_bids = [bid for bid in later_bids if int(bid["value"]) > winning_value] first_better = min(better_bids, key=lambda bid: bid["slot_offset_ms"], default=None) best_later = max(later_bids, key=lambda bid: int(bid["value"]), default=None) def eth(wei): return Decimal(wei) / Decimal(10**18) print("status:", summary["status"]) print("winner:", eth(winner["value"]), "ETH at", winner["slot_offset_ms"], "ms") print("first better:", first_better) print("best later:", best_later) print("missed value:", eth(summary["missed_value"]), "ETH") ``` *** ## Audit the Alternatives with JavaScript This Node.js 18+ example uses `BigInt` so bid values remain exact. ```javascript theme={null} const baseUrl = 'https://beaconcha.in/api/v2/ethereum' const blockNumber = 25378998 const headers = { Authorization: `Bearer ${process.env.BEACONCHAIN_API_KEY}`, 'Content-Type': 'application/json', } async function post(path, payload) { const response = await fetch(`${baseUrl}/${path}`, { method: 'POST', headers, body: JSON.stringify(payload), }) if (!response.ok) { throw new Error(`${response.status} ${await response.text()}`) } return response.json() } const selector = { chain: 'mainnet', block: { number: blockNumber } } const { data: summary } = await post('block/mev-timing', selector) const winner = summary.winning_bid if (!winner) { throw new Error(`No identified winner: ${summary.status}`) } let cursor = '' const bids = [] do { const payload = { ...selector, slot_offset_ms_range: { min: winner.slot_offset_ms, max: 4000, }, page_size: 200, ...(cursor && { cursor }), } const page = await post('block/mev-bids', payload) if (!page.ready) { throw new Error('Bid data is still processing; retry later') } bids.push(...page.data) cursor = page.paging?.next_cursor ?? '' } while (cursor) const laterBids = bids.filter(bid => bid.slot_offset_ms !== null && bid.slot_offset_ms > winner.slot_offset_ms, ) const winningValue = BigInt(winner.value) const betterBids = laterBids.filter(bid => BigInt(bid.value) > winningValue) const firstBetter = betterBids.reduce((first, bid) => !first || bid.slot_offset_ms < first.slot_offset_ms ? bid : first, null) const bestLater = laterBids.reduce((best, bid) => !best || BigInt(bid.value) > BigInt(best.value) ? bid : best, null) console.log({ status: summary.status, winner, first_better: firstBetter, best_later: bestLater, missed_value_wei: summary.missed_value, }) ``` Relay observations can contain duplicate economic bids from different sources or relays. The timing summary uses beaconcha.in's canonical aggregation. Treat the raw ladder as offchain observational audit data, not as a complete or independently verifiable record and not as a drop-in replacement for the summary fields. *** ## Best Practices Use `block/mev-timing` first. Fetch the full ladder only when the outcome needs deeper investigation. Restrict `slot_offset_ms_range` to the relevant interval to avoid downloading an unnecessarily large ladder. Parse values with Python integers, `Decimal`, JavaScript `BigInt`, or another arbitrary-precision type. Retry `pending` summaries and `ready: false` ladders after the roughly four-hour processing lag. *** ## Related Resources * [MEV Analysis Introduction](/use-cases/mev-analysis-introduction) ā€” Endpoint selection, timing bands, and freshness * [Compare MEV Timing](/use-cases/compare-mev-timing) ā€” Find aggregate outliers before drilling into blocks * [MEV Timing Games](/mev-timing-games/introduction) ā€” Winning, first better, and best later bids explained * [API Pagination](/api/pagination) ā€” Cursor handling for long bid ladders # Introduction Source: https://docs.beaconcha.in/use-cases/mev-analysis-introduction Analyze MEV timing behavior across the Ethereum network, entities, validator sets, and individual blocks ## Overview The MEV Timing APIs let you measure when winning relay bids arrive relative to the start of an Ethereum slot. Use them to track network trends, compare staking operators, profile your validators, or audit the bid ladder behind a single proposal. **API Endpoints:** This section covers the five MEV timing endpoints: | Endpoint | Best For | | - | - | | [`/api/v2/ethereum/mev-timing`](/api-reference/ethereum/mev-timing) | Daily network-wide timing trends | | [`/api/v2/ethereum/entity/mev-timing`](/api-reference/ethereum/entity/mev-timing) | Daily entity or sub-entity trends | | [`/api/v2/ethereum/validators/mev-timing-aggregate`](/api-reference/ethereum/validators/mev-timing-aggregate) | A 180-day timing profile for a validator set | | [`/api/v2/ethereum/block/mev-timing`](/api-reference/ethereum/block/mev-timing) | The winning and later-bid outcome for one block | | [`/api/v2/ethereum/block/mev-bids`](/api-reference/ethereum/block/mev-bids) | The complete relay bid ladder for one block | MEV relay and timing data is currently available on **mainnet only**. Relay bid collection began on **June 3, 2024 (UTC)**, so earlier periods do not have timing history. *** ## Guides in This Section Compare daily network and entity behavior, then profile a validator set over the rolling 180-day window. Inspect the winning bid, value left on the table, and the full relay bid ladder for one proposal. *** ## Interpret MEV Timing Data API references: [Network timing](/api-reference/ethereum/mev-timing) and [block timing](/api-reference/ethereum/block/mev-timing). When comparing results, use the same protocol era and report relay coverage alongside the timing outcome. The current classification thresholds describe pre-Glamsterdam slots; post-fork classifications may change as slot production changes. Read [MEV Timing Games](/mev-timing-games/introduction) for the slot clock, why the 1.2-second and 2.6-second thresholds matter, and how delay affects attesters. *** ## Choosing the Right Endpoint | Question | Endpoint | Result Shape | | - | - | - | | Is timing-game activity increasing across Ethereum? | `ethereum/mev-timing` | Paginated UTC daily series | | Is an operator's behavior changing over time? | `ethereum/entity/mev-timing` | Paginated UTC daily series for an entity or sub-entity | | What is the overall posture of my validators? | `validators/mev-timing-aggregate` | One timing label and a 22-bucket histogram for 180 days | | What happened in this proposal? | `block/mev-timing` | Winning bid, later alternatives, missed value, relay count, and bid count | | Which relay bids arrived, and when? | `block/mev-bids` | Paginated bid ladder ordered by arrival time | The entity daily series and full block bid ladder require a Scale or Enterprise plan. The validator aggregate accepts validator identifiers and dashboard selectors on free plans; address and entity selectors require Scale or Enterprise. *** ## Quick Start: Network Timing Trend Fetch a daily network series for June 2026. Timestamp ranges are inclusive and the endpoint buckets them into whole UTC days. ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/mev-timing \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "range": { "timestamp": { "start": 1780272000, "end": 1782863999 } }, "min_slots_per_day": 100, "page_size": 100 } ' ``` Each row contains exact category counts and a 22-bucket histogram. The illustrative response below shortens the histogram to two buckets: ```json theme={null} { "data": [ { "timestamp": 1780272000, "date": "2026-06-01", "slots_with_relay": 6812, "slots_with_relay_winners": 6475, "slots_without_relay": 388, "timing_breakdown": { "on_time_mev": 5118, "timing_games": 1214, "aggressive_tg": 143 }, "median_slot_offset_ms": 984, "histogram": [ { "slot_offset_ms_min": -200, "slot_offset_ms_max": 0, "count": 12, "max_value": "84000000000000000" }, { "slot_offset_ms_min": 0, "slot_offset_ms_max": 200, "count": 146, "max_value": "132000000000000000" } ] } ], "paging": { "next_cursor": "" }, "range": { "slot": { "start": 14453998, "end": 14669998 }, "epoch": { "start": 451687, "end": 458437 }, "timestamp": { "start": 1780272000, "end": 1782863999 } } } ``` For a daily row, the timing-game share among identified relay winners is: ```text theme={null} (timing_games + aggressive_tg) / slots_with_relay_winners ``` Use `slots_with_relay_winners` as the denominator when analyzing timing behavior. `slots_with_relay` and `slots_without_relay` measure relay-data coverage, not timing categories, and should not be added to `timing_breakdown`. *** ## Reporting Guidance For finalized reporting, exclude the newest three daily buckets. For a recent block, retry provisional results instead of treating them as evidence that no MEV occurred. The exact freshness and readiness behavior is documented on each linked API reference. Convert wei with integer or decimal arithmetic: `1 ETH = 10^18 wei`. Avoid binary floating-point for financial totals. *** ## Related Resources * [Compare MEV Timing](/use-cases/compare-mev-timing) ā€” Benchmark entities and validator sets against the network * [Investigate a Block](/use-cases/investigate-mev-block) ā€” Audit one proposal and its relay bid ladder * [MEV Timing Games](/mev-timing-games/introduction) ā€” Conceptual explanation of timing games and their risks * [API Pagination](/api/pagination) ā€” Follow cursors for daily series and bid ladders # Analyze Missed Rewards Source: https://docs.beaconcha.in/use-cases/missed-rewards Identify and quantify rewards lost due to missed or delayed validator duties ## Overview Missed rewards represent potential earnings your validators could have received if they had performed perfectly. Tracking missed rewards helps you identify issues, optimize performance, and quantify the cost of downtime or misconfigurations. **API Endpoint:** This guide uses [`/api/v2/ethereum/validators/rewards-list`](/api-reference/ethereum/validators/rewards-list) for per-epoch missed reward breakdowns. **See Also:** The [APY & ROI Metrics](/use-cases/apy-roi) endpoint also provides missed reward data as part of its return calculations. Use this document for detailed per-epoch analysis; use APY & ROI for aggregated impact on your returns. *** ## Why Track Missed Rewards? Identify which duty types (attestations, proposals, sync) are causing losses. Calculate the exact ETH lost during outages or maintenance windows. Compare missed rewards before/after configuration changes to measure improvements. Show customers transparent breakdowns of actual vs. potential earnings. See how missed rewards affect your overall APY & ROI using aggregated metrics. *** ## Understanding Missed Rewards This workflow focuses on diagnosing which duties contributed to lost earnings over time. See the [Rewards List API reference](/api-reference/ethereum/validators/rewards-list). **Missed vs Penalty:** Missed rewards are potential earnings you didn't receive. Penalties are actual deductions from your balance. Both reduce your net rewards, but penalties are more severe. *** ## Quick Start: Fetch Missed Rewards Get missed rewards for a specific epoch: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-list \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "epoch": 414000, "page_size": 10 } ' ``` ### Response ```json theme={null} { "data": [ { "validator": { "index": 123456, "public_key": "0xabc..." }, "total": "9103000000000", "total_reward": "9103000000000", "total_penalty": "0", "total_missed": "250000000000", "attestation": { "total": "9103000000000", "head": { "total": "2348000000000", "reward": "2348000000000", "penalty": "0", "missed_reward": "0" }, "source": { "total": "2364000000000", "reward": "2364000000000", "penalty": "0", "missed_reward": "0" }, "target": { "total": "4391000000000", "reward": "4391000000000", "penalty": "0", "missed_reward": "0" } }, "sync_committee": { "total": "0", "reward": "0", "penalty": "0", "missed_reward": "0" }, "proposal": { "total": "0", "missed_cl_reward": "0", "missed_el_reward": "0" } } ] } ``` ## Common Causes of Missed Rewards | Cause | Affected Duties | Solution | | - | - | - | | **Network latency** | Head votes | Reduce latency to beacon node, use local execution client | | **Node downtime** | All duties | Implement redundancy, monitoring, and failover | | **Missed proposals** | Proposals | Ensure MEV-boost and execution client are responsive | | **Sync committee offline** | Sync committee | Keep validators online during sync committee periods | | **Clock drift** | Attestations | Use NTP synchronization | Use the [Notifications](/notifications-monitoring/notifications) system to get alerts when validators miss duties. Early detection minimizes losses. *** ## Best Practices Track missed rewards weekly to catch degradation before it becomes significant. Alert when missed rewards exceed a percentage of total rewards (e.g., >0.1%). Use BeaconScoreĀ® for relative comparison; use missed rewards for absolute ETH impact. When missed rewards spike, check node logs, network status, and duty assignments. *** ## See Missed Rewards Impact on APY & ROI For a high-level view of how missed rewards affect your overall returns, use the [APY & ROI API](/use-cases/apy-roi). This endpoint provides aggregated missed reward data as part of its return calculations: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/apy-roi \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "dashboard_id": 123 }, "evaluation_window": "30d" }' ``` The following example uses the [APY & ROI API](/api-reference/ethereum/validators/apy-roi): ```json theme={null} { "data": { "execution_layer": { "roi": { "total": 0.0012, "missed": -0.0001 }, "apy": { "total": 0.0146, "missed": -0.0012 } }, "consensus_layer": { "roi": { "total": 0.0008, "missed": -0.00005 }, "apy": { "total": 0.0097, "missed": -0.0006 } } } } ``` **When to use which endpoint:** * Use **`rewards-list`** (this document) for detailed per-epoch missed reward breakdowns by duty type * Use **`apy-roi`** for aggregated impact on your overall returns as a percentage *** ## Related Resources * [Monitor Validator Performance](/use-cases/performance-introduction) ā€” BeaconScoreĀ® and efficiency metrics * [APY & ROI Metrics](/use-cases/apy-roi) ā€” Calculate return on investment * [Custom Range Rewards](/use-cases/rewards-custom-range) ā€” Calculate rewards for any date range * [Notifications](/notifications-monitoring/notifications) ā€” Set up alerts for missed duties # Introduction Source: https://docs.beaconcha.in/use-cases/performance-introduction Monitor validator performance using BeaconScoreĀ® and the Performance API ## Overview BeaconScoreĀ® is a transparent, comprehensive metric that measures how well your validators perform their duties. It combines attestations, block proposals, and sync committee participation into a single score. **API Endpoints:** This guide covers [`/api/v2/ethereum/validators/performance-aggregate`](/api-reference/ethereum/validators/performance-aggregate) for summary metrics and [`/api/v2/ethereum/validators/performance-list`](/api-reference/ethereum/validators/performance-list) for per-epoch breakdowns. BeaconScoreĀ® is designed to normalize for luckā€”validators with fewer block proposals aren't unfairly penalized. This makes it ideal for comparing performance across different validators, nodes, or client configurations. Note that some [residual luck factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors) outside a validator's control can still influence the score, especially over short evaluation windows. *** ## Why Monitor Performance? Spot underperforming validators before they significantly impact your rewards. Evaluate different client software, hardware setups, or network configurations. Provide transparent performance metrics to your staking customers. Track improvements over time and validate infrastructure changes. *** ## BeaconScoreĀ® Components BeaconScoreĀ® integrates three components weighted by their contribution to validator rewards: | Component | Weight | Description | | - | - | - | | **Attestations** | 84.4% | Head, source, and target votes each epoch (\~6.4 min) | | **Block Proposals** | 12.5% | CL rewards from proposed blocks (luck-normalized; see [residual factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors)) | | **Sync Committees** | 3.1% | Participation when elected to sync committee | Learn more about how each component is calculated in [BeaconScoreĀ®](/beaconscore/introduction). *** ## Benchmark Values | BeaconScoreĀ® | Rating | Action | | - | - | - | | ā‰„ 99.5% | Excellent | Optimal performance | | 99.0% - 99.5% | Good | Within acceptable range | | 98.0% - 99.0% | Fair | Minor issues, monitor closely | | \< 98.0% | Poor | Investigate immediately | *** ## Quick Start: Check Your Performance Get the aggregated BeaconScoreĀ® for your validators over the last 30 days: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "30d" } } ' ``` ### Response ```json theme={null} { "data": { "beaconscore": { "total": 0.9945, "attestation": 0.9952, "proposal": 0.9876, "sync_committee": 0.9991 }, "duties": { "attestation": { "included": 7983797, "assigned": 7985250, "missed": 1453 }, "proposal": { "successful": 229, "assigned": 231, "missed": 2 }, "sync_committee": { "successful": 134833, "assigned": 135818, "missed": 985 } } }, "range": { "epoch": { "start": 407453, "end": 414202 } } } ``` *** ## Per-Epoch Performance History For detailed analysis, query performance for specific epochs: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/performance-list \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "validator_identifiers": [1, 2, 3] }, "epoch": 413950, "page_size": 100 } ' ``` The `epoch` parameter is required for the performance-list endpoint. Use this to investigate specific time periods or track performance over time. *** ## Choose an Evaluation Window Use the same window for every value in a comparison. Available windows are `24h`, `7d`, `30d`, `90d`, and `all_time`. See the [Performance Aggregate API reference](/api-reference/ethereum/validators/performance-aggregate). On [Scale and Enterprise plans](https://beaconcha.in/pricing) you can also pass a custom `timestamp`, `epoch`, or `slot` range instead of a named window. Custom ranges are served at whole-UTC-day granularity, and the response `range` echoes the actual covered range. *** ## Best Practices Short windows are noisy due to [luck](/validator-dashboard/metric-validator-efficiency#residual-luck-factors). Use 30d or longer for meaningful comparisons. Create dashboard groups for each node, client, or geographic location. Configure [notifications](/notifications-monitoring/notifications) for performance drops. Schedule weekly or monthly performance reviews to catch gradual degradation. *** ## Deep Dive Guides Per-epoch breakdown of rewards lost due to missed duties. Diagnose issues by duty type (attestations, proposals, sync). Aggregated return metrics with EL/CL breakdown. Includes missed reward impact on overall APY. Integrate BeaconScoreĀ® into your product with attribution guidelines. *** ## Related Resources * [BeaconScoreĀ® Calculation](/beaconscore/introduction) ā€” Deep dive into the formula * [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets) ā€” Organize validators into groups * [Notifications](/notifications-monitoring/notifications) ā€” Set up performance alerts API references: [Performance Aggregated](/api-reference/ethereum/validators/performance-aggregate) and [Performance List](/api-reference/ethereum/validators/performance-list). # Private Entity Benchmarking with Dashboards Source: https://docs.beaconcha.in/use-cases/private-entity-benchmarking-with-dashboard Use validator dashboards as private entities and benchmark them against the network using the same methodology as public entity comparisons ## Overview Benchmark any validator set, including operators not in the public entity registry, against the network average using the same methodology as the public leaderboard. **API Endpoints:** This guide uses [`validators/performance-aggregate`](/api-reference/ethereum/validators/performance-aggregate), [`validators/apy-roi`](/api-reference/ethereum/validators/apy-roi), [`validators/rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate), and [`performance-aggregate`](/api-reference/ethereum/performance-aggregate). **Plan requirement:** `validators/performance-aggregate` with `dashboard_id`, `validators/apy-roi`, and `validators/rewards-aggregate` are available on all paid plans. `performance-aggregate` (network baseline) is available on all plans. **When to use this guide:** Use this when your validator set is not covered by the public entity registry, or when you need to benchmark an internal subset (e.g. a specific node operator, region, or client configuration) that does not correspond to a public entity. **Configurable evaluation window:** All examples below use `30d`, but you can change `evaluation_window` to `24h`, `7d`, `30d`, or `90d` depending on your use case. Use consistent windows across all calls in the same comparison. See [Evaluation Windows](/use-cases/entity-benchmarking-overview#evaluation-windows) for guidance. *** ## Why Use Dashboards as Private Entities? Define your own operator boundaries regardless of public label coverage. Useful for staking protocols, custodians, or infrastructure providers managing validators across multiple withdrawal credentials. The benchmark methodology (BeaconScoreĀ® delta, component efficiency, missed reward % of earned) is identical to the public entity leaderboard. You can produce comparable reports without being labeled in the public registry. Organize validators into dashboard groups by node, region, client, or team. Benchmark each group independently using `group_id`, mirroring the sub-entity drill-down available for public entities. Produce performance reports for customers or internal stakeholders using your own segmentation, with network-relative deltas as the baseline. *** ## Step 1: Define Your Private Entity Set Create a [Validator Dashboard](https://beaconcha.in/dashboard) and add the validators that constitute your private entity. Each dashboard can represent one entity; dashboard groups represent sub-entities. * Use **`dashboard_id`** for the full private entity set * Use **`dashboard_id` + `group_id`** for sub-entity benchmarking For setup, grouping workflows, and validator import methods, see [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets#dashboard-as-private-sets). **Unlabeled validators:** If your validators appear as `Unknown` in the public entity list, they are not assigned to any public entity. Using a dashboard is the correct approach for benchmarking these validators. See [Validator Tagging](/validator-tagging/overview) for information on label coverage. *** ## Step 2: Fetch Private Entity BeaconScoreĀ® Fetch the aggregated BeaconScoreĀ® for your dashboard: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "30d" } }' ``` For group-level benchmarking (sub-entity equivalent): ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "dashboard_id": 123, "group_id": 456 }, "range": { "evaluation_window": "30d" } }' ``` Use the total and component scores in the comparison below. See [Validator Performance Aggregate](/api-reference/ethereum/validators/performance-aggregate). *** ## Step 3: Fetch Network Baseline ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/performance-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "range": { "evaluation_window": "30d" } }' ``` Use `data.beaconscore.total` as the network baseline. Use the same `evaluation_window` as Step 2. *** ## Step 4: Compute BeaconScoreĀ® Delta ```python theme={null} delta_total = private_beaconscore - network_beaconscore d_att = private_attestation - network_attestation d_sync = private_sync - network_sync_committee d_prop = private_proposal - network_proposal ``` ### Threshold Reference | šŸŸ¢ Green | šŸŸ” Yellow | šŸ”“ Red | | - | - | - | | `delta >= +0.0025` | `-0.0025 < delta < +0.0025` | `delta <= -0.0025` | These thresholds apply to the total delta and all three component deltas. *** ## Step 5: Fetch APY / ROI for the Private Set ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/apy-roi \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "30d" } }' ``` Compare the combined, consensus-layer, and execution-layer APY totals against a network-level query with the validator selector omitted. Use the same Ā±0.25pp thresholds for coloring. See [APY & ROI](/api-reference/ethereum/validators/apy-roi). *** ## Step 6: Fetch Missed Rewards for the Private Set ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "30d" } }' ``` **Wei values are JSON strings.** All reward values from `rewards-aggregate` are returned as large integer strings. Always cast with `int(str(v))` before dividing by `1e18`. Apply the same missed rewards methodology used for public entities: ```python theme={null} def w(v): return int(str(v)) if v is not None else 0 d = response["data"] att = d["attestation"] sc = d["sync_committee"] prop = d["proposal"] m_cl_eth = (w(att["head"]["missed_reward"]) + w(att["source"]["missed_reward"]) + w(att["target"]["missed_reward"]) + w(sc["missed_reward"]) + w(prop["missed_cl_reward"])) / 1e18 m_el_eth = w(prop["missed_el_reward"]) / 1e18 m_total_eth = m_cl_eth + m_el_eth earned_eth = w(d["total_reward"]) / 1e18 # data.total_reward = gross (pre-penalty) pct_missed = m_total_eth / (m_total_eth + earned_eth) * 100 ``` ### Missed % of Earned Thresholds (lower = better) | šŸŸ¢ Green | šŸŸ” Yellow | šŸ”“ Red | | - | - | - | | `< 0.40%` | `0.40% ā€“ 0.60%` | `> 0.60%` | *** ## Example: Full Private Entity Benchmark Script (Python) ```python theme={null} import requests import time API_KEY = "" BASE = "https://beaconcha.in" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} WINDOW = "30d" DASHBOARD_ID = 123 def post(endpoint, payload): r = requests.post(f"{BASE}{endpoint}", headers=HEADERS, json=payload, timeout=30) r.raise_for_status() return r.json() def w(v): return int(str(v)) if v is not None else 0 # Step 1: Private entity BeaconScore perf = post("/api/v2/ethereum/validators/performance-aggregate", { "chain": "mainnet", "validator": {"dashboard_id": DASHBOARD_ID}, "range": {"evaluation_window": WINDOW}, }) priv_score = perf["data"]["beaconscore"]["total"] priv_att = perf["data"]["beaconscore"]["attestation"] priv_sync = perf["data"]["beaconscore"]["sync_committee"] priv_prop = perf["data"]["beaconscore"]["proposal"] # Step 2: Network baseline net = post("/api/v2/ethereum/performance-aggregate", { "chain": "mainnet", "range": {"evaluation_window": WINDOW}, }) NET = net["data"]["beaconscore"] delta = priv_score - NET["total"] print(f"BeaconScore: {priv_score*100:.4f}% | Network: {NET['total']*100:.4f}% | Delta: {delta*100:+.2f}pp") print(f" Att: {priv_att*100:.4f}% vs {NET['attestation']*100:.4f}% ({(priv_att-NET['attestation'])*100:+.2f}pp)") print(f" Sync: {priv_sync*100:.4f}% vs {NET['sync_committee']*100:.4f}% ({(priv_sync-NET['sync_committee'])*100:+.2f}pp)") print(f" Prop: {priv_prop*100:.4f}% vs {NET['proposal']*100:.4f}% ({(priv_prop-NET['proposal'])*100:+.2f}pp)") # Step 3: APY time.sleep(1) apy_r = post("/api/v2/ethereum/validators/apy-roi", { "chain": "mainnet", "validator": {"dashboard_id": DASHBOARD_ID}, "range": {"evaluation_window": WINDOW}, }) apy = apy_r["data"]["combined"]["apy"]["total"] cl_apy = apy_r["data"]["consensus_layer"]["apy"]["total"] el_apy = apy_r["data"]["execution_layer"]["apy"]["total"] print(f"\nAPY: {apy*100:.2f}% (CL: {cl_apy*100:.2f}%, EL: {el_apy*100:.2f}%)") # Step 4: Missed rewards time.sleep(1) rw = post("/api/v2/ethereum/validators/rewards-aggregate", { "chain": "mainnet", "validator": {"dashboard_id": DASHBOARD_ID}, "range": {"evaluation_window": WINDOW}, }) d = rw["data"] att = d["attestation"] sc = d["sync_committee"] prop = d["proposal"] m_cl_eth = (w(att["head"]["missed_reward"]) + w(att["source"]["missed_reward"]) + w(att["target"]["missed_reward"]) + w(sc["missed_reward"]) + w(prop["missed_cl_reward"])) / 1e18 m_el_eth = w(prop["missed_el_reward"]) / 1e18 m_total_eth = m_cl_eth + m_el_eth earned_eth = w(d["total_reward"]) / 1e18 pct_missed = m_total_eth / (m_total_eth + earned_eth) * 100 flag = "šŸŸ¢" if pct_missed < 0.40 else ("šŸ”“" if pct_missed > 0.60 else "šŸŸ”") print(f"\nMissed: {m_total_eth:.2f} ETH {flag} {pct_missed:.3f}% of earned") print(f" CL: {m_cl_eth:.2f} ETH | EL: {m_el_eth:.2f} ETH") ``` *** ## Multi-Group Benchmarking (Sub-Entity Pattern) To benchmark multiple internal groups in the same way public entity sub-entities are benchmarked, query each `group_id` independently and compare to the same network baseline: ```python theme={null} GROUP_IDS = [1, 2, 3] # your dashboard group IDs net_score = network_beaconscore # from performance-aggregate for gid in GROUP_IDS: perf = post("/api/v2/ethereum/validators/performance-aggregate", { "chain": "mainnet", "validator": {"dashboard_id": DASHBOARD_ID, "group_id": gid}, "range": {"evaluation_window": WINDOW}, }) score = perf["data"]["beaconscore"]["total"] delta = score - net_score flag = "šŸŸ¢" if delta >= 0.0025 else ("šŸ”“" if delta <= -0.0025 else "šŸŸ”") print(f"Group {gid}: {score*100:.4f}% {flag} {delta*100:+.2f}pp vs network") time.sleep(1) ``` *** ## Best Practices Longer windows reduce noise from proposal luck variance (see [residual luck factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors)). Use 30d as the minimum for meaningful comparisons. Keep group-to-infrastructure mappings consistent. Reorganizing groups mid-period makes historical deltas incomparable. Verify which validators are in each dashboard before publishing benchmark results. Validator exits, activations, or reassignments can silently change group composition. If your private set shows elevated EL APY, verify it reflects actual MEV outcomes (check proposal count) rather than a group composition issue. Store private-set vs network deltas over time. A persistent downward drift in delta (even within the yellow band) may indicate gradual infrastructure degradation before it becomes a visible issue. *** ## Related Resources * [Entity Benchmarking Overview](/use-cases/entity-benchmarking-overview) * [Rank and Compare Entities](/use-cases/rank-and-compare-entities) * [Benchmark Entity vs Network](/use-cases/benchmark-entity-vs-network) * [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets#dashboard-as-private-sets) * [APY & ROI Metrics](/use-cases/apy-roi) * [Analyze Missed Rewards](/use-cases/missed-rewards) * [BeaconScoreĀ® vs. 3rd Party Metrics](/beaconscore/BeaconScore-vs-3rd-party-metrics) * [Validator Tagging](/validator-tagging/overview) # Introduction Source: https://docs.beaconcha.in/use-cases/queue-tracking Overview of the Queue APIs ā€” track Ethereum's staking queues at network and validator level ## Overview Every state change in Ethereum staking passes through a queue: deposits wait to become active stake, exits wait to leave the active set, and withdrawn ETH waits for the sweep to credit it. The Queue APIs expose all of these queues ā€” network-wide and per validator ā€” with sizes, balances, churn rates, and estimated processing times. **API Endpoints:** This section covers [`/api/v2/ethereum/queues`](/api-reference/ethereum/queues) for network-wide queue statistics and [`/api/v2/ethereum/validators/queues`](/api-reference/ethereum/validators/queues) for per-validator queue positions. Queue data reflects the **current** state of the chain, and processing times are estimates based on the current churn rate. Balance values are returned in wei (1 ETH = 10Ā¹āø wei). *** ## Use Case Guides Activation and exit ETAs from queue lengths and churn rates ā€” for customer communication and operations planning. Measure pending ETH in transit ā€” deposits awaiting activation and exits awaiting redemption. *** ## The Queues at a Glance Use the network snapshot to compare pending inflows, outflows, withdrawal processing, consolidations, and compounding credential switches at the same point in time. See the [network queue API reference](/api-reference/ethereum/queues). *** ## Choosing the Right Endpoint | Endpoint | Best For | Response | | - | - | - | | **Network Queue Overview** (`/api/v2/ethereum/queues`) | Network totals: queue sizes, churn, overall wait times | Single object, one entry per queue | | **Validator Queue ETA** (`/api/v2/ethereum/validators/queues`) | Queue positions and ETAs for selected validators | Paginated list, one entry per validator | ### Use the Network Queue Overview endpoint when you need: * Network-wide queue lengths and total pending balances * Overall activation/exit wait-time estimates * A demand signal for staking analytics ### Use the Validator Queue ETA endpoint when you need: * Individual activation or exit ETAs for specific validators * Queue positions for your own fleet ā€” by index, public key, `dashboard_id`, or (on [Scale & Enterprise plans](https://beaconcha.in/pricing)) withdrawal credential, deposit address, or entity * Validators still in the deposit queue: select them by public key; `index` is `null` until activation *** ## Quick Start: Network Queue Snapshot ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/queues \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/vnd.beaconcha.in.v2.1+json' \ --data '{"chain": "mainnet"}' ``` ```json theme={null} { "data": { "deposit_queue": { "deposit_count": 1184, "deposit_balance": "37888000000000000000000", "topup_count": 243, "topup_balance": "1850000000000000000000", "estimated_processed_at": { "epoch": 454155, "timestamp": 1781099520 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "exit_queue": { "count": 420, "balance": "13440000000000000000000", "estimated_processed_at": { "epoch": 454053, "timestamp": 1781060352 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "manual_withdrawal_queue": { "count": 310, "balance": "5120000000000000000000", "estimated_processed_at": { "epoch": 454210, "timestamp": 1781120640 } }, "withdrawal_sweep": { "estimated_sweep_delay": 777600, "last_swept_validator_index": 1284503 }, "finality": "not_finalized" } } ``` The full response also includes the `consolidation_queue` and `compounding_switch_queue` (omitted above). See the [network queue API reference](/api-reference/ethereum/queues) and [Estimate Queue Wait Times](/use-cases/queue-wait-times). *** ## Related Resources * [Estimate Queue Wait Times](/use-cases/queue-wait-times) ā€” Read queue statistics and turn them into ETAs * [Staking Inflows & Outflows](/use-cases/staking-inflows-outflows) ā€” Measure pending ETH in transit * [Understanding Validator Queues](/faqs/understanding-validator-queues) ā€” How the queues work at the protocol level * [Deposit Process](/faqs/deposit-process) ā€” The full lifecycle of a deposit * [How Withdrawals Work](/faqs/how-withdrawals-work) ā€” Eligibility delay and the withdrawal sweep API references: [Network Queue Overview](/api-reference/ethereum/queues) and [Validator Queue ETA](/api-reference/ethereum/validators/queues). # Estimate Queue Wait Times Source: https://docs.beaconcha.in/use-cases/queue-wait-times Estimate validator activation and exit times from queue lengths and churn rates ## Overview Every deposit and exit waits in a queue before it takes effect. This guide shows how to read the network queue statistics, estimate how long a new deposit or exit will wait, and get individual ETAs for specific validators ā€” so you can give customers accurate timelines and plan operations. **API Endpoints:** This guide uses [`/api/v2/ethereum/queues`](/api-reference/ethereum/queues) for network-wide queue statistics and [`/api/v2/ethereum/validators/queues`](/api-reference/ethereum/validators/queues) for per-validator ETAs. *** ## Why Track Wait Times? Understand how long new deposits will take to activate based on current queue length. Provide accurate ETAs to staking customers for deposits and withdrawals. Monitor queue lengths to understand overall network staking demand. Plan validator exits based on current exit queue processing rate. *** ## Network Queue Statistics Get overall network queue lengths and processing rates: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/queues \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/vnd.beaconcha.in.v2.1+json' \ --data '{"chain": "mainnet"}' ``` ### Response ```json theme={null} { "data": { "deposit_queue": { "deposit_count": 1184, "deposit_balance": "37888000000000000000000", "topup_count": 243, "topup_balance": "1850000000000000000000", "estimated_processed_at": { "epoch": 454155, "timestamp": 1781099520 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "exit_queue": { "count": 420, "balance": "13440000000000000000000", "estimated_processed_at": { "epoch": 454053, "timestamp": 1781060352 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "manual_withdrawal_queue": { "count": 310, "balance": "5120000000000000000000", "estimated_processed_at": { "epoch": 454210, "timestamp": 1781120640 } }, "withdrawal_sweep": { "estimated_sweep_delay": 777600, "last_swept_validator_index": 1284503 }, "consolidation_queue": { "count": 18, "balance": "1152000000000000000000", "estimated_processed_at": { "epoch": 454060, "timestamp": 1781063040 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "compounding_switch_queue": { "count": 25, "estimated_processed_at": { "epoch": 454048, "timestamp": 1781058432 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "finality": "not_finalized" } } ``` *** ## Read the Queue Snapshot See the [network queue API reference](/api-reference/ethereum/queues) before applying the wait-time calculation below. *** ## Estimating a Wait Time `estimated_processed_at` tells you when the **last item currently in the queue** will be processed. A deposit or exit submitted *now* joins right behind it, so the same value doubles as the queue-join ETA: ``` wait ā‰ˆ queue balance / churn.amount Ɨ churn.interval_seconds ``` With the example numbers above, a new deposit waits: ``` (37,888 + 1,850) ETH Ć· 256 ETH per epoch ā‰ˆ 155 epochs Ɨ 384 s ā‰ˆ 16.6 hours ``` and a new exit waits `13,440 Ć· 256 ā‰ˆ 53 epochs ā‰ˆ 5.6 hours`. **Full exits take longer than the exit queue.** After leaving the active set, the balance waits through the withdrawal eligibility delay (\~27 hours) and the withdrawal sweep (`withdrawal_sweep.estimated_sweep_delay`) before it is credited. See [Staking Inflows & Outflows](/use-cases/staking-inflows-outflows) for the full redemption timeline. *** ## Per-Validator ETAs For individual validators ā€” including ones still in the deposit queue with no index yet ā€” query the per-validator overview: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/queues \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "validator_identifiers": ["0x93247f22...09abcaf5", 1284503] }, "page_size": 10 } ' ``` See the [Validator Queue ETA API reference](/api-reference/ethereum/validators/queues) and [Staking Inflows & Outflows](/use-cases/staking-inflows-outflows#per-validator-tracking). *** ## Best Practices Queue lengths change as validators enter and exit. Poll every 1-4 hours for accurate estimates. Queue processing speed varies with network conditions. Provide time ranges, not exact times. The churn rate determines how fast queues are processed. Track it to understand network capacity. *** ## Related Resources * [Introduction](/use-cases/queue-tracking) ā€” Overview of the Queue APIs and the staking queues * [Staking Inflows & Outflows](/use-cases/staking-inflows-outflows) ā€” Measure pending ETH in transit * [Understanding Validator Queues](/faqs/understanding-validator-queues) ā€” How the queues work at the protocol level * [How Withdrawals Work](/faqs/how-withdrawals-work) ā€” Eligibility delay and the withdrawal sweep * [Notifications](/notifications-monitoring/notifications) ā€” Set up alerts API references: [Network Queue Overview](/api-reference/ethereum/queues) and [Validator Queue ETA](/api-reference/ethereum/validators/queues). # Rank and Compare Entities Source: https://docs.beaconcha.in/use-cases/rank-and-compare-entities Rank public staking entities by BeaconScoreĀ®, APY, missed rewards, and network share ## Overview Rank all public staking entities on Ethereum and reproduce the metrics published in the monthly beaconcha.in leaderboard. **API Endpoints:** This guide uses [`/api/v2/ethereum/entities`](/api-reference/ethereum/entities/overview), [`/api/v2/ethereum/validators/apy-roi`](/api-reference/ethereum/validators/apy-roi), and [`/api/v2/ethereum/validators/rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate). **Premium access:** `entities`, `apy-roi` (with entity selector), and `rewards-aggregate` (with entity selector) require a Scale or Enterprise plan. **Attribution required:** If you display BeaconScoreĀ® publicly, follow the [BeaconScoreĀ® License](/legal/beaconscore-license) and [License Materials](/legal/license-materials). **Public labels vs private sets:** Entity labels are public mappings. For unlabeled validators or custom groupings, see [Private Entity Benchmarking with Dashboards](/use-cases/private-entity-benchmarking-with-dashboard). **Configurable evaluation window:** All examples below use `30d`, but you can change `evaluation_window` to `24h`, `7d`, `30d`, or `90d` depending on your use case. Use consistent windows across all calls in the same comparison. See [Evaluation Windows](/use-cases/entity-benchmarking-overview#evaluation-windows) for guidance. *** ## Why Compare Entities? Evaluate operational quality across staking providers before selecting integrations or partners. Track how entity rankings shift across windows to detect persistent vs. short-lived changes. Measure stake concentration using `net_share` and `validator_count`. Fetch the exact data behind the [@beaconcha\_in](https://x.com/beaconcha_in) monthly leaderboard posts using the steps below. *** ## Step 1: Fetch Ranked Entities Retrieve entities sorted by network share (the order used in the leaderboard): ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/entities \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "range": { "evaluation_window": "30d" }, "sort_by": "net_share", "sort_order": "desc", "page_size": 10 }' ``` **Filtering Unknown:** `page_size` maximum is 10. If `Unknown` appears in the first page, use the `paging.next_cursor` from the response to fetch the next page and complete your top-10 named entity list: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/entities \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "range": { "evaluation_window": "30d" }, "sort_by": "net_share", "sort_order": "desc", "page_size": 10, "cursor": "" }' ``` For a network-share leaderboard, sort descending by `net_share` as shown above. See the [Entities API reference](/api-reference/ethereum/entities/overview). *** ## Step 2: Fetch APY / ROI per Entity Query annualized returns for each entity. Run serially with a 1-second sleep between calls to avoid rate limits: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/apy-roi \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "entity": "Lido" }, "range": { "evaluation_window": "30d" } }' ``` Use the layer and combined totals. See [APY & ROI](/api-reference/ethereum/validators/apy-roi). **APY and BeaconScoreĀ® measure different things.** BeaconScoreĀ® is a duty efficiency metric (0-100%): a score of 100% means the validator earned the maximum possible rewards for every assigned duty. APY is a financial return metric expressing annualized yield on staked ETH (e.g., 3%). A validator can have a perfect BeaconScoreĀ® of 100% and an APY of 3% simultaneously; the two are not comparable on the same scale. Use BeaconScoreĀ® for operational performance comparison and APY for absolute return reporting. See [BeaconScoreĀ® vs. 3rd Party Metrics](/beaconscore/BeaconScore-vs-3rd-party-metrics). *** ## Step 3: Fetch Missed Rewards per Entity Query missed reward data per entity. Run serially with a 1-second sleep between calls: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "validator": { "entity": "Lido" }, "range": { "evaluation_window": "30d" } }' ``` Read the reward breakdown from the [Rewards Aggregated API reference](/api-reference/ethereum/validators/rewards-aggregate). Cast wei strings with `int(str(v))` before arithmetic, and divide by `1e18` only when formatting ETH. ### Missed Rewards Methodology ``` CL missed = att_head.missed + att_source.missed + att_target.missed + sync_committee.missed_reward + proposal.missed_cl_reward EL missed = proposal.missed_el_reward (foregone MEV + tips) Total missed = CL missed + EL missed % of earned = total_missed / (total_missed + total_reward_eth) x 100 ``` `inactivity_leak_penalty` is a penalty on earned rewards, not a missed opportunity. Exclude it from all missed reward totals. *** ## Step 4: Fetch the Network Baseline To compute "vs average" deltas, fetch the network-wide baseline over the same window: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/performance-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "chain": "mainnet", "range": { "evaluation_window": "30d" } }' ``` **Known behavior:** This endpoint does not accept an entity filter. It always returns network-wide data regardless of any entity parameter passed. Use `rewards-aggregate` component ratios to derive per-entity BeaconScoreĀ® component approximations. Use the total and component scores as the baseline values. See [Network Performance Aggregate](/api-reference/ethereum/performance-aggregate). *** ## Step 5: Compute Derived Metrics Once you have data from all three entity endpoints and the network baseline, compute the leaderboard metrics: ```python theme={null} # BeaconScore delta vs network delta_total = entity_beaconscore - NET_total # Per-component efficiency (derived from rewards-aggregate) # Cast all wei fields: int(str(v)) att_earned = (att_head_reward + att_src_reward + att_tgt_reward) / 1e18 att_missed = (m_head + m_src + m_tgt) / 1e18 att_eff = att_earned / (att_earned + att_missed) sync_earned = sync_reward / 1e18 sync_missed = m_sync / 1e18 sync_eff = sync_earned / (sync_earned + sync_missed) prop_cl_earned = (prop_att_incl + prop_sync_incl + prop_slash_incl) / 1e18 prop_cl_missed = m_pcl / 1e18 prop_eff = prop_cl_earned / (prop_cl_earned + prop_cl_missed) # Deltas vs network d_att = att_eff - NET_attestation d_sync = sync_eff - NET_sync_committee d_prop = prop_eff - NET_proposal # Missed reward totals m_cl = att_missed + sync_missed + (m_pcl / 1e18) m_total = m_cl + (m_pel / 1e18) earned = earned_gross / 1e18 # data.total_reward pct_missed = m_total / (m_total + earned) * 100 ``` ### "vs Average" Thresholds Applied consistently to BeaconScoreĀ® total, all three components, and APY deltas: | šŸŸ¢ Green | šŸŸ” Yellow | šŸ”“ Red | | - | - | - | | `delta >= +0.0025` | `-0.0025 < delta < +0.0025` | `delta <= -0.0025` | ### Missed % of Earned Thresholds (lower = better) | šŸŸ¢ Green | šŸŸ” Yellow | šŸ”“ Red | | - | - | - | | `< 0.40%` | `0.40% ā€“ 0.60%` | `> 0.60%` | *** ## Example: Full Leaderboard Script (Python) ```python theme={null} import requests import time import json API_KEY = "" BASE = "https://beaconcha.in" HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} WINDOW = "30d" def post(endpoint, payload): r = requests.post(f"{BASE}{endpoint}", headers=HEADERS, json=payload, timeout=30) r.raise_for_status() return r.json() def w(v): """Cast wei string/int to int.""" return int(str(v)) if v is not None else 0 # Step 1: Top 10 named entities by net share raw = post("/api/v2/ethereum/entities", { "chain": "mainnet", "range": {"evaluation_window": WINDOW}, "sort_by": "net_share", "sort_order": "desc", "page_size": 10, }) entities = [e for e in raw["data"] if e["entity"] != "Unknown"] # If Unknown was on the page, fetch more to complete 10 while len(entities) < 10 and "next_cursor" in raw.get("paging", {}): raw = post("/api/v2/ethereum/entities", { "chain": "mainnet", "range": {"evaluation_window": WINDOW}, "sort_by": "net_share", "sort_order": "desc", "page_size": 10, "cursor": raw["paging"]["next_cursor"], }) for e in raw["data"]: if e["entity"] != "Unknown": entities.append(e) if len(entities) >= 10: break entities = entities[:10] # Step 2: Network baseline net = post("/api/v2/ethereum/performance-aggregate", { "chain": "mainnet", "range": {"evaluation_window": WINDOW}, }) NET = net["data"]["beaconscore"] # Steps 3 & 4: APY and missed rewards per entity results = [] for e in entities: name = e["entity"] try: apy_r = post("/api/v2/ethereum/validators/apy-roi", { "chain": "mainnet", "validator": {"entity": name}, "range": {"evaluation_window": WINDOW}, }) apy = apy_r["data"]["combined"]["apy"]["total"] cl_apy = apy_r["data"]["consensus_layer"]["apy"]["total"] el_apy = apy_r["data"]["execution_layer"]["apy"]["total"] roi = apy_r["data"]["combined"]["roi"]["total"] except Exception: apy = cl_apy = el_apy = roi = None time.sleep(1) try: rw = post("/api/v2/ethereum/validators/rewards-aggregate", { "chain": "mainnet", "validator": {"entity": name}, "range": {"evaluation_window": WINDOW}, }) d = rw["data"] att = d["attestation"] sc = d["sync_committee"] prop = d["proposal"] # Earned att_head_r = w(att["head"]["reward"]) att_src_r = w(att["source"]["reward"]) att_tgt_r = w(att["target"]["reward"]) sync_r = w(sc["reward"]) prop_cl_e = w(prop["attestation_inclusion_reward"]) + \ w(prop["sync_inclusion_reward"]) + \ w(prop["slashing_inclusion_reward"]) earned_gross = w(d["total_reward"]) # Missed m_head = w(att["head"]["missed_reward"]) m_src = w(att["source"]["missed_reward"]) m_tgt = w(att["target"]["missed_reward"]) m_sync = w(sc["missed_reward"]) m_pcl = w(prop["missed_cl_reward"]) m_pel = w(prop["missed_el_reward"]) # Compute att_eff = (att_head_r + att_src_r + att_tgt_r) / \ (att_head_r + att_src_r + att_tgt_r + m_head + m_src + m_tgt) sync_eff = sync_r / (sync_r + m_sync) if (sync_r + m_sync) > 0 else 0 prop_eff = prop_cl_e / (prop_cl_e + m_pcl) if (prop_cl_e + m_pcl) > 0 else 0 m_cl_eth = (m_head + m_src + m_tgt + m_sync + m_pcl) / 1e18 m_total_eth = m_cl_eth + m_pel / 1e18 earned_eth = earned_gross / 1e18 pct_missed = m_total_eth / (m_total_eth + earned_eth) * 100 except Exception: att_eff = sync_eff = prop_eff = None m_total_eth = m_cl_eth = pct_missed = None time.sleep(1) delta = e["beaconscore"] - NET["total"] results.append({ "rank": len(results) + 1, "entity": name, "beaconscore": e["beaconscore"], "net_share": e["net_share"], "delta": delta, "apy": apy, "cl_apy": cl_apy, "el_apy": el_apy, "att_eff": att_eff, "sync_eff": sync_eff, "prop_eff": prop_eff, "m_total": m_total_eth, "m_cl": m_cl_eth, "pct_missed": pct_missed, }) # Print summary print(f"{'#':<3} {'Entity':<20} {'Score':>10} {'vs Avg':>10} {'APY':>8} {'Missed%':>10}") for r in results: score = f"{r['beaconscore']*100:.4f}%" delta = f"{r['delta']*100:+.2f}pp" apy = f"{r['apy']*100:.2f}%" if r['apy'] else "/" miss = f"{r['pct_missed']:.3f}%" if r['pct_missed'] is not None else "/" print(f"{r['rank']:<3} {r['entity']:<20} {score:>10} {delta:>10} {apy:>8} {miss:>10}") ``` *** ## Compare Across Time Windows Run the same query across windows to identify persistent vs. short-lived performance changes: | Window | Typical use | | - | - | | `24h` | Incident detection | | `7d` | Weekly review | | `30d` | Monthly benchmarking (leaderboard default) | | `90d` | Long-term trend analysis | *** ## Best Practices Always exclude `entity == "Unknown"` before ranking. Unknown validators are unlabeled and may skew concentration metrics. EL APY scales with proposal luck in short windows. Use BeaconScoreĀ® as the primary efficiency metric (see [residual luck factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors)). V1 and V2 API calls share one combined rate limit bucket. Sleep 1 second between serial `apy-roi` and `rewards-aggregate` calls. If you receive a 429, read the `ratelimit-reset` header and wait before retrying. Export ranking snapshots periodically for trend reporting and incident investigation. *** ## Related Resources * [Entity Benchmarking Overview](/use-cases/entity-benchmarking-overview) * [Benchmark Entity vs Network](/use-cases/benchmark-entity-vs-network) * [Private Entity Benchmarking with Dashboards](/use-cases/private-entity-benchmarking-with-dashboard) * [APY & ROI Metrics](/use-cases/apy-roi) * [Analyze Missed Rewards](/use-cases/missed-rewards) * [BeaconScoreĀ® vs. 3rd Party Metrics](/beaconscore/BeaconScore-vs-3rd-party-metrics) * [Supported Entities List](https://beaconcha.in/entities) * [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets#dashboard-as-private-sets) # Custom Range Rewards Source: https://docs.beaconcha.in/use-cases/rewards-custom-range Get validator rewards for any custom epoch or date range ā€” a single aggregated call on Scale/Enterprise, or per-epoch iteration for finer detail ## Overview There are two ways to get rewards for a **specific date range** that doesn't match the predefined evaluation windows (`24h`, `7d`, `30d`, `90d`, `all_time`): A single [Rewards Aggregated](/api-reference/ethereum/validators/rewards-aggregate) call with an explicit `timestamp`, `epoch`, or `slot` range. Requires a [Scale or Enterprise plan](https://beaconcha.in/pricing). Served at whole-UTC-day granularity. Iterate each epoch with the [Rewards List](/api-reference/ethereum/validators/rewards-list) endpoint. Works on any plan and returns per-epoch values ā€” needed for finer-than-daily detail and tax reporting. *** ## Aggregated Custom Range šŸ’Ž With a [Scale or Enterprise plan](https://beaconcha.in/pricing), pass an explicit range to `rewards-aggregate` to get a single total for that period ā€” no epoch iteration required. Specify the range by `timestamp` (Unix seconds), `epoch`, or `slot`. ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "timestamp": { "start": 1710460800, "end": 1719705600 } } } ' ``` **Whole-UTC-day granularity:** Aggregated custom ranges are rounded outward to whole UTC days ā€” the query covers every UTC day your range touches. The response `range` echoes the range actually covered by the returned data. It can be wider than requested (outward day expansion) or narrower: leading or trailing days with no data for the selected validators do not extend the range. For sub-day precision or per-epoch values, use per-epoch iteration below. *** ## Per-Epoch Iteration When you need per-epoch values ā€” finer-than-daily precision, per-epoch fiat conversion, or you're on a plan without custom-range aggregation ā€” iterate each epoch using the **Rewards List** endpoint. **API Usage Consideration:** Each epoch requires a separate API call. A full month contains \~6,750 epochs, and a full year contains \~82,000 epochs. Ensure your API plan supports this volume of requests. **API Endpoint:** This approach uses [`/api/v2/ethereum/validators/rewards-list`](/api-reference/ethereum/validators/rewards-list) for per-epoch reward data. *** ## When to Use Each Approach | Scenario | Approach | | - | - | | Last 30 days summary (total only) | Use `rewards-aggregate` with `30d` āœ… | | All-time rewards (total only) | Use `rewards-aggregate` with `all_time` āœ… | | Specific month total (e.g., March 2024) šŸ’Ž | Use `rewards-aggregate` with a custom range āœ… | | Q1 total (Jan 1 - Mar 31) šŸ’Ž | Use `rewards-aggregate` with a custom range āœ… | | **Tax reporting (any year)** | Iterate epochs with `rewards-list` āš ļø | | Per-epoch data for fiat conversion | Iterate epochs with `rewards-list` āš ļø | | Sub-day / exact-epoch precision | Iterate epochs with `rewards-list` āš ļø | **Tax Calculations:** Even if your validators started during the tax year, you still need per-epoch data to calculate fiat values at the time rewards were received. Neither the `all_time` nor a custom-range aggregate can be used for tax purposes, because both return a single summed total rather than per-epoch amounts. See [Tax Year Calculations](/use-cases/rewards-tax-calculations) for complete tax guidance. *** ## Per-Epoch Iteration Performance These estimates apply to the **per-epoch iteration** approach (the aggregated custom range is a single call). They compare processing time between the **Free Trial** (1 req/s) and **Scale** plan (5 req/s): | Range | Epochs | Est. API Calls | Est. Time (Free) | Est. Time (Scale) | | - | - | - | - | - | | 1 day | \~225 | \~225 | \~4-5 min | \~1 min | | 1 week | \~1,575 | \~1,575 | \~25-30 min | \~5-6 min | | 1 month | \~6,750 | \~6,750 | \~2 hours | \~25 min | | 1 quarter | \~20,250 | \~20,250 | \~6 hours | \~1 hour | | 1 year | \~82,000 | \~82,000 | \~23 hours | \~4-5 hours | **Optimize API Usage:** For large ranges, consider: * **Use dashboards and groups** ā€” Query all validators in a dashboard with a single `dashboard_id` or filter by `group_id`, reducing the need for multiple requests per epoch * **Run calculations during off-peak hours** ā€” Better API response times * **Use parallel requests** ā€” Respecting your plan's rate limits **Upgrade for Faster Processing:** [Scale](https://beaconcha.in/pricing) offers 5 req/sec, while [Enterprise plans](https://beaconcha.in/pricing) offer custom limits for high-volume needs. *** ## Related Resources * [Introduction](/use-cases/rewards-introduction) ā€” Overview and endpoint comparison * [Tax Year Calculations](/use-cases/rewards-tax-calculations) ā€” Specific guidance for annual tax reporting * [Epoch & Time Zone Conversion](/use-cases/rewards-epoch-conversion) ā€” Detailed epoch/timestamp math * [Pagination Guide](/api/pagination) ā€” Handling paginated responses API references: [Rewards Aggregated](/api-reference/ethereum/validators/rewards-aggregate) and [Rewards List](/api-reference/ethereum/validators/rewards-list). # Dashboard as Private Sets Source: https://docs.beaconcha.in/use-cases/rewards-dashboard-private-sets Use the Validator Dashboard to organize validators into queryable groups ## Overview Instead of manually tracking validator indices, you can use the [Validator Dashboard](https://beaconcha.in/dashboard) to create **private sets** of validators. Once configured, query your entire dashboard or specific groups using a single `dashboard_id`. **Validator Selector:** The `dashboard_id` and `group_id` selectors work with validator endpoints including [`rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate), [`rewards-list`](/api-reference/ethereum/validators/rewards-list), and [`performance-aggregate`](/api-reference/ethereum/validators/performance-aggregate). *** ## Why Use Dashboard Selectors? Create custom validator groups to represent nodes, servers, or client configurations. Query rewards for each group separately using `group_id`. With [premium or Add-on subscriptions](https://beaconcha.in/premium), your dashboard can scale up to 320,000+ ETH in stake. Add validators once to your dashboard, then query by `dashboard_id` without maintaining lists of indices. The dashboard UI provides real-time slot visualization and performance metrics alongside API access. *** ## Setting Up Your Dashboard ### Step 1: Create a Dashboard Visit [beaconcha.in/dashboard](https://beaconcha.in/dashboard) and create a new dashboard. ### Step 2: Add Validators You can add validators using multiple methods: | Method | Description | Best For | | - | - | - | | Validator indices | Enter indices like `1, 2, 3` | Small sets | | Public keys | Enter full public keys | Specific validators | | Deposit address | All validators from an address | Operators | | Withdrawal credentials | All validators with same credentials | Staking pools | | Graffiti matching | Validators with specific graffiti | Node operators | ### Step 3: Create Groups (Optional) Organize validators into groups to represent: * Different nodes or servers * Different client configurations (Lighthouse, Prysm, Teku, etc.) * Geographic locations * Customer segments Groups must currently be created through the [Dashboard UI](/validator-dashboard/validator-groups). Once created, you can manage validators within groups using the [Dashboard Management APIs](/validator-dashboard/manage-validators-api). *** ## Finding Your IDs ### Dashboard ID Your Dashboard ID is visible in the URL: ``` https://beaconcha.in/dashboard/123 ^^^ Dashboard ID ``` ### Group ID To find your Group ID: 1. Go to your [Validator Dashboard](https://beaconcha.in/dashboard) 2. Click the **Manage Groups** button (grid icon) in the dashboard header 3. In the modal that opens, you'll see a list of all your groups 4. The **Group ID** is displayed next to each group name The default group (containing validators not assigned to any specific group) has Group ID `0`. *** ## Querying Rewards by Dashboard Query rewards for **all validators** in your dashboard: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "30d" } } ' ``` *** ## Querying Rewards by Group Query rewards for a **specific group** within your dashboard by adding `group_id` to your request: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123, "group_id": 456 }, "range": { "evaluation_window": "all_time" } } ' ``` *** ## Managing Your Dashboard via API Once your dashboard and groups are set up, you can programmatically manage validators: | Action | Endpoint | Documentation | | - | - | - | | Add validators | `POST /api/i/validator-dashboards/{id}/validators` | [API Reference](/validator-dashboard/manage-validators-api-endpoints/validators_post) | | Remove from group | `DELETE /api/i/validator-dashboards/{id}/groups/{gid}/validators` | [API Reference](/validator-dashboard/manage-validators-api-endpoints/groups_delete) | | Bulk delete | `POST /api/i/validator-dashboards/{id}/validators/bulk-deletions` | [API Reference](/validator-dashboard/manage-validators-api-endpoints/validators_bulk_delete_post) | Dashboard management APIs require an [Orca subscription](https://beaconcha.in/premium). *** ## Dashboard Tiers Dashboard capacity is based on **Max Stake (ETH)**, not validator count: | Tier | Max Stake | Dashboards | Price/mo | Best For | | - | - | - | - | - | | Free | ā€” | 1 | Free | Individual stakers | | Guppy | 3,200 ETH | 1 | ā‚¬8.99\* | Small operators | | Dolphin | 9,600 ETH | 2 | ā‚¬25.99\* | Professional operators | | Orca | 32,000 ETH | 2 | ā‚¬39.99\* | Large operators | \*Prices for annual billing, excluding VAT ### Premium Add-Ons Need more capacity? Add-ons stack on top of your base tier: | Add-On | Extra Capacity | Price/mo | | - | - | - | | +32,000 ETH | +32,000 ETH per dashboard | ā‚¬59.99\* | | +320,000 ETH | +320,000 ETH per dashboard | ā‚¬359.99\* | Upgrade at [beaconcha.in/premium](https://beaconcha.in/premium) to increase your dashboard capacity. Contact [support](https://beaconcha.in/pricing) for even higher limits. *** ## Best Practices Use `dashboard_id` to query all validators, or add `group_id` to filter by a specific group. Create groups by node, client, or geographic location to isolate performance metrics. Name groups clearly so API results are easy to interpret and report on. Periodically verify your dashboard contains all expected validators. *** ## Related Resources * [Introduction](/use-cases/rewards-introduction) ā€” Overview and endpoint comparison * [Validator Dashboard Introduction](/validator-dashboard/introduction) ā€” Full dashboard documentation * [Validator Groups](/validator-dashboard/validator-groups) ā€” Creating and managing groups * [Dashboard Management APIs](/validator-dashboard/manage-validators-api) ā€” API reference # Epoch & Time Zone Conversion Source: https://docs.beaconcha.in/use-cases/rewards-epoch-conversion Convert between Ethereum epochs, timestamps, and local time zones for rewards calculations ## Overview The beaconcha.in API provides some data indexed by epoch. To better understand the relationship between time and epochs, you can use the [Slot Finder](https://beaconcha.in/slots/finder) tool and the time constants provided below. We are developing endpoints designed to streamline the retrieval of summarized data for user-defined periods. Manually summing up rewards epoch-by-epoch doesn't scale well for many validators over long timeframes. *** ## Ethereum Time Constants | Constant | Value | Description | | - | - | - | | Genesis Timestamp | `1606824023` | December 1, 2020, 12:00:23 UTC | | Seconds per Slot | `12` | Time between slots | | Slots per Epoch | `32` | Slots in one epoch | | Seconds per Epoch | `384` | 32 Ɨ 12 seconds | | Epochs per Day | `225` | 86,400 / 384 | | Epochs per Year | `~82,125` | 365 Ɨ 225 | *** ## Related Resources * [Introduction](/use-cases/rewards-introduction) ā€” Overview and endpoint comparison * [Custom Range Rewards](/use-cases/rewards-custom-range) ā€” Calculate rewards for any date range * [Tax Year Calculations](/use-cases/rewards-tax-calculations) ā€” Calculate rewards for specific tax years # Introduction Source: https://docs.beaconcha.in/use-cases/rewards-introduction Learn how to calculate validator rewards (CL + EL) using the V2 API ## Overview The beaconcha.in V2 API provides comprehensive validator rewards data including consensus layer (CL) attestation, sync committee, and proposal rewards, plus execution layer (EL) MEV and tips. **API Endpoints:** This guide covers [`/api/v2/ethereum/validators/rewards-aggregate`](/api-reference/ethereum/validators/rewards-aggregate) for quick summaries and [`/api/v2/ethereum/validators/rewards-list`](/api-reference/ethereum/validators/rewards-list) for per-epoch breakdowns. All rewards data is available only for **finalized epochs**. Values are returned in wei (1 ETH = 10Ā¹āø wei). *** ## Quick Start Guides Get rewards for any date range ā€” a single aggregated call on Scale/Enterprise, or by iterating epochs for per-epoch detail. Calculate per-epoch rewards for Jan 1 ā€“ Dec 31 with fiat conversion for tax reporting. Query validators by `dashboard_id` or filter by `group_id` instead of tracking indices. Convert between epochs, timestamps, and local time zones for precise date calculations. *** ## Choosing the Right Endpoint | Endpoint | Best For | Response | | - | - | - | | **Rewards Aggregated** | Quick summaries over fixed windows (24h, 7d, 30d, 90d, all\_time) or a custom date range šŸ’Ž | Single aggregated result | | **Rewards List** | Per-epoch breakdowns, per-epoch fiat/tax calculations | Paginated list per epoch | ### Use Rewards Aggregated when you need: * Total rewards for the last 24h, 7d, 30d, 90d, or all time * Total rewards for a custom date range (šŸ’Ž Scale or Enterprise plans; served at whole-UTC-day granularity) * A quick summary without iterating through epochs * Aggregated data for multiple validators combined ### Use Rewards List when you need: * Epoch-by-epoch reward breakdown for a specific epoch * Individual validator rewards per epoch * Per-epoch fiat conversion for tax reporting (see [Tax Year Calculations](/use-cases/rewards-tax-calculations)) * Custom date ranges on any plan, or at finer-than-daily granularity (requires iterating epochs) *** ## Rewards Aggregated Endpoint Returns cumulative rewards for validators over a fixed evaluation window, or over a custom date range on [Scale and Enterprise plans](https://beaconcha.in/pricing). ### Basic Example ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "validator_identifiers": [1, 2, 3, 4, 5] }, "range": { "evaluation_window": "30d" } } ' ``` See the [Rewards Aggregated API reference](/api-reference/ethereum/validators/rewards-aggregate). ### Using Dashboard Selector Query all validators in your [Validator Dashboard](/use-cases/rewards-dashboard-private-sets): ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "all_time" } } ' ``` ### Custom Date Range šŸ’Ž With a [Scale or Enterprise plan](https://beaconcha.in/pricing), pass an explicit `timestamp`, `epoch`, or `slot` range instead of an evaluation window. Custom ranges are served at whole-UTC-day granularity: any UTC day the range touches is returned in full, and the response `range` echoes the actual covered range. ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "timestamp": { "start": 1706000000, "end": 1709000000 } } } ' ``` ### Response Structure ```json theme={null} { "data": { "total": "12345678901234567890", "total_reward": "12400000000000000000", "total_penalty": "54321098765432110", "total_missed": "100000000000000000", "attestation": { "source": { "total": "...", "reward": "...", "penalty": "...", "missed": "..." }, "target": { "total": "...", "reward": "...", "penalty": "...", "missed": "..." }, "head": { "total": "...", "reward": "...", "penalty": "...", "missed": "..." } }, "sync_committee": { "total": "...", "reward": "...", "penalty": "...", "missed": "..." }, "proposal": { "total": "...", "execution_layer_reward": "...", "attestation_inclusion_reward": "...", "sync_inclusion_reward": "...", "slashing_inclusion_reward": "...", "missed_cl_reward": "...", "missed_el_reward": "..." } }, "range": { "epoch": { "start": 123456, "end": 234567 }, "timestamp": { "start": 1706000000, "end": 1709000000 } } } ``` **PRO Feature:** With a [Scale or Enterprise plan](https://beaconcha.in/pricing), query by `withdrawal` address or `deposit_address` instead of individual indices. The validator set for these selectors updates once per epoch (\~6.4 minutes). *** ## Rewards List Endpoint Returns per-validator rewards for a **specific epoch**. Requires iteration for per-epoch detail over a date range. The `epoch` parameter is **required** for this endpoint. To get per-epoch rewards over a date range, iterate through each epoch ā€” or, on [Scale and Enterprise plans](https://beaconcha.in/pricing), get the range total in one call with `rewards-aggregate` (daily granularity). See [Custom Range Rewards](/use-cases/rewards-custom-range) for both approaches. ### Basic Example ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-list \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "validator_identifiers": [1, 2, 3, 4, 5] }, "epoch": 413950, "page_size": 100 } ' ``` ### Pagination See the [Rewards List API reference](/api-reference/ethereum/validators/rewards-list) and [Pagination Guide](/api/pagination). A subsequent request looks like this: ```bash theme={null} # Subsequent request with cursor curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-list \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "validator_identifiers": [1, 2, 3, 4, 5] }, "epoch": 413950, "cursor": "eyJpIjoxMjM0NTY3ODkwfQ", "page_size": 100 } ' ``` *** ## Daily Rewards For the most recent 24-hour period, use the `24h` evaluation window: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "dashboard_id": 123 }, "range": { "evaluation_window": "24h" } } ' ``` *** ## Best Practices For quick totals over standard time windows, the aggregated endpoint is faster and simpler. Aggregated accepts custom ranges on Scale/Enterprise (daily granularity); use the list endpoint for per-epoch data or on other plans. Create a dashboard to organize validators and query by `dashboard_id` instead of tracking indices. All values are in wei. Divide by 10Ā¹āø to convert: `eth = wei / 1e18` **Upgrade to PRO:** [Scale and Enterprise plans](https://beaconcha.in/pricing) unlock `withdrawal` and `deposit_address` selectors, plus higher rate limits for epoch iteration. *** ## Related Resources * [Validator Dashboard](/validator-dashboard/introduction) * [Premium Plans](https://beaconcha.in/premium) API references: [Rewards Aggregated](/api-reference/ethereum/validators/rewards-aggregate) and [Rewards List](/api-reference/ethereum/validators/rewards-list). # Tax Year Calculations Source: https://docs.beaconcha.in/use-cases/rewards-tax-calculations Calculate validator rewards for specific tax years (January 1 - December 31) with per-epoch data for fiat conversion **API Usage:** A full tax year contains \~82,000 epochs. Each epoch requires a separate API call. See [Custom Range Rewards](/use-cases/rewards-custom-range#performance-considerations) for performance estimates and optimization tips. We are developing endpoints designed to streamline the retrieval of summarized data for user-defined periods. Manually summing up rewards epoch-by-epoch doesn't scale well for many validators over long timeframes. ## Overview For tax reporting, you need **per-epoch reward data** to calculate the fiat value of rewards at the time they were received. This requires iterating through epochs using the [Custom Range Rewards](/use-cases/rewards-custom-range) approach. **API Endpoint:** This guide uses [`/api/v2/ethereum/validators/rewards-list`](/api-reference/ethereum/validators/rewards-list) for per-epoch reward data required for tax calculations. **Disclaimer:** This guide provides technical instructions for fetching reward data. It is not tax advice. Consult a qualified tax professional for guidance on how staking rewards should be reported in your jurisdiction. ## Why Per-Epoch or Per-Day Data is Required Most tax jurisdictions require you to report the **fiat value** of staking rewards at the time they were received. This means you need: 1. **Reward amount** for each epoch or day 2. **Historical ETH-USD price** at that time 3. **Calculation**: `fiat_value = reward_eth Ɨ price_at_time` The `all_time` or rolling period windows from Rewards Aggregated only provide a total sumā€”they cannot be used for tax calculations because you need per-epoch data to match with historical prices. ## Obtaining Historical ETH Prices You'll need historical ETH-USD prices for each day. Common sources include: | Source | Notes | | - | - | | [CoinGecko API](https://www.coingecko.com/en/api) | Free tier available, daily historical prices | | [CryptoCompare](https://min-api.cryptocompare.com/) | Hourly historical data available | | [Kraken](https://docs.kraken.com/rest/) | Exchange prices, high accuracy | | Tax software | Many crypto tax tools include price data | For tax compliance, use a consistent price source throughout your calculations and document which source you used. *** ## Common Tax Year Time Zone Offsets | Region | Time Zone | UTC Offset | Notes | | - | - | - | - | | UK | GMT/BST | 0 / +1 | BST during summer | | Central Europe | CET/CEST | +1 / +2 | CEST during summer | | US Eastern | EST/EDT | -5 / -4 | EDT during summer | | US Pacific | PST/PDT | -8 / -7 | PDT during summer | | Japan | JST | +9 | No daylight saving | | Australia Eastern | AEST/AEDT | +10 / +11 | AEDT during summer | For tax purposes, use your local time zone's **standard offset** (non-daylight-saving) or consult with your tax authority about which time zone to use. Some jurisdictions may require UTC. *** ## Related Resources * [Introduction](/use-cases/rewards-introduction) ā€” Overview and endpoint comparison * [Custom Range Rewards](/use-cases/rewards-custom-range) ā€” Complete epoch iteration code * [Epoch & Time Zone Conversion](/use-cases/rewards-epoch-conversion) ā€” Detailed epoch/timestamp math * [Pagination Guide](/api/pagination) **PRO Feature:** With a [Scale or Enterprise plan](https://beaconcha.in/pricing), you can query by `withdrawal` address to capture all validators, and benefit from significantly higher rate limits. Use [dashboards with groups](/use-cases/rewards-dashboard-private-sets) to organize validators and query them efficiently with a single `dashboard_id`. # Track Staking Inflows & Outflows Source: https://docs.beaconcha.in/use-cases/staking-inflows-outflows Measure ETH in transit ā€” pending deposits entering staking and pending exits and withdrawals leaving it ## Overview ETH does not enter or leave Ethereum staking instantly. Deposits wait in the deposit queue before becoming active stake (**ETH in activation ā€” not yet staked**), and exiting stake passes through the exit queue, the withdrawal eligibility delay, and the withdrawal sweep before it can be redeemed (**ETH in withdrawal ā€” not yet redeemed**). This pending ETH is often called **ETH in transit**. The Queue APIs expose both directions of this flow: network-wide totals and per-validator positions, each with estimated processing times. Use them to report pending balances to customers, forecast liquidity, or analyze staking supply dynamics. **API Endpoints:** This guide uses the Queue API family: | Endpoint | Best For | | - | - | | [`/api/v2/ethereum/queues`](/api-reference/ethereum/queues) | Network-wide totals for inflow/outflow snapshots | | [`/api/v2/ethereum/validators/queues`](/api-reference/ethereum/validators/queues) | Queue overview for selected validators, with ETAs | ## This guide focuses on combining queue data into inflow and outflow measures. ## Why Track Staking Flows? Show customers ETH that is deposited but not yet earning, or exiting but not yet redeemable, as distinct balance states. Predict when exiting ETH becomes liquid and when queued deposits start earning, down to the epoch. Give per-validator activation and withdrawal estimates instead of network-wide averages. Track net pending flow (inflows minus outflows) as a leading indicator of staking supply changes. *** ## Mapping "Pending ETH" to Queue Data All balance fields are returned in wei (1 ETH = 10Ā¹āø wei). | Metric | Definition | Source Fields | | - | - | - | | **ETH in activation** | Deposited, not yet active stake | `deposit_queue.deposit_balance` (new validators) + `deposit_queue.topup_balance` (top-ups to existing validators) | | **ETH in exit** | Exit requested, validator still active | `exit_queue.balance` | | **ETH in manual withdrawal** | Withdrawal requests queued on the execution layer | `manual_withdrawal_queue.balance` | | **Pending inflow** | All ETH entering staking | `deposit_balance` + `topup_balance` | | **Pending outflow** | All ETH leaving staking | `exit_queue.balance` + `manual_withdrawal_queue.balance` | | **Net pending flow** | Direction of staking supply | Pending inflow āˆ’ pending outflow | **Don't count consolidations as flows.** The `consolidation_queue` and `compounding_switch_queue` track validators moving stake between validators or switching to compounding credentials ā€” that ETH stays staked and is neither an inflow nor an outflow. **The last leg of an outflow:** after a validator exits, its balance waits through the eligibility delay (\~27 hours) and the withdrawal sweep before being credited. The network endpoint exposes the current sweep duration via `withdrawal_sweep.estimated_sweep_delay`, and the [per-validator overview](#per-validator-tracking) returns min/max sweep estimates for each exiting validator. *** ## Network-Wide Snapshot Get the total pending inflow and outflow for the entire network: ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/queues \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/vnd.beaconcha.in.v2.1+json' \ --data '{"chain": "mainnet"}' ``` ### Response ```json theme={null} { "data": { "deposit_queue": { "deposit_count": 1184, "deposit_balance": "37888000000000000000000", "topup_count": 243, "topup_balance": "1850000000000000000000", "estimated_processed_at": { "epoch": 454155, "timestamp": 1781099520 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "exit_queue": { "count": 420, "balance": "13440000000000000000000", "estimated_processed_at": { "epoch": 454053, "timestamp": 1781060352 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "manual_withdrawal_queue": { "count": 310, "balance": "5120000000000000000000", "estimated_processed_at": { "epoch": 454210, "timestamp": 1781120640 } }, "withdrawal_sweep": { "estimated_sweep_delay": 777600, "last_swept_validator_index": 1284503 }, "consolidation_queue": { "count": 18, "balance": "1152000000000000000000", "estimated_processed_at": { "epoch": 454060, "timestamp": 1781063040 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "compounding_switch_queue": { "count": 25, "estimated_processed_at": { "epoch": 454048, "timestamp": 1781058432 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "finality": "not_finalized" } } ``` In this example: pending inflow = 37,888 + 1,850 = **39,738 ETH**, pending outflow = 13,440 + 5,120 = **18,560 ETH**, net pending flow = **+21,178 ETH** entering staking. See the [network queue API reference](/api-reference/ethereum/queues) before applying this calculation. *** ## Per-Validator Tracking Track queue positions for your own validator set ā€” including validators that are still in the deposit queue and have no index yet (select them by public key): ```bash theme={null} curl --request POST \ --url https://beaconcha.in/api/v2/ethereum/validators/queues \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "chain": "mainnet", "validator": { "validator_identifiers": ["0x93247f22...09abcaf5", 1284503] }, "page_size": 10 } ' ``` ### Response ```json theme={null} { "data": [ { "validator": { "index": null, "public_key": "0x93247f22...09abcaf5" }, "deposit_queue": { "deposit_count": 1, "deposit_balance": "32000000000000000000", "topup_count": 0, "topup_balance": "0", "estimated_processed_at": { "epoch": 454102, "timestamp": 1781079168 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "exit_queue": null, "manual_withdrawal_queue": null, "withdrawal_sweep": null, "consolidation_queue": null, "compounding_switch_queue": null, "finality": "not_finalized" }, { "validator": { "index": 1284503, "public_key": "0xb5a3c901...77fe12d4" }, "deposit_queue": null, "exit_queue": { "count": 1, "balance": "32890000000000000000", "estimated_processed_at": { "epoch": 454031, "timestamp": 1781051904 }, "churn": { "amount": "256000000000000000000", "interval_seconds": 384 } }, "manual_withdrawal_queue": null, "withdrawal_sweep": { "min": { "estimated_processed_at": { "epoch": 454800, "timestamp": 1781347200 } }, "max": { "estimated_processed_at": { "epoch": 455400, "timestamp": 1781577600 } } }, "consolidation_queue": null, "compounding_switch_queue": null, "finality": "not_finalized" } ], "paging": { "next_cursor": "" } } ``` How to read this: * The first validator is **in activation**: 32 ETH deposited, expected to be processed at epoch 454102. Its `index` is `null` because it has not been activated yet. * The second validator is **in withdrawal**: its exit is expected at epoch 454031, and the sweep is expected to credit its balance between epochs 454800 and 455400. * Queues a validator is not part of are returned as `null`. * If a validator has multiple pending items (e.g. several queued top-ups), `estimated_processed_at` refers to its **last** one. **Track whole fleets without index lists:** on [Scale & Enterprise plans](https://beaconcha.in/pricing), the `validator` selector also accepts a `withdrawal` credential/address, a `deposit_address`, or an `entity` name ā€” convenient when your validators all share withdrawal credentials. *** ## Building Historical Snapshots The Queue APIs return the **current** queue state. To analyze trends ā€” daily net flow, queue growth, average wait times ā€” poll on a schedule and store each snapshot: ```python theme={null} import csv import requests from datetime import datetime, timezone API_KEY = "" URL = "https://beaconcha.in/api/v2/ethereum/queues" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", "Accept": "application/vnd.beaconcha.in.v2.1+json", # pin the unified schema } data = requests.post(URL, headers=headers, json={"chain": "mainnet"}).json()["data"] def balance(queue, *fields): """Sum wei string fields of a possibly-null queue object.""" if queue is None: return 0 return sum(int(queue.get(field) or 0) for field in fields) def eta(queue): if queue and queue.get("estimated_processed_at"): return queue["estimated_processed_at"]["timestamp"] return None inflow_wei = balance(data["deposit_queue"], "deposit_balance", "topup_balance") outflow_wei = balance(data["exit_queue"], "balance") + balance( data["manual_withdrawal_queue"], "balance" ) with open("staking_flow_snapshots.csv", "a", newline="") as f: csv.writer(f).writerow([ datetime.now(timezone.utc).isoformat(), inflow_wei, outflow_wei, inflow_wei - outflow_wei, # net pending flow eta(data["deposit_queue"]), eta(data["exit_queue"]), ]) ``` Run it from a scheduler (cron, Airflow, etc.). Queue state changes every epoch (\~6.4 minutes), so per-epoch polling is the maximum useful resolution; **hourly snapshots** are enough for most reporting, and daily snapshots already reveal supply trends. Snapshots only exist from the moment you start collecting them ā€” set up polling before you need the history. *** ## Best Practices Estimates assume the current churn rate and queue composition. Re-poll regularly and present time ranges to customers, not exact times. Wei values exceed float64 precision. Parse the string amounts with arbitrary-precision integers and convert to ETH only for display. Empty or not-applicable queues are returned as `null`. Treat them as zero when aggregating. *** ## Related Resources * [Introduction](/use-cases/queue-tracking) ā€” Overview of the Queue APIs and the staking queues * [Estimate Queue Wait Times](/use-cases/queue-wait-times) ā€” Turn queue statistics into activation and exit ETAs * [Understanding Validator Queues](/faqs/understanding-validator-queues) ā€” How the queues work at the protocol level * [Deposit Process](/faqs/deposit-process) ā€” The full lifecycle of a deposit * [How Withdrawals Work](/faqs/how-withdrawals-work) ā€” Eligibility delay and the withdrawal sweep * [Pagination](/api/pagination) ā€” Cursor-based pagination for the per-validator queue endpoint # Introduction Source: https://docs.beaconcha.in/validator-dashboard/introduction Overview of the validator dashboard, key features, and transition notes from the legacy dashboard. # šŸŽ‰ Introducing our new validator dashboard Our new validator dashboard features a variety of new features and addresses issues observed in the past years when monitoring validators. Most importantly, it scales massively with [premium plans and add-ons](https://beaconcha.in/premium), supporting up to 320,000+ ETH in stake per dashboard. * Mainnet: [https://beaconcha.in/dashboard](https://beaconcha.in/dashboard) * Hoodi: [https://hoodi.beaconcha.in/dashboard](https://hoodi.beaconcha.in/dashboard) *** ## New validator dashboard features ### [Data](./slot-visualization) Introduction of real-time data to identify problems and aggregated historical data for debugging and research purposes. Users will no longer need to *read* the tables to spot problems with their validators; instead, they can *look* at the slot viz which provides [multi-color feedback](./slot-visualization), and the best part ā€“ it scales massively with [premium add-ons](https://beaconcha.in/premium). ### [Groups](./validator-groups.md) Many of our users manage multiple nodes and servers, and it has been challenging to identify issues without a complex Grafana dashboard or a dedicated DevOps team. To address this, we have introduced "Groups," which allow users to assign validators to groups and track them separately in real-time. ### [Sharing](./share-your-custom-dashboard) Sharing beaconcha.in login information in large corporations can be complicated; the new Sharing feature allows users to easily provide view-only access to their team members. ### New Metric: [BeaconScoreĀ®](/beaconscore/introduction) The familiar "Attestation Effectiveness" metric has been replaced by a new metric called "BeaconScoreĀ®" which considers all validator duties and provides better feedback to the user. For those who have been subscribed to [beaconcha.in](https://beaconcha.in) in the past ā€” thank you for supporting us! You will have access to the new premium features for the **same price**. * Plankton and Goldfish subscribers have been migrated to [Guppy](https://beaconcha.in/pricing). * Whale subscribers have been migrated to [Dolphin](https://beaconcha.in/pricing). # Manage validators Source: https://docs.beaconcha.in/validator-dashboard/manage-validators A modal to add, remove and assign validators ## Bulk adding to the validator dashboard Users looking to add thousands of validators have several options: * Add validators using our [API](./manage-validators-api) * Add validators using validator **graffiti** * Add validators by **deposit address** * Add validators by **withdrawal credentials** * Add validators with a **comma-separated** list via validator indices or validator public key (e.g., `1,2,3,4,5`) ## Filtering validators in the validator manage modal #### Filter for a specific group * To view validators from a specific group, select the group from the top left dropdown. * Adding a validator while a group filter is active assigns the validator to that group. * Adding a validator under 'All groups' sets the default group for the newly added validator. #### Quick add to a group * Adding a validator while a group filter is active assigns the validator to that group. * Adding a validator under 'All groups' sets the default group for the newly added validator. # Introduction Source: https://docs.beaconcha.in/validator-dashboard/manage-validators-api Manage your validators via API # āš’ļø Manage Validator Dashboards To modify the validator dashboard via API, make sure you have an active [**Orca**](https://beaconcha.in/premium) subscription. After creating a [validator dashboard](https://beaconcha.in/dashboard) and the desired [validator groups](./validator-groups) through the UI, you can add and assign validators to groups using our API. *** * The Group ID is shown in the Group Manage modal on the Dashboard (see [validator groups](./validator-groups)) * The Dashboard ID is visible in the dashboard URL * The API key is only visible in your account settings: [https://beaconcha.in/user/settings#api](https://beaconcha.in/user/settings#api) Adjust the base URL for your target network: * Mainnet: beaconcha.in * Hoodi: hoodi.beaconcha.in ## Add validators to a dashboard Use the [POST endpoint](/validator-dashboard/manage-validators-api-endpoints/validators_post) to add validators to a dashboard. Provide the API key as a query parameter and a JSON body. See the API spec below for the exact payload shape. ## Remove validators from a group Use the [DELETE endpoint](/validator-dashboard/manage-validators-api-endpoints/groups_delete) to remove validators from a specific group. ## Bulk delete validators from a dashboard Use the [bulk deletions endpoint](/validator-dashboard/manage-validators-api-endpoints/validators_bulk_delete_post) to remove many validators at once. Looking for how to create and manage groups in the UI? See [validator groups](/validator-dashboard/validator-groups). # Delete validators from groups Source: https://docs.beaconcha.in/validator-dashboard/manage-validators-api-endpoints/groups_delete .gitbook/assets/API_spec.json DELETE /api/v2/validator-dashboards/{dashboard_id}/groups/{group_id}/validators Delete all validators from a specified group in a specified validator dashboard. # Bulk delete validators from a dashboard Source: https://docs.beaconcha.in/validator-dashboard/manage-validators-api-endpoints/validators_bulk_delete_post .gitbook/assets/API_spec.json POST /api/v2/validator-dashboards/{dashboard_id}/validators/bulk-deletions Remove specific validators from a specified dashboard in bulk. # Manage dashboard validators Source: https://docs.beaconcha.in/validator-dashboard/manage-validators-api-endpoints/validators_post .gitbook/assets/API_spec.json POST /api/v2/validator-dashboards/{dashboard_id}/validators Add new validators to a specified dashboard or update the group of already-added validators. This endpoint will always add as many validators as possible, even if more validators are provided than allowed by the subscription plan. The response will contain a list of added validators. # Migrating from the legacy dashboard Source: https://docs.beaconcha.in/validator-dashboard/migrating-legacy-dashboard Step-by-step guide to migrate your v1 dashboard and validators to the v2 dashboard. # Migrating v1 dashboard to v2 dashboard The v2 dashboard is limited to 20 validators (up to 3,200 maxEB) for free users. For higher limits, please check out our subscriptions: [https://beaconcha.in/premium](https://beaconcha.in/premium) **Migration guide** 1. Access your v1 dashboard (via your bookmark or saved link). The URL contains the validator indices you need to migrate. 2. Right-click on the URL in your browser's address bar and select "Copy" to copy the validator indices from the URL. e.g., `1,2641,2642,2643,2645,3288,3292,3400,3401,3402,3403,3404` v1 dashboard URL showing validator indices 3. Log in at [https://beaconcha.in/login](https://beaconcha.in/login) and create a v2 dashboard: [https://beaconcha.in/dashboard](https://beaconcha.in/dashboard) 4. Click on `Manage Validators` and add your validators as a comma-separated list or use other methods as described in [manage-validators](../validator-dashboard/manage-validators#bulk-adding-to-the-validator-dashboard): Manage Validators modal in v2 dashboard **Done!** *** Please note that the new dashboard includes new notifications. If you'd like to migrate those as well, see [../notifications-monitoring/notifications#migrating-from-v1-notification-to-v2](../notifications-monitoring/notifications#migrating-from-v1-notification-to-v2) ## Backlinks The new dashboard can also be opened by passing the indices through the URL: [https://beaconcha.in/dashboard?validators=1,5,8](https://beaconcha.in/dashboard?validators=1,5,8) # Share dashboard Source: https://docs.beaconcha.in/validator-dashboard/share-your-custom-dashboard Share a read-only validator dashboard with custom groups and settings. # šŸ¤ Share your custom dashboard The [Group ](./validator-groups.md)feature makes every dashboard unique. For example, even if two dashboards contain the same validators, the charts and statistics would be different if the validators were assigned to different groups. Thus, the dashboard allows you to share (read-only) a dashboard with its custom settings. This is extremely useful for larger staking entities that want to share their validator set internally, without providing access to a sensitive database. # Slot visualization Source: https://docs.beaconcha.in/validator-dashboard/slot-visualization A metric for real-time validator monitoring # šŸŸ© Slot visualization The slot viz has been redesigned and integrated into the dashboard to visualize real-time data for the user's validator set. A multi-color scheme has been introduced to simplify issue detection and allow preparation for upcoming validator duties for operators. This significantly enhances user experience, as users no longer need to read and switch between data tables. Users that run hundreds of validators can reduce the noise in their slot viz using the filters located in the top left corner šŸ™‚ *** ### **How does it work?** Each block has two states. The network status and the users' validator status. Slot visualization: network and validator states This makes it easy to backtrack if a missed duty was related to network issue. Slot visualization: missed duty backtracking #### **Content Color Scheme** Slot visualization: content color scheme #### Border Color Scheme Slot visualization: border color scheme #### **Examples** Slot visualization examples: case 1 Slot visualization examples: case 2 Slot visualization examples: case 3 *** # Summary table Source: https://docs.beaconcha.in/validator-dashboard/summary-table Visualizes your validator performance in multiple time frames # šŸ¦ø Summary view The summary table is part of the [validator dashboard](https://beaconcha.in/dashboard). It provides detailed performance metrics for each validator [group](./validator-groups), including [efficiency](#efficiency) and validator rewards across various time frames. It also features a [historical chart view](#summary-chart-view). *** ## Overview Each row in the summary table represents a [validator group](./validator-groups). Users with multiple groups will see an additional row above the thin orange line, labeled as the Ī£-row. ### Expandable rows Expanding a row provides detailed data for each group. ### Absolute vs relative values The summary table can be viewed in both absolute and relative values. This feature is especially useful for large entities with millions of attestations that prefer a relative value. 1. **Summary table with relative values** 2. **Summary table with absolute values** ### Missed Rewards Calculation When a validator misses rewards ā€” whether from the Consensus Layer (CL) or Execution Layer (EL) proposals, including MEV ā€” those missed rewards are calculated using the median (p50) of the surrounding rewards. Specifically: 1. **Identify the Surrounding Slots** * For each missed slot, consider the 32 slots surrounding it: slots where `slot >= missed.slot - 16` AND `slot < missed.slot + 16` 2. **Calculate the Median (p50)** * Collect the rewards from each of those surrounding 32 slots. * Compute the *median* (50th percentile, or p50) of that set of rewards. 3. **Assign the Median as the Missed Reward** * The resulting median value becomes the *missed reward* for that specific slot. #### Example * Suppose a missed proposal occurred at slot `100`. * Look at slots `84` through `115` (i.e., `100 - 16` to `100 + 15`). * Gather each validatorā€™s reward (MEV rewards + CL rewards) from those slots. * Sort these rewards and take the median value. * The median is then recorded as the missed reward for slot `100`. ## APR calculation The APR is calculated based on the growth rate of your consensus layer (CL) staking balance over the selected period, using epoch-level granularity. At the start of the period, the total CL balance across all validators is recorded. The total rewards earned during the period are divided by this starting balance to determine the period growth rate. This rate is then annualized by scaling to one year. `APR = (RewardsInPeriod / BalanceAtPeriodStart) * (EpochsPerYear / EpochsInPeriod) * 100` * **BalanceAtPeriodStart**: Sum of all validator CL balances at the start of the period. * **RewardsInPeriod**: Total rewards accrued by those validators during the period. * **EpochsInPeriod**: Number of epochs in the selected period (each epoch is \~6.4 minutes). * **EpochsPerYear**: Total number of epochs in a year (ā‰ˆ51,480). The All time period currently shows the 90-day APR. This is subject to change in the future. ## Luck calculation Validators are randomly selected for duties, such as proposing blocks or participating in the sync committee. The chance of being assigned duties depends on the total number of validators on the network and their effective balance. Luck values are purely informative and cannot be actively influenced. **Blocks** 1. It is calculated how likely a validator was to be chosen to propose a block in each epoch. ``` ExpectedBlocks = (ValidatorEffectiveBalance / NetworkEffectiveBalance) * SlotsPerEpoch ``` 2. The number of blocks a validator proposed is measured against the expected number, expressed as a percentage. ``` BlockLuckPercent = (ProposedBlocks / ExpectedBlocks) * 100 ``` In practice, this calculation is performed for all validators over the selected time frame. **Sync Committee** 1. It is calculated how likely it was for a validator to be chosen as a member of the sync committee in each election. ``` ExpectedSyncParticipations = (ValidatorEffectiveBalance / NetworkEffectiveBalance) * SyncCommitteeSize ``` 2. The number of actual participations is compared to the expected participations and expressed as a percentage. ``` SyncLuckPercent = (ActualSyncParticipations / ExpectedSyncParticipations) * 100 ``` In practice, this calculation is performed for all validators over the selected time frame. ## Summary chart view `[1]` View the historical performance of your validator groups by clicking this button and switching to the summary chart view. `[2]` The summary chart view is perfect for debugging issues, as it provides historical performance data with epoch-level granularity. The Groups dropdown lets users filter specific groups, while the Total line (orange line) shows the average performance of all groups in the dashboard.\ \ To identify missed blocks, sync duties, or attestations, users can use the Efficiency dropdown to filter for those specific duties. ## Status column The status column offers a quick way to check key duties, such as your current sync committees, whether you're part of the upcoming sync committee, and if any of your validators have been slashed.\ \ Hover over the icons for more details. ## Validator column The validator column displays the state of each validator in each group: * Online validators (green icon) * Offline validators (red icon) * Exited validators (gray icon) A comma-separated list of validator indices for each group can be found in the popout modal for each row in the table. *The relative value only accounts for online and offline validators, ignoring those that have already exited the chain. This offers quick insights into whether your group is experiencing issues.* ## BeaconScoreĀ® The [BeaconScoreĀ®](#beaconscore) metric is a comprehensive measure of validator performance, combining multiple components: * **Red arrow**: Underperforming the network average by at least 0.25%. * **Green arrow**: Outperforming the network average by at least 0.25%. * **Yellow arrow**: Within a range of +/- 0.25% of the network average. Hovering over an arrow displays the exact performance of each group. For historical performance, switch to the summary chart view. ### Attestations vs Attester efficiency * **Attester Efficiency**: This measures how much reward a validator could have earned for attestations versus how much they actually earned. For example, if a validator could have earned 100 GWEI for attestations but only received 98 GWEI, the attester efficiency would be 98%. * **Attestations (%-value)**: This represents the percentage of attestations successfully included in the network. For instance, if a validator managed to include 99 out of 100 attestations, the Attestation (%) value would be 99%. The absolute values can be viewed by hovering over this percentage or by switching to the absolute-table view. # Validator groups Source: https://docs.beaconcha.in/validator-dashboard/validator-groups Group your validators to measure your nodes performance # šŸ«‚ Validator groups The grouping feature extremely flexible and covers multiple use cases such as representing your customized node-operator sets, your server structure or simply just comparing the validator performances within a single dashboard. Create groups in the Manage Groups modal and assign your validators to specific groups in the Manage Validators window. # Validator tagging Source: https://docs.beaconcha.in/validator-tagging/overview An in-depth guide to the validator tagging module, explaining how beaconcha.in attributes validators to [entities](https://beaconcha.in/entities) (including whales) using data sources and on-chain lookups. # Overview #### Summary This article explains how [beaconcha.in](https://beaconcha.in) assigns humanā€‘readable tags to Ethereum validators. Tags make it easier to understand which validators belong to wellā€‘known entities (e.g., Lido, Rocket Pool), as well as large independent operators ("whales"). It covers data sources, the stepā€‘byā€‘step tagging pipeline, how often tagging runs, and how conflicts are resolved. Shoutā€‘out: A big thankā€‘you to [Hildobby](https://x.com/hildobby) for maintaining a community dataset of validator/entity mappings used by many in the ecosystem. *** #### What is a validator tag? A validator tag is a short, human-readable label associated with one or more validators. Tags help you: * Attribute validator performance to entities via their BeaconScoreĀ® benchmark value. * Understand decentralization by operator/entity. * Identify large clusters of validators controlled by the same address. Examples include: * `Coinbase` or `Binance` * `Lido`, `Lido Simple DVT`, or `Lido CSM` (Lido modules) * `Rocket Pool` (Rocket Pool validators) * `Whale_0x1234` (an independent cluster labeled by address prefix) *** #### Highā€‘level pipeline At a high level, the tagging module: 1. Imports community tags from the [Hildobby](https://x.com/hildobby) dataset 2. Queries onā€‘chain contracts to detect Lido validators (Curated v1 and v2, Simple DVT, Community Staking) 3. Queries onā€‘chain contracts to detect Rocket Pool validators 4. For any remaining untagged validators, clusters by withdrawal address and assigns whale tags if the cluster balance exceeds 320 ETH 5. For any remaining untagged validators, clusters by deposit (funding) address and assigns whale tags if the cluster balance exceeds 320 ETH The pipeline runs automatically once a day. ```mermaid theme={null} flowchart TD A[Start] --> B[Import Hildobby dataset] B --> C[Import Lido modules
- Curated Modules v1 and v2
- Simple DVT Module
- Community Staking] C --> D[Import on-chain Rocket Pool validators] D --> E[Cluster remaining by withdrawal address
Assign Whale_0x1234 if balance > 320 ETH] E --> F[Cluster remaining by deposit address
Assign Whale_0x1234 if balance > 320 ETH] F --> G[Precompute Dashboard Data] ``` *** #### Stepā€‘byā€‘step details **1) Community tags via Hildobby** * Source: [Hildobbyā€™s](https://x.com/hildobby) public validator/entity dataset (community maintained). * Matching: The dataset contains mappings of validator indices or pubkeys to known entities. We import those tags directly. * Why first? Communityā€‘maintained mappings often include entities that are not easily inferred from onā€‘chain structures. * Note: We retain Hildobbyā€™s naming semantics and apply them as the baseline when no higherā€‘certainty onā€‘chain inference is available. **2) Lido validators from onā€‘chain contracts** We identify validators belonging to Lido by reading their onā€‘chain registry data. This includes: * `Lido Curated Module v1` * `Lido Curated Module v2` * `Lido SimpleDVT Module` * `Lido Community Staking Module` Implementation outline: * Enumerate the validator set exposed by each moduleā€™s contracts * Read Curated Module v2 operator names from its on-chain MetaRegistry * Map each validator pubkey to the appropriate tag: `Lido`, `Lido Simple DVT`, or `Lido CSM` * Prefer these determinations over community tags when a contract says a validator belongs to Lido Rationale: Onā€‘chain state is authoritative for Lidoā€™s modules and provides the highestā€‘certainty attribution. **3) Rocket Pool validators from onā€‘chain contracts** We detect Rocket Pool validators by reading the relevant Rocket Pool contracts that register or imply validator ownership (e.g., minipools and their validator keys/addresses). Implementation outline: * Enumerate active and historical minipools * Retrieve associated validator pubkeys * Tag those validators as `RocketPool` Rationale: Like Lido, Rocket Poolā€™s onā€‘chain structures allow for accurate, direct inference of validator membership. **4) Whale tagging by withdrawal address (> 320 ETH)** For remaining untagged validators, we infer likely common control by clustering validators sharing the same withdrawal credentials/address. * Cluster key: withdrawal address * Cluster size metric: total effective balance of validators in the cluster * Threshold: `> 320 ETH` (equivalent to more than 10 full validators at 32 ETH each) * Tag format: `Whale_0x1234` where `0x1234` is a short prefix of the withdrawal address for readability Operators often consolidate withdrawals to a single address, making it a strong signal of common ownership/control. **5) Whale tagging by deposit (funding) address (> 320 ETH)** For any stillā€‘untagged validators, we cluster by the funding address that sent the deposit transaction(s). * Cluster key: deposit/funding (from) address * Cluster size metric: total effective balance of validators funded by that address * Threshold: `> 320 ETH` * Tag format: `Whale_0x1234` Large operators often fund many deposits from a single address, even if they diversify withdrawal addresses. *** #### Tag priority and conflict resolution When a validator qualifies for multiple tags, we follow this precedence (from highest to lowest certainty): 1. Onā€‘chain entity detection (Lido modules, Rocket Pool) 2. Community dataset (Hildobby) 3. Inferred whale clustering by withdrawal address 4. Inferred whale clustering by deposit address *** #### Schedule and freshness The tagging system runs on a fixed UTC schedule: * Daily at 10:00 UTC: Full tagging pipeline (all steps) runs in order, followed by a precompute job that updates the entity data dashboards. * Hourly (other than 10:00): Precompute only. This ensures UI remains fast and consistent even between daily runs. *** #### Examples * A validator included in either version of Lidoā€™s Curated module contracts will be tagged `Lido`, with its node operator recorded as the sub-entity. * An independent operator running 15 validators with the same withdrawal address will be tagged `Whale_0xABCD` where `0xABCD` is a short prefix of their withdrawal address. * A cluster of 8 validators funded from address `0xF...` will not get a whale tag because the balance threshold (`> 320 ETH`) is not met. *** #### How to request a correction If you believe a tag is incorrect: * Open an issue in the beaconcha.in [support channel](https://dsc.gg/beaconchain) and include validator indices or pubkeys, plus the correct attribution if known. * For onā€‘chain attributions (Lido/Rocket Pool), please provide the relevant contract references or transaction links. Corrections propagate after the next daily run. *** #### Frequently asked questions * Why does a whale tag use a short address prefix? * For readability in the UI. The underlying full address is retained for accuracy. * Will small operators get whale tags? * No. The threshold is strict: only clusters with total balance `> 320 ETH` qualify. * When are tags assigned for new validators? * Tags refresh daily with new data and may evolve if onā€‘chain ownership changes or the community dataset is updated. * Does tagging affect rewards or protocol behavior? * No. Tagging is a UI attribution feature only; it does not interact with consensus or execution layer incentives. *** #### Contact If you have questions or suggestions about validator tagging, please reach out via our [support channel](https://dsc.gg/beaconchain). # Getting Started Source: https://docs.beaconcha.in/welcome Learn how to use the beaconcha.in explorer and how to monitor the performance of your validators. šŸ‘‹ Welcome to the beaconcha.in knowledgebase! [beaconcha.in](https://beaconcha.in/) is the only explorer that visually merges the Ethereum consensus and execution layer, significantly improving the user experience. It comes with a [mobile app](https://beaconcha.in/mobile) for android and IOS! This knowledgebase covers * Tutorials * Definitions * API explanations For questions and suggestions you can find us on [X](https://x.com/beaconcha_in) and [Discord](https://dsc.gg/beaconchain). **Building with AI?** Connect your AI assistant to our documentation via [AI Integration](/api/ai-integration). Get accurate, up-to-date answers about the beaconcha.in API directly in your development environment. **Quick start** Get your API key and make your first request to the V2 API in minutes. Introducing the new validator dashboard and its features. Understand the real-time slot visualization and color scheme. Learn how the BeaconScoreĀ® metric is calculated. *** ## What do you want to build? Track earnings, calculate tax-ready reports, and analyze reward breakdowns. Use BeaconScoreĀ® to track efficiency and identify missed duties. Rank and benchmark staking providers against the network. Monitor activation, exit, and withdrawal queues with estimated wait times. Connect your AI assistant to beaconcha.in via MCP, llms.txt, or skill.md. Step-by-step guide to move your integration from V1 to V2 API.