Onboarding API

Platform

Platform Account Operations

Create a platform account

Create a platform account with an ACTIVE status.

WARNING Integrators should make sure that the depositor has gone through an effective KYC/KYB process and is deemed within appetite to stake their ETH through the Liquid Collective.

When creating the depositor an integrator should supply a non-empty, unique identifying key (it can typically be an internal user identifier).

As long as a depositor remains in ACTIVE status, it is possible to attach wallets to it that will automatically be submitted to the protocol on-chain allowlist.

POSThttps://api.alluvial.finance/v0/platform/accounts

Body

application/json

Account, requires external 'key' to create

keystring

Unique identifier of the account (supplied by the client)

Example: "depositor_example"

Response

201400401403500

Account has been created

Body

application/json

created_atstring

Time the account was created

Example: "2024-01-24T13:07:50.335845Z"

idstring

Identifier of the account (generated server side)

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

keystring

Unique key identifying the account (supplied by the client when creating the account)

Example: "depositor_example"

org_idstring

Organization identifier the account belongs to

Example: "org_28CLGCvsdG7TlOHf"

statusstring

Status of the account (managed by the integrator)

Example: "ACTIVE"

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "created_at": "2024-01-24T13:07:50.335845Z",
  "id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "key": "depositor_example",
  "org_id": "org_28CLGCvsdG7TlOHf",
  "status": "ACTIVE"
}

List platform accounts

List platform accounts

GEThttps://api.alluvial.finance/v0/platform/accounts

Response

200401403500

OK

Body

application/json

created_atstring

Time the account was created

Example: "2024-01-24T13:07:50.335845Z"

idstring

Identifier of the account (generated server side)

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

keystring

Unique key identifying the account (supplied by the client when creating the account)

Example: "depositor_example"

org_idstring

Organization identifier the account belongs to

Example: "org_28CLGCvsdG7TlOHf"

statusstring

Status of the account (managed by the integrator)

Example: "ACTIVE | PAUSED | REMOVED | DENIED"

walletsarray of Wallet (object)

Wallets attached to the account

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "created_at": "2024-01-24T13:07:50.335845Z",
    "id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
    "key": "depositor_example",
    "org_id": "org_28CLGCvsdG7TlOHf",
    "status": "ACTIVE | PAUSED | REMOVED | DENIED",
    "wallets": [
      {
        "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"
      }
    ]
  }
]

Get platform account

Get platform account

GEThttps://api.alluvial.finance/v0/platform/accounts/{idOrKey}

Path parameters

idOrKey*string

Account ID or Key of the platform account

Response

200401403404500

OK

Body

application/json

created_atstring

Time the account was created

Example: "2024-01-24T13:07:50.335845Z"

idstring

Identifier of the account (generated server side)

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

keystring

Unique key identifying the account (supplied by the client when creating the account)

Example: "depositor_example"

org_idstring

Organization identifier the account belongs to

Example: "org_28CLGCvsdG7TlOHf"

statusstring

Status of the account (managed by the integrator)

Example: "ACTIVE | PAUSED | REMOVED | DENIED"

walletsarray of Wallet (object)

Wallets attached to the account

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts/{idOrKey}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "created_at": "2024-01-24T13:07:50.335845Z",
  "id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "key": "depositor_example",
  "org_id": "org_28CLGCvsdG7TlOHf",
  "status": "ACTIVE | PAUSED | REMOVED | DENIED",
  "wallets": [
    {
      "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 a platform account

Set account's status to REMOVED.

Integrators can call this method for their inactive users to be removed from the liquid staking protocol(s) allowlist.

Once account's status has been set to REMOVED:

• It is no longer possible to attach new wallets to the account
• Alluvial will remove any previously attached wallets from protocol's on-chain allowlist

Removing a wallet from the protocol allowlist results in disabling the ability to stake or redeem ETH.

Note that removing a wallet from the allowlist is an asynchronous process that can take some time.

PATCHhttps://api.alluvial.finance/v0/platform/accounts/{idOrKey}/remove

Path parameters

idOrKey*string

Account ID or Key of the account to remove

Response

200400401403404500

OK

Body

application/json

created_atstring

Time the account was created

Example: "2024-01-24T13:07:50.335845Z"

idstring

Identifier of the account (generated server side)

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

keystring

Unique key identifying the account (supplied by the client when creating the account)

Example: "depositor_example"

org_idstring

Organization identifier the account belongs to

Example: "org_28CLGCvsdG7TlOHf"

statusstring

Status of the account (managed by the integrator)

Example: "REMOVED"

walletsarray of WalletRemove (object)

Wallets attached to the account

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/remove', {
    method: 'PATCH',
    headers: {},
});
const data = await response.json();

Response

{
  "created_at": "2024-01-24T13:07:50.335845Z",
  "id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "key": "depositor_example",
  "org_id": "org_28CLGCvsdG7TlOHf",
  "status": "REMOVED",
  "wallets": [
    {
      "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"
    }
  ]
}

Deny a platform account

Set account's status to DENIED.

Platform should call this method when they wish to invalidate the KYC status of one of their accounts.

Once account status has been set to DENIED:

• it is no longer possible to attach new wallets to the depositor
• Alluvial will deny any previously attached wallets on the protocol's allowlist

WARNING Denying a wallet on the protocol's allowlist results in disabling the wallet ability to perform any protocol operations including depositing, redeeming and transferring of LsETH.

Note that removing a wallet from the allowlist is an asynchronous process but Alluvial will aim at getting the denial submitted on-chain as rapidly as possible (ideally in less than a minute).

PATCHhttps://api.alluvial.finance/v0/platform/accounts/{idOrKey}/deny

Path parameters

idOrKey*string

Account ID or Key of the account to deny

Response

200400401403404500

OK

Body

application/json

created_atstring

Time the account was created

Example: "2024-01-24T13:07:50.335845Z"

idstring

Identifier of the account (generated server side)

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

keystring

Unique key identifying the account (supplied by the client when creating the account)

Example: "depositor_example"

org_idstring

Organization identifier the account belongs to

Example: "org_28CLGCvsdG7TlOHf"

statusstring

Status of the account (managed by the integrator)

Example: "DENIED"

walletsarray of Wallet (object)

Wallets attached to the account

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/deny', {
    method: 'PATCH',
    headers: {},
});
const data = await response.json();

Response

{
  "created_at": "2024-01-24T13:07:50.335845Z",
  "id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "key": "depositor_example",
  "org_id": "org_28CLGCvsdG7TlOHf",
  "status": "DENIED",
  "wallets": [
    {
      "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"
    }
  ]
}

Pause a platform account

Set account's status to PAUSED.

Once an account's status has been set to PAUSED:

• If the account has allowlisted wallet they will be unable to stake nor redeem.
• Wallets will be able to transfer LsETH normally.
• Accounts won't be able to add new wallets.

PATCHhttps://api.alluvial.finance/v0/platform/accounts/{idOrKey}/pause

Path parameters

idOrKey*string

Account ID or Key of the account to remove

Response

200400401403404500

OK

Body

application/json

created_atstring

Time the account was created

Example: "2024-01-24T13:07:50.335845Z"

idstring

Identifier of the account (generated server side)

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

keystring

Unique key identifying the account (supplied by the client when creating the account)

Example: "depositor_example"

org_idstring

Organization identifier the account belongs to

Example: "org_28CLGCvsdG7TlOHf"

statusstring

Status of the account (managed by the integrator)

Example: "PAUSED"

walletsarray of Wallet (object)

Wallets attached to the account

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/pause', {
    method: 'PATCH',
    headers: {},
});
const data = await response.json();

Response

{
  "created_at": "2024-01-24T13:07:50.335845Z",
  "id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "key": "depositor_example",
  "org_id": "org_28CLGCvsdG7TlOHf",
  "status": "PAUSED",
  "wallets": [
    {
      "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"
    }
  ]
}

Reactivate a platform account

Set a PAUSED account's status to ACTIVE.

This will enable the account to stake and redeem again (if the account has allowlisted wallets), and enable you to add more wallets to the account.

This is only possible for PAUSED accounts - DENIED or REMOVED accounts cannot be reactivated.

PATCHhttps://api.alluvial.finance/v0/platform/accounts/{idOrKey}/reactivate

Path parameters

idOrKey*string

Account ID or Key of the account to reactivate

Response

200400401403404500

OK

Body

application/json

created_atstring

Time the account was created

Example: "2024-01-24T13:07:50.335845Z"

idstring

Identifier of the account (generated server side)

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

keystring

Unique key identifying the account (supplied by the client when creating the account)

Example: "depositor_example"

org_idstring

Organization identifier the account belongs to

Example: "org_28CLGCvsdG7TlOHf"

statusstring

Status of the account (managed by the integrator)

Example: "ACTIVE"

walletsarray of Wallet (object)

Wallets attached to the account

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/reactivate', {
    method: 'PATCH',
    headers: {},
});
const data = await response.json();

Response

{
  "created_at": "2024-01-24T13:07:50.335845Z",
  "id": "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16",
  "key": "depositor_example",
  "org_id": "org_28CLGCvsdG7TlOHf",
  "status": "ACTIVE",
  "wallets": [
    {
      "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"
    }
  ]
}

Platform Wallet Operations

Get platform wallet

Get platform wallet

GEThttps://api.alluvial.finance/v0/platform/wallets/{idOrAddress}

Path parameters

idOrAddress*string

Wallet ID or Address of the wallet (address in hex format prefixed with 0x)

Response

200400401403404500

OK

Body

application/json

account_idstring

The account ID of the wallet

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

addressstring

Wallet address in hexadecimal format with 0x prefix

Example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

allowlistedboolean

Whether the wallet is allowlisted

Example: true

created_atstring

Time the wallet was created

Example: "2024-01-25T13:07:50.335845Z"

idstring

Our UUID for this wallet

Example: "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d"

on_platformboolean

Whether the wallet is on platform

Example: true

statusall of

Status of the submission of the wallet account on-chain

Example: "ALLOWLISTED"

typestring

The type of wallet - chain or protocol it exists on

Example: "ETH"

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/wallets/{idOrAddress}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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"
}

List platform wallets

List platform wallets

GEThttps://api.alluvial.finance/v0/platform/wallets

Query parameters

Response

200400401403500

OK

Body

application/json

account_idstring

The account ID of the wallet

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

addressstring

Wallet address in hexadecimal format with 0x prefix

Example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

allowlistedboolean

Whether the wallet is allowlisted

Example: true

created_atstring

Time the wallet was created

Example: "2024-01-25T13:07:50.335845Z"

idstring

Our UUID for this wallet

Example: "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d"

on_platformboolean

Whether the wallet is on platform

Example: true

statusall of

Status of the submission of the wallet account on-chain

Example: "ALLOWLISTED"

typestring

The type of wallet - chain or protocol it exists on

Example: "ETH"

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/wallets', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "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"
  }
]

Platform Account Wallet Operations

Add wallet on platform

Create a wallet attached to an account

If the account is in ACTIVE status and if the wallet's has the allowlisted property set to true Alluvial will add the wallet address to the protocol on-chain allowlist.

Adding a wallet to the protocol allowlist results in enabling the wallet to proceed to deposit and redeem ETH on the protocol.

Note that submitting the wallet to the on-chain allowlist is an asynchronous process that can take some time. The onboarding allows to check the submission status by getting the wallet.

Important Notes:

• Alluvial will never ask for private keys of the wallets**
• You will only be able to create allowlisted wallets if your organization is configured to do so.
• If your organization is able to allowlist wallets, it method will do so by default.

POSThttps://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets

Path parameters

idOrKey*string

Account ID or Key of the account to add wallets to

Body

application/json

Wallet to create

addressstring

Wallet address in hexadecimal format with 0x prefix

Example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

allowlistedboolean

Opt out of wallet being added to the OnPlatform list

Example: true

typestring

The type of wallet - chain or protocol it exists on

Example: "ETH"

Response

200400401403500

OK

Body

application/json

account_idstring

The account ID of the wallet

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

addressstring

Wallet address in hexadecimal format with 0x prefix

Example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

allowlistedboolean

Whether the wallet is allowlisted

Example: true

created_atstring

Time the wallet was created

Example: "2024-01-25T13:07:50.335845Z"

idstring

Our UUID for this wallet

Example: "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d"

on_platformboolean

Whether the wallet is on platform

Example: true

statusall of

Status of the submission of the wallet account on-chain

Example: "ALLOWLISTED"

typestring

The type of wallet - chain or protocol it exists on

Example: "ETH"

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "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"
}

List all the platform account wallets

List all wallets for a platform account

GEThttps://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets

Path parameters

idOrKey*string

Account ID or Key of the account

Query parameters

Response

200400401403500

OK

Body

application/json

account_idstring

The account ID of the wallet

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

addressstring

Wallet address in hexadecimal format with 0x prefix

Example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

allowlistedboolean

Whether the wallet is allowlisted

Example: true

created_atstring

Time the wallet was created

Example: "2024-01-25T13:07:50.335845Z"

idstring

Our UUID for this wallet

Example: "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d"

on_platformboolean

Whether the wallet is on platform

Example: true

statusall of

Status of the submission of the wallet account on-chain

Example: "ALLOWLISTED"

typestring

The type of wallet - chain or protocol it exists on

Example: "ETH"

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "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

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

PATCHhttps://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets/{idOrAddress}/remove

Path parameters

idOrKey*string

Account ID or Key of the account to remove wallet from

idOrAddress*string

Wallet ID or Address of the wallet to be removed

Query parameters

Response

200400401403404500

OK

Body

application/json

account_idstring

The account ID of the wallet

Example: "ac0d0cdf-92bc-4cbe-a180-a2efb2387d16"

addressstring

Wallet address in hexadecimal format with 0x prefix

Example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

created_atstring

Time the wallet was created

Example: "2024-01-25T13:07:50.335845Z"

idstring

Our UUID for this wallet

Example: "dd8eefc8-0cc4-4a27-adc0-e1ebebed598d"

statusall of

Status of the submission of the wallet account on-chain

Example: "REMOVED"

typestring

The type of wallet - chain or protocol it exists on

Example: "ETH"

Request

JavaScriptCurl

const response = await fetch('https://api.alluvial.finance/v0/platform/accounts/{idOrKey}/wallets/{idOrAddress}/remove', {
    method: 'PATCH',
    headers: {},
});
const data = await response.json();

Response

{
  "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"
}