Using the Rewards API

The Rewards API queries staking rewards data. By staking on a validator, a user earns rewards while securing the network. Indexing and querying this data is challenging and very time-consuming on your own; the Rewards API is your gateway to succinct rewards data on a daily basis or by epoch.

Authentication

Read about the authentication HERE

Requests

You can send an HTTP GET request to the endpoint to fetch rewards data.

The JSON payload must include the following parameters:

• accounts: An array containing one or more accounts addresses
• start: The start of epcoh/time for collecting rewards data, epoch should be in integer format (Rewards by Epoch) and timestamp in YYYY-MM-DD format (Rewards by Day).
• end: The end of epoch/time for collecting rewards data, epoch should in integer format (Rewards by Epoch) and timestamp in YYYY-MM-DD format (Rewards by Day).
• aggregation: daily (only for Reward by Day)

Example JSON for a Rewards API query

{
  "accounts": [
    "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
  ],
  "start": "2022-11-06",
  "end": "2022-11-07",
  "aggregation": "daily"
}

info

If you want to fetch rewards by epoch, make sure that start and end align with that epoch—otherwise you may get an empty response.

If you want to fetch rewards by day, keep the start and end reasonably close together (within five days). Large ranges will cause latency in the response.

Example Requests

info

In example requests, the text API-KEY must be replaced with your actual credentials for it to function. Similarly, you would need to replace the value of the constant API_KEY in any code examples.

curl

Example curl request to Rewards API for Ethereum Mainnet

curl -X GET https://eth-rewards.datahub.figment.io/rewards \
-H 'Content-Type: application/json' \
-H 'Authorization: API-KEY' \
-d '{
  "accounts": [
    "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
  ],
  "start": "2022-11-06",
  "end": "2022-11-07",
  "aggregation": "daily"
}'

JavaScript

Example JavaScript Fetch request to Rewards API for Ethereum Mainnet

const API_KEY = "YOUR API KEY";

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", API_KEY);

var raw = JSON.stringify({
  accounts: [
    "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0",
  ],
  start_time: "2022-11-06",
  end_time: "2022-11-07",
  aggregation: "daily",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch(`https://eth-rewards.datahub.figment.io/rewards`, requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Click to view example response

Example Rewards API JSON response

{
  "data": [
    {
      "accounts": [
        "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
      ],
      "chain_id": "mainnet",
      "rewards": [
        {
          "text": "0.003154426 ETH",
          "currency": "ETH",
          "numeric": 3154426000000000,
          "exp": 18,
          "type": "staking",
          "recipient": "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
        }
      ],
      "validator": "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0",
      "timestamp": "2022-11-06T00:00:00Z"
    },
    {
      "accounts": [
        "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
      ],
      "chain_id": "mainnet",
      "rewards": [
        {
          "text": "0.033305945 ETH",
          "currency": "ETH",
          "numeric": 33305945000000000,
          "exp": 18,
          "type": "staking",
          "recipient": "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
        },
        {
          "text": "0.182060023767382816 ETH",
          "currency": "ETH",
          "numeric": 182060023767382820,
          "exp": 18,
          "type": "tips",
          "recipient": "0x1cedc0f3af8f9841b0a1f5c1a4ddc6e1a1629074",
          "sender": "0xdafea492d9c6733ae3d56b7ed1adb60692c98bc5",
          "slot": 5083891,
          "block": 15918695,
          "is_mev": true,
          "mev_service": "Flashbots"
        }
      ],
      "validator": "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0",
      "timestamp": "2022-11-07T00:00:00Z"
    }
  ],
  "meta": {
    "network": "ethereum",
    "period_unit": "daily"
  }
}

API Reference

View the full Rewards API reference HERE

---