Introduction to Ethereum Reporting API v2

Overview

The Ethereum Staking Reporting API expands its feature set to include timezone-based reporting capabilities, epoch-level data availability, and improved tracking of MEV (Maximum Extractable Value) rewards. It also provides a detailed breakdown of rewards per epoch, including block, attestation, and sync committee rewards.

🌐 Supported networks are:

• Mainnet
• Hoodi

➡️ Get the Rewards

This endpoint returns the total rewards for the queried period from one or more validator addresses.

Total Reward comprises of:

1. Consensus layer rewards - These are payments of newly minted ETH to validators for performing duties that maintain network security and consensus. These duties include:

• Attestation (attestationReward): Validators receive rewards for attesting to the validity of blocks. These rewards are predictable and occur once per epoch.
  • Block proposal (blockReward): Validators earn rewards for proposing new blocks, incentivizing their participation in network maintenance.
  • Sync committee participation (syncCommitteeReward): Validators earn rewards for participating in the sync committee.

2. Execution layer rewards - These include transaction fees and Maximal Extractable Value (MEV) rewards.

• Transaction fees (blockFeeReward): Validators earn a share of the gas fees from user transactions included in the blocks they propose.
  • MEV rewards (mevBlockReward): Validators earn MEV rewards when they propose a block.

👍

Tips

You can use a withdrawal address to query rewards for its associated validator pubkeys. The request will fail if that withdrawal address is linked to more than 1,000 validator pubkeys. Currently, only execution layer deposits are used to track pubkey to withdrawal address mappings and not BLS changes, so some mappings may be missing currently

📘

Info

To receive a report in your timezone, submit the day start and end times in epoch seconds. You can convert these times using Epoch Converter.

Endpoints

Sample Object

The response below is returned from the Get a Stream of Rewards for a Single Address endpoint.

{
    "address": "0x8e8af6ca89592811c6e28bfec529dd5eea347e9049999fbdef4fbc2fe4535a1083498d0f0eb359f11ae08e0dee9d32cf",
    "denomination": "GWEI",
    "return": "9359",
    "startTime": 1737627095,
    "endTime": 1737627479,
    "startBalance": "32004966921",
    "period": "RAW",
    "metadata": {
      "epoch": "340633",
      "withdrawals": "0",
      "deposits": "0",
      "index": "790001",
      "syncCommitteeReward": "0",
      "blockReward": "0",
      "attestationReward": "9359",
      "mevBlockReward": "0"
    }
}

How Reward Allocation Works?

In v2, rewards are allocated based on when an epoch ends. The API will only include rewards for epochs that end during the period you specify. This approach reflects rewards based on when the activity is fully completed to give a more accurate match to daily totals.

How it works

If you query rewards for a specific day, the API returns rewards for any epoch that ended on that day.

Example

For a UTC day query on the 11th of the month:

• Epoch 1 starts at 11:57 PM on the 10th and ends at 12:03 AM on the 11th.

This epoch will be included in the rewards for the 11th, because it ended on the 11th.

• Epoch 2 starts at 11:57 PM on the 11th and ends at 12:03 AM on the 12th.

This epoch will not be included in the rewards for the 11th, because it ended on the 12th.

➡️ Get a Validator Status

This endpoint returns the current status of a validator. Possible statuses include:

• UNKNOWN
• PENDING
• ACTIVE
• EXITED
• WITHDRAWAL
• DEPOSITED

Mappings from on-chain statuses show how we classify different statuses.

Endpoints

Sample Object

The response below is returned from the Get Validator Status for an Address endpoint.

{
  "address": "0x821dcb238db02d80a16f20c585027dd8e2390de32062f8e14f41d5236c4e520acf6e920e05435bc144c6d84b8b6debef",
  "status": "ACTIVE",
  "timestamp": 1730818391,
  "metadata": {
    "rawStatus": "active_ongoing",
    "balance": "32011887937",
    "index": "1111111",
    "withdrawalCredentials": "0x01000000000000000000000080e163f67ab78222b1ac109e8db63801cb34b682",
    "effectiveBalance": "32000000000",
    "slashed": "false",
    "activationEligibilityEpoch": "253795",
    "activationEpoch": "253861",
    "exitEpoch": "18446744073709551615",
    "withdrawableEpoch": "18446744073709551615"
  }
}

The metadata fields returned from this call represent the validator's activation and withdrawal states, such as:

• activationEligibilityEpoch: The epoch when the validator was registered by the network and entered the queue for activation.
• activationEpoch: The epoch when the validator became active and started earning rewards.
• exitEpoch: The epoch when the validator exited the network and stopped earning rewards.
• withdrawableEpoch: The epoch when the validator can withdraw or transfer funds. The withdrawal process can be activated for the 32 ETH deposit and remaining rewards.

📘

Info

If the exitEpoch or withdrawableEpoch values are set to 18446744073709551615, it means that the validator is still active in the network and has not exited or withdrawn yet.

➡️ Get Health

The endpoint provides the health status of the rewards processing system. You can track:

• The latest epoch with available rewards.
• The current status of the blockchain.

Sample Object

The response shows whether the reward processing is running optimally or not (degraded).

{
  "status": "OPTIMAL",
  "timestamp": 1720715486,
  "metadata": {
    "chainEpoch": "296590",
    "lastProcessedEpoch": "296589"
  }
}

👋 Need Help?

Contact us through email or our support page for any issues, bugs, or assistance you may need.