Migrating from v1 to v2

Enhanced features and improvements in Polygon Staking Reporting API v2.

What's New in Version 2

See the comparison between v1 and v2 in the table below.

Key Points	v1	v2
Network	Mainnet Mumbai Testnet (deprecated)	Mainnet
Most Recent Reward Endpoints	Supported	Not Supported
Historical Reward Endpoints	Supported	Supported
Status Endpoints	Supported	Supported
Timezone-based Reporting	Not Officially Supported	Supported The grouping periods are calculated based on the start timestamp and the chosen period type.
Checkpoint Level Data	Supported	Supported
Response Formats	All endpoints are `application/json`.	Most endpoints are `application/ndjson`.
Rewards for Inactive Validators	Returns rewards with “0” return.	Does not return reward objects.
Checkpoint Period Allocation	Uses the start time.	Uses the end time.
Gzip Support	Not Supported.	Supported in responses but not requests.

Let's delve into the details for each key point:

1. Most Recent Reward

➡️ v1

You can use the following request to get the most recent rewards in v1.

curl --request GET \
     --url https://svc.blockdaemon.com/reporting/staking/v1/polygon/mainnet/delegator/rewards/0x2Be2Fa0C5A0BA2c046eDE2255E4bD08854347dE1 \
     --header 'X-API-Key: YOUR_KEY \
     --header 'accept: application/json'

{
  "rewards": [
    {
      "address": "0x2Be2Fa0C5A0BA2c046eDE2255E4bD08854347dE1",
      "currency": "MATIC",
      "metadata": {
        "epoch": 60712
      },
      "return": 0.222737193,
      "startingBalance": 122783.666751616,
      "timeAggregation": "epoch",
      "timeEnd": "2024-04-15T12:16:11Z",
      "timeStart": "2024-04-15T12:16:11Z",
      "validator": "0x8f846C443CFa44A6e95aaCD2aC362b6cF4fd4335"
    }
  ]
}

➡️ v2

Most recent rewards are not supported. But you can achieve similar functionality by making a rewards request that contains the latest reward (end times can be in the future) and then selecting the one with the highest start time.

2. Historical Reward

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

The examples below are for delegator requests. For validator requests, replace "delegator" with "validator" in the URI.

➡️ v1

Single Delegator: Send the request below to retrieve historical rewards for a single delegator.

curl --request POST \
     --url https://svc.blockdaemon.com/reporting/staking/v1/polygon/mainnet/delegator/history/0xee4587b218c3dd7a90174fd70f7f8e855d4c0f67 \
     --header 'X-API-Key: YOUR_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "fromTime": 1681736207,
  "toTime": 1682294200,
  "timeUnit": "weekly"
}

{
  "rewards": [
    {
      "address": "0xEe4587b218C3dd7A90174fd70f7F8e855d4C0f67",
      "currency": "MATIC",
      "metadata": {
        "epoch": 0
      },
      "return": 10996.36234845,
      "startingBalance": 2632100173.999994,
      "timeAggregation": "weekly",
      "timeEnd": "2023-04-23T23:59:59Z",
      "timeStart": "2023-04-17T00:00:00Z",
      "validator": "0x875e901465A639f2E71fcfC10F426eD32F5A909a"
    }
  ]
}

Multiple Delegators: Send the request below to retrieve historical rewards for multiple delegators in one request.

curl --request POST \
     --url https://svc.blockdaemon.com/reporting/staking/v1/polygon/mainnet/delegator/history \
     --header 'X-API-Key: YOUR_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "fromTime": 1704067200,
  "toTime": 1711843200,
  "timeUnit": "monthly",
  "addresses": [
    "0xee4587b218c3dd7a90174fd70f7f8e855d4c0f67"
  ]
}'

{
  "rewards": [
    {
      "address": "0xEe4587b218C3dd7A90174fd70f7F8e855d4C0f67",
      "currency": "MATIC",
      "metadata": {
        "epoch": 0
      },
      "return": 53116.063920059,
      "startingBalance": 19241074533.999897,
      "timeAggregation": "monthly",
      "timeEnd": "2024-01-31T23:59:59Z",
      "timeStart": "2024-01-01T00:00:00Z",
      "validator": "0x875e901465A639f2E71fcfC10F426eD32F5A909a"
    },
    {
      "address": "0xEe4587b218C3dd7A90174fd70f7F8e855d4C0f67",
      "currency": "MATIC",
      "metadata": {
        "epoch": 0
      },
      "return": 49903.318235084,
      "startingBalance": 20043372447.999893,
      "timeAggregation": "monthly",
      "timeEnd": "2024-03-31T23:59:59Z",
      "timeStart": "2024-03-01T00:00:00Z",
      "validator": "0x875e901465A639f2E71fcfC10F426eD32F5A909a"
    }
  ]
}

➡️ v2

Single Delegator: Send the request below to retrieve historical rewards for a single delegator.

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'

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

Multiple Delegators: In v2, you can include a maximum of 1000 addresses per request. If you have more, you will have to make multiple requests.

curl --location 'https://svc.blockdaemon.com/reporting/staking/v2/polygon/mainnet/delegator/rewards' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_KEY' \
--data '{
    "startTime": 1704067200,
    "endTime": 1711843200,
    "addresses": [
        "0xee4587b218c3dd7a90174fd70f7f8e855d4c0f67"
    ],
    "period": "monthly"
}'

{
    "address": "0xEe4587b218C3dd7A90174fd70f7F8e855d4C0f67",
    "denomination": "Wei",
    "return": "49027463563609864931023",
    "startTime": 1706745600,
    "endTime": 1709251199,
    "period": "MONTHLY",
    "startBalance": "14075402000000000000000000",
    "metadata": {
        "blockNumber": "0x123e619-0x1270d4c",
        "epoch": "57191-58627",
        "restakeTotal": "0",
        "validatorContract": "0x875e901465A639f2E71fcfC10F426eD32F5A909a",
        "validatorId": "143",
        "withdrawal": "52745163180048825083811"
    }
}
{
    "address": "0xEe4587b218C3dd7A90174fd70f7F8e855d4C0f67",
    "denomination": "Wei",
    "return": "49903318235083669648660",
    "startTime": 1709251200,
    "endTime": 1711929599,
    "period": "MONTHLY",
    "startBalance": "14075402000000000000000000",
    "metadata": {
        "blockNumber": "0x1270da4-0x12a4fac",
        "epoch": "58628-60051",
        "restakeTotal": "0",
        "validatorContract": "0x875e901465A639f2E71fcfC10F426eD32F5A909a",
        "validatorId": "143",
        "withdrawal": "47675349243927293547182"
    }
}

🚧
Note:
In v2, the response comes in ndjson format, so there's no wrapper JSON object. However, the above response has been formatted for better readability.

3. Status Endpoints

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

The examples below are for delegator requests. For validator requests, replace "delegator" with "validator" in the URI.

➡️ v1

Single Delegator: To retrieve the status of a single delegator, send the request below.

curl --request GET \
     --url https://svc.blockdaemon.com/reporting/staking/v1/polygon/mainnet/delegator/status/0x227A4b69400cf702a14705216ef9E122E5A96B39 \
     --header 'X-API-Key: YOUR_KEY' \
     --header 'accept: application/json'

{
  "activationDate": "2023-09-21",
  "address": "0x227A4b69400cf702a14705216ef9E122E5A96B39",
  "status": "active"
}

Multiple Delegators: To retrieve the status of multiple delegators, send the request below.

curl --request POST \
     --url https://svc.blockdaemon.com/reporting/staking/v1/polygon/mainnet/delegator/status \
     --header 'X-API-Key: YOUR_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "addresses": [
    "0x227A4b69400cf702a14705216ef9E122E5A96B39",
    "0xC856f78b5ceB43dd64702BEf4553D28f14f17B6E"
  ]
}

{
  "addresses": [
    {
      "activationDate": "2023-09-21",
      "address": "0x227A4b69400cf702a14705216ef9E122E5A96B39",
      "status": "active"
    },
    {
      "activationDate": "2022-10-10",
      "address": "0xC856f78b5ceB43dd64702BEf4553D28f14f17B6E",
      "status": "active"
    }
  ]
}

➡️ v2

Single Delegator: For a delegator, you have to include the validatorId that you want the status for. For a validator, you can use the validator's contract address or owner's address.

curl --location --request GET 'https://svc.blockdaemon.com/reporting/staking/v2/polygon/mainnet/delegator/status/0x227A4b69400cf702a14705216ef9E122E5A96B39?validatorId=143' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_KEY' \

The timestamp is the time that the delegator most recently delegated, not the first time.

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

Multiple Delegators: In v2, you can look up multiple statuses for a single validator 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"
]'

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

🚧
Note:
In v2, the response comes in ndjson format, so there's no wrapper JSON object. However, the above response has been formatted for better readability.

4. Timezone-based Reporting

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

The examples below are for validator requests. For delegator requests, replace "validator" with "delegator" in the URI.

➡️ v1

In v1, rewards are divided into UTC days, weeks, or months (time units). Send the request below if you want to see rewards for a different time zone.

curl 'https://svc.blockdaemon.com/reporting/staking/v1/polygon/mainnet/validator/history' \
-H 'X-API-Key: YOUR_KEY' \
-H 'Content-Type: application/json' \
-d '{
    "fromTime": 1711972800, // 24/4/1 12:00:00 UTC 
    "toTime": 1712059200, // 24/4/2 12:00:00 UTC
    "timeUnit": "daily",
    "addresses": [
        "0xAB30eF276ADC2bE22CE58d75B4F4009173A73676"
    ]
}'

{  
  "rewards": [  
    {  
      "address": "0xAB30eF276ADC2bE22CE58d75B4F4009173A73676",  
      "currency": "MATIC",  
      "metadata": {  
        "epoch": 0  
      },  
      "return": 329.281010212,  
      "startingBalance": 20,  
      "timeAggregation": "daily",  
      "timeEnd": "2024-04-01T23:59:59Z",  
      "timeStart": "2024-04-01T00:00:00Z",  
      "validator": "0x875e901465A639f2E71fcfC10F426eD32F5A909a"  
    }
  ]  
}

➡️ v2

In v2, time units adjust automatically based on your start time and chosen unit. Here's how to handle different time zones:

Time Zone Conversion: To get rewards in a time zone different from UTC, convert your timestamp to UTC seconds. For example, if you want data from 00:00 to 00:00 in CET, use timestamps for 22:00 to 22:00 in UTC seconds.
Partitioning: Rewards come in whole units. For example, if your chosen period ends midday (start = 12:00, end = 10:00 the next day), the start/end timestamp in the reward will reflect a full day. However, the data will only include rewards up to the chosen end timestamp.

👍
Note:
You can use the Epoch Converter tool for the conversion.

curl --location 'https://svc.blockdaemon.com/reporting/staking/v2/polygon/mainnet/validator/rewards' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
    "startTime": 1711972800,
    "endTime": 1712059200,
    "addresses": [
        "0xAB30eF276ADC2bE22CE58d75B4F4009173A73676"
    ],
    "period": "daily"
}'

Rewards are in wei. If you need them in MATIC, you'll have to convert them.

{  
    "address": "0xAB30eF276ADC2bE22CE58d75B4F4009173A73676",  
    "denomination": "Wei",  
    "return": "635200532164260773738",  
    "startTime": 1711972800,  
    "endTime": 1712059199,  
    "period": "DAILY",  
    "startBalance": "1000000000000000000",  
    "metadata": {  
        "blockNumber": "0x12a79a2-0x12a9520",  
        "epoch": "60124-60166",  
        "restakeTotal": "0",  
        "validatorContract": "0x875e901465A639f2E71fcfC10F426eD32F5A909a",  
        "validatorId": "143",  
        "withdrawal": "0"  
    }  
}

5. Checkpoint Level Data

Both v1 and v2 support fetching checkpoint level data.

v1: Set the time unit field to epoch.
v2: Set the period field to raw.

6. Response Formats

v1: All endpoints return application/json response.
v2: Most endpoints return application/nd+json, while the "GET single status" endpoint returnsapplication/json.

7. Rewards for Inactive Validators

v1: If a validator is deactivated (by extension, any delegations to it), then one or more reward objects with a 0 return will be included for delegator requests. For validator requests, a 404 response is returned.
v2: No rewards are returned. A 200 status code is returned with an empty body.

8. Checkpoint Period Allocation

v1: Checkpoints are allocated to partitions based on the start time.
v2: Checkpoints are allocated based on the end time. There can be some small discrepancies if a checkpoint crosses the end timestamp boundaries.

9. Gzip Support

v1: Gzip is not supported.
v2: Gzip is supported on responses via the Accept-Encoding header.

Migrating from v1 to v2

What's New in Version 2

1. Most Recent Reward

➡️ v1

➡️ v2

2. Historical Reward

👍
Note:

➡️ v1

➡️ v2

🚧
Note:

3. Status Endpoints

👍
Note:

➡️ v1

➡️ v2

🚧
Note:

4. Timezone-based Reporting

👍
Note:

➡️ v1

➡️ v2

👍
Note:

5. Checkpoint Level Data

6. Response Formats

7. Rewards for Inactive Validators

8. Checkpoint Period Allocation

9. Gzip Support

👋 Need Help?

What's New in Version 2

1. Most Recent Reward

➡️ v1

➡️ v2

2. Historical Reward

👍Note:

➡️ v1

➡️ v2

🚧Note:

3. Status Endpoints

👍Note:

➡️ v1

➡️ v2

🚧Note:

4. Timezone-based Reporting

👍Note:

➡️ v1

➡️ v2

👍Note:

5. Checkpoint Level Data

6. Response Formats

7. Rewards for Inactive Validators

8. Checkpoint Period Allocation

9. Gzip Support

👋 Need Help?

👍
Note:

🚧
Note:

👍
Note:

🚧
Note:

👍
Note:

👍
Note: