Reporting

Pre-read

Review the Authentication Guide for the Alluvial API.

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 who 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. The request body includes two objects that represents a change in balance (balance increased from 1 to 2 on 04-11-2024).

• The first lot has a balance a 1 and the Platform wants to see the ETH network rewards received during the period from 2024-04-01 to 2024-04-10.

• The second lot has a balance a 2 and the Platform wants to see the ETH network rewards received during the period from 2024-04-01 to the current date.

Request

curl --location 'https://api.staging.alluvial.finance/eth/v0/rewards' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ...Q' \
--data '[
 {
  "balance": "1",
  "from": "2024-04-01",
  "to": "2024-04-10"
 },
 {
  "balance": "2",
  "from": "2024-04-01"
 }
]'

Response

The response shows that the total balance is 3 and the total rewards earned for the given lots.

{
    "balance": "3",
    "accrued_rewards": "0.0103122076749559",
    "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-01",
            "to": "2024-04-24",
            "start_conversion_rate": "1.0014257204933798",
            "end_conversion_rate": "1.0061213180966859",
            "balance": "2",
            "accrued_rewards": "0.0093911952066122"
        }
    ]
}

Segregated account structure

Coming soon!

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 --location '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"
    }
]