Rewards API - Ethereum

Change Network: Jump to:

API AuthenticationClick to view API Authentication details

API calls require authentication with API key via Authorization request header or URL property. Calls are made to one of the Ethereum Rewards API endpoints found in your app's dashboard.

For example: https://eth-rewards.datahub.figment.io

Here's some boilerplate to get you started.

Fetch with Header
Fetch with Parameter
CURL with Header
CURL with Parameter

fetch("https://eth-rewards.datahub.figment.io/v2/rewards", {
    method: 'POST', // can also be 'GET', 'PUT' or any appropriate method
    headers: {
        "Authorization" : "<api_key>",
        "Content-Type": "application/json" // if method is 'POST'
    },
    body: JSON.stringify({
      // JSON Payload
    })
})

fetch("https://eth-rewards.datahub.figment.io/apikey/{{apikey}}/v2/rewards", {
    method: 'POST', // can also be 'GET', 'PUT' or any appropriate method
    headers: {
        "Content-Type": "application/json" // if method is 'POST'
    },
    body: JSON.stringify({
      // JSON Payload
    })
})

curl -X POST 'https://eth-rewards.datahub.figment.io/v2/rewards' \
--header 'Content-Type: application/json' \
--header 'Authorization: <api_key>' \
--data '{
  // JSON Payload
}'

curl -X POST 'https://eth-rewards.datahub.figment.io/apikey/{{apikey}}/v2/rewards' \
--header 'Content-Type: application/json' \
--data '{
  // JSON Payload
}'

Available Methods

ETH Rewards by validator address

Returns gross validator rewards

Request Body (try it)

{
  "accounts": [
    "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
  ],
  "start": "2023-03-22",
  "end": "2023-03-23"
}

{
  "accounts": [
    "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
  ],
  "start": "2023-03-22",
  "end": "2023-03-23"
}

Example Response
{
  "data": [
    {
      "accounts": [
        "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
      ],
      "chain_id": "mainnet",
      "rewards": [
        {
          "text": "0.000013666 ETH",
          "currency": "ETH",
          "numeric": 13666000000000,
          "exp": 18,
          "type": "staking",
          "recipient": "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
        }
      ],
      "period": "164726",
      "validator": "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0",
      "timestamp": "2022-12-03T14:46:24Z",
      "withdrawal_credentials": "0x0100000000000000000000001cedc0f3af8f9841b0a1f5c1a4ddc6e1a1629074"
    },
    {
      "accounts": [
        "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
      ],
      "chain_id": "mainnet",
      "rewards": [
        {
          "text": "0.000013569 ETH",
          "currency": "ETH",
          "numeric": 13569000000000,
          "exp": 18,
          "type": "staking",
          "recipient": "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0"
        }
      ],
      "period": "164727",
      "validator": "0x968c329ed829636a0bbbb57a25d9634ffd0d17bc1ff33adf93fd6a98920a82a83de930b9f2dddaebc4104ac90581ada0",
      "timestamp": "2022-12-03T14:52:48Z",
      "withdrawal_credentials": "0x0100000000000000000000001cedc0f3af8f9841b0a1f5c1a4ddc6e1a1629074"
    }
  ],
  "meta": {
    "network": "ethereum",
    "period_unit": "epoch"
  }
}

SpecificationView Specification

Body

accounts takes an array of validator's public addresses. 50 max. Required.
start and end are epoch numbers (as integers) or timestamps (as strings "YYYY-MM-DD"). Required.
aggregation allows you to get rewards by epoch (default if nothing is passed) or by day (if daily is passed).

Response

The response is broken down between meta and data

meta
- network is the name of the network queried
- period_unit is the unit of the period field under data : epoch or daily
data is an array of objects, one for each period and accounts, containing:
- validator is the validator that distributed the rewards
- period is the epoch number (only present when no aggregation is requested)
- timestamp is the timestamp of the end of the period
- rewards is an array of objects.
  - The formula to compute the final rewards in the currency unit is numeric x 10^(-exp) (text being the string version of this).
  - type is either staking (for consensus layer rewards) or tips (for execution layer rewards).
  - recipient is the address of the rewards recipient.
- balances is an array of objects containing numeric, exp, currency, and text. It returns the validator's current balance

MEV fields

When a reward is of type tips we attach extra metadata for data.rewards

sender is the "from" address of the tips transaction
tx_hash is the transaction identifier for the tips payout
slot is the consensus layer slot at which the block proposal occurred
block is the execution layer block in which the transaction was included
is_mev indicates if the block was built with MEV
mev_service specifies which service built the MEV block

There can be multiple type=tips objects per period: one per proposed blocks. We don't aggregate them in one object because they could have different recipient addresses. type=staking only have one object: we aggregate all subtypes (block proposals, attestations, sync committees, slashing)

Limitations

This API serves data for the last 7 days for epoch and 60 days for daily aggregation
This API returns rewards for Figment validators only
Data is available approximately an hour after the end of the day or epoch. When requesting daily for the current day, the data will be available but obviously partially complete as the day progresses.

FAQ

Reward Types: staking type rewards are the net aggregation of all consensus layer rewards: block proposal, attestation, sync committee and slashing. There is one staking bucket per period. tips type rewards are the effective amount received by the fee recipient of the proposed block on the execution layer. There can be multiple buckets per period (one per block proposed)
Negative Rewards: In theory, there could be a negative rewards amount for a day. But slashing events are rare. Current negative amounts would more likely be caused by repeatedly missing attestations and/or sync committee votes.

ETH Rewards by withdrawal address