Ethereum Reporting API Overview

Overview

The Ethereum Staking Reporting API v2 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
• Holesky

👍

Info:

For more information, please refer to the Migration Guide.

➡️ Get the Rewards

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

Total Reward comprises mevBlockReward, syncCommitteeReward, attestationReward, and blockReward from the metadata fields.

📘

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": "0x821dcb238db02d80a16f20c585027dd8e2390de32062f8e14f41d5236c4e520acf6e920e05435bc144c6d84b8b6debef",
    "denomination": "wei",
    "return": "234992641843725404",
    "startTime": 1710505035,
    "endTime": 1713183434,
    "period": "MONTHLY",
    "startBalance": "32007042885000000000",
    "metadata": {
        "attestationReward": "66144485000000000",
        "blockFeeReward": "74040431334628186",
        "blockReward": "75359369000000000",
        "deposits": "0",
        "epoch": "270002-276976",
        "index": "1111111",
        "mevBlockReward": "93488787843725404",
        "syncCommitteeReward": "0",
        "withdrawals": "148393011000000000"
    }
}

ℹ️ 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.