The Rated API facilitates efficient and detailed management of rewards distributed on Ethereum. By leveraging the API, users can achieve granular insight into their reward dynamics, aiding in precise accounting and better decision-making.

  1. Node Operators can keep track of their rewards in granular detail, accounting for the attribution of rewards for specific validator duties.

  2. Pools, Custodians and Centralised Exchanges can take stock of the rewards they receive from one or more staking providers in a consolidated view, including a breakdown of the different sources of rewards.

​
Integration Steps

​
Step 1: Generate Authorization Token

Sign into the Rated Console to generate your API Token.

​
Step 2: Get Rewards Data

The Rated API offers time window aggregation, allowing you to consolidate data over various time periods such as day, week, month, quarter, year or all time. You can retrieve reward info in two ways:

  1. Pre-materialized views

  2. Specific validator groups

​
Step 2.1: Getting Rewards for Pre-materialized Views

Imagine you’re Kiln (a Node Operator), Lido (a Pool), or Coinbase (an Exchange). You want all your reward details (consensus layer and execution layer including penalties) for August 2023, shown daily. Here’s how you’d go about getting this data.

Call the Operator effectivenessendpoint with the following parameters set:

KeyRequired?ValueDescription
operator_idYesstringName of the Entity. For this example, you should either put Lido ,Kiln orCoinbase Note: the operator_id is case-sensitive and should follow the same typecase as they are on the Rated Explorer.
idTypeYesstringThe type of entity class you would like returned. You might ask for pool, poolShare, nodeOperator, depositAddress, or withdrawalAddress. Note: it is optional and can be inferred automatically for pools, pool shares and node operators. It defaults to depositAddress if it is missing and an address is provided.
granularityYesstringThe size of time increments you are looking to query. Can be day / week / month / quarter / year. For this example, you should set granularity to day.
fromYesstringStart day (integer) or date (e.g. from=“2022-12-01”) For this example, set from to 2023-08-31
sizeYesintegerThe number of results included per page. For this example, you should set size as 31 as we want the monthly data for August 2023.
filterTypeYesstringhour, day and datetime For this example, set to datetime
includeYesarrayA list of field names. To get the rewards data, you should include the following data: day, sumEarnings, sumEstimatedRewards, sumEstimatedPenalties, sumPriorityFees, sumBaselineMev, sumMissedExecutionRewards, sumConsensusBlockRewards, sumMissedConsensusBlockRewards, sumAllRewards, sumAttestationRewards, sumMissedAttestationRewards, sumMissedAttestationPenalties, sumWrongTargetPenalties, sumLateTargetPenalties, sumWrongHeadPenalties and sumLateSourcePenalties

​
Get Effectiveness

GET
/
v0
/
eth
/
operators
/
{operator_id}
/
effectiveness

Example: Obtaining daily reward metrics for the month of August 2023 for Kiln

You will get the following response:

Note that if you’re looking to get the same data grouped by withdrawal/deposit address, you can simply input operator_id as the address (0x..) and idType as withdrawalAddress or depositAddress.

​
Step 2.2: Getting Rewards for specific validators groups

For validator groupings, you will need to call the Aggregating validator indices endpoint. We’ll show this similarly as above for all reward details for the month of August 2023 for a set of validator indices, aggregated daily.

KeyRequired?ValueDescription
pubkeys (OR) indicesYesarray [string] (OR) array [integer]Array of validator pubkeys or indicies you’re performing the grouped analysis for. For this example, you should put indices as 675893 675894 and 675895
filterTypeYesstringhour, day and datetime. For this example, set to datetime
fromYesstringThe most recent date for your desired timeline. In this example, it is 2023-08-31
sizeYesintegerThe number of results included per page. For this example, you should set size as 31 as we want the monthly data for August 2023.
granularityYesstringThe size of time increments you are looking to query. Can be day / week / month / quarter / year. For this example, set granularity to day.
groupByYesstringAggregation groupings. Can be timeWindow if you’d like to aggregation for your desired time window or validator if you’d like it per validator. For this example, set it to timeWindow.
includeYesarray [string]A list of field names. To get the rewards data, you should include the following data: day, sumEarnings, sumEstimatedRewards, sumEstimatedPenalties, sumPriorityFees, sumBaselineMev, sumMissedExecutionRewards, sumConsensusBlockRewards, sumMissedConsensusBlockRewards, sumAllRewards, sumAttestationRewards, sumMissedAttestationRewards, sumMissedAttestationPenalties, sumWrongTargetPenalties, sumLateTargetPenalties, sumWrongHeadPenalties and sumLateSourcePenalties

​
Get Effectiveness Aggregation

GET
/
v0
/
eth
/
validators
/
effectiveness

Example: Obtaining daily reward metrics for the month of August 2023 for Validator group {675893, 675894, 675895}

You will get the following response:

ValidatorsPerformance Benchmarking