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 [e-mail].

Entity summary statistics

Get Summaries

GET/v0/eth/operators

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

page*Page

total*Total

data*Data

nextNext

Request

JavaScriptCurlPython

const response = await fetch('/v0/eth/operators?window=1d', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "page": {
    "from": 0,
    "to": 0,
    "size": 10,
    "granularity": "hour",
    "filterType": "hour"
  },
  "total": 0,
  "data": [
    {
      "id": "0xa40dfee99e1c85dc97fdc594b16a460717838703",
      "idType": "depositAddress",
      "timeWindow": "1d",
      "validatorCount": 37361,
      "avgCorrectness": 0.9872805930783213,
      "avgInclusionDelay": 1.0209945048723401,
      "avgUptime": 0.9990847259025307,
      "avgValidatorEffectiveness": 96.65219797373126,
      "clientPercentages": [
        {
          "client": "Prysm",
          "percentage": 0.8462792766083606
        },
        {
          "client": "Nimbus",
          "percentage": 0.04797904931317324
        },
        {
          "client": "Teku",
          "percentage": 0.034044866093487496
        },
        {
          "client": "Lighthouse",
          "percentage": 0.07169680798497875
        }
      ],
      "networkPenetration": 0.07855633469653803,
      "relayerPercentages": [],
      "operatorTags": [],
      "displayName": "0xa40dfee99e1c85dc97fdc594b16a460717838703"
    }
  ],
  "next": "text"
}

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 👇

Parameter	Context
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 👇

Get Operator Summary

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

Path parameters

operator_id*Operator Id

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

id*Id

idType*IdType

An enumeration.

depositAddresswithdrawalAddressnodeOperatorpoolpoolShareentityvalidatorprivateSet

timeWindow*TimeWindow

An enumeration.

1d7d30dall

validatorCount*Validatorcount

avgCorrectness*Avgcorrectness

avgInclusionDelayAvginclusiondelay

avgUptime*Avguptime

avgValidatorEffectiveness*Avgvalidatoreffectiveness

clientPercentages*Clientpercentages

networkPenetrationNetworkpenetration

relayerPercentages*Relayerpercentages

nodeOperatorCountNodeoperatorcount

operatorTags*Operatortags

displayNameDisplayname

aprPercentageAprpercentage

Request

JavaScriptCurlPython

const response = await fetch('/v0/eth/operators/{operator_id}/summary?window=1d', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "id": "0xa40dfee99e1c85dc97fdc594b16a460717838703",
  "idType": "depositAddress",
  "timeWindow": "1d",
  "validatorCount": 37361,
  "avgCorrectness": 0.9872805930783213,
  "avgInclusionDelay": 1.0209945048723401,
  "avgUptime": 0.9990847259025307,
  "avgValidatorEffectiveness": 96.65219797373126,
  "clientPercentages": [
    {
      "client": "Prysm",
      "percentage": 0.8462792766083606
    },
    {
      "client": "Nimbus",
      "percentage": 0.04797904931317324
    },
    {
      "client": "Teku",
      "percentage": 0.034044866093487496
    },
    {
      "client": "Lighthouse",
      "percentage": 0.07169680798497875
    }
  ],
  "networkPenetration": 0.07855633469653803,
  "relayerPercentages": [],
  "operatorTags": [],
  "displayName": "0xa40dfee99e1c85dc97fdc594b16a460717838703"
}

Parameter	Context
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

Get Percentiles

GET/v0/eth/operators/percentiles

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

timeWindow*TimeWindow

An enumeration.

1d7d30dall

rank*Rank

value*Value

Request

JavaScriptCurlPython

const response = await fetch('/v0/eth/operators/percentiles?window=1d&idType=depositAddress', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

[
  {
    "timeWindow": "1d",
    "rank": 0,
    "value": 0
  }
]

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 👇

Parameter	Context
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

Get Operator

GET/v0/eth/operators/{operator_id}

Path parameters

operator_id*Operator Id

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

id*Id

idType*IdType

An enumeration.

depositAddresswithdrawalAddressnodeOperatorpoolpoolShareentityvalidatorprivateSet

displayName*Displayname

operatorTags*Operatortags

nodeOperatorCountNodeoperatorcount

Request

JavaScriptCurlPython

const response = await fetch('/v0/eth/operators/{operator_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "id": "Stakefish",
  "idType": "nodeOperator",
  "displayName": "Stakefish",
  "operatorTags": [
    {
      "name": "operator"
    }
  ],
  "nodeOperatorCount": 2
}

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 👇

Parameter	Context
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

Get Effectiveness

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

Path parameters

operator_id*Operator Id

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

page*Page

total*Total

data*Data

nextNext

Request

JavaScriptCurlPython

const response = await fetch('/v0/eth/operators/{operator_id}/effectiveness', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "page": {
    "from": 0,
    "to": 0,
    "size": 10,
    "granularity": "hour",
    "filterType": "hour"
  },
  "total": 0,
  "data": [
    {
      "day": 796,
      "startEpoch": 179324,
      "endEpoch": 179100,
      "id": "Stakefish",
      "idType": "nodeOperator",
      "validatorCount": 16075,
      "avgInclusionDelay": 1.0138705386457403,
      "avgUptime": 0.9999466390184881,
      "avgCorrectness": 0.9929917401071404,
      "avgProposerEffectiveness": 99.53271028037379,
      "avgValidatorEffectiveness": 97.96642775943795,
      "totalUniqueAttestations": 3616682,
      "sumCorrectHead": 3547355,
      "sumCorrectTarget": 3612248,
      "sumInclusionDelay": 3666847,
      "sumProposedCount": 213,
      "sumProposerDutiesCount": 214,
      "slashesCollected": 0,
      "slashesReceived": 0,
      "sumEarnings": 56766373292,
      "sumEstimatedRewards": 56675239144,
      "sumEstimatedPenalties": -82967688,
      "networkPenetration": 0.03132911454080191,
      "sumPriorityFees": 10662221791,
      "sumBaselineMev": 5266131924,
      "sumMissedExecutionRewards": 58181568,
      "sumConsensusBlockRewards": 6554423259,
      "sumMissedConsensusBlockRewards": 31228533,
      "sumAllRewards": 72694727007,
      "sumCorrectSource": 3614403,
      "avgAttesterEffectiveness": 97.9580945527236,
      "sumMissedSyncSignatures": 2837,
      "sumSyncCommitteePenalties": -44317643,
      "sumLateSourceVotes": 2279,
      "sumWrongTargetVotes": 4434,
      "sumLateTargetVotes": 0,
      "sumWrongTargetPenalties": -28763358,
      "sumLateTargetPenalties": 0,
      "sumMissedAttestations": 193,
      "sumMissedAttestationPenalties": -1926140,
      "sumWrongHeadVotes": 48767,
      "sumWrongHeadPenalties": 0,
      "sumAttestationRewards": 50120815885,
      "sumLateSourcePenalties": -7960547,
      "sumExecutionProposedEmptyCount": 0,
      "sumMissedAttestationRewards": 269961427,
      "sumMissedSyncCommitteeRewards": 44317643,
      "sumExternallySourcedExecutionRewards": 14862131536
    }
  ],
  "next": "text"
}

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 👇

Parameter	Context
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

Get Relayer Stats

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

Path parameters

operator_id*Operator Id

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

relayer*Relayer

percentage*Percentage

Request

JavaScriptCurlPython

const response = await fetch('/v0/eth/operators/{operator_id}/relayers', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

[
  {
    "relayer": "agnostic",
    "percentage": 0.00041296716911005574
  }
]

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 👇

Parameter	Context
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%

Get Operator Apr

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

Path parameters

operator_id*Operator Id

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

id*Id

idType*IdType

An enumeration.

depositAddresswithdrawalAddressnodeOperatorpoolpoolShareentityvalidatorprivateSet

timeWindow*TimeWindow

An enumeration.

1d7d30dall

aprType*AprType

An enumeration.

backwardforward

percentage*Percentage

percentageConsensus*Percentageconsensus

percentageExecution*Percentageexecution

activeStake*Activestake

activeValidators*Activevalidators

Request

JavaScriptCurlPython

const response = await fetch('/v0/eth/operators/{operator_id}/apr?window=1d', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "id": "Lido",
  "idType": "pool",
  "timeWindow": "1d",
  "aprType": "backward",
  "percentage": 5.35,
  "percentageConsensus": 4.04,
  "percentageExecution": 1.31,
  "activeStake": 4823520000000000,
  "activeValidators": 150735
}

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 👇

Parameter	Context
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

Get Activations Exits Aggregate

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

Path parameters

operator_id*Operator Id

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

timeWindow*TimeWindow

An enumeration.

1d7d30dall

id*Id

idType*IdType

An enumeration.

depositAddresswithdrawalAddressnodeOperatorpoolpoolShareentityvalidatorprivateSet

stakeAction*StakeAction

An enumeration.

activationexit

validatorCount*Validatorcount

avgEpochsToAction*Avgepochstoaction

avgMinutesToAction*Avgminutestoaction

amountGweiAmountgwei

Request

JavaScriptCurlPython

const response = await fetch('/v0/eth/operators/{operator_id}/stakeMovement', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

[
  {
    "timeWindow": "1d",
    "id": "text",
    "idType": "depositAddress",
    "stakeAction": "activation",
    "validatorCount": 0,
    "avgEpochsToAction": 0,
    "avgMinutesToAction": 0,
    "amountGwei": 0
  }
]

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 👇

Parameter	Context
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.