Reporting

Alluvial's reporting API enables Platforms to request the ETH network rewards that their users have received. Below are two guides:

  1. Platforms with omnibus account structure.

  2. Platforms with segregated account structure.

Omnibus account structure

Platforms that support an omnibus structure should use the /eth/v0/rewards endpoint. This will return data in a lots structure. Lots represent LsETH balance changes for a given period. Rewards can then be calculated for each period. Total rewards for a user is the sum of rewards for each lot.

Below is an example request where a Platform wants to see the rewards for a wallet. Assume that the user has a total balance of 3 but acquired at different dates.

  • The user had 1 LsETH from 2024-04-01 to 2024-04-10. As such this will be the first lot added to the request body.

  • The user then acquired 2 more LsETH, for a total of 3, as of 2024-04-11.

In our request below assume that the current date for which we want data is til 2024-04-15.

Request

curl --request POST 'https://api.staging.alluvial.finance/eth/v0/rewards' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer e...g' \
--data '[
	{
		"balance": "1",
		"from": "2024-04-01",
		"to": "2024-04-10"
	},
	{
		"balance": "3",
		"from": "2024-04-11",
		"to": "2024-04-15"
	}
]'

Response

{
    "balance": "4",
    "accrued_rewards": "0.0041516089956458",
    "lots": [
        {
            "from": "2024-04-01",
            "to": "2024-04-10",
            "start_conversion_rate": "1.0014257204933798",
            "end_conversion_rate": "1.0023467329617235",
            "balance": "1",
            "accrued_rewards": "0.0009210124683437"
        },
        {
            "from": "2024-04-11",
            "to": "2024-04-15",
            "start_conversion_rate": "1.0026157619809285",
            "end_conversion_rate": "1.0036926274900292",
            "balance": "3",
            "accrued_rewards": "0.0032305965273021"
        }
    ]
}

Segregated account structure

Platforms that support a segregated structure can use two different endpoints to get reward data at the account or wallet level.

List rewards by account(s)

Use the endpoint /eth/v0/rewards/accounts to display ETH network rewards at the account level.

Request

curl --request POST 'https://api.staging.alluvial.finance/eth/v0/rewards/accounts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Impersonate-Org: org_uLD0aCAXyWYg4WQH' \
--header 'Authorization: Bearer ey...Qg' \
--data '{
	"accounts": [
		"8f9d6eff-d630-4389-810f-89c4b07b8fc5"
	],
	"date": "2024-05-15",
	"unit": "eth"
}'

Response

Below is the response show the aggregated rewards for the account in addition for each address.

[
    {
        "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
        "totals": {
            "balance_lseth": "0.0000198315414745",
            "rewards_eth": "0.000000000092766089"
        },
        "date": "2024-05-15",
        "wallets": [
            {
                "oracle_report": "1437a7330f02400a5662ed70f5c23b251d76fdb1ede48240d9f1e7bcd70540470000014b",
                "address": "0x7fc2B172EcC8E4609088f341Aa0Fb3841De8A77A",
                "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
                "org_id": "org_WaYHN06ay6WoTjcz",
                "date": "2024-05-15",
                "balance_lseth": "0.00000991577073725",
                "rewards_eth": "0.000000000092766089",
                "total_rewards_eth": "0.000000000092766089",
                "conversion_rate": "1.0085131998588114",
                "previous_conversion_rate": "1.0085038444500037",
                "mints_lseth": "0",
                "total_mints_lseth": "0.00000991577073725",
                "burns_lseth": "0",
                "total_burns_lseth": "0",
                "fees_eth": "0.000000000010307343",
                "total_fees_eth": "0.000000000010307343",
                "dao_fees_eth": "0.000000000000979198",
                "total_dao_fees_eth": "0.000000000000979198",
                "provider_fees_eth": "0.000000000000360757",
                "total_provider_fees_eth": "0.000000000000360757",
                "slashing_fees_eth": "0.00000000000030922",
                "total_slashing_fees_eth": "0.00000000000030922",
                "platform_fees_eth": "0.000000000007112067",
                "total_platform_fees_eth": "0.000000000007112067",
                "operator_fees_eth": "0.000000000001546101",
                "total_operator_fees_eth": "0.000000000001546101"
            }
        ]
    }
]

List rewards by wallet(s)

Use the endpoint /eth/v0/rewards/wallets to display ETH network rewards at the wallet level.

Request

curl --request POST 'https://api.staging.alluvial.finance/eth/v0/rewards/wallets' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Impersonate-Org: org_uLD0aCAXyWYg4WQH' \
--header 'Authorization: Bearer ey...Qg' \
--data '{
	"addresses": [
		"0x7fc2B172EcC8E4609088f341Aa0Fb3841De8A77A"
	],
	"date": "2024-05-15",
	"unit": "eth"
}'

Response

Below is the response showing the aggregated rewards for the account in addition for each address.

[
    {
        "oracle_report": "1437a7330f02400a5662ed70f5c23b251d76fdb1ede48240d9f1e7bcd70540470000014b",
        "address": "0x7fc2B172EcC8E4609088f341Aa0Fb3841De8A77A",
        "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
        "org_id": "org_WaYHN06ay6WoTjcz",
        "date": "2024-05-15",
        "balance_lseth": "0.00000991577073725",
        "rewards_eth": "0.000000000092766089",
        "total_rewards_eth": "0.000000000092766089",
        "conversion_rate": "1.0085131998588114",
        "previous_conversion_rate": "1.0085038444500037",
        "mints_lseth": "0",
        "total_mints_lseth": "0.00000991577073725",
        "burns_lseth": "0",
        "total_burns_lseth": "0",
        "fees_eth": "0.000000000010307343",
        "total_fees_eth": "0.000000000010307343",
        "dao_fees_eth": "0.000000000000979198",
        "total_dao_fees_eth": "0.000000000000979198",
        "provider_fees_eth": "0.000000000000360757",
        "total_provider_fees_eth": "0.000000000000360757",
        "slashing_fees_eth": "0.00000000000030922",
        "total_slashing_fees_eth": "0.00000000000030922",
        "platform_fees_eth": "0.000000000007112067",
        "total_platform_fees_eth": "0.000000000007112067",
        "operator_fees_eth": "0.000000000001546101",
        "total_operator_fees_eth": "0.000000000001546101"
    }
]

Staking Reward Rate

The Alluvial API provides a staking rewards rate (SRR), which is calculated as a 7 day trailing average.

To get SRR information, call the /protocol endpoint.

Request

curl 'https://api.alluvial.finance/eth/v0/protocol/2024-05-01' \
--header 'Accept: application/json' \
--header 'Accept: application/json'

Response

Based on providing a specific date of 2024-05-01, the returned SRR is 2.85%.

[
    {
        "oracle_report": "2e39c7e7e0b78c043ac98e190175fa7f057a75197647d4d844864ac06c98aa3400000225",
        "date": "2024-05-01T12:14:47Z",
        "total_protocol_mints_lseth": "89180.704128270784037675",
        "total_protocol_burns_lseth": "6676.332903830493099868",
        "total_protocol_active_keys_count": 2703,
        "rewards_eth": "6.66289490787142415",
        "gross_fee_rate": "0.1",
        "gross_fee_lseth": "0.636483355669561459",
        "conversion_rate": "1.0468294022963504",
        "total_lseth_supply": "82674.954629966742503924",
        "a_srr_7d": "2.85"
    }
]

Last updated