Overview

The Polygon Staking Reporting API provides access to detailed Polygon staking information. It includes features such as timezone-based reporting, near-real-time data availability with updates per epoch instead of end-of-day rollups, and enhanced tracking of validator and delegator statuses for more accurate insights.

🌐 Supported network: Mainnet

➡️ Get Rewards

The API provides access to a rewards calculation system that operates within an eventually consistent architecture. This means that while the data may not immediately reflect the most recent updates, it will converge to a consistent state over time.

❗️
Please Be Aware
The transient inconsistencies may occur during short time windows due to the nature of the underlying system.

Rewards Calculation

Rewards are based on changes in liquid rewards between epochs (time periods). Here’s how it works:

Difference in Liquid Rewards: At the end of each epoch, the API calculates how much liquid rewards have increased or decreased compared to the previous epoch.
Adjustments for Claims or Restakes: If rewards were claimed or restated during the epoch, these actions are included in the calculation to provide accurate net rewards.

Endpoints

Endpoint
Get a Stream of Rewards - `POST /rewards`
Get a Stream of Rewards for a Single Address - `GET /rewards/{address}`

Sample Request

👍
Note
Validators and delegators follow the same request/response format in both API versions.

Below is a sample request for a single delegator. For multiple delegators, you can include up to 1000 addresses per request.

curl --location --request GET 'https://svc.blockdaemon.com/reporting/staking/v2/polygon/mainnet/delegator/rewards/0xee4587b218c3dd7a90174fd70f7f8e855d4c0f67?startTime=1681736207&endTime=1682294200&period=weekly' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_KEY'

This would return a response below. If you need the reward data in a different timezone, you can convert the timestamps using Epoch Converter.

{
    "address": "0xEe4587b218C3dd7A90174fd70f7F8e855d4C0f67",
    "denomination": "Wei",
    "return": "10996362348449925578900",
    "startTime": 1681736207,
    "endTime": 1682341006,
    "period": "WEEKLY",
    "startBalance": "14075402000000000000000000",
    "metadata": {
        "blockNumber": "0x1046aee-0x1051cfa",
        "epoch": "44957-45143",
        "restakeTotal": "0",
        "validatorContract": "0x875e901465A639f2E71fcfC10F426eD32F5A909a",
        "validatorId": "143",
        "withdrawal": "0"
    }
}

📘
Info
To get the most recent rewards, you need to make a request for either epoch or raw rewards by specifying an end time in the future and a start time.
In the response, the highest startTime value shows the most recent reward.

➡️ Get Status

This endpoint returns the current status of a validator/delegator.

Endpoints

Endpoint
Get a Stream of Statuses - `POST /status`
Get Status for an Address - `POST /status/address`

Sample Request

👍
Note
Validators and delegators follow the same request/response format in both API versions.

Below is an example of getting multiple statuses for a single delegator at a time.

curl --location 'https://svc.blockdaemon.com/reporting/staking/v2/polygon/mainnet/delegator/status?validatorId=143' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_KEY' \
--data '[
    "0x227A4b69400cf702a14705216ef9E122E5A96B39",
    "0xC233bA15941e3179C536c56d2c85d2498838dAF7",
    "0xC856f78b5ceB43dd64702BEf4553D28f14f17B6E"
]'

This would return a response below.

{
    "address": "0x227A4b69400cf702a14705216ef9E122E5A96B39",
    "status": "ACTIVE",
    "timestamp": 1710867791,
    "metadata": {
        "type": "delegator",
        "validatorContract": "0x875e901465A639f2E71fcfC10F426eD32F5A909a",
        "validatorId": "143"
    }
}
{
    "address": "0xC856f78b5ceB43dd64702BEf4553D28f14f17B6E",
    "status": "ACTIVE",
    "timestamp": 1713187811,
    "metadata": {
        "type": "delegator",
        "validatorContract": "0x875e901465A639f2E71fcfC10F426eD32F5A909a",
        "validatorId": "143"
    }
}

➡️ Get Health

A health endpoint provides a high-level overview of the reward processing status. It also includes a breakdown of the status of individual reward types in the metadata object.

Endpoints

Endpoint
Get the Protocol Rewards Processing Health - `GET /health`

Sample Request

Below is an example request.

curl --request GET \
     --url https://svc.blockdaemon.com/reporting/staking/v2/polygon/mainnet/health \
     --header 'X-API-Key: YOUR_KEY' \
     --header 'accept: application/json'

The response shows whether the reward processing is running optimally or not.

{
  "status": "OPTIMAL",
  "timestamp": 1717992000,
  "metadata": {
    "chainCheckpoint": "63629",
    "lastProcessedCheckpoint": "63628"
  }
}