1 of 8

APIs

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

API-Reference

Authentication API Ethereum Data API Allowlisting API Redemption API Reporting API Discounting API

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

curl -X 'POST' \
  'https://auth.staging.alluvial.finance/' \
  -H 'content-type: application/json' \
  -d '{
    "audience": "https://api.staging.alluvial.finance",
  "grant_type": "client_credentials",
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>"
}'

Response

{
  "access_token": "eyJz93a...k4laUZw",
  "scope": "read:eth-oracle...read:eth-operators",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Production

Request

curl -X 'POST' \
  'https://auth.alluvial.finance/oauth/token' \
  -H 'content-type: application/json' \
  -d '{
    "audience": "https://api.alluvial.finance",
  "grant_type": "client_credentials",
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>"
}'

Response

{
  "access_token": "eyJz93a...k4laUWw",
  "scope": "read:eth-oracle...read:eth-operators",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Ethereum Data API

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

Allowlisting API

Platform

Platform Account Operations

Platform Wallet Operations

Platform Account Wallet Operations

List all the platform account wallets

get

List all wallets for a platform account

Authorizations

Path parameters

idOrKeystringrequired

Account ID or Key of the account

Query parameters

allowlistbooleanoptional

Enable to only return allowlisted wallets

on_platformbooleanoptional

Enable to only return wallets on_platform

offsetintegeroptional

Offset for pagination

limitintegeroptional

Limit for pagination

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets' \
  --header 'Authorization: Bearer JWT'

200

400

401

403

500

[
  {
    "account_id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "allowlisted": true,
    "created_at": "2024-01-25T13:07:50.335845Z",
    "id": "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d",
    "on_platform": true,
    "status": "ALLOWLISTED",
    "type": "ETH"
  }
]

Remove wallet on platform

patch

Remove wallet from a given wallet from either the on_platform, the allowlisted, or both.

Authorizations

Path parameters

idOrKeystringrequired

Account ID or Key of the account to remove wallet from

idOrAddressstringrequired

Wallet ID or Address of the wallet to be removed

Query parameters

allowlistbooleanoptional

Enable to remove wallet from the allowlist

on_platformbooleanoptional

Enable to remove wallet on_platform

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets/{idOrAddress}/remove' \
  --header 'Authorization: Bearer JWT'

200

400

401

403

404

500

{
  "account_id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "created_at": "2024-01-25T13:07:50.335845Z",
  "id": "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d",
  "status": "REMOVED",
  "type": "ETH"
}

Pause wallet

patch

Set wallet's status to PAUSED.

Once a wallet's status has been set to PAUSED:

If the wallet was allowlisted, it will be unable to stake nor redeem.
Wallet will be able to transfer LsETH normally.

Authorizations

Path parameters

idOrKeystringrequired

Depositor ID or Key of the depositor to pause wallet from

idOrAddressstringrequired

Wallet ID or Address of the wallet to be paused

Query parameters

allowlistbooleanoptional

Enable to pause wallet from the allowlist

on_platformbooleanoptional

Enable to pause wallet on_platform

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets/{idOrAddress}/pause' \
  --header 'Authorization: Bearer JWT'

200

400

401

403

404

409

500

{
  "account_id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "allowlisted": true,
  "created_at": "2024-01-25T13:07:50.335845Z",
  "id": "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d",
  "on_platform": true,
  "status": "PAUSED | ALLOWLISTED",
  "type": "ETH"
}

Reactivate wallet

patch

Set a PAUSED wallet's status to ACTIVE.

This will enable the wallet to stake and redeem again.

This action can only be performed under these conditions:

The wallet has PAUSED status - DENIED or REMOVED wallets cannot be reactivated.
A wallet can only be reactivated if the associated account has an ACTIVE status.

Authorizations

Path parameters

idOrKeystringrequired

Depositor ID or Key of the depositor to reactivate wallet from

idOrAddressstringrequired

Wallet ID or Address of the wallet to be reactivated

Query parameters

allowlistbooleanoptional

Enable to reactivate wallet from the allowlist

on_platformbooleanoptional

Enable to reactivate wallet on_platform

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets/{idOrAddress}/reactivate' \
  --header 'Authorization: Bearer JWT'

200

400

401

403

404

409

500

{
  "account_id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "allowlisted": true,
  "created_at": "2024-01-25T13:07:50.335845Z",
  "id": "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d",
  "on_platform": true,
  "status": "PAUSED | ALLOWLISTED",
  "type": "ETH"
}

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

List the redeem requests

get

List the redeem requests for one or multiple owners (addresses)

Authorizations

Query parameters

ownerstringrequired

The address or addresses to query, separated by commas

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.alluvial.finance/eth/v0/redeems?owner=text' \
  --header 'Authorization: Bearer JWT'

200

400

401

403

500

[
  {
    "claimable_amount_lseth": 1,
    "claimed_amount_eth": 1,
    "claimed_amount_lseth": 1,
    "height": 1,
    "id": 1,
    "max_redeemable_amount_eth": 1,
    "owner": [
      1
    ],
    "requested_at": 1,
    "status_claim": "NOT_CLAIMED",
    "status_satisfaction": "NOT_CLAIMED",
    "timestamp": "text",
    "total_amount_lseth": 1,
    "withdrawal_event_id": 1
  }
]

List a redeem request by id

get

List a redeem request by the request id, obtained from /eth/v0/redeems

Authorizations

Path parameters

idxintegerrequired

The redeem request id to query

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.alluvial.finance/eth/v0/redeems/{idx}' \
  --header 'Authorization: Bearer JWT'

200

400

401

404

500

{
  "claimable_amount_lseth": 1,
  "claimed_amount_eth": 1,
  "claimed_amount_lseth": 1,
  "height": 1,
  "id": 1,
  "max_redeemable_amount_eth": 1,
  "owner": [
    1
  ],
  "requested_at": 1,
  "status_claim": "NOT_CLAIMED",
  "status_satisfaction": "NOT_CLAIMED",
  "timestamp": "text",
  "total_amount_lseth": 1,
  "withdrawal_event_id": 1
}

Get a redeem request time projection

get

Get a redeem request time projection for becoming redeemable

Authorizations

Path parameters

idxintegerrequired

The redeem request id to query

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.alluvial.finance/eth/v0/redeems/{idx}/projection' \
  --header 'Authorization: Bearer JWT'

200

400

401

404

500

{
  "projected_redeemable_at": "text"
}

List the redeem manager

get

List the withdrawal event height and redeem request height

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.alluvial.finance/eth/v0/redeems_info' \
  --header 'Authorization: Bearer JWT'

200

404

500

{
  "total_amount_redeem_queue_lseth": 1,
  "total_amount_withdrawal_stack_lseth": 1
}

Get the redeem manager time projection

get

Get the redeem manager time projection for being fulfilled

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.alluvial.finance/eth/v0/redeems_info/projection' \
  --header 'Authorization: Bearer JWT'

200

400

401

404

{
  "projected_fulfilled_at": "text"
}

Reporting API

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

APIs

API-Reference

Authentication API

Staging

Production

Ethereum Data API

Allowlisting API

Platform

Platform Account Operations

Platform Wallet Operations

Platform Account Wallet Operations

List all the platform account wallets

Remove wallet on platform

Pause wallet

Reactivate wallet

Redemption API

List the redeem requests

List a redeem request by id

Get a redeem request time projection

List the redeem manager

Get the redeem manager time projection

Reporting API

Public endpoints (no authentication required)

Private endpoints ( authentication required)

Reward Summary

Discounting API

Public APIs