NEAR API v2 Overview

Overview

Version 2 of NEAR Staking Reporting API enhances its capabilities with features like tracking deposits and withdrawals, timezone-based reporting, near-real-time data availability (including per-epoch and yearly roll-ups), and improved handling of validator and delegator statuses for more accurate reporting.

Supported network: Mainnet

📘

Info:

For more information, please refer to the Migration Guide.

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.

❗️

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.

➡️ Get Rewards

This endpoint returns the total rewards for the given period from one or more addresses of validators and delegators.

📘

Info:

To receive a report in your timezone, submit the day start and end times in epoch seconds. You can convert these times using Epoch Converter.

Endpoints

Sample Object

The response below is returned from the historical rewards request for a validator.

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

➡️ Get Status

This endpoint returns the current status from one or more addresses of validators and delegators. Possible statuses are

• UNKNOWN
• ACTIVE
• INACTIVE

Endpoints

Sample Object

The response below shows the status of a single validator.

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

➡️ Get Health

This endpoint displays the current reporting status. You can track:

• The latest epoch with available rewards
• The current status of the reward processing

Sample Object

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

👋 Need Help?

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