Operators

Querying into pre-materialized operator groupings.

The Rated API enables users to query into key metrics of pre-materialized entities. This works pretty much as hinted by the Rated Network Explorer, but with a much higher degree of flexibility in terms of time-frames, and granularity in terms of metrics.

What are pre-materialized entities?

The shortest way to put it, in an Ethereum context, is "groups of validators bound together by agency". This could be:

  1. a pool (e.g. Lido)

  2. a node operator (e.g. Allnodes)

  3. a fraction of a node operator's fleet that maps under a specific pool (e.g. Stakefish under Lido)

  4. a group of validator indices mapped to a specific deposit address (e.g. 0xdd192...)

  5. a group of validator indices mapped to a specific withdrawal address (e.g. 0xdd192...)

If you want to get your pre-materialized set tracked on Rated, get in touch via hello@rated.network.

Entity summary statistics

This endpoint returns summary statistics for all the operators Rated has pre-materialized views onโ€“โ€“commensurate to the output you might see on the Rated Network Explorer.

Here's how to interpret the inputs required to operate it ๐Ÿ‘‡

ParameterContext

window

The time window of aggregation. You might ask for 1d, 7d, 30d or All-time data

idType

The type of entity class you would like returned. You might ask for pool, poolShare, nodeOperator, depositAddress or withdrawalAddress

size

The number of results included per page

parentId

Specifying a pool or node operator so that the response is focused on the Pool sharesof said entity.

For an endpoint that returns the same information, but only for a specified entityโ€“โ€“rather than a list of entities, see ๐Ÿ‘‡

ParameterContext

idType

The 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.

Percentile ranks

This endpoint returns a list of entities with their respective percentile rank score, according to their effectiveness rating. You can learn more about percentiles through our docs. Also worth digging deeper into the Rated Effectiveness Rating if you're not already familiar with it.

Here's how to interpret the inputs required to operate it ๐Ÿ‘‡

ParameterContext

window

The time window of aggregation. You might ask for 1d, 7d, 30d or All-time data

idType

The type of entity class you would like returned. You might ask for pool, poolShare, nodeOperator, depositAddress or withdrawalAddress

Operator metadata

This endpoint returns profile information on specific operators. It's still relatively nascent, but expect this to be enriched with all kinds of useful information in the coming quarters.

Here's how to interpret the inputs required to operate it ๐Ÿ‘‡

ParameterContext

operatorId

The name of the entity in question. This could be deposit address, a withdrawal address, a node operator, or a pool. Please see our docs to get a better understanding of how we aggregate validators.

idType

The 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.

The pool and node operator inputs are case sensitive. For example:

โŒ coinbase

โ˜‘๏ธ Coinbase

Operator effectiveness

This endpoint returns a bunch of useful information on the historical performance of a single operator. This includes rewards (aggregate and granular), performance (effectiveness and its components), slashing history and much more. For a glossary of the variables returned see effectiveness.

Here's how to interpret the inputs required to operate it ๐Ÿ‘‡

ParameterContext

filterType

hour, day and datetime

from

Start day (integer) or datetime (e.g. from=โ€œ2022-12-01โ€)

granularity

The size of time increments you are looking to query. Can be day / week / month / quarter / year.

size

The number of results included per page

idType

The 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.

include

A list of field names. Use it to filter the specific fields you want in the response payload

Relay distribution

This endpoints returns information relating to an entity's historical distribution of relays they have procured blocks from.

Here's how to interpret the inputs required to operate it ๐Ÿ‘‡

ParameterContext

operatorId

The name of the entity in question. This could be deposit address, a node operator, or a pool. Please see our docs to get a better understanding of how we aggregate validators.

window

The time window of aggregation. You might ask for 1d, 7d, 30d or All-time data.

idType

The 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.

Entity APR%

This endpoint returns historical data on the returns any of the entities supported have recorded. What's really exciting about this one, is the ability to dig deep into the components of the aggregate return (e.g. returned earned on the execution layer vs the consensus layer etc).

Here's how to interpret the inputs required to operate it ๐Ÿ‘‡

ParameterContext

operatorId

The name of the entity in question. This could be deposit address, a node operator, or a pool. Please see our docs to get a better understanding of how we aggregate validators.

window

The time window of aggregation. You might ask for 1d, 7d, 30d or All-time data.

idType

The type of entity class you would like returned. You might ask for pool, poolShare, nodeOperator, depositAddress and withdrawalAddress.

Activations and withdrawals state and status

This endpoint returns data on the activation and exit activity of a specific pre-materialized view (e.g. operator, deposit address etc).

Here's how to interpret the inputs required to operate it ๐Ÿ‘‡

ParameterContext

operatorId

The name of the entity in question. This could be deposit address, a node operator, or a pool. Please see our docs to get a better understanding of how we aggregate validators.

stakeAction

Direction of flow. This can be either of activation or exit.

window

The time window of aggregation. You might ask for 1d, 7d, 30d or All-time data.

idType

The 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.

Last updated