Rewards

Returns gross rewards, as earned by validators

Notes:

• For mainnet and hoodi
• Returns data for any Figment validator that was created through Create Validators
• Daily and all time rollups
• Filters by date (start and end timestamps, inclusive), by validator pubkey or by withdrawal address/credentials.
• For a single validator’s rewards, pass only pubkey and omit withdrawal_addresses.
• Rewards are available approximatively 3 hours after they are distributed onchain. Daily rollups are done based on UTC days
• Includes execution layer rewards, swept consensus layer rewards and unswept consensus layer rewards
• Slashing penalties are reflected in the "balances" field, and subsequent missed attestations appear as negative values in consensus rewards.

General features described in Rewards Overview

Time Rollup

time_rollup
string
enum
required
The granularity of the rewards data. Use epoch for one record per validator per epoch, daily for rewards aggregated by UTC calendar day, or all_time for cumulative rewards since validator activation.

Allowed:
epoch daily all_time

Start

start
string
required
Lower bound of rewards data. For epoch time_rollup: accepts an epoch number as an integer (e.g. 261702) or a date string ("YYYY-MM-DD"). For daily time_rollup: accepts a date string ("YYYY-MM-DD"). Ignored for all_time time_rollup.

End

end
string
required
Upper bound of rewards data. For epoch time_rollup: accepts an epoch number as an integer (e.g. 261703) or a date string ("YYYY-MM-DD"). For daily time_rollup: accepts a date string ("YYYY-MM-DD"). Ignored for all_time time_rollup.

Groups

groups
string
Filter using comma-separated group uuids.

Network

network
string
enum
Defaults to mainnet

Allowed:
mainnet hoodi

Pubkeys

pubkeys
array of strings
A list of validator pubkeys for filtering.

Withdrawal Addresses

withdrawal_addresses
array of strings
A list of withdrawal addresses or credentials for filtering.

Page

page
object

Include Penalties

include_penalties
boolean
Defaults to false

When true, includes a separate consensus_penalty entry in the rewards array representing attestation and sync committee penalties for the period. Defaults to false.

Example CURL Request

curl --request POST \
     --url https://api.figment.io/ethereum/rewards \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: your-api-key-here' \
     --data '
{
  "time_rollup": "epoch",
  "network": "mainnet",
  "include_penalties": false
}
'  

Example Response

{
  "data": [
    {
      "pubkey": "0x9a0059ed6c2d2e35104a5113fdefa9d06cbd855b7be170f068b100391ffc811f55af4933e5e832a6c4ccfa69e7e4d120",
      "rewards": [
        {
          "text": "0.002932238",
          "currency": "ETH",
          "numeric": 2932238000000000,
          "exp": 18,
          "type": "consensus"
        },
        {
          "text": "0.019767962495220182",
          "currency": "ETH",
          "numeric": 19767962495220184,
          "exp": 18,
          "type": "execution",
          "recipient": "0xed488e6cc4b030eb5bfdde3227c3d5da2b9040e8",
          "sender": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5",
          "slot": 7334788,
          "block": 18146590,
          "is_mev": true,
          "mev_relay": "Block Native",
          "tx_hash": "0x25e3a03462a55b2632573cfc8e36cbb431d38793b6d26603cb11fd0251fee73b"
        }
      ],
      "balances": [
        {
          "text": "33.824197321",
          "currency": "ETH",
          "numeric": 33824197321000000000,
          "exp": 18
        }
      ],
      "timestamp": "2023-02-22T00:00:00Z",
      "max_epoch": 183036,
      "withdrawal_address": "0xeD488E6cc4B030eb5BfddE3227C3D5da2b9040E8",
      "withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
    }
  ],

"meta": {
    "protocol": "ethereum",
    "network": "mainnet",
    "time_rollup": "daily"
  }
}