Skip to main content

​
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 for quick summaries and /api/v2/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

Custom Range Rewards

Calculate rewards for any date range by iterating through epochs—months, quarters, or custom periods.

Tax Year Calculations

Calculate per-epoch rewards for Jan 1 – Dec 31 with fiat conversion for tax reporting.

Dashboard Private Sets

Query validators by dashboard_id or filter by group_id instead of tracking indices.

Epoch & Time Zones

Convert between epochs, timestamps, and local time zones for precise date calculations.

​
Choosing the Right Endpoint

EndpointBest ForResponse
Rewards AggregatedQuick summaries over fixed windows (24h, 7d, 30d, 90d, all_time)Single aggregated result
Rewards ListPer-epoch breakdowns, custom date rangesPaginated list per epoch

​
Use Rewards Aggregated when you need:

  • Total rewards for the last 24h, 7d, 30d, 90d, or all time
  • 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
  • Custom date range calculations (requires iterating epochs)

​
Rewards Aggregated Endpoint

Returns cumulative rewards for validators over a fixed evaluation window.

​
Basic Example

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": {
    "validator_identifiers": [1, 2, 3, 4, 5]
  },
  "range": {
    "evaluation_window": "30d"
  }
}
'

​
Available Evaluation Windows

All windows except all_time are rolling periods—continuously moving time windows that always end at the current epoch.
WindowDescription
24hLast 24 hours (rolling)
7dLast 7 days (rolling)
30dLast 30 days (rolling)
90dLast 90 days (rolling)
all_timeSince validator activation
What are rolling periods? A rolling period is a moving time window that shifts forward with each new epoch (~6.4 minutes). For example, 30d always returns rewards from exactly 30 days ago until now—not a fixed calendar month. As new epochs are finalized, older epochs drop out of the window and new ones are added.

​
Using Dashboard Selector

Query all validators in your Validator Dashboard: 
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": {
    "dashboard_id": 123
  },
  "range": {
    "evaluation_window": "all_time"
  }
}
'

​
Response Structure

{
  "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, 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 date ranges.
The epoch parameter is required. To calculate rewards for a date range, you must iterate through each epoch. See Custom Range Rewards for complete examples.

​
Basic Example

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/rewards-list \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": {
    "validator_identifiers": [1, 2, 3, 4, 5]
  },
  "epoch": 413950,
  "page_size": 100
}
'

​
Pagination

The response includes paging.next_cursor when more data exists: 
# Subsequent request with cursor
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/rewards-list \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": { "validator_identifiers": [1, 2, 3, 4, 5] },
  "epoch": 413950,
  "cursor": "eyJpIjoxMjM0NTY3ODkwfQ",
  "page_size": 100
}
'
See the Pagination Guide for complete details.

​
Daily Rewards

For the most recent 24-hour period, use the 24h evaluation window: 
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": { "dashboard_id": 123 },
  "range": { "evaluation_window": "24h" }
}
'

​
Best Practices

Use Aggregated for Summaries

For quick totals over standard time windows, the aggregated endpoint is faster and simpler.

Use List for Custom Ranges

For precise date ranges not covered by evaluation windows, iterate through epochs with the list endpoint.

Use Dashboard Selectors

Create a dashboard to organize validators and query by dashboard_id instead of tracking indices.

Convert Wei to ETH

All values are in wei. Divide by 10¹⁸ to convert: eth = wei / 1e18
Upgrade to PRO: Scale and Enterprise plans unlock withdrawal and deposit_address selectors, plus higher rate limits for epoch iteration.
For detailed API specifications, see the Rewards (CL + EL) section in the V2 API Docs sidebar.