Skip to main content

Rewards - Ethereum


Rewards by validator address

Returns gross validator rewards.

URL

https://eth-rewards.datahub.figment.io/v2/rewards

Request

  • accounts* : Takes an array of validator's public addresses. Maximum of 50.
  • start* and end* : Epoch numbers (as integers) or timestamps (as strings "YYYY-MM-DD").
  • 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 : The name of the network queried.
    • period_unit : The unit of the period field under data : epoch or daily
  • data : An array of objects, one for each period and accounts, containing:
    • validator : The validator which distributed the rewards.
    • period : The epoch number (only present when no aggregation is requested).
    • timestamp : The timestamp of the end of the period.
    • rewards : 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 : 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 : The "from" address of the tips transaction.
  • tx_hash : The transaction identifier for the tips payout.
  • slot : The consensus layer slot at which the block proposal occurred.
  • block ; 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.
Request (try it)
Example Response
{
"data": [
{
"accounts": [
"0x829e842c3d59b4026592e3f15ee0bb9dd3058418a8dda4db95591c4d8ff9e8c7d65ce0b4765523be392e001ae9d92f91"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.038060104",
"currency": "ETH",
"numeric": 38060104000000000,
"exp": 18,
"type": "staking",
"recipient": "0x829e842c3d59b4026592e3f15ee0bb9dd3058418a8dda4db95591c4d8ff9e8c7d65ce0b4765523be392e001ae9d92f91"
},
{
"text": "0.100341753551404924",
"currency": "ETH",
"numeric": 100341753551404930,
"exp": 18,
"type": "tips",
"recipient": "0x2af46c290563c1b242e2d1de5669396eb6a71986",
"sender": "0x1f9090aae28b8a3dceadf281b0f12828e676c326",
"slot": 6769678,
"block": 17586480,
"is_mev": true,
"mev_service": "Flashbots",
"tx_hash": "0xda61f1b0c11d4ea6bc659912640f73c01396cdb98da0b06fb4a41c20a607fcb9"
}
],
"balances": [
{
"text": "32.000633772",
"currency": "ETH",
"numeric": 32000633772000000000,
"exp": 18
}
],
"validator": "0x829e842c3d59b4026592e3f15ee0bb9dd3058418a8dda4db95591c4d8ff9e8c7d65ce0b4765523be392e001ae9d92f91",
"timestamp": "2023-06-29T00:00:00Z",
"withdrawal_credentials": "0x0100000000000000000000002af46c290563c1b242e2d1de5669396eb6a71986"
},
{
"accounts": [
"0x829e842c3d59b4026592e3f15ee0bb9dd3058418a8dda4db95591c4d8ff9e8c7d65ce0b4765523be392e001ae9d92f91"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.002093661",
"currency": "ETH",
"numeric": 2093661000000000,
"exp": 18,
"type": "staking",
"recipient": "0x829e842c3d59b4026592e3f15ee0bb9dd3058418a8dda4db95591c4d8ff9e8c7d65ce0b4765523be392e001ae9d92f91"
}
],
"balances": [
{
"text": "32.002727433",
"currency": "ETH",
"numeric": 32002727433000000000,
"exp": 18
}
],
"validator": "0x829e842c3d59b4026592e3f15ee0bb9dd3058418a8dda4db95591c4d8ff9e8c7d65ce0b4765523be392e001ae9d92f91",
"timestamp": "2023-06-30T00:00:00Z",
"withdrawal_credentials": "0x0100000000000000000000002af46c290563c1b242e2d1de5669396eb6a71986"
}
],
"meta": {
"network": "ethereum",
"period_unit": "daily"
}
}


Rewards by withdrawal address

Returns gross validator rewards.

URL

https://eth-rewards.datahub.figment.io/v2/rewards

Request

  • addresses* takes an array of withdrawal addresses.
  • start* and end* are epoch numbers (as integers) or timestamps (as strings "YYYY-MM-DD").
  • 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 : The name of the network queried.
    • period_unit : The unit of the period field under data : epoch or daily.
  • data : An array of objects, one for each period and address, containing:
    • validator : The validator that distributed the rewards.
    • accounts : An array containing the validator address that received the rewards.
    • withdrawal_credentials : The withdrawal credentials of the validator entity.
    • period : The epoch number (only present when no aggregation is requested).
    • timestamp : The timestamp of the end of the period.
    • rewards : 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 : Either staking (for consensus layer rewards) or tips (for execution layer rewards).
      • recipient : The address of the rewards recipient.
    • balances : 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 : The "from" address of the tips transaction.
  • tx_hash : The transaction identifier for the tips payout.
  • slot : The consensus layer slot at which the block proposal occurred.
  • block : 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.
Request (try it)
Example Response
{
"data": [
{
"accounts": [
"0x8cc1e20644cefd72737768a4d501288437705ddb52411f95567e29319dcdd609bd15b4c80ca0f3ff7d320d9868ee0c02"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013666 ETH",
"currency": "ETH",
"numeric": 13666000000000,
"exp": 18,
"type": "staking",
"recipient": "0x8cc1e20644cefd72737768a4d501288437705ddb52411f95567e29319dcdd609bd15b4c80ca0f3ff7d320d9868ee0c02"
},
{
"text": "0.100341753551404924",
"currency": "ETH",
"numeric": 100341753551404930,
"exp": 18,
"type": "tips",
"recipient": "0x2af46c290563c1b242e2d1de5669396eb6a71986",
"sender": "0x1f9090aae28b8a3dceadf281b0f12828e676c326",
"slot": 6769678,
"block": 17586480,
"is_mev": true,
"mev_service": "Flashbots",
"tx_hash": "0xda61f1b0c11d4ea6bc659912640f73c01396cdb98da0b06fb4a41c20a607fcb9"
}
],
"period": "164726",
"validator": "0x8cc1e20644cefd72737768a4d501288437705ddb52411f95567e29319dcdd609bd15b4c80ca0f3ff7d320d9868ee0c02",
"timestamp": "2022-12-03T14:46:24Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0x8cc1e20644cefd72737768a4d501288437705ddb52411f95567e29319dcdd609bd15b4c80ca0f3ff7d320d9868ee0c02"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013569 ETH",
"currency": "ETH",
"numeric": 13569000000000,
"exp": 18,
"type": "staking",
"recipient": "0x8cc1e20644cefd72737768a4d501288437705ddb52411f95567e29319dcdd609bd15b4c80ca0f3ff7d320d9868ee0c02"
}
],
"period": "164727",
"validator": "0x8cc1e20644cefd72737768a4d501288437705ddb52411f95567e29319dcdd609bd15b4c80ca0f3ff7d320d9868ee0c02",
"timestamp": "2022-12-03T14:52:48Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0x8e0776a9c0c895ba1b6d136d7d47fb142287b56d5d70ef6c05e18e19ba60425324f8d9c2ac5113984b348b79ca20502e"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013666 ETH",
"currency": "ETH",
"numeric": 13666000000000,
"exp": 18,
"type": "staking",
"recipient": "0x8e0776a9c0c895ba1b6d136d7d47fb142287b56d5d70ef6c05e18e19ba60425324f8d9c2ac5113984b348b79ca20502e"
}
],
"period": "164726",
"validator": "0x8e0776a9c0c895ba1b6d136d7d47fb142287b56d5d70ef6c05e18e19ba60425324f8d9c2ac5113984b348b79ca20502e",
"timestamp": "2022-12-03T14:46:24Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0x8e0776a9c0c895ba1b6d136d7d47fb142287b56d5d70ef6c05e18e19ba60425324f8d9c2ac5113984b348b79ca20502e"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013569 ETH",
"currency": "ETH",
"numeric": 13569000000000,
"exp": 18,
"type": "staking",
"recipient": "0x8e0776a9c0c895ba1b6d136d7d47fb142287b56d5d70ef6c05e18e19ba60425324f8d9c2ac5113984b348b79ca20502e"
}
],
"period": "164727",
"validator": "0x8e0776a9c0c895ba1b6d136d7d47fb142287b56d5d70ef6c05e18e19ba60425324f8d9c2ac5113984b348b79ca20502e",
"timestamp": "2022-12-03T14:52:48Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0x9008570e9ecc3779030df0d70b6819247432a7e70ea6ef494652f920692a2ccd4aafb9feb570659ddaa29c5a0d29994b"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013666 ETH",
"currency": "ETH",
"numeric": 13666000000000,
"exp": 18,
"type": "staking",
"recipient": "0x9008570e9ecc3779030df0d70b6819247432a7e70ea6ef494652f920692a2ccd4aafb9feb570659ddaa29c5a0d29994b"
}
],
"period": "164726",
"validator": "0x9008570e9ecc3779030df0d70b6819247432a7e70ea6ef494652f920692a2ccd4aafb9feb570659ddaa29c5a0d29994b",
"timestamp": "2022-12-03T14:46:24Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0x9008570e9ecc3779030df0d70b6819247432a7e70ea6ef494652f920692a2ccd4aafb9feb570659ddaa29c5a0d29994b"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000010136 ETH",
"currency": "ETH",
"numeric": 10136000000000,
"exp": 18,
"type": "staking",
"recipient": "0x9008570e9ecc3779030df0d70b6819247432a7e70ea6ef494652f920692a2ccd4aafb9feb570659ddaa29c5a0d29994b"
}
],
"period": "164727",
"validator": "0x9008570e9ecc3779030df0d70b6819247432a7e70ea6ef494652f920692a2ccd4aafb9feb570659ddaa29c5a0d29994b",
"timestamp": "2022-12-03T14:52:48Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0xa2ce5e3fdb77aca2c2559d18f7adb31955f7ec6d547bb2098803cb277399965a3124327a115ef97709285245667b48e0"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013666 ETH",
"currency": "ETH",
"numeric": 13666000000000,
"exp": 18,
"type": "staking",
"recipient": "0xa2ce5e3fdb77aca2c2559d18f7adb31955f7ec6d547bb2098803cb277399965a3124327a115ef97709285245667b48e0"
}
],
"period": "164726",
"validator": "0xa2ce5e3fdb77aca2c2559d18f7adb31955f7ec6d547bb2098803cb277399965a3124327a115ef97709285245667b48e0",
"timestamp": "2022-12-03T14:46:24Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0xa2ce5e3fdb77aca2c2559d18f7adb31955f7ec6d547bb2098803cb277399965a3124327a115ef97709285245667b48e0"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013569 ETH",
"currency": "ETH",
"numeric": 13569000000000,
"exp": 18,
"type": "staking",
"recipient": "0xa2ce5e3fdb77aca2c2559d18f7adb31955f7ec6d547bb2098803cb277399965a3124327a115ef97709285245667b48e0"
}
],
"period": "164727",
"validator": "0xa2ce5e3fdb77aca2c2559d18f7adb31955f7ec6d547bb2098803cb277399965a3124327a115ef97709285245667b48e0",
"timestamp": "2022-12-03T14:52:48Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0xa2ee5d468ef53d82368d9026e321ab2c6d47f44c33b7b9f62369bf6dcf37fb0208f95dd6b485325ce1bbf5fec7ad45bb"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013666 ETH",
"currency": "ETH",
"numeric": 13666000000000,
"exp": 18,
"type": "staking",
"recipient": "0xa2ee5d468ef53d82368d9026e321ab2c6d47f44c33b7b9f62369bf6dcf37fb0208f95dd6b485325ce1bbf5fec7ad45bb"
}
],
"period": "164726",
"validator": "0xa2ee5d468ef53d82368d9026e321ab2c6d47f44c33b7b9f62369bf6dcf37fb0208f95dd6b485325ce1bbf5fec7ad45bb",
"timestamp": "2022-12-03T14:46:24Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0xa2ee5d468ef53d82368d9026e321ab2c6d47f44c33b7b9f62369bf6dcf37fb0208f95dd6b485325ce1bbf5fec7ad45bb"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013569 ETH",
"currency": "ETH",
"numeric": 13569000000000,
"exp": 18,
"type": "staking",
"recipient": "0xa2ee5d468ef53d82368d9026e321ab2c6d47f44c33b7b9f62369bf6dcf37fb0208f95dd6b485325ce1bbf5fec7ad45bb"
}
],
"period": "164727",
"validator": "0xa2ee5d468ef53d82368d9026e321ab2c6d47f44c33b7b9f62369bf6dcf37fb0208f95dd6b485325ce1bbf5fec7ad45bb",
"timestamp": "2022-12-03T14:52:48Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0xac3ed947685ae451f813e6a5d3938881f583ee71aba6770c6fc19e86273bffd876dd64db2f217521671fe658dfd86aec"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000010231 ETH",
"currency": "ETH",
"numeric": 10231000000000,
"exp": 18,
"type": "staking",
"recipient": "0xac3ed947685ae451f813e6a5d3938881f583ee71aba6770c6fc19e86273bffd876dd64db2f217521671fe658dfd86aec"
}
],
"period": "164726",
"validator": "0xac3ed947685ae451f813e6a5d3938881f583ee71aba6770c6fc19e86273bffd876dd64db2f217521671fe658dfd86aec",
"timestamp": "2022-12-03T14:46:24Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
},
{
"accounts": [
"0xac3ed947685ae451f813e6a5d3938881f583ee71aba6770c6fc19e86273bffd876dd64db2f217521671fe658dfd86aec"
],
"chain_id": "mainnet",
"rewards": [
{
"text": "0.000013569 ETH",
"currency": "ETH",
"numeric": 13569000000000,
"exp": 18,
"type": "staking",
"recipient": "0xac3ed947685ae451f813e6a5d3938881f583ee71aba6770c6fc19e86273bffd876dd64db2f217521671fe658dfd86aec"
}
],
"period": "164727",
"validator": "0xac3ed947685ae451f813e6a5d3938881f583ee71aba6770c6fc19e86273bffd876dd64db2f217521671fe658dfd86aec",
"timestamp": "2022-12-03T14:52:48Z",
"withdrawal_credentials": "0x010000000000000000000000ed488e6cc4b030eb5bfdde3227c3d5da2b9040e8"
}
],
"meta": {
"network": "ethereum",
"period_unit": "epoch"
}
}


Withdrawals by validator address

Returns a history of withdrawals for the specified addresses. Staking provider agnostic. Goes all the way back to the upgrade of April 12th 2023.

URL

https://eth-rewards.datahub.figment.io/v2/withdrawals

Request

  • validator_addresses* : Takes an array of validator public keys.
  • start* and end* are epoch numbers (as integers) or timestamps (as strings "YYYY-MM-DD").

Response

  • index : The unique index of the withdrawal on chain (from round robin process).
  • validator_public_key : The public key of the validator.
  • validator_index : The index of the validator.
  • withdrawal_address : The withdrawal address of the validator.
  • amount_text : The withdrawal amount (as text).
  • currency : "ETH".
  • amount_numeric : The withdrawal amount (as an integer) - needs exp below.
  • exp : The exponent used to calculate the final ETH amount.
  • full_withdrawal : a boolean indicating whether the validator exited or not.
  • slot : The consensus layer slot at which the withdrawal occurred.
  • epoch : The execution layer block in which the transaction was included.
  • timestamp : The timestamp of the end of the epoch.
Request (try it)
Example Response
{
"data": [
{
"index": 3151238,
"validator_public_key": "0x86556ae9c606d2da8c23b6fad6be999b318e7fc2384847f19a80ffce12a1705c19162b5c425b924b5334ad876231ef49",
"validator_index": 63905,
"withdrawal_address": "0x13da6583b4e567af24ae6b07ea057f251a38139e",
"full_withdrawal": true,
"slot": 251284,
"epoch": 7852,
"timestamp": "2021-01-05T09:36:48Z",
"amount_text": "32",
"currency": "ETH",
"amount_numeric": 32000000000,
"exp": 9
},
{
"index": 3151231,
"validator_public_key": "0xa335249a6ea599870a5bb30f686635fe2b8d41abc8935b29a7a0a0239c7deb8d0c0df501d21ba8c67c7b9b29bb25f4ba",
"validator_index": 63886,
"withdrawal_address": "0x13da6583b4e567af24ae6b07ea057f251a38139e",
"full_withdrawal": true,
"slot": 251283,
"epoch": 7852,
"timestamp": "2021-01-05T09:36:36Z",
"amount_text": "32",
"currency": "ETH",
"amount_numeric": 32000000000,
"exp": 9
}
],
"meta": {
"network": "ethereum"
}
}


Withdrawals by withdrawal address

Returns a history of withdrawals for the specified addresses. Staking provider agnostic. Goes all the way back to the upgrade of April 12th 2023.

URL

https://eth-rewards.datahub.figment.io/v2/withdrawals

Request

  • withdrawal_addresses* : Takes an array of withdrawal addresses
  • start* and end* are epoch numbers (as integers) or timestamps (as strings "YYYY-MM-DD")

Response

  • index : The unique index of the withdrawal on chain (from round robin process).
  • validator_public_key : The public key of the validator.
  • validator_index : The index of the validator.
  • withdrawal_address : The withdrawal address of the validator.
  • amount_text : The withdrawal amount (as text).
  • currency : "ETH".
  • amount_numeric : The withdrawal amount (as an integer) - needs exp below.
  • exp : The exponent used to calculate the final ETH amount.
  • full_withdrawal : A boolean indicating whether the validator exited or not.
  • slot : The consensus layer slot in which the withdrawal was included.
  • epoch : The execution layer block in which the transaction was included.
  • timestamp : The timestamp of the end of the epoch.
Request (try it)
Example Response
{
"data": [
{
"index": 3150495,
"validator_public_key": "0xb9a5b7fae184c0172943ef3a3a6c6d02172ffe74b61e01a4018ca7ea0d6c01a9d37183996416364af28a950040d0524c",
"validator_index": 63048,
"withdrawal_address": "0x2b43f331b7d9d2889de336d3c1d2444fd9d482ba",
"full_withdrawal": false,
"slot": 251234,
"epoch": 7851,
"timestamp": "2021-01-05T09:26:48Z",
"amount_text": "0.000277936",
"currency": "ETH",
"amount_numeric": 277936,
"exp": 9
},
{
"index": 3150494,
"validator_public_key": "0xa053a07168cb5df6d900d6af9de26936d9b1c5e9368eacfa12e71dd4546e3ff1d59d1d8c6a7f59442693870c54589c9f",
"validator_index": 63045,
"withdrawal_address": "0x536d380a267684eb445032c3c492e01da3c5bafc",
"full_withdrawal": false,
"slot": 251234,
"epoch": 7851,
"timestamp": "2021-01-05T09:26:48Z",
"amount_text": "0.000230992",
"currency": "ETH",
"amount_numeric": 230992,
"exp": 9
}
],
"meta": {
"network": "ethereum"
}
}