Migrating NEAR from v1 to v2

How to upgrade from NEAR API v1 to v2 and access new features and better performance

What's New in Version 2

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

Key Points	v1	v2
Network	Mainnet	Mainnet
Tracking deposits and withdrawals	Partial Unsupported transaction types: `deposit_and_stake` & `withdraw_all`	Partial Unsupported transaction types: `deposit_and_stake` & `withdraw_all`
Most recent reward endpoints	Supported	Unsupported
Historical reward endpoints	Supported	Supported
Status endpoints	Supported	Supported
Timezone based reporting	Not Supported	Supported The grouping periods are calculated based on the start timestamp and the chosen period type
Data granularity	Epoch	Epoch
Response formats	All endpoints are `application/json`	Most endpoints are `application/nd+json`
Reward period allocation	Uses the start time	Uses the end time
Health endpoint	Unsupported	Supported
Gzip support	Unsupported	Supported in Responses but not requests

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

1. Tracking Deposits and Withdrawals

In NEAR, five smart contract methods manage deposits, staking, and withdrawals. Blockdaemon’s support for each of these methods is outlined below.


`deposit`	Supported
`stake`	Supported
`deposit_and_stake`	Not supported
`withdraw`	Supported
`withdraw_all`	Not supported

❗️
Note
If unsupported methods are used within an epoch, those events will not be tracked by our API.

Potential Impact

v1: This limitation can lead to inaccurate rewards for the epoch, resulting in either very high or very low rewards.
v2: If you use an untracked method during an epoch, we will not track any rewards for that period. As a result, it may seem like rewards are missing. However, the deposit and withdraw functions track rewards accurately, and if no functions are used, rewards remain accurate.

2. Most Recent Rewards

➡️ v1

To retrieve the most recent reward earned by a delegator, you can use the following request:

curl --request GET \
     --url https://svc.blockdaemon.com/reporting/staking/v1/near/mainnet/delegator/rewards/41b965acd61cbb4458eedb758afdfe17f2a26eca22afe3b235935ebba88e4590 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer KEY'

You will get a response below.

{
  "rewards": [
    {
      "address": "41b965acd61cbb4458eedb758afdfe17f2a26eca22afe3b235935ebba88e4590",
      "currency": "NEAR",
      "metadata": {
        "depositAmount": 0,
        "stakedEndBalance": 525.36995126,
        "stakedStartingBalance": 525.299841814,
        "startingBlock": "130391511",
        "unstakedEndBalance": 0,
        "unstakedStartingBalance": 0,
        "withdrawalAmount": 0
      },
      "return": 0.070109447,
      "startingBalance": 525.299841814,
      "timeAggregation": "daily",
      "timeEnd": "2024-10-15T23:17:12Z",
      "timeStart": "2024-10-15T23:17:12Z",
      "validator": "astro-stakers.poolv1.near"
    }
  ]
}

➡️ v2

To achieve similar functionality in v2, you would need to make a rewards request with a wide enough window to include the latest reward (end times can be in the future) and then pick the one with the highest start time.

3. Historical Reward

👍
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

Single Validator: Send the request below to get historical rewards for a single validator.

curl --request POST \
     --url https://svc.blockdaemon.com/reporting/staking/v1/near/mainnet/validator/history/blockdaemon.poolv1.near \
     --header 'accept: application/json' \
     --header 'authorization: Bearer KEY \
     --header 'content-type: application/json' \
     --data '
{
  "fromTime": 1727740800,
  "toTime": 1728345600,
  "timeUnit": "weekly"
}

This would return a response below.

{
  "rewards": [
    {
      "address": "blockdaemon.poolv1.near",
      "currency": "NEAR",
      "return": 0,
      "startingBalance": 0,
      "timeAggregation": "weekly",
      "timeEnd": "2024-10-13T23:59:59Z",
      "timeStart": "2024-10-07T00:00:00Z",
      "validator": "blockdaemon.poolv1.near"
    },
    {
      "address": "blockdaemon.poolv1.near",
      "currency": "NEAR",
      "return": 0,
      "startingBalance": 0,
      "timeAggregation": "weekly",
      "timeEnd": "2024-10-06T23:59:59Z",
      "timeStart": "2024-09-30T00:00:00Z",
      "validator": "blockdaemon.poolv1.near"
    }
  ]
}

Multiple Validators: Send the request below to retrieve historical rewards for multiple validators in one request.

curl --request POST \
     --url https://svc.blockdaemon.com/reporting/staking/v1/near/mainnet/validator/history \
     --header 'accept: application/json' \
     --header 'authorization: Bearer KEY \
     --header 'content-type: application/json' \
     --data '
{
  "fromTime": 1727740800,
  "toTime": 1728345600,
  "timeUnit": "weekly",
  "addresses": [
    "blockdaemon.poolv1.near"
  ]
}

This would return a response below.

{
  "rewards": [
    {
      "address": "blockdaemon.poolv1.near",
      "currency": "NEAR",
      "return": 0,
      "startingBalance": 0,
      "timeAggregation": "weekly",
      "timeEnd": "2024-10-06T23:59:59Z",
      "timeStart": "2024-09-30T00:00:00Z",
      "validator": "blockdaemon.poolv1.near"
    },
    {
      "address": "blockdaemon.poolv1.near",
      "currency": "NEAR",
      "return": 0,
      "startingBalance": 0,
      "timeAggregation": "weekly",
      "timeEnd": "2024-10-13T23:59:59Z",
      "timeStart": "2024-10-07T00:00:00Z",
      "validator": "blockdaemon.poolv1.near"
    }
  ]
}

➡️ v2

Single Validator: Send the request below to retrieve historical rewards for a single validator.

curl --location 'https://svc.blockdaemon.com/reporting/staking/v2/near/mainnet/validator/rewards' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer KEY \
--data '{
    "startTime": 1727740800,
    "endTime": 1728345600,
    "addresses": [
        "blockdaemon.poolv1.near"
    ],
    "period": "weekly"
}'

This would return a response below.

{
    "address": "blockdaemon.poolv1.near",
    "denomination": "yocto",
    "return": "1655699299859045601926409113",
    "startTime": 1727740800,
    "endTime": 1728345599,
    "period": "WEEKLY",
    "startBalance": "10355397604811593953839513368507",
    "metadata": {
        "startBlockNumber": "129268311-129743511",
        "epoch": "2765-2776",
        "type": "validator",
        "delegatorCount": "569"
    }
}

Multiple Validators: 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/near/mainnet/validator/rewards' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer KEY \
--data '{
    "startTime": 1727740800,
    "endTime": 1728345600,
    "addresses": [
        "blockdaemon.poolv1.near"
    ],
    "period": "weekly"
}'

This would return a response below.

{
    "address": "blockdaemon.poolv1.near",
    "denomination": "yocto",
    "return": "1655699299859045601926409113",
    "startTime": 1727740800,
    "endTime": 1728345599,
    "period": "WEEKLY",
    "startBalance": "10355397604811593953839513368507",
    "metadata": {
        "startBlockNumber": "129268311-129743511",
        "epoch": "2765-2776",
        "type": "validator",
        "delegatorCount": "569"
    }
}

🚧
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. Status Endpoints

👍
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

Single Validator: To retrieve the status of a single validator, send the request below.

curl --request GET \
     --url https://svc.blockdaemon.com/reporting/staking/v1/near/mainnet/validator/status/blockdaemon.poolv1.near \
     --header 'accept: application/json' \
     --header 'authorization: Bearer KEY

{
  "activationDate": "2024-01-26",
  "address": "blockdaemon.poolv1.near",
  "status": "active"
}

Multiple Validators: To retrieve the status of multiple validators, send the request below.

curl --request POST \
     --url https://svc.blockdaemon.com/reporting/staking/v1/near/mainnet/validator/status \
     --header 'accept: application/json' \
     --header 'authorization: Bearer KEY \
     --header 'content-type: application/json' \
     --data '
{
  "addresses": [
    "blockdaemon.poolv1.near"
     ]
}

{
  "addresses": [
    {
      "activationDate": "2024-01-26",
      "address": "blockdaemon.poolv1.near",
      "status": "active"
    }
  ]
}

➡️ v2

❗️
Note:
In v2, status timestamps are the epoch seconds at when the status was last updated.

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

curl -X 'GET' \
  'https://svc.blockdaemon.com/reporting/staking/v2/near/mainnet/validator/status/blockdaemon.poolv1.near' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_TOKEN'

{
  "address": "blockdaemon.poolv1.near",
  "status": "ACTIVE",
  "timestamp": 1729144803,
  "metadata": {
    "isSlashed": "false",
    "stake": "10815192854705206479902003688909"
  }
}

Multiple Validators: In v2, you can look up multiple statuses for a single validator.

curl -X 'POST' \
  'https://svc.blockdaemon.com/reporting/staking/v2/near/mainnet/validator/status' \
  -H 'accept: application/x-ndjson' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer KEY \
  -d '[
  "blockdaemon.poolv1.near"
]'

{
  "address": "blockdaemon.poolv1.near",
  "status": "ACTIVE",
  "timestamp": 1729144803,
  "metadata": {
    "isSlashed": "false",
    "stake": "10815192854705206479902003688909"
  }
}

🚧
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.

5. Timezone-based Reporting

➡️ v1

In v1, rewards are divided into UTC days, weeks, and months. To view rewards for a different time zone, send a request below.

curl --request POST \
     --url https://svc.blockdaemon.com/reporting/staking/v1/near/mainnet/validator/history/blockdaemon.poolv1.near \
     --header 'accept: application/json' \
     --header 'authorization: Bearer KEY \
     --header 'content-type: application/json' \
     --data '
{
  "fromTime": 1727740800,
  "toTime": 1728345600,
  "timeUnit": "weekly"
}

You will get a response below.

{
  "rewards": [
    {
      "address": "blockdaemon.poolv1.near",
      "currency": "NEAR",
      "return": 0,
      "startingBalance": 0,
      "timeAggregation": "weekly",
      "timeEnd": "2024-10-13T23:59:59Z",
      "timeStart": "2024-10-07T00:00:00Z",
      "validator": "blockdaemon.poolv1.near"
    },
    {
      "address": "blockdaemon.poolv1.near",
      "currency": "NEAR",
      "return": 0,
      "startingBalance": 0,
      "timeAggregation": "weekly",
      "timeEnd": "2024-10-06T23:59:59Z",
      "timeStart": "2024-09-30T00:00:00Z",
      "validator": "blockdaemon.poolv1.near"
    }
  ]
}

➡️ v2

In v2, time units adjust automatically based on your start time and chosen unit.

Handling Different Timezones

When working with reward data in UTC, you need to convert your local timestamps to UTC seconds before making a request.

Identify your local timezone (e.g., CET).
Determine your local start and end times. For example, you need data from 00:00 to 00:00 in CET.
Convert your local times to UTC. For CET (UTC+1), subtract 1 hour to get the UTC times.
Change the UTC times to Unix timestamps (seconds since epoch). The API requires this format.
If your end timestamp is within a day, remember that the returned data will include the full day but only up to the specified end timestamp.

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

Example Request

curl --location 'https://svc.blockdaemon.com/reporting/staking/v2/near/mainnet/validator/rewards' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer KEY \
--data '{
    "startTime": 1727740800,
    "endTime": 1728345600,
    "addresses": [
        "blockdaemon.poolv1.near"
    ],
    "period": "weekly"
}'

Rewards are in yoctoNEAR. You’ll need to convert them to get NEAR.

{
    "address": "blockdaemon.poolv1.near",
    "denomination": "yocto",
    "return": "1655699299859045601926409113",
    "startTime": 1727740800,
    "endTime": 1728345599,
    "period": "WEEKLY",
    "startBalance": "10355397604811593953839513368507",
    "metadata": {
        "startBlockNumber": "129268311-129743511",
        "epoch": "2765-2776",
        "type": "validator",
        "delegatorCount": "569"
    }
}

6. Data Granularity

v1: Rewards are available for daily, weekly, or monthly roll-ups in aggregated formats.
v2: Rewards are available at the epoch level and daily, weekly, monthly, and yearly roll-ups.

7. Response Formats

v1: All endpoints return application/json response.
v2: Most endpoints return application/x-ndjson, while the Get Status for an Address endpoint returnsapplication/json.

8. Reward Period Allocation

v1: Rewards are allocated to partitions based on the start time.
v2: Rewards are allocated based on the end time (when the rewards are available). Comparing the two versions may show small discrepancies if a reward crosses the end timestamp boundaries.

9. Health Endpoint

In v2, a health endpoint provides a high-level overview of the reward processing status. The metadata object also includes a breakdown of the status of individual reward types.

Below is an example request.

curl --location --request GET 'https://svc.blockdaemon.com/reporting/staking/v2/near/mainnet/health' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer KEY'

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

{
    "status": "OPTIMAL",
    "timestamp": 1729152000,
    "metadata": {
        "lastProcessedEpoch": "2791",
        "chainEpoch": "2792",
        "reason": "OPTIMAL"
    }
}

10. GZIP Support

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

Migrating NEAR from v1 to v2

What's New in Version 2

1. Tracking Deposits and Withdrawals

❗️
Note

Potential Impact

2. Most Recent Rewards

➡️ v1

➡️ v2

3. Historical Reward

👍
Note:

➡️ v1

➡️ v2

🚧
Note:

4. Status Endpoints

👍
Note:

➡️ v1

➡️ v2

❗️
Note:

🚧
Note:

5. Timezone-based Reporting

➡️ v1

➡️ v2

Handling Different Timezones

👍
Note:

Example Request

6. Data Granularity

7. Response Formats

8. Reward Period Allocation

9. Health Endpoint

10. GZIP Support

👋 Need Help?

What's New in Version 2

1. Tracking Deposits and Withdrawals

❗️Note

Potential Impact

2. Most Recent Rewards

➡️ v1

➡️ v2

3. Historical Reward

👍Note:

➡️ v1

➡️ v2

🚧Note:

4. Status Endpoints

👍Note:

➡️ v1

➡️ v2

❗️Note:

🚧Note:

5. Timezone-based Reporting

➡️ v1

➡️ v2

Handling Different Timezones

👍Note:

Example Request

6. Data Granularity

7. Response Formats

8. Reward Period Allocation

9. Health Endpoint

10. GZIP Support

👋 Need Help?

❗️
Note

👍
Note:

🚧
Note:

👍
Note:

❗️
Note:

🚧
Note:

👍
Note: