> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  **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.
</Note>

<Info>
  All rewards data is available only for **finalized epochs**. Values are returned in wei (1 ETH = 10¹⁸ wei).
</Info>

***

## Quick Start Guides

<CardGroup cols={2}>
  <Card title="Custom Range Rewards" icon="calendar-range" href="/use-cases/rewards-custom-range">
    Calculate rewards for any date range by iterating through epochs—months, quarters, or custom periods.
  </Card>

  <Card title="Tax Year Calculations" icon="calculator" href="/use-cases/rewards-tax-calculations">
    Calculate per-epoch rewards for Jan 1 – Dec 31 with fiat conversion for tax reporting.
  </Card>

  <Card title="Dashboard Private Sets" icon="table-columns" href="/use-cases/rewards-dashboard-private-sets">
    Query validators by `dashboard_id` or filter by `group_id` instead of tracking indices.
  </Card>

  <Card title="Epoch & Time Zones" icon="clock" href="/use-cases/rewards-epoch-conversion">
    Convert between epochs, timestamps, and local time zones for precise date calculations.
  </Card>
</CardGroup>

***

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

```bash theme={null}
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](/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 <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": {
    "dashboard_id": 123
  },
  "range": {
    "evaluation_window": "all_time"
  }
}
'
```

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

<Tip>
  **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).
</Tip>

***

## Rewards List Endpoint

Returns per-validator rewards for a **specific epoch**. Requires iteration for date ranges.

<Note>
  The `epoch` parameter is **required**. To calculate rewards for a date range, you must iterate through each epoch. See [Custom Range Rewards](/use-cases/rewards-custom-range) for complete examples.
</Note>

### Basic Example

```bash theme={null}
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](/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 <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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Use Aggregated for Summaries" icon="chart-line">
    For quick totals over standard time windows, the aggregated endpoint is faster and simpler.
  </Card>

  <Card title="Use List for Custom Ranges" icon="list" href="/use-cases/rewards-custom-range">
    For precise date ranges not covered by evaluation windows, iterate through epochs with the list endpoint.
  </Card>

  <Card title="Use Dashboard Selectors" icon="table-columns">
    Create a dashboard to organize validators and query by `dashboard_id` instead of tracking indices.
  </Card>

  <Card title="Convert Wei to ETH" icon="coins">
    All values are in wei. Divide by 10¹⁸ to convert: `eth = wei / 1e18`
  </Card>
</CardGroup>

<Tip>
  **Upgrade to PRO:** [Scale and Enterprise plans](https://beaconcha.in/pricing) unlock `withdrawal` and `deposit_address` selectors, plus higher rate limits for epoch iteration.
</Tip>

***

## Related Resources

* [Validator Dashboard](/validator-dashboard/introduction)
* [Premium Plans](https://beaconcha.in/premium)

<Tip>
  API references: [Rewards Aggregated](/api-reference/ethereum/validators/rewards-aggregate) and [Rewards List](/api-reference/ethereum/validators/rewards-list).
</Tip>