API reference

Resources dedicated to exposing and explaining the various endpoints that the Rated API supports.

You can access our API's Swagger documentation via api.rated.network/docs

Making sense of the API input

The standard form of the Rated API looks something like this 👇


At the highest level, here's how you should interpret the class of instructions you are passing to it:



The version of the API you are on. Currently the API is in v0


The network you are querying


The class of entity you are querying for. This could be either of Validators, Operators and Network


The specific resource you are querying for

How time works for Ethereum


All rewards and performance metrics are hosted under the "effectiveness" endpoint.

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 between epochs [0, 225), and maps to datetime 2020-12-01 12:00:23 UTC to 2022-12-02 12:00:11 UTC.

How time works for Polygon

By default, the API returns data per checkpoint starting from checkpoint 52109 which corresponds to timestamp 2023-10-13 00:21:25 UTC

You can also request for data per date ie say 2024-01-01. The response will contain a list of items where each item corresponds to a day's worth of data, say from 2024-01-01 00:00:00 UTC to 2024-01-01 23:59:59 UTC


All endpoints under Polygon are mainly indexed on UTC days or numbered checkpoints submitted by the PoS chain to Ethereum.


The "rewards" and "performance" endpoints, which contains validator rewards and performance data respectively, returns data in daily chunks, indexed on UTC days, epochs, or 20 minute intervals.

The "latency" endpoint, which mainly contains data on validator voting latency, returns real-time data over the last 20 minutes.

Entity granularity on Ethereum

The Rated API 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).

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. rated.network/o/Lido).

If that's relevant to your use case, get in touch with us via hello@rated.network.

Time window aggregation on Ethereum

The Rated API also supports aggregation, so days can be rolled up in weeks, months, quarters, years and even all time on Ethereum.

To use this feature, the granularity query parameter can be used. For example, to obtain monthly aggregates for validator index 100 on Ethereum:

curl -X 'GET' \\   
	'[<https://api.rated.network/v0/eth/validators/100/effectiveness?size=10&granularity=month&filterType=day>]' \\
   -H 'accept: application/json' \\
   -H 'X-Rated-Network: mainnet'

Time window aggregation on Polygon

Aggregations on Polygon can be done with on a day basis for the effectiveness endpoint and on a 1d, 7d, 30d and all time window for other endpoints.

For example, to obtain daily aggregates on effectiveness for validator index 87 on Polygon:

curl -X 'GET' \\   
	'[<https://api.rated.network/v0/polygon/validators/87/effectiveness?from=2024-03-29&granularity=day)>]' \\
   -H 'accept: application/json' \\
   -H 'X-Rated-Network: polygon'

Last updated