Introduction

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

Endpoint	Best For	Response
Rewards Aggregated	Quick summaries over fixed windows (24h, 7d, 30d, 90d, all_time)	Single aggregated result
Rewards List	Per-epoch breakdowns, custom date ranges	Paginated 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"
  }
}
'

See the Rewards Aggregated API reference.

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

See the Rewards List API reference and Pagination Guide. A subsequent request looks like this:

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

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.

API references: Rewards Aggregated and Rewards List.

V2 API Docs

V1 API Docs

Introduction

Overview

Quick Start Guides

Custom Range Rewards

Tax Year Calculations

Dashboard Private Sets

Epoch & Time Zones

Choosing the Right Endpoint

Use Rewards Aggregated when you need:

Use Rewards List when you need:

Rewards Aggregated Endpoint

Basic Example

Using Dashboard Selector

Response Structure

Rewards List Endpoint

Basic Example

Daily Rewards

Best Practices

Use Aggregated for Summaries

Use List for Custom Ranges

Use Dashboard Selectors

Convert Wei to ETH

​Overview

​Quick Start Guides

Custom Range Rewards

Tax Year Calculations

Dashboard Private Sets

Epoch & Time Zones

​Choosing the Right Endpoint

​Use Rewards Aggregated when you need:

​Use Rewards List when you need:

​Rewards Aggregated Endpoint

​Basic Example

​Using Dashboard Selector

​Response Structure

​Rewards List Endpoint

​Basic Example

​Pagination

​Daily Rewards

​Best Practices

Use Aggregated for Summaries

Use List for Custom Ranges

Use Dashboard Selectors

Convert Wei to ETH

​Related Resources

Overview

Quick Start Guides

Choosing the Right Endpoint

Use Rewards Aggregated when you need:

Use Rewards List when you need:

Rewards Aggregated Endpoint

Basic Example

Using Dashboard Selector

Response Structure

Rewards List Endpoint

Basic Example

Pagination

Daily Rewards

Best Practices

Related Resources