Public APIs

Alluvial exposes several non-authenticated APIs to support DApps

List latest high-level protocol info

get

List latest available high-level protocol

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

unitstringOptional

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

Responses

200

OK

application/json

a_srr_7dnumberOptionalExample: 3.95

conversion_ratenumberOptionalExample: 1.012345

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

gross_fee_lsethnumberOptionalExample: 0.1851

gross_fee_ratenumberOptionalExample: 0.15

oracle_reportstringOptionalExample: f071c15d86fd9ae82f62bb4bb04963f14e04045bbcac8b5439984733207821bc000000ef

protocol_service_fee_ratenumberOptionalExample: 0.11

rewards_ethnumberOptionalExample: 1.234

total_eth_stakednumberOptionalExample: 122007944.381

total_lseth_supplynumberOptionalExample: 120520123.456789

total_protocol_active_keys_countintegerOptionalExample: 76

total_protocol_burns_lsethnumberOptionalExample: 32

total_protocol_mints_lsethnumberOptionalExample: 32

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal error

application/json

get

/eth/v0/protocol

HTTPcURLJavaScriptPython

GET /eth/v0/protocol HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "a_srr_7d": 3.95,
  "conversion_rate": 1.012345,
  "date": "2023-01-02T03:04:05Z",
  "gross_fee_lseth": 0.1851,
  "gross_fee_rate": 0.15,
  "oracle_report": "f071c15d86fd9ae82f62bb4bb04963f14e04045bbcac8b5439984733207821bc000000ef",
  "protocol_service_fee_rate": 0.11,
  "rewards_eth": 1.234,
  "total_eth_staked": 122007944.381,
  "total_lseth_supply": 120520123.456789,
  "total_protocol_active_keys_count": 76,
  "total_protocol_burns_lseth": 32,
  "total_protocol_mints_lseth": 32
}

List high-level protocol info

get

List high-level protocol info for a given date

Authorizations

bearer

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.

Responses

200

OK

application/json

a_srr_7dnumberOptionalExample: 3.95

conversion_ratenumberOptionalExample: 1.012345

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

gross_fee_lsethnumberOptionalExample: 0.1851

gross_fee_ratenumberOptionalExample: 0.15

oracle_reportstringOptionalExample: f071c15d86fd9ae82f62bb4bb04963f14e04045bbcac8b5439984733207821bc000000ef

protocol_service_fee_ratenumberOptionalExample: 0.11

rewards_ethnumberOptionalExample: 1.234

total_eth_stakednumberOptionalExample: 122007944.381

total_lseth_supplynumberOptionalExample: 120520123.456789

total_protocol_active_keys_countintegerOptionalExample: 76

total_protocol_burns_lsethnumberOptionalExample: 32

total_protocol_mints_lsethnumberOptionalExample: 32

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal error

application/json

get

/eth/v0/protocol/{date}

HTTPcURLJavaScriptPython

GET /eth/v0/protocol/{date} HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "a_srr_7d": 3.95,
    "conversion_rate": 1.012345,
    "date": "2023-01-02T03:04:05Z",
    "gross_fee_lseth": 0.1851,
    "gross_fee_rate": 0.15,
    "oracle_report": "f071c15d86fd9ae82f62bb4bb04963f14e04045bbcac8b5439984733207821bc000000ef",
    "protocol_service_fee_rate": 0.11,
    "rewards_eth": 1.234,
    "total_eth_staked": 122007944.381,
    "total_lseth_supply": 120520123.456789,
    "total_protocol_active_keys_count": 76,
    "total_protocol_burns_lseth": 32,
    "total_protocol_mints_lseth": 32
  }
]

List wallet rewards public summary

get

List rewards for a wallet with daily reports (public info) for a specific time period.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

addressstringRequired

Wallet address

Query parameters

fromstringOptional

Start date (default: 1 month ago)

tostringOptional

End date (default: current time)

unitstringOptional

Currency unit

csvstringOptional

Export to CSV

page_sizeintegerOptional

Page size (default: 100)

next_cursorstringOptional

Next cursor (default: empty)

Responses

200

OK

application/json

400

Bad request

application/json

404

Not found

application/json

500

Internal error

application/json

get

/eth/v0/wallet/{address}/rewards

HTTPcURLJavaScriptPython

GET /eth/v0/wallet/{address}/rewards HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "address": "0x30e2a735D692fC28CD31C28F1A8259b4790f9A23",
    "daily_reports": [
      {
        "address": "0x30e2a735D692fC28CD31C28F1A8259b4790f9A23",
        "avg_srr_hist": 0.00534633387,
        "balance_lseth": 0.3827486422527215,
        "burns_lseth": 0.1,
        "conversion_rate": 1.037253225665527,
        "date": "2024-04-11",
        "fees_eth": 0.000006719219000121,
        "mints_lseth": 0.48208860235174045,
        "oracle_report": "68bbc70ba87b9467831cc3ff56fc114f3659ba9e646042007d1d54f6b95f267d00000164",
        "previous_conversion_rate": 1.0371537463463845,
        "rewards_eth": 0.000038075574334017,
        "total_burns_lseth": 0.109,
        "total_fees_eth": 0.000006936273417258,
        "total_mints_lseth": 0.49174864225272147,
        "total_rewards_eth": 0.00003930554936445
      }
    ],
    "end_conversion_rate": 1.0454865181649966,
    "from": "2024-04-01",
    "start_conversion_rate": 1.006282340620787,
    "to": "2024-04-30",
    "total_burns_lseth": 0.109,
    "total_fees_eth": 0.000006936273417258,
    "total_mints_lseth": 0.49174864225272147,
    "total_rewards_eth": 0.00003930554936445
  },
  "metadata": {
    "next_cursor": null
  }
}

Get wallet status

get

Provides status information of the wallet (ex. ALLOWLISTED, SUBMITTED, etc...)

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

addressstringRequired

Wallet address

Responses

200

OK

application/json

allowlistedbooleanOptionalExample: true

statusstringOptionalExample: ALLOWLISTED| PAUSED | DENIED

400

Bad request

application/json

404

Not found

application/json

500

Internal error

application/json

get

/eth/v0/wallet/{address}/status

HTTPcURLJavaScriptPython

GET /eth/v0/wallet/{address}/status HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "allowlisted": true,
  "status": "ALLOWLISTED| PAUSED | DENIED"
}

List wallet transactions

get

List wallet transactions for a given time period and wallet address

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

addressstringRequired

Wallet address

Query parameters

fromstringOptional

Start date (default: 1 year ago)

tostringOptional

End date (default: current time)

csvstringOptional

Output as CSV

page_sizestringOptional

Page size (default: 100)

next_cursorstringOptional

Next cursor

Responses

200

OK

application/json

400

Bad request

application/json

404

Not found

application/json

500

Internal error

application/json

get

/eth/v0/wallet/{address}/transactions

HTTPcURLJavaScriptPython

GET /eth/v0/wallet/{address}/transactions HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "amount_eth": 10,
      "amount_lseth": 9.5,
      "conversion_rate": 0.96,
      "date": "2024-06-21",
      "finalized": true,
      "transaction_hash": "0x5E9E16C6DEB4022399E4FCD387BCB59AC5855762",
      "transaction_type": "Deposit"
    }
  ],
  "metadata": {
    "next_cursor": {
      "amount": 1,
      "blockNumber": 1,
      "date": "text",
      "eventID": [
        1
      ],
      "finalized": true,
      "newTotalEthSupply": 1,
      "newTotalSupply": 1,
      "transactionHash": [
        1
      ],
      "transactionType": "Deposit"
    }
  }
}

List the redeem requests

get

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

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

ownerstringRequired

The address or addresses to query, separated by commas

Responses

200

OK

application/json

claimable_amount_lsethnumberOptional

The possible amount available to claim in LsETH

claimed_amount_ethnumberOptional

The amount already claimed in ETH

claimed_amount_lsethnumberOptional

The amount already claimed in LsETH

heightnumberOptional

The height is the cumulative sum of all the sizes of preceding redeem requests

idintegerOptional

The ID of the redeem request

max_redeemable_amount_ethnumberOptional

The maximum amount of ETH redeemable by this request

ownerinteger[]Optional

The owner of the redeem request

requested_atintegerOptional

Block time

status_claimall ofOptional

The status of the claimed request

string · enumOptionalPossible values:

status_satisfactionall ofOptional

The status of the satisfaction (withdrawal stack matching the redeem queue)

string · enumOptionalPossible values:

timestampstringOptional

Timestamp

total_amount_lsethnumberOptional

The amount of the redeem request in LsETH

withdrawal_event_idintegerOptional

The withdrawal event ID needed to claim the redeem (or -1 when no withdrawals available)

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Error

application/json

get

/eth/v0/redeems

HTTPcURLJavaScriptPython

GET /eth/v0/redeems?owner=text HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Returns validator exit queue info

get

Returns validator exit queue info, inclding time estimates.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

OK

application/json

exit_time_hoursnumberOptional

mandatory_exit_delay_hoursnumberOptional

sweep_time_hoursnumberOptional

500

Internal error

application/json

get

/eth/v0/validators/queue

HTTPcURLJavaScriptPython

GET /eth/v0/validators/queue HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "exit_time_hours": 1,
  "mandatory_exit_delay_hours": 1,
  "sweep_time_hours": 1
}