API Reference
SupportStatus

Cosmos Reporting API Overview

Overview

The Cosmos Staking Reporting API provides access to detailed Cosmos staking information. It includes features such as near-real-time data availability and enhanced tracking of validator and delegator statuses for more accurate insights.

🌐 Supported network: Mainnet


❗️

Please Note

  • Rewards payouts are based on complete UTC days, with one entry per validator/delegator each day.
  • A minimum delegation of 100 ATOM is required to start tracking a delegator.
  • Data is available only from May 1, 2025, onward.

➡️ Get Rewards

This endpoint returns the total rewards for the queried period from one or more addresses.

Endpoints

Endpoint
Get a Stream of Rewards - POST /{type}/rewards
Get a Stream of Rewards for a Single Address - GET /{type}/rewards/{address}
Get a Stream of Yield Summaries - GET /yield

Sample Request

👍

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

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

curl --request GET \
  --url 'https://svc.blockdaemon.com/reporting/staking/v2/cosmos/mainnet/validator/rewards/<ADDRESS>?startTime=1709251200&endTime=1711929600&period=raw' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'accept: application/x-ndjson'

This would return a response below.

{
  "address": "cosmosvaloper10nzaaeh2kq28t3nqsh5m8kmyv90vx7ym5mpakx",
  "denomination": "uatom",
  "return": "283291849202",
  "startTime": 1709251200,
  "endTime": 1711929600,
  "period": "raw",
  "startBalance": "124222",
  "metadata": {
    "commission": "532626257312",
    "withdrawals": "8869338515563405",
    "validatorAddress": "cosmosvaloper10nzaaeh2kq28t3nqsh5m8kmyv90vx7ym5mpakx",
    "claimableCommission": "251296884",
    "startBlock": "25274224",
    "endBlock": "25286409",
    "stake": "532626257312",
    "claimableRewards": "532626257312"
  }
}

➡️ Get Status

This endpoint returns the current status of a validator/delegator. Possible statuses include:

  • UNKNOWN
  • ACTIVE
  • INACTIVE

Endpoints

Endpoint
Get a Stream of Statuses - POST /{type}/status
Get Status for an Address - GET /{type}/status/{address}

Sample Request

👍

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

Below is an example of getting the status of a single delegator.

curl --request GET \
  --url https://svc.blockdaemon.com/reporting/staking/v2/cosmos/mainnet/delegator/status/<ADDRESS> \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'accept: application/json'

This would return a response below.

{
  "address": "FQwewNXahV7MiZcLpY6p1xhUs2acVGQ3U5Xxc7FzV571",
  "status": "UNKNOWN",
  "timestamp": 1708612182
}

➡️ Get Health

The endpoint provides the health status of the rewards processing system. You can track:

  • The latest epoch with available rewards.
  • The current status of the blockchain.
Endpoint
Get the Protocol Rewards Processing Health - GET /health

Sample Object

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

{
  "status": "PROCESSING",
  "timestamp": 1704067200,
  "metadata": {
    "lastProcessedDate": "2025-04-20",
    "progress": "231/545",
    "minDelegation": "100 ATOM"
  }
}

👋 Need Help?

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