Using Alluvial APIs makes it easy to onboard and interact with the Liquid Collective protocol.

There are two types of Liquid Collective Platforms. Platforms either:

• Enable mint/redeem: These Platforms enable direct Liquid Collective protocol interactions, including depositing ETH to Ethereum's deposit contract and redeeming LsETH for ETH (minting and redeeming). These Platforms offer KYC/AML and Sanctions Screening procedures for their users, then submit the user's wallet address to Liquid Collective's Allowlist smart contract upon successful completion.

• Enable secondary interactions: These Platforms do not enable minting, redeeming, or direct Liquid Collective protocol interactions, but do enable secondary protocol interactions such as trading, lending, or other services not required to Allowlist KYC/AML and Sanctions Screened wallet addresses. Users of these Platforms can seamlessly interact with LsETH, and may accrue Ethereum's consensus and execution layer network rewards simply by holding LsETH.

There are two lists that Platforms can interact with:

• Allowlist: Any address added to this list can mint and/or burn directly with the Liquid Collective protocol. Only wallets that have on-ramped via a mint/redeemed enabled Platform can be added to this list.

• On-Platform: Platforms that only enable secondary interactions can only add wallets to the On-Platform list, and cannot interact with the Allowlist smart contract. When a wallet address is added to the Allowlist it is also automatically added to the On-Platform list. This list is used for calculating Platform rebates.

Below are two guides for Platforms to add their users to the appropriate lists.

Alluvial's APIs can also interact with other third party services, such as those offered by third party custodians that Platforms may use to custody funds staked using Liquid Collective.

Please note that these guides are to support Platforms who are connecting with third party products that are not offered by or in partnership or affiliation with Alluvial. Products and services offered by third parties are subject to separate terms and conditions. Visit the website of the third parties noted in these guides for more information on their offerings.

Ethereum Data API is a collection of APIs that expose read data from the Ethereum network.

Alluvial exposes several non-authenticated APIs to support DApps

Reporting API is a collection of APIs Platforms use to get information about Liquid Collective Protocol Service Fees.

This page shows the process for creating an access token.

1. When onboarding with Alluvial, you will receive API credentials. These include a client_id and client_secret.

2. After receiving your credentials use the curl request below, updating the client_id and client_secret with your specific credentials.

Response

Redemption API is a collection of APIs that expose read data on redemptions.

To see APIs used in an example implementation check out the Redemption guide (below).

Alluvial exposes several APIs to help developers interact with the Liquid Collective Protocol.

API-Reference

To help illustrate how a Platform utilizes the Alluvial APIs to support its Liquid Collective protocol integration, this guide introduces a few fictional characters:

• Acme Custodian Corp: Financial institution that is a Platform for the Liquid Collective protocol and will offer its customers the ability to participate in the Liquid Collective protocol by staking ETH.

• Alice: user of Acme Custodian Corp

• Bob: user of Acme Custodian Corp

A custodial wallet's private key(s) are held by either a 3rd party or by the financial institution that is servicing the wallet account on behalf of the customer. In this example, Alice and Bob have a custodial account with Acme Corp and Acme Corp owns / has access to the private key associated with Alice's and Bob's wallet addresses.

Below is an example of the flow of funds, showing how the staking action by Alice and Bob will flow through Acme's architecture and the Alluvial APIs.

Non-custodial (or self-managed) wallets are those in which the customer holds the private keys. In this example, Alice is the only one with access to the private key for her wallet.

The largest differences between the two flow of funds diagrams are the wallet ownership and actions (i.e. signing transactions).

A segregated account structure is one where each customer at the financial institution (ex. Acme Corp) has their own unique, separate account. In this example, both Alice and Bob have their own unique Ethereum address associated with their individual accounts at Acme Corp.

Based on the example segregated account structure, you can see how Acme Corp will map its internal accounts to the technical resources (Organization, Depositor, Wallet) created when interacting with the Alluvial API.

An omnibus account is an account structure in which all users' accounts are grouped into a single wallet address.

Below is an image of how to map Acme's architecture to resources (Organization, Depositor, and Wallet) created via Alluvial's API.

Alluvial isn't aware of, and at no time has control over, the underlying account structure Acme implements. Acme will create a Depositor object that represents all of the internal customers.

Alluvial is a software development company supporting the development of the Liquid Collective protocol. We're focused on the overall growth and maturity of the ecosystem by fostering participation in proof of stake blockchains.

To learn more about the Liquid Collective protocol and how it works, check out Liquid Collective's documentation.

New to Alluvial's documentation?

The Alluvial docs have three key sections:

1. Guides: This section contains several step by step guides for how technical teams can implement key Liquid Staking flows.

2. : This section shows all the raw API requests that Liquid Collective Platforms can call.

3. : This section includes guides for how to interact with the Liquid Collective protocol via other software platforms.

If you are an engineer or technical person, looking to understand the level of effort or work involved in implementing the key flows (ETH staking and LsETH redemptions) then we recommend reviewing the and guides. The is a helpful compliment to these key guides.

This guide walks users through how to use authenticate requests using the Alluvial APIs.

Below is a ladder diagram showing the flow to create an access token.

This flow involves 3 parties:

• Platform Server: the client looking to access the Alluvial API and which has previously been given a Client ID and Client Secret credentials.

Review the for the Alluvial API.

Platforms that enable secondary protocol interactions, such as trading, lending, or other services, can create an Account object. The Account object is generally associated with a Platform's customer.

Request:

Response:

After an Account object is created, associate a Wallet object to an account. You can associate one or many Wallet objects to a given Account object.

Request:

Pre-read

Review the Authentication Guide for the Alluvial API.

Onboarding wallets

Create an Account object

First create an account object for each of your users.

Request:

curl -X 'POST' \

Response:

{
  "id": "da36a6fa-070d-4cd1-b99a-f2da4f4ccb20",
  "key": "FO123",
  "org_id": "org_WaYHN06ay6WoTjcz",
  "status": "ACTIVE",
  "created_at": "2023-03-17T17:24:18.031434748Z",
  "wallets": []
}

Create Wallet objects

Add wallet to Allowlist

Attach a wallet object to each account. You can add the wallet to the Allowlist (on-chain) or the On-Platform list (off-chain).

The first example below shows how to add a wallet address to the Allowlist (which be default is added to the On-Platform list).

Request:

Response:

Platforms that enable mint/redeem may also need to add a wallet address to the On-Platform list separately. The following request is for a Platform that enables mint/redeem to add a wallet to the On-Platform list.

Request:

Request:

Now that you have an Account object created and Wallet objects associated, the user can stake ETH and mint LsETH. Before depositing, ensure that the Wallet object(s) have a status = ALLOWLISTED.

To complete the staking process, review .

Alluvial's changelog records changes made to the Alluvial API specification, including new features, improvements, bug fixes, and more.

May 1, 2026

• Commercials V3 is live. New v1 reporting endpoints expose platform, originator, and operator fees and rates under the V3 fee model: /eth/v1/platforms/{date}, /eth/v1/originators/{date}, and /eth/v1/operators/{date}. See the Reporting API reference.

• The v0 /eth/v0/platforms/{date} and /eth/v0/operators/{date} endpoints stop populating platform fees and rates from this date forward. They remain valid for historical data through 2026-04-30. Migrate to the v1 endpoints for any period on or after 2026-05-01.

• Discounting APIs are live! These APIs enable adding a new target rate in the event Platforms need to adjust the net Protocol Service Fee rate for specific accounts and/or wallets.

• Summary APIs are now exposed within the Reporting API. Summary APIs allow for teams to get data for a range of dates rather than a specific day.

• Reporting API now exposes an endpoint for Platforms with segregated accounts to get rewards information. You can see examples in our .

• Reporting API now exposes an endpoint for Platforms with an omnibus to get rewards information. You can see examples in our .

• On-Platform list has been created to allow Platforms that only want to allow for a wallet to take part in secondary actions of LsETH to be accounted for. More information can be found in the guide or guide.

• When creating a wallet, Platforms that allow for minting and redeeming, but only want to allow a wallet for secondary interactions can add these wallets to the on_platform list.

• Introduction of . These replace the Depositor APIs that are now marked for .

• Expose redemption requests by address via /eth/v0/redeems

• Expose redemption requests by id via /eth/v0/redeems/{idx}

• Expose redemption manager (heights) via /eth/v0/redeems_info

This API can be used with the .

• Expose redeem projected redeemable at timestamp via /eth/v0/redeems/{idx}/projection

• Expose manager projected fulfilled at timestamp via /eth/v0/redeems_info/projection

This API can be used with the .

• Remove address from Allowlister via PATCH /v0/depositors/{idOrKey}/wallets/{idOrAddress}/remove

Rather than removing the entire Depositor object, Platforms can now remove only the wallet address. This is the recommended approach for most cases where an a Platform needs to revoke a wallet address' Allowlist permissions.

The wallet will is still able to transfer LsETH to other wallets.

Checks whether a Solana wallet address is allowlisted for staking and redemption operations.

Endpoint: GET https://api.alluvial.finance/sol/v0/allowlist/{address}

Path Parameters:

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/v1/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.

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

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

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

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

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

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

To get SRR information, call the endpoint.

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

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 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).

The target fee rate is now set at 8%.

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.

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 achieve the the 8% target fee rate (or conversely, a 2% discount on the gross Protocol Service Fee).

The discount data is exposed via the following API endpoints:

• /rewards/wallets

• /eth/v0/rewards/accounts/:idOrKey/summary

• /eth/v0/rewards/wallets/:idOrKey/summary