Validators

Querying into individual validator indices or aggregations of validator indices.

The RatedAPI allows you to aggregate stats on validator indices on-the-fly. Head on over to Aggregating validator indices to learn more.

The Validators class is the lowest order of aggregation that the Rated API supports. The effectiveness endpoint returns you all kinds of useful information (e.g. rewards, performance etc) about a specific validator index, in the requested time-frame.

Single validator index effectiveness

Get Effectiveness

GET/v0/eth/validators/{validator_index_or_pubkey}/effectiveness

Path parameters

validator_index_or_pubkey*Validator Index Or Pubkey

integerstring

Query parameters

Header parameters

Response

200307400

Successful Response

Body

application/json

page*Page

total*Total

data*Data

nextNext

Request

JavaScriptCurlPython

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

Response

200400

{
  "page": {
    "filterType": "day",
    "granularity": "day",
    "size": 1
  },
  "data": [
    {
      "attesterEffectiveness": 98.82005899705014,
      "avgCorrectness": 0.9925925925925926,
      "avgInclusionDelay": 1.0044444444444445,
      "day": 803,
      "earnings": 2958548,
      "endEpoch": 180675,
      "estimatedPenalties": -6461,
      "estimatedRewards": 2965823,
      "executionProposedEmptyCount": 0,
      "proposedCount": 0,
      "proposerDutiesCount": 0,
      "slashesCollected": 0,
      "slashesReceived": 0,
      "startEpoch": 180899,
      "sumAllRewards": 2958548,
      "sumAttestationRewards": 2965823,
      "sumBaselineMev": 0,
      "sumConsensusBlockRewards": 0,
      "sumCorrectHead": 221,
      "sumCorrectSource": 225,
      "sumCorrectTarget": 224,
      "sumExternallySourcedExecutionRewards": 0,
      "sumInclusionDelay": 226,
      "sumLateSourcePenalties": 0,
      "sumLateSourceVotes": 0,
      "sumLateTargetPenalties": 0,
      "sumLateTargetVotes": 0,
      "sumMissedAttestationPenalties": 0,
      "sumMissedAttestationRewards": 19233,
      "sumMissedAttestations": 0,
      "sumMissedConsensusBlockRewards": 0,
      "sumMissedExecutionRewards": 0,
      "sumMissedSyncCommitteeRewards": 0,
      "sumPriorityFees": 0,
      "sumSyncCommitteePenalties": 0,
      "sumWrongHeadPenalties": 0,
      "sumWrongHeadVotes": 3,
      "sumWrongTargetPenalties": -6461,
      "sumWrongTargetVotes": 1,
      "syncSignatureCount": 0,
      "totalAttestationAssignments": 225,
      "totalAttestations": 237,
      "totalUniqueAttestations": 225,
      "uptime": 1,
      "validatorEffectiveness": 98.82005899705014,
      "validatorIndex": 100
    }
  ],
  "next": "/v0/eth/validators/100/effectiveness?size=1&from=802&granularity=day&filterType=day",
  "total": 804
}

This endpoint returns all the useful information you will ever need on the historical performance of a single validator index. 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	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
include	A list of field names. Use it to filter the specific fields you want in the response payload

Aggregating validator indices

Get Effectiveness Aggregation

GET/v0/eth/validators/effectiveness

Query parameters

Header parameters

Response

200307400

Successful Response

Body

application/json

PaginatedValidatorEffectivenessDataOrAggregation

PaginatedValidatorEffectivenessDataPaginatedValidatorEffectivenessAggregation

Request

JavaScriptCurlPython

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

Response

200400

{
  "data": [
    {
      "attesterEffectiveness": 98.46868397067385,
      "avgCorrectness": 0.9951851851851852,
      "avgInclusionDelay": 1.0107407407407407,
      "day": 803,
      "earnings": 35804991,
      "endDay": 792,
      "endEpoch": 178200,
      "estimatedPenalties": -22921,
      "estimatedRewards": 35849013,
      "executionProposedEmptyCount": 0,
      "proposedCount": 0,
      "proposerDutiesCount": 0,
      "slashesCollected": 0,
      "slashesReceived": 0,
      "startDay": 803,
      "startEpoch": 180899,
      "sumAllRewards": 35804991,
      "sumAttestationRewards": 35849013,
      "sumBaselineMev": 0,
      "sumConsensusBlockRewards": 0,
      "sumCorrectHead": 2665,
      "sumCorrectSource": 2699,
      "sumCorrectTarget": 2697,
      "sumExternallySourcedExecutionRewards": 0,
      "sumInclusionDelay": 2729,
      "sumLateSourcePenalties": -3486,
      "sumLateSourceVotes": 1,
      "sumLateTargetPenalties": 0,
      "sumLateTargetVotes": 0,
      "sumMissedAttestationPenalties": 0,
      "sumMissedAttestationRewards": 137813,
      "sumMissedAttestations": 0,
      "sumMissedConsensusBlockRewards": 0,
      "sumMissedExecutionRewards": 0,
      "sumMissedSyncCommitteeRewards": 0,
      "sumPriorityFees": 0,
      "sumSyncCommitteePenalties": 0,
      "sumWrongHeadPenalties": 0,
      "sumWrongHeadVotes": 21,
      "sumWrongTargetPenalties": -19435,
      "sumWrongTargetVotes": 3,
      "syncSignatureCount": 0,
      "totalAttestationAssignments": 2700,
      "totalAttestations": 2919,
      "totalUniqueAttestations": 2700,
      "uptime": 1,
      "validatorEffectiveness": 98.46868397067385
    }
  ],
  "next": "/v0/eth/validators/effectiveness?indices=100&indices=101&groupBy=timeWindow&granularity=month&size=1&from=791&filterType=day",
  "page": {
    "filterType": "day",
    "granularity": "month",
    "size": 1
  },
  "total": 27
}

The Rated API enables the aggregation of all the metrics that live under effectiveness accross an arbitrary number of validator indices or pubkeys, at the endpoint level.

Here's how to interpret the inputs required to operate it 👇

Parameter	Context
filterType	day and datetime
from	Start day (integer) or datetime (e.g. from=“2022-12-01”)
to	End 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
groupBy	Time window or validator; we either group by validator index or across time
include	A list of field names. Use it to filter the specific fields you want in the response payload

Validator metadata [single keys]

Get Metadata

GET/v0/eth/validators/{validator_index_or_pubkey}

Path parameters

validator_index_or_pubkey*Validator Index Or Pubkey

integerstring

Header parameters

Response

200307400

Successful Response

Body

application/json

validatorIndex*Validatorindex

validatorPubkey*Validatorpubkey

poolPool

dvtNetworkDvtnetwork

nodeOperatorsNodeoperators

depositAddressesDepositaddresses

dvtOperatorsDvtoperators

activationEpochActivationepoch

activationEligibilityEpochActivationeligibilityepoch

exitEpochExitepoch

withdrawableEpochWithdrawableepoch

withdrawalAddressWithdrawaladdress

subpoolSubpool

Request

JavaScriptCurlPython

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

Response

200400

{
  "activationEpoch": 0,
  "activationEligibilityEpoch": 0,
  "depositAddresses": [
    "0x74134d0c91798d720a5585364bb4be7396c5b973"
  ],
  "dvtOperators": [],
  "nodeOperators": [],
  "validatorIndex": 100,
  "validatorPubkey": "0xb5bc96b70df0dfcc252c9ff0d1b42cb6dc0d55f8defa474dc0a5c7e0402c241e2850fea9c582e276b638b3c2c3a5ec55",
  "withdrawalAddress": "0xfff1ce616cf83327981bf61396ad0c04e0c8b771"
}

This endpoint allows for a reverse lookup into the entity-to-validator index mappings that live in the RatedDB. Simply pass a validator index to the endpoint, and the response will tell you which operator or pool this validator is associated with.

Validators metadata [groups]

Get Metadata List

GET/v0/eth/validators

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/validators', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "page": {
    "from": 0,
    "size": 3
  },
  "total": 11,
  "data": [
    {
      "validatorIndex": 1,
      "validatorPubkey": "0xb44440543ceef8d77e065c70da15f7b731e56db5457571c465f025e032bbcd263a0990c8749b4ca6ff20d77004466666",
      "pool": "",
      "subpool": "",
      "dvtNetwork": "",
      "nodeOperators": [],
      "depositAddresses": [
        "0xc34eb7e3f34e54646d7cd140bb7c20a466b3e852"
      ],
      "dvtOperators": [],
      "activationEpoch": 169000,
      "activationEligibilityEpoch": 171000,
      "exitEpoch": 172000,
      "withdrawableEpoch": 172256,
      "withdrawalAddress": "0x0d369bb49efa5100fd3b86a9f828c55da04d2d50"
    },
    {
      "validatorIndex": 4,
      "validatorPubkey": "0xa62420543ceef8d77e065c70da15f7b731e56db5457571c465f025e032bbcd263a0990c8749b4ca6ff20d77004454b51",
      "pool": "",
      "subpool": "",
      "dvtNetwork": "",
      "nodeOperators": [],
      "depositAddresses": [
        "0xc34eb7e3f34e54646d7cd140bb7c20a466b3e852"
      ],
      "dvtOperators": [],
      "activationEpoch": 169000,
      "activationEligibilityEpoch": 171000,
      "exitEpoch": 172000,
      "withdrawableEpoch": 172256,
      "withdrawalAddress": "0x0d369bb49efa5100fd3b86a9f828c55da04d2d50"
    },
    {
      "validatorIndex": 10,
      "validatorPubkey": "0xc55540543ceef8dccc065c70da15f7b731e56db5457571c465f0254442bbcd263a0111c8749b4ca6ff20d77004466777",
      "pool": "",
      "subpool": "",
      "dvtNetwork": "",
      "nodeOperators": [],
      "depositAddresses": [
        "0xc34eb7e3f34e54646d7cd140bb7c20a466b3e852"
      ],
      "dvtOperators": [],
      "activationEpoch": 169000,
      "activationEligibilityEpoch": 171000,
      "exitEpoch": 172000,
      "withdrawableEpoch": 172256,
      "withdrawalAddress": "0x0d369bb49efa5100fd3b86a9f828c55da04d2d50"
    }
  ],
  "next": "/v0/eth/validators?from=11&size=3&operatorsIds=&idType="
}

This endpoint allows users to request metadata for a group of validators that map to the same operator or pool (i.e. it gives you an answer to the question "give me all of Kiln's validator indices under Lido").

Parameter	Context
idType	The type of entity class you would like to filter by. You might ask for pool, nodeOperator
operatorsIds	An array of entities names you want to filter by
from	The validator index you want to start to navigate from
size	The number of results included per page
withdrawalAddress	Filter by the withdrawal address

Rated builds and operates the most complete dataset for validator id mappings. These are gated endpoints and is being provisioned on a case-by-case basis. If you're interested in working with it, get in touch via [e-mail] with an overview of your use case.

Validators APR

Get Apr

GET/v0/eth/validators/{validator_index_or_pubkey}/apr

Path parameters

validator_index_or_pubkey*Validator Index Or Pubkey

integerstring

Query parameters

Header parameters

Response

200307400

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/validators/{validator_index_or_pubkey}/apr?window=1d', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "validatorIndex": 1000,
  "idType": "validator",
  "timeWindow": "all",
  "aprType": "backward",
  "percentage": 5.35,
  "percentageConsensus": 4.04,
  "percentageExecution": 1.31,
  "activeStake": 4823520000000000,
  "activeValidators": 150735
}

This endpoint returns historical data on the returns of a validator index. 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).

window refers to the time window of the aggregation, with 1d, 7d, 30d and all being the supported values.

Note: a validator must be active throughout the time window for the value to be produced. For all time the last 90 days are considered.