Alluvial's reporting API enables Platforms to request the ETH network rewards that their users have received. Below are two guides:
Platforms with omnibus account structure.
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
Copy 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
Copy {
"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.
For a range of days, use the endpoint /eth/v0/rewards/accounts/:idOrKey/summary
Request
Copy 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.
Copy [
{
"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.
For a range of days, use the endpoint /eth/v0/rewards/wallets/:idOrKey/summary
Request
Copy 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.
Copy [
{
"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
Copy 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%.
Copy [
{
"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"
}
] Discounting API
Platforms that want to provide a custom discount to their users can use the Discounting APIs to offload the calculations of a discounted net Protocol Service Fee to Alluvial's enterprise accounting service. Platforms can then use the API to call ETH network rewards, Protocol Service Fees, and end user discounts for one or more wallets or user accounts.
First, you will set a new target fee rate. This represents the new gross Protocol Service Fee rate that will be calculated for an account and/or wallet.
For example, the current gross Protocol Service Fee rate is 10%. To offer a user an effective net rate of 8%, you'd set the target fee rate at 0.08, which effectively provides a 2% discount to the associated wallet(s) and/or account(s).
Request
Copy curl --location --request POST 'https://api.staging.alluvial.finance/v0/platform/accounts/8f9d6eff-d630-4389-810f-89c4b07b8fc5/discount_rate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJQ' \
--data '{
"target_fee_rate": 0.08
}' The target fee rate is now set at 8%.
Response
Copy {
"account_id" : "8f9d6eff-d630-4389-810f-89c4b07b8fc5" ,
"target_fee_rate" : "0.08" ,
"created_at" : "2024-06-24T21:27:07.387160077Z"
} On each Oracle report, you can use the Reporting APIs to see discounted values for the associated account, including the discounted net Protocol Service Fee, ETH network rewards received adjusted for that Fee, and effective end user discounts.
Request
Copy curl --location --request POST 'https://api.staging.alluvial.finance/eth/v0/rewards/accounts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ...mQ' \
--data '{
"accounts": [
"8f9d6eff-d630-4389-810f-89c4b07b8fc5"
],
"date": "2024-06-22",
"unit": "lseth"
}' In the response below, you can see that the rebate_eth or rebate_lseth will reflect the amount the wallet is attributed to be reimbursed in order to acheive the the 8% target fee rate (or conversely, a 2% discount on the gross Protocol Service Fee).
Response
Copy [
{
"account_id" : "8f9d6eff-d630-4389-810f-89c4b07b8fc5" ,
"totals" : {
"balance_lseth" : "0.947997263286356641" ,
"rewards_eth" : "0.001671038079957103"
} ,
"date" : "2024-06-22" ,
"wallets" : [
{
"oracle_report" : "43306f4695a1d7ed4118c68fecd150e1f071b338815007960e61900d8d9c123e00000046" ,
"address" : "0x4D1c3ec0B381F012A90f096cD4E8bc7746e4f2eB" ,
"account_id" : "8f9d6eff-d630-4389-810f-89c4b07b8fc5" ,
"org_id" : "org_WaYHN06ay6WoTjcz" ,
"date" : "2024-06-22" ,
"balance_lseth" : "0.00001" ,
"rewards_eth" : "0.000000000087955639" ,
"total_rewards_eth" : "0.000000020987954327" ,
"conversion_rate" : "1.0106749980064223" ,
"previous_conversion_rate" : "1.0106662024425232" ,
"mints_lseth" : "0" ,
"total_mints_lseth" : "0" ,
"burns_lseth" : "0" ,
"total_burns_lseth" : "0" ,
"fees_eth" : "0.000000000009772849" ,
"total_fees_eth" : "0.000000002331994927" ,
"dao_fees_eth" : "0.000000000000928421" ,
"total_dao_fees_eth" : "0.000000000221539524" ,
"provider_fees_eth" : "0.00000000000034205" ,
"total_provider_fees_eth" : "0.000000000081619819" ,
"slashing_fees_eth" : "0.000000000000293185" ,
"total_slashing_fees_eth" : "0.00000000006995985" ,
"platform_fees_eth" : "0.000000000006743266" ,
"total_platform_fees_eth" : "0.000000001609076496" ,
"platform_fees_at_discount_rate_eth" : "0" ,
"total_platform_fees_at_discount_rate_eth" : "0" ,
"operator_fees_eth" : "0.000000000001465927" ,
"total_operator_fees_eth" : "0.00000000034979924" ,
"gross_protocol_fee_rate" : "0" ,
"discount_rate" : "0" ,
"gross_fees_eth" : "0.000000000009772849" ,
"total_gross_fees_eth" : "0.000000002331994927" ,
"gross_rewards_eth" : "0.000000000097728488" ,
"total_gross_rewards_eth" : "0.000000000189971905" ,
"rebate_eth" : "0" ,
"total_rebate_eth" : "0" ,
"rebate_lseth" : "0" ,
"total_rebate_lseth" : "0"
} ,
{
"oracle_report" : "43306f4695a1d7ed4118c68fecd150e1f071b338815007960e61900d8d9c123e00000046" ,
"address" : "0x7fc2B172EcC8E4609088f341Aa0Fb3841De8A77A" ,
"account_id" : "8f9d6eff-d630-4389-810f-89c4b07b8fc5" ,
"org_id" : "org_WaYHN06ay6WoTjcz" ,
"date" : "2024-06-22" ,
"balance_lseth" : "0.947987263286356641" ,
"rewards_eth" : "0.000008338082549768" ,
"total_rewards_eth" : "0.001671017092002776" ,
"conversion_rate" : "1.0106749980064223" ,
"previous_conversion_rate" : "1.0106662024425232" ,
"mints_lseth" : "0" ,
"total_mints_lseth" : "5.947997863289656641" ,
"burns_lseth" : "0" ,
"total_burns_lseth" : "0.0000006000033" ,
"fees_eth" : "0.000000926453616641" ,
"total_fees_eth" : "0.000185668565778085" ,
"dao_fees_eth" : "0.000000088013093581" ,
"total_dao_fees_eth" : "0.000017638513748923" ,
"provider_fees_eth" : "0.000000032425876582" ,
"total_provider_fees_eth" : "0.000006498399802232" ,
"slashing_fees_eth" : "0.000000027793608499" ,
"total_slashing_fees_eth" : "0.000005570056973343" ,
"platform_fees_eth" : "0.000000639252995482" ,
"total_platform_fees_eth" : "0.000128111310386881" ,
"platform_fees_at_discount_rate_eth" : "0" ,
"total_platform_fees_at_discount_rate_eth" : "0" ,
"operator_fees_eth" : "0.000000138968042496" ,
"total_operator_fees_eth" : "0.000027850284866709" ,
"gross_protocol_fee_rate" : "0" ,
"discount_rate" : "0" ,
"gross_fees_eth" : "0.000000926453616641" ,
"total_gross_fees_eth" : "0.000185668565778085" ,
"gross_rewards_eth" : "0.000009264536166409" ,
"total_gross_rewards_eth" : "0.000018009094566287" ,
"rebate_eth" : "0" ,
"total_rebate_eth" : "0" ,
"rebate_lseth" : "0" ,
"total_rebate_lseth" : "0"
}
]
}
] The discount data is exposed via the following API endpoints:
/eth/v0/rewards/accounts/:idOrKey/summary
/eth/v0/rewards/wallets/:idOrKey/summary
