This document outlines the current structure of the RatedAPI, provides context on the semantics that underlie it, and insight into how it will evolve in the coming weeks.
🔎 https://api.rated.network/docs
The RatedAPI has been live since May 2022, and is currently adopted for rewards tracking, performance monitoring and benchmarking, as well as a source of truth, by the likes of Lido, Kiln, SSV Network, Obol, Nexus Mutual and an additional 30+ regular users. We are working through some really exciting integrations that we will be announcing in Q1 2023.
In order to make it maximum flexible and frictionless for downstream adopters to integrate with, and maximise the surface for learning, we made the conscious decision to allow the permission-less use of our API.
This design decision has had direct influence in the current structure of the schema, keeping it purposefully expansive—a property that is subject to change.
<aside> 💡 See the Extensions section below for more info on upcoming changes.
</aside>
All rewards and performance metrics are hosted under the "effectiveness" endpoint [https://api.rated.network/docs#/default/get_effectiveness_v0_eth_validators__validator_index_or_pubkey__effectiveness_get]
By default, the API returns data in daily chunks (24h / 225 epoch / 7200 slot increments), starting from Beacon Chain genesis. As such, Day 0 encompasses the 225 epoch period betwee epochs [0, 225), and maps to datetime 2020-12-01 12:00:23 UTC to 2022-12-02 12:00:11 UTC.
The RatedAPI supports querying for rewards, performance and metadata at the validator pubkey level, all the way up to a pre-configured operator (list of pubkeys) or pool (list of operators).
<aside> 💡 We have the capability to aggregate statistics on an arbitrary number of keys, and can pre-configure entity aggregations that follow continuously updated registries (e.g. https://rated.network/o/Lido)
</aside>
The RatedAPI also supports aggregation, so days can be rolled up in weeks, months, quarters, years and even all time.
To use this feature, the granularity query parameter can be used. For example, to obtain monthly aggregates for validator index 100:
curl -X 'GET' \\ Â
'[<https://api.rated.network/v0/eth/validators/100/effectiveness?size=10&granularity=month&filterType=day>](<https://api.rated.network/v0/eth/validators/100/effectiveness?size=10&granularity=day&filterType=day>)' \\
 -H 'accept: application/json' \\
 -H 'X-Rated-Network: mainnet'
Pagination works backwards from the last full day to genesis. So from=700&size=10 will return data from day 700 until day 691.
datetime is also supported in from. Alternatively, one could query from=2022-12-01&size=10 to obtain data from 2022-12-01 .