Polygon Reporting API Overview

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:

1. 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.
2. 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

Sample Request

👍

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

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

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"
  }
}

👋 Need Help?

Contact us through email or our support page for any issues, bugs, or assistance you may need.