Already familiar with staking rewards? Read about our rewards API here.

Of course, the reason you are staking with us is to earn some of that sweet ETH in return for securing the chain. Rewards are accrued at two layers when you are staking a validator:

1. Consensus layer: Rewards for fulfilling validator duties, such as completing attestations, sync committee duties, and proposing blocks - paid via newly minted ETH on the consensus layer.
2. Execution layer: Rewards from MEV and priority fees.

Our API not only facilitates running your validators to help you earn rewards but also emphasises the importance of auditability and reporting. Our API provides detailed access to the daily income on a per-validator basis.

Consensus Layer Rewards

The official Ethereum.org documentation does a great job at breaking down the rewards calculations. These rewards will be directly accumulate into your validators balance every epoch (~6.4 minutes). Because there is no additional benefit for maintaining a balance > 32 ETH, there will be a periodic sweeping of these rewards into your withdrawal address.

Execution Layer Rewards

When your validator proposes a block, any Maximum Extractable Value (MEV) rewards and/or tips set by transaction senders are immediately delivered to your fee recipient address. It's important to note that the ETH earned on the execution layer is not newly minted. Instead, it is transferred via the gas fees used to pay for transactions within the block.

Execution Layer Rewards Distribution

• Every validator that we operate makes use of a 'fee recipient' which is where the execution layer rewards are sent. Every institutional partner needs to have their default recipient configured during onboarding. We are able to deploy a dedicated smoothing contract, identical to the one stakefish uses for our own retails customers.
• Additionally, the default fee recipient can be overwritten to any Ethereum address during validator creation.

Rewards API

As explained above, there are various moving parts when it comes to rewards which can present a challenge if you want to track your validators performance. Fortunately this is a problem that we have solved with our purpose built rewards ingestion pipeline.

We keep track of every single reward and penalty for all of our validators, and then once a day at midnight UTC we perform final accounting and prepare this data for delivery via our API. The two key endpoints that you will use to track your rewards are detailed below.

Daily Rewards

The /v2/rewardsendpoint returns historical rewards on a daily basis for a list of validator indices, also includes the cumulative data which is very handy for displaying charts as shown below.

Example request

curl 'https://staging-holesky-rewards.oracle.ethereum.fish/v2/rewards' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  --data-raw '{"validatorIndices":[1712396,1712400,1713616],"startDate":"2024-07-23","endDate":"2024-08-21"}'

Example response

{
  "results": [
    {
      "validatorCount": 3,
      "summaryDate": "2024-08-21",
      "effectiveBalance": "32000000000000000000",
      "closingBalance": "32002005720000000000",
      "executionIncome": "0",
      "cumulativeExecutionIncome": "9680955466478960",
      "consensusRewards": "1447403000000000",
      "consensusPenalties": "12925000000000",
      "withdrawals": "0",
      "consensusIncome": "1434478000000000",
      "cumulativeConsensusIncome": "171865607000000000",
      "cumulativeTotalIncome": "181546562466478960"
    },
    {
      "validatorCount": 3,
      "summaryDate": "2024-08-20",
      "effectiveBalance": "32000000000000000000",
      "closingBalance": "32000571242000000000",
      "executionIncome": "0",
      "cumulativeExecutionIncome": "9680955466478960",
      "consensusRewards": "1430945000000000",
      "consensusPenalties": "1925000000000",
      "withdrawals": "7253083000000000",
      "consensusIncome": "1429020000000000",
      "cumulativeConsensusIncome": "170431129000000000",
      "cumulativeTotalIncome": "180112084466478960"
    },
    ...
  ],
  "totalItems": 30
}

Charts, beautiful charts!

Reward Statistics

The/v2/rewards/statsendpoint returns the APR and estimated rewards computed over a specific range & for a list of validators.

Example request

curl 'https://staging-holesky-rewards.oracle.ethereum.fish/v2/rewards/stats' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  --data-raw '{"validatorIndices":[1712396,1712400,1713616],"startDate":"2024-07-23","endDate":"2024-08-21"}'

Example response

{
  "percentageTotal": "3.90915209954494168125",
  "percentageExecution": "0.3683301025136915595",
  "percentageConsensus": "3.54082199703125012175",
  "estimatedTotalIncome": "102745681466478960",
  "estimatedConsensusIncome": "93064726000000000",
  "estimatedExecutionIncome": "9680955466478960",
  "aprType": "backward",
  "timeWindow": "30d"
}

What it looks like in action

👉

Because rewards are aggregated at the end of each day, its important to note that you can only fetch the rewards information for today() -1. If no start & end dates are specified in your request we will return the latest 14 days of data.