Validators

Querying into individual validator IDs

The following endpoints return all kinds of useful information (e.g. rewards, performance, metadata) about a validator or a specific set of validators in the requested time-frame.

Single validator effectiveness

Validator Checkpoint Effectiveness

GET/v0/polygon/validators/{validator_id}/effectiveness

Path parameters

validator_id*Validator Id

Query parameters

Response

200400

Successful Response

Body

application/json

page*Page

total*Total

data*Data

nextNext

Request

JavaScriptCurlPython

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

Response

200400

{
  "page": {
    "from": 0,
    "to": 0,
    "granularity": "checkpoint",
    "size": 0
  },
  "total": 0,
  "data": [],
  "next": "text"
}

This endpoint returns all the useful information you will ever need on the historical performance of a single validator. This includes rewards (checkpoint signings, proposals, Bor proposals), performance (effectiveness and its components), stake distribution, and so much more. For a glossary of the variables returned, see effectiveness.

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

Parameter	Context
from	Starting checkpoint (integer, e.g. 52922) or UTC date (e.g. from=“2023-10-31”)
granularity	The size of time increments you are looking to query. Can be checkpoint or day
size	The number of results included per page

Validator metadata

Validator Metadata

GET/v0/polygon/validators/{validator_id}

Path parameters

validator_id*Validator Id

Response

200400

Successful Response

Body

application/json

validatorId*Validatorid

name*Name

status*Status

currentState*Currentstate

owner*Owner

signer*Signer

urlUrl

descriptionDescription

commission*Commission

Request

JavaScriptCurlPython

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

Response

200400

{
  "validatorId": 103,
  "name": "Stake Capital",
  "status": "active",
  "currentState": "healthy",
  "owner": "0x00000",
  "signer": "0x00000",
  "url": "https://stake.capital",
  "description": "<p>Stake Capital is a validator for Polygon.</p>",
  "commission": 0.1,
  "__$markdownParsed": true
}

This endpoint returns pertinent information about a validator including the name of the entity running the validator, its commission rate, and current state.

Single validator summary

Validator Summary

GET/v0/polygon/validators/{validator_id}/summary

Path parameters

validator_id*Validator Id

Query parameters

Response

200400

Successful Response

Body

application/json

validatorId*Validatorid

timeWindow*TimeWindow

An enumeration.

1d7d30dall

name*Name

currentState*Currentstate

networkPenetration*Networkpenetration

validatorApr*Validatorapr

netValidatorApr*Netvalidatorapr

commissionRate*Commissionrate

delegatorApr*Delegatorapr

effectiveness*Effectiveness

Request

JavaScriptCurlPython

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

Response

200400

{
  "validatorId": 103,
  "timeWindow": "30d",
  "name": "Stake Capital",
  "currentState": "healthy",
  "networkPenetration": 0.24,
  "validatorApr": 0.05,
  "commissionRate": 0.05,
  "netValidatorApr": 0.049,
  "delegatorApr": 0.05,
  "effectiveness": 0.984
}

This endpoint returns high level information about a validator over the time period such as its entity name, network penetration, annual percentage rate (APR), and effectiveness.

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

Parameter	Context
window	Window of the aggregation, with 1d, 7d, 30d and all being the supported values

Multiple validator summary

Validator Summaries

GET/v0/polygon/validators

Query parameters

Response

200400

Successful Response

Body

application/json

page*Page

total*Total

data*Data

nextNext

Request

JavaScriptCurlPython

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

Response

200400

{
  "page": {
    "from": 0,
    "to": 0,
    "granularity": "checkpoint",
    "size": 0
  },
  "total": 0,
  "data": [],
  "next": "text"
}

Similar to the Single validator summary but returns the summary stats for all validators. What is great about this endpoint is that you can filter it for validators under a specific delegator, essentially giving you a per validator view of a delegator's delegations.

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

Parameter	Context
window	Window of the aggregation, with 1d, 7d, 30d and all being the supported values
from	From a specific validator's ranking based on their order in terms of network_penetration
size	The number of results included per page
delegator_address	The Ethereum address of the delegator to filter the results by