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

Get rewards for any date range — a single aggregated call on Scale/Enterprise, or by iterating epochs for per-epoch detail.

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) 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)
• 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.

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

Custom Date Range 💎

With a Scale or Enterprise plan, 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.

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": {
    "timestamp": { "start": 1706000000, "end": 1709000000 }
  }
}
'

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 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, get the range total in one call with rewards-aggregate (daily granularity). See Custom Range Rewards for both approaches.

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.

Custom Ranges

Aggregated accepts custom ranges on Scale/Enterprise (daily granularity); use the list endpoint for per-epoch data or on other plans.

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.

---

Related Resources

• Validator Dashboard
• Premium Plans

API references: Rewards Aggregated and Rewards List.