1 of 21

Alluvial

Who is Alluvial?

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:

: This section contains several step by step guides for how technical teams can implement key Liquid Staking flows.
: This section shows all the raw API requests that Liquid Collective Platforms can call.
: This section includes guides for how to interact with the Liquid Collective protocol via other software platforms.

Helpful tips

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.

Guides

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.

Mint and Redeem support

Pre-read

Review the for the Alluvial API.

Onboarding wallets

Secondary Interaction support

Pre-read

Review the Authentication Guide for the Alluvial API.

Create an Account object

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:

Create a Wallet object

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:

Response:

Your Platform is all set! Wallets added to the On-Platform list will be used to calculate the relevant Protocol Service Fee Rebates.

Reporting

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

Response

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

Response

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

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

Response

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

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

Request

Response

Based on providing a specific date of 2024-05-01, the returned SRR is 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 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

The target fee rate is now set at 8%.

Response

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

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

Response

The discount data is exposed via the following API endpoints:

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

Supplemental Guides

Architecture

This guide is intended for Platforms to learn about how they can integrate the Liquid Collective protocol with the support of Alluvial's APIs.

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

Authentication

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

Client Credentials Flow

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

This flow involves 3 parties:

APIs

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

API-Reference

Authentication API

This page shows the process for creating an access token.

When onboarding with Alluvial, you will receive API credentials. These include a client_id and client_secret.
After receiving your credentials use the curl request below, updating the client_id and client_secret with your specific credentials.

Staging

Response

Production

Request

Response

Ethereum Data API

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

Allowlisting API

Ethereum

Platform Account Operations

Platform Wallet Operations

Platform Account Wallet Operations

Solana

Check Allowlist Status

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:

Parameter

Type

Description

Response:

Response Fields:

Field

Type

Description

Add Wallet to Allowlist

Adds a Solana wallet address to the allowlist, granting permissions for staking and/or redemption operations.

Endpoint: POST https://api.alluvial.finance/sol/v0/allowlist

Request Body:

Request Fields:

Field

Type

Required

Description

Response:

Response Fields:

Field

Type

Description

Redemption API

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

Reporting API

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

Public endpoints (no authentication required)

Private endpoints ( authentication required)

Reward Summary

Discounting API

APIs that allow Platforms to create target discount schedules.

Public APIs

Alluvial exposes several non-authenticated APIs to support DApps

Third Party Integration Guides

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.

Changelog

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

July 9, 2024

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.

May 17, 2024

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

April 24, 2024

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

March 25, 2024

On-Platform list

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.

Platform APIs

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

May 5th, 2023

Release redeems APIs

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 .

May 18th, 2023

Release projection APIs for LsETH redemptions

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 .

November 20th, 2023

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.

Get status of the Ethereum protocol at a given block number

get

Get global information about protocol token supplies at a given block number

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

block_numberintegerRequired

Block height to query

Responses

200

application/json

active_validator_countintegerOptional

Count of total validators minus stopped validators on the consensus layer

Example: 58

active_validators_eth_balancestringOptional

Total consensus ETH balance of all validators on the consensus layer (as reported by the Oracle) in Wei

Example: 128000000000000000000

block_numberintegerOptional

Height of the returned data

Example: 15034284

collected_rewardsstringOptional

Total collected rewards

Example: 3200000000000000000000

contract_eth_balancestringOptional

ETH balance on the contract in Wei

Example: 5000000000000000000

conversion_ratenumberOptional

deposit_countintegerOptional

Number of deposits

Example: 2

exited_validators_eth_balancestringOptional

Total ETH balance of exited validators on the consensus layer (as reported by the Oracle) in Wei

Example: 128000000000000000000

exiting_validators_eth_balancestringOptional

Total ETH balance of exiting validators on the consensus layer (as reported by the Oracle) in Wei

Example: 128000000000000000000

funded_validator_countintegerOptional

Count of funded validators

Example: 102

funded_valitor_countintegerOptional

Previous typo made, keeping for backwards compatibility

Example: 102

pending_validator_countintegerOptional

Count of funded validators and pending activation on the consensus layer (as reported by the Oracle)

Example: 2

pending_validators_eth_balancestringOptional

Total ETH balance of pending validators in GWei

Example: 64000000000000000000

rebalance_deposit_to_redeem_modebooleanOptionalExample: true

skimmed_validators_eth_balancestringOptional

Total ETH balance of skimmed withdrawals (as reported by the Oracle) in Wei

Example: 128000000000000000000

slashing_containment_modebooleanOptionalExample: false

stopped_validator_countintegerOptional

Count of stopped LC validators on the consensus layer (as reported by the Oracle)

Example: 42

total_eth_balancestringOptional

Total ETH balance managed by the River protocol in GWei

Example: 3200000000000000000000

total_eth_depositedstringOptional

Total ETH deposited

Example: 3200000000000000000000

total_supplystringOptional

Total LsETH supply

Example: 3200000000000000000000

total_validator_countintegerOptional

Count of all LC validators found on the consensus layer (as reported by the Oracle)

Example: 100

400

Bad Request

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

401

Unauthorized

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

403

Forbidden

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

500

Internal error

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

get

/eth/v0/status/{block_number}

List platform fees

get

List all platform fees for a given date

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

datestringRequired

Date filter by year, month or day (eg. 2023, 2023-12, 2023-12-31). Note: times are UTC

Query parameters

unitstringOptional

Display LsETH values in units of wei or ether. If not present, LsETH is set by default.

page_sizeintegerOptional

Number of oracle reports per page (1-1000, default 100)

next_cursorstringOptional

Cursor returned from previous page

Responses

200

application/json

conversion_ratenumberOptionalExample: 1.012345

dao_fees_lsethnumberOptionalExample: 0.00001234567

dao_fees_ratenumberOptionalExample: 0.0015

datestringOptionalExample: 2023-01-02T03:04:05Z

gross_fee_lsethnumberOptionalExample: 0.0001234

operator_fees_lsethnumberOptionalExample: 0.000123456789

operator_fees_ratenumberOptionalExample: 0.0035

oracle_reportstringOptionalExample: f071c15d86fd9ae82f62bb4bb04963f14e04045bbcac8b5439984733207821bc000000ef

org_idstringOptionalExample: org_example1234

fees_lsethnumberOptionalExample: 0.0001234567

fees_ratenumberOptionalExample: 0.097

adjusted_total_net_outflows_fees_lsethnumberOptionalExample: 0.0001234567

adjusted_total_net_outflows_lsethnumberOptionalExample: 0.0001234567

adjusted_total_net_outflows_transfers_lsethnumberOptionalExample: 0.0001234567

fees_paid_lsethnumberOptionalExample: 0.0001234567

off_platform_attributable_fees_lsethnumberOptionalExample: 0.0001234567

off_platform_balance_lsethnumberOptionalExample: 0.0001234567

off_platform_fees_lsethnumberOptionalExample: 0.0001234567

off_platform_gross_fee_lsethnumberOptionalExample: 0.0001234567

outflow_rationumberOptionalExample: 0.0001234567

total_burns_lsethnumberOptionalExample: 32.1234

total_mints_lsethnumberOptionalExample: 32.1234

total_net_outflows_lsethnumberOptionalExample: 0.0001234567

total_on_platform_lsethnumberOptionalExample: 0.0001234567

total_outflows_lsethnumberOptionalExample: 0.0001234567

total_platform_transfers_in_lsethnumberOptionalExample: 0.0001234567

total_platform_transfers_out_lsethnumberOptionalExample: 0.0001234567

on_platform_attributable_fees_lsethnumberOptionalExample: 0.0001234567

on_platform_fees_lsethnumberOptionalExample: 0.0001234567

on_platform_lsethnumberOptionalExample: 120520123.456789

on_platform_rationumberOptionalExample: 0.0001234567

total_balance_lsethnumberOptionalExample: 0.0001234567

slashing_coverage_fees_lsethnumberOptionalExample: 0.0000012345678

slashing_coverage_fees_ratenumberOptionalExample: 0.003

tech_provider_fees_lsethnumberOptionalExample: 0.0000123456789

tech_provider_fees_ratenumberOptionalExample: 0.0035

total_eth_supplynumberOptionalExample: 120520123.456789

total_lseth_supplynumberOptionalExample: 120520123.456789

versionintegerOptionalExample: 3

block_timestringOptional

event_idinteger[]Optional

400

Bad Request

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

401

Unauthorized

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

403

Forbidden

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

500

Internal error

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

get

/eth/v0/platforms/{date}

List account rewards

post

List rewards by account for a specific date

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

accountsstring[]OptionalExample: ["bb3e6114-af15-43a6-9b36-a5ec011d9d95"]

datestringOptionalExample: 2024-04-11

unitstringOptionalExample: lseth

Responses

200

application/json

account_idstringOptionalExample: bb3e6114-af15-43a6-9b36-a5ec011d9d95

datestringOptionalExample: 2024-04-11

balance_lsethnumberOptionalExample: 0.3827486422527215

rewards_ethnumberOptionalExample: 0.00003930554936445

account_idstringOptionalExample: ab3e5114-af15-45b8-9c43-a5ec011d9d95

addressstringOptionalExample: 0x30e2a735D692fC28CD31C28F1A8259b4790f9A23

avg_srr_histnumberOptionalExample: 0.00534633387

balance_lsethnumberOptionalExample: 0.3827486422527215

burns_lsethnumberOptionalExample: 0.1

conversion_ratenumberOptionalExample: 1.037253225665527

dao_fees_ethnumberOptionalExample: 4.25550536674e-7

datestringOptionalExample: 2024-04-11

fees_ethnumberOptionalExample: 0.000006719219000121

gross_fees_ethnumberOptionalExample: 0.000006264174837104

gross_protocol_fee_ratenumberOptionalExample: 0.000006264174837104

gross_rewards_ethnumberOptionalExample: 0.000006264174837104

mints_lsethnumberOptionalExample: 0.48208860235174045

operator_fees_ethnumberOptionalExample: 0.000006264174837104

oracle_reportstringOptionalExample: 68bbc70ba87b9467831cc3ff56fc114f3659ba9e646042007d1d54f6b95f267d00000164

org_idstringOptionalExample: org_aDL0aCAXyWYgHQ4W

platform_fees_at_discount_rate_ethnumberOptionalExample: 0.000006264174837104

platform_fees_ethnumberOptionalExample: 0.00000519619602676

previous_conversion_ratenumberOptionalExample: 1.0371537463463845

provider_fees_ethnumberOptionalExample: 1.56781776669e-7

rebate_ethnumberOptionalExample: 0.000006264174837104

rebate_lsethnumberOptionalExample: 0.000006264174837104

rewards_ethnumberOptionalExample: 0.000038075574334017

slashing_fees_ethnumberOptionalExample: 1.34384380002e-7

target_fee_ratenumberOptionalExample: 0.08

total_burns_lsethnumberOptionalExample: 0.109

total_dao_fees_ethnumberOptionalExample: 4.39297316428e-7

total_fees_ethnumberOptionalExample: 0.000006936273417258

total_gross_fees_ethnumberOptionalExample: 0.000006264174837104

total_gross_rewards_ethnumberOptionalExample: 0.000006264174837104

total_mints_lsethnumberOptionalExample: 0.49174864225272147

total_operator_fees_ethnumberOptionalExample: 0.000006264174837104

total_platform_fees_at_discount_rate_ethnumberOptionalExample: 0.000006264174837104

total_platform_fees_ethnumberOptionalExample: 0.000005364051442679

total_provider_fees_ethnumberOptionalExample: 1.61846379739e-7

total_rebate_ethnumberOptionalExample: 0.000006264174837104

total_rebate_lsethnumberOptionalExample: 0.000006264174837104

total_rewards_ethnumberOptionalExample: 0.00003930554936445

total_slashing_fees_ethnumberOptionalExample: 1.38725468346e-7

401

Unauthorized

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

403

Forbidden

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

500

Internal error

application/json

messagestringOptionalExample: error message

statusstringOptionalExample: IR001

post

/eth/v0/rewards/accounts

List wallet rewards

post

Get rewards for a list of wallets on a specific date

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

addressesstring[]OptionalExample: ["0x5d811a9d059dDAB0C18B385ad3b752f734f011cB"]

datestringOptionalExample: 2024-04-11

unitstringOptionalExample: eth