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

Important Notes

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

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

Response Format

The response content type depends on the Accept header you specify:

`Accept` header	Response format
`application/x-ndjson` (default)	Newline-delimited JSON stream
`application/json`	Standard JSON
`text/csv`	CSV

cURL

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.

JSON

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

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

cURL

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.

JSON

{
  "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).

JSON

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

👋 Need Help?

Updated about 1 month ago