Delegators

Querying into individual delegators

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

Single delegator summary

Delegator Summary

GET/v0/polygon/delegators/{delegator_address}/summary

Path parameters

delegator_address*Delegator Address

Query parameters

Response

200400

Successful Response

Body

application/json

delegatorAddress*Delegatoraddress

timeWindow*TimeWindow

An enumeration.

1d7d30dall

networkPenetration*Networkpenetration

delegations*Delegations

aprGrossAprgross

aprNetAprnet

aggregateEffectiveness*Aggregateeffectiveness

blendedCommissionRate*Blendedcommissionrate

totalDelegatorStake*Totaldelegatorstake

totalGrossRewards*Totalgrossrewards

totalNetRewards*Totalnetrewards

totalCommissionPaid*Totalcommissionpaid

Request

JavaScriptCurlPython

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

Response

200400

{
  "delegatorAddress": "0x00000",
  "timeWindow": "30d",
  "networkPenetration": 0.1,
  "delegations": [
    {
      "validatorId": 103,
      "validatorName": "Stake Capital",
      "stakePercentage": 0.1
    },
    {
      "validatorId": 104,
      "validatorName": "Coinbase Cloud",
      "stakePercentage": 0.1
    }
  ],
  "aprGross": 0.05,
  "aprNet": 0.05,
  "aggregateEffectiveness": 0.98865,
  "blendedCommissionRate": 0.05125,
  "totalDelegatorStake": 400995914.00753,
  "totalGrossRewards": 1859026.3456,
  "totalNetRewards": 1746304.13028,
  "totalCommissionPaid": 112722.21532
}

This endpoint returns high level information about a delegator over the time period such as their network penetration, rewards, annual percentage rate (APR), paid commissions, and the aggregate effectiveness of their validator delegates.

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 delegator summary

Delegator Summaries

GET/v0/polygon/delegators

Query parameters

Response

200400

Successful Response

Body

application/json

page*Page

total*Total

data*Data

nextNext

Request

JavaScriptCurlPython

const response = await fetch('/v0/polygon/delegators?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 delegators.

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 rewards

Delegator Rewards

GET/v0/polygon/delegators/{delegator_address}/rewards

Path parameters

delegator_address*Delegator Address

Query parameters

Response

200400

Successful Response

Body

application/json

page*Page

total*Total

data*Data

nextNext

Request

JavaScriptCurlPython

const response = await fetch('/v0/polygon/delegators/{delegator_address}/rewards', {
    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 information about the rewards received by a delegator and the rewards it has missed out on over a number of checkpoints. The rewards can be broken down at a per checkpoint level or daily level as well.

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

Parameter	Context
from	Starting (highest) checkpoint (integer, e.g. 54000) or UTC date (e.g. from=“2023-11-22”)
to	Ending (lowest) 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