Alluvial
  • 🚀Who is Alluvial?
  • 🗺️Guides
    • Mint and Redeem support
    • Secondary Interaction support
    • Reporting
    • Supplemental Guides
      • Architecture
      • Authentication
      • Redemptions
      • Staking
  • 📖APIs
    • Authentication API
    • Ethereum Data API
    • Allowlisting API
    • Redemption API
    • Reporting API
    • Discounting API
    • Public APIs
  • 🌎Third Party Integration Guides
    • Fireblocks
  • Changelog
Powered by GitBook
On this page

Was this helpful?

Export as PDF
  1. APIs

Reporting API

PreviousRedemption APINextDiscounting API

Last updated 4 months ago

Was this helpful?

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

📖

List latest high-level protocol info

get

List latest available high-level protocol

Authorizations
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
400
Bad Request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
500
Internal error
application/json
get
GET /eth/v0/protocol HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
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
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
400
Bad Request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
500
Internal error
application/json
get
GET /eth/v0/protocol/{date} HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
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 transactions

get

List wallet transactions for a given time period and wallet address

Authorizations
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
GET /eth/v0/wallet/{address}/transactions HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
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 platform fees

get

List all platform fees for a given date

Authorizations
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
400
Bad Request
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
500
Internal error
application/json
get
GET /eth/v0/platforms/{date} HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
Accept: */*

[
  {
    "conversion_rate": 1.012345,
    "dao_fees_lseth": 0.00001234567,
    "dao_fees_rate": 0.0015,
    "date": "2023-01-02T03:04:05Z",
    "gross_fee_lseth": 0.0001234,
    "operator_fees_lseth": 0.000123456789,
    "operator_fees_rate": 0.0035,
    "oracle_report": "f071c15d86fd9ae82f62bb4bb04963f14e04045bbcac8b5439984733207821bc000000ef",
    "org_id": "org_example1234",
    "platform": {
      "fees_lseth": 0.0001234567,
      "fees_rate": 0.097,
      "off_platform_rebate": {
        "adjusted_total_net_outflows_fees_lseth": 0.0001234567,
        "adjusted_total_net_outflows_lseth": 0.0001234567,
        "fees_paid_lseth": 0.0001234567,
        "off_platform_attributable_fees_lseth": 0.0001234567,
        "off_platform_balance_lseth": 0.0001234567,
        "off_platform_fees_lseth": 0.0001234567,
        "off_platform_gross_fee_lseth": 0.0001234567,
        "outflow_ratio": 0.0001234567,
        "total_burns_lseth": 32.1234,
        "total_mints_lseth": 32.1234,
        "total_net_outflows_lseth": 0.0001234567,
        "total_on_platform_lseth": 0.0001234567,
        "total_outflows_lseth": 0.0001234567
      },
      "on_platform_rebate": {
        "on_platform_attributable_fees_lseth": 0.0001234567,
        "on_platform_fees_lseth": 0.0001234567,
        "on_platform_lseth": 120520123.456789,
        "on_platform_ratio": 0.0001234567
      },
      "total_balance_lseth": 0.0001234567
    },
    "slashing_coverage_fees_lseth": 0.0000012345678,
    "slashing_coverage_fees_rate": 0.003,
    "tech_provider_fees_lseth": 0.0000123456789,
    "tech_provider_fees_rate": 0.0035,
    "total_eth_supply": 120520123.456789,
    "total_lseth_supply": 120520123.456789,
    "version": 3
  }
]

List operator fees

get

List platform operator fees for a given date

Authorizations
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
401
Unauthorized
application/json
403
Forbidden
application/json
500
Internal error
application/json
get
GET /eth/v0/operators/{date} HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
Accept: */*

[
  {
    "conversion_rate": 1.012345,
    "date": "2023-01-02T03:04:05Z",
    "operator_active_keys_count": 5,
    "operator_active_keys_ratio": 0.5,
    "operator_fees_lseth": 0.00006,
    "oracle_report": "f071c15d86fd9ae82f62bb4bb04963f14e04045bbcac8b5439984733207821bc000000ef",
    "org_id": "org_example1234",
    "total_active_keys_count": 10,
    "total_operator_fees_lseth": 0.00012,
    "version": 3
  }
]

List account rewards summary

get

Provides a summary of rewards with a breakdown of reward totals for each wallet within the account. NOTE: Daily breakdown for each wallet address within the account is NOT included in the response.

Authorizations
Path parameters
idOrKeystringRequired

Account ID

Query parameters
fromstringOptional

Start date (default: 1 month ago)

tostringOptional

End date (default: current time)

csvstringOptional

Export to CSV

unitstringOptional

Currency unit

Responses
200
OK
application/json
400
Bad request
application/json
404
Not found
application/json
500
Internal error
application/json
get
GET /eth/v0/rewards/accounts/{idOrKey}/summary HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
Accept: */*

{
  "data": {
    "account_id": "ab3e5114-af15-45b8-9c43-a5ec011d9d95",
    "end_conversion_rate": 1.0454865181649966,
    "from": "2024-04-01",
    "org_id": "org_aDs4aCACyWYgMQ4A",
    "start_conversion_rate": 1.006282340620787,
    "to": "2024-04-30",
    "wallets": [
      {
        "account_id": "ab3e5114-af15-45b8-9c43-a5ec011d9d95",
        "address": "0xF523F31Acf07Ff41D2616f9c1b73E762Ba8E5660",
        "daily_reports": [
          {
            "address": "0xF523F31Acf07Ff41D2616f9c1b73E762Ba8E5660",
            "balance_lseth": 0.00099376738985375,
            "burns_lseth": 2.22405e-13,
            "conversion_rate": 1.006282340620787,
            "dao_fees_eth": 7.86854637e-10,
            "date": "2024-04-01",
            "fees_at_discount_rate_eth": 4.80412e-13,
            "fees_eth": 8.282680389e-9,
            "gross_fees_eth": 8.2826803894e-8,
            "gross_protocol_fee_rate": 0.000006264174837104,
            "gross_rewards_eth": 0.000006264174837104,
            "mints_lseth": 4.4554123505e-8,
            "operator_fees_eth": 1.242402058e-9,
            "oracle_report": "68bbc70ba87b9467831cc3ff56fc114f3659ba9e646042007d1d54f6b95f267d00000164",
            "platform_fees_at_discount_rate_eth": 0.000005236375878362,
            "platform_fees_eth": 5.715049468e-9,
            "previous_conversion_rate": 1.0371537463463845,
            "provider_fees_eth": 2.89893814e-10,
            "rebate_eth": 0.000006264174837104,
            "rebate_lseth": 0.000006264174837104,
            "rewards_eth": 7.4544123505e-8,
            "slashing_fees_eth": 2.48480412e-10,
            "target_fee_rate": 0.000006264174837104
          }
        ],
        "end_conversion_rate": 1.0454865181649966,
        "from": "2024-04-01",
        "org_id": "org_aDs4aCACyWYgMQ4A",
        "start_conversion_rate": 1.006282340620787,
        "to": "2024-04-01",
        "total_burns_lseth": 0,
        "total_dao_fees_eth": 4.34597684399e-7,
        "total_fees_eth": 0.000006787291484265,
        "total_gross_fees_eth": 0.000006787291484265,
        "total_gross_rewards_eth": 0.000045747124673728,
        "total_mints_lseth": 0.00099376738985375,
        "total_operator_fees_eth": 8.18961611118e-7,
        "total_platform_fees_at_discount_rate_eth": 0.000005236375878362,
        "total_platform_fees_eth": 0.000005236375878362,
        "total_provider_fees_eth": 1.60114936353e-7,
        "total_rebate_eth": 0,
        "total_rebate_lseth": 0,
        "total_rewards_eth": 0.000038959833189463,
        "total_slashing_fees_eth": 1.37241374012e-7
      }
    ]
  },
  "metadata": {
    "next_cursor": null
  }
}

List wallet rewards summary

get

List wallet rewards summary with daily reports for a specific time period

Authorizations
Path parameters
idOrAddressstringRequired

Wallet ID or address

Query parameters
fromstringOptional

Start date (default: 1 month ago)

tostringOptional

End date (default: current time)

csvstringOptional

Export to CSV

unitstringOptional

Currency unit

Responses
200
OK
application/json
400
Bad request
application/json
404
Not found
application/json
500
Internal error
application/json
get
GET /eth/v0/rewards/wallets/{idOrAddress}/summary HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
Accept: */*

{
  "data": {
    "account_id": "ab3e5114-af15-45b8-9c43-a5ec011d9d95",
    "address": "0xF523F31Acf07Ff41D2616f9c1b73E762Ba8E5660",
    "daily_reports": [
      {
        "address": "0xF523F31Acf07Ff41D2616f9c1b73E762Ba8E5660",
        "balance_lseth": 0.00099376738985375,
        "burns_lseth": 2.22405e-13,
        "conversion_rate": 1.006282340620787,
        "dao_fees_eth": 7.86854637e-10,
        "date": "2024-04-01",
        "fees_at_discount_rate_eth": 4.80412e-13,
        "fees_eth": 8.282680389e-9,
        "gross_fees_eth": 8.2826803894e-8,
        "gross_protocol_fee_rate": 0.000006264174837104,
        "gross_rewards_eth": 0.000006264174837104,
        "mints_lseth": 4.4554123505e-8,
        "operator_fees_eth": 1.242402058e-9,
        "oracle_report": "68bbc70ba87b9467831cc3ff56fc114f3659ba9e646042007d1d54f6b95f267d00000164",
        "platform_fees_at_discount_rate_eth": 0.000005236375878362,
        "platform_fees_eth": 5.715049468e-9,
        "previous_conversion_rate": 1.0371537463463845,
        "provider_fees_eth": 2.89893814e-10,
        "rebate_eth": 0.000006264174837104,
        "rebate_lseth": 0.000006264174837104,
        "rewards_eth": 7.4544123505e-8,
        "slashing_fees_eth": 2.48480412e-10,
        "target_fee_rate": 0.000006264174837104
      }
    ],
    "end_conversion_rate": 1.0454865181649966,
    "from": "2024-04-01",
    "org_id": "org_aDs4aCACyWYgMQ4A",
    "start_conversion_rate": 1.006282340620787,
    "to": "2024-04-01",
    "total_burns_lseth": 0,
    "total_dao_fees_eth": 4.34597684399e-7,
    "total_fees_eth": 0.000006787291484265,
    "total_gross_fees_eth": 0.000006787291484265,
    "total_gross_rewards_eth": 0.000045747124673728,
    "total_mints_lseth": 0.00099376738985375,
    "total_operator_fees_eth": 8.18961611118e-7,
    "total_platform_fees_at_discount_rate_eth": 0.000005236375878362,
    "total_platform_fees_eth": 0.000005236375878362,
    "total_provider_fees_eth": 1.60114936353e-7,
    "total_rebate_eth": 0,
    "total_rebate_lseth": 0,
    "total_rewards_eth": 0.000038959833189463,
    "total_slashing_fees_eth": 1.37241374012e-7
  },
  "metadata": {
    "next_cursor": null
  }
}
  • Public endpoints (no authentication required)
  • GETList latest high-level protocol info
  • GETList high-level protocol info
  • GETList wallet transactions
  • Private endpoints ( authentication required)
  • GETList platform fees
  • GETList operator fees
  • POSTList rewards
  • POSTList account rewards
  • POSTList wallet rewards
  • Reward Summary
  • GETList account rewards summary
  • GETList wallet rewards summary

List rewards

post

List rewards for a time period

Authorizations
Body
balancestringOptionalExample: 0.382748642252721461
fromstringOptionalExample: 2024-01-01
tostringOptionalExample: 2024-01-31
Responses
200
OK
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
500
Internal error
application/json
post
POST /eth/v0/rewards HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 74

[
  {
    "balance": "0.382748642252721461",
    "from": "2024-01-01",
    "to": "2024-01-31"
  }
]
{
  "accrued_rewards": 0.00003930554936445,
  "lots": [
    {
      "accrued_rewards": 0.000038075574334017,
      "balance": 0.3827486422527215,
      "end_conversion_rate": 1.037253225665527,
      "from": "2024-01-01",
      "start_conversion_rate": 1.0371537463463845,
      "to": "2024-01-31"
    }
  ]
}

List account rewards

post

List rewards by account for a specific date

Authorizations
Body
accountsstring[]OptionalExample: ["bb3e6114-af15-43a6-9b36-a5ec011d9d95"]
datestringOptionalExample: 2024-04-11
unitstringOptionalExample: lseth
Responses
200
OK
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
500
Internal error
application/json
post
POST /eth/v0/rewards/accounts HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "accounts": [
    "bb3e6114-af15-43a6-9b36-a5ec011d9d95"
  ],
  "date": "2024-04-11",
  "unit": "lseth"
}
[
  {
    "account_id": "bb3e6114-af15-43a6-9b36-a5ec011d9d95",
    "date": "2024-04-11",
    "totals": {
      "balance_lseth": 0.3827486422527215,
      "rewards_eth": 0.00003930554936445
    },
    "wallets": [
      {
        "account_id": "ab3e5114-af15-45b8-9c43-a5ec011d9d95",
        "address": "0x30e2a735D692fC28CD31C28F1A8259b4790f9A23",
        "avg_srr_hist": 0.00534633387,
        "balance_lseth": 0.3827486422527215,
        "burns_lseth": 0.1,
        "conversion_rate": 1.037253225665527,
        "dao_fees_eth": 4.25550536674e-7,
        "date": "2024-04-11",
        "fees_eth": 0.000006719219000121,
        "gross_fees_eth": 0.000006264174837104,
        "gross_protocol_fee_rate": 0.000006264174837104,
        "gross_rewards_eth": 0.000006264174837104,
        "mints_lseth": 0.48208860235174045,
        "operator_fees_eth": 0.000006264174837104,
        "oracle_report": "68bbc70ba87b9467831cc3ff56fc114f3659ba9e646042007d1d54f6b95f267d00000164",
        "org_id": "org_aDL0aCAXyWYgHQ4W",
        "platform_fees_at_discount_rate_eth": 0.000006264174837104,
        "platform_fees_eth": 0.00000519619602676,
        "previous_conversion_rate": 1.0371537463463845,
        "provider_fees_eth": 1.56781776669e-7,
        "rebate_eth": 0.000006264174837104,
        "rebate_lseth": 0.000006264174837104,
        "rewards_eth": 0.000038075574334017,
        "slashing_fees_eth": 1.34384380002e-7,
        "target_fee_rate": 0.08,
        "total_burns_lseth": 0.109,
        "total_dao_fees_eth": 4.39297316428e-7,
        "total_fees_eth": 0.000006936273417258,
        "total_gross_fees_eth": 0.000006264174837104,
        "total_gross_rewards_eth": 0.000006264174837104,
        "total_mints_lseth": 0.49174864225272147,
        "total_operator_fees_eth": 0.000006264174837104,
        "total_platform_fees_at_discount_rate_eth": 0.000006264174837104,
        "total_platform_fees_eth": 0.000005364051442679,
        "total_provider_fees_eth": 1.61846379739e-7,
        "total_rebate_eth": 0.000006264174837104,
        "total_rebate_lseth": 0.000006264174837104,
        "total_rewards_eth": 0.00003930554936445,
        "total_slashing_fees_eth": 1.38725468346e-7
      }
    ]
  }
]

List wallet rewards

post

Get rewards for a list of wallets on a specific date

Authorizations
Body
addressesstring[]OptionalExample: ["0x5d811a9d059dDAB0C18B385ad3b752f734f011cB"]
datestringOptionalExample: 2024-04-11
unitstringOptionalExample: eth
Responses
200
OK
application/json
401
Unauthorized
application/json
403
Forbidden
application/json
500
Internal error
application/json
post
POST /eth/v0/rewards/wallets HTTP/1.1
Host: api.alluvial.finance
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "addresses": [
    "0x5d811a9d059dDAB0C18B385ad3b752f734f011cB"
  ],
  "date": "2024-04-11",
  "unit": "eth"
}
[
  {
    "account_id": "ab3e5114-af15-45b8-9c43-a5ec011d9d95",
    "address": "0x30e2a735D692fC28CD31C28F1A8259b4790f9A23",
    "avg_srr_hist": 0.00534633387,
    "balance_lseth": 0.3827486422527215,
    "burns_lseth": 0.1,
    "conversion_rate": 1.037253225665527,
    "dao_fees_eth": 4.25550536674e-7,
    "date": "2024-04-11",
    "fees_eth": 0.000006719219000121,
    "gross_fees_eth": 0.000006264174837104,
    "gross_protocol_fee_rate": 0.000006264174837104,
    "gross_rewards_eth": 0.000006264174837104,
    "mints_lseth": 0.48208860235174045,
    "operator_fees_eth": 0.000006264174837104,
    "oracle_report": "68bbc70ba87b9467831cc3ff56fc114f3659ba9e646042007d1d54f6b95f267d00000164",
    "org_id": "org_aDL0aCAXyWYgHQ4W",
    "platform_fees_at_discount_rate_eth": 0.000006264174837104,
    "platform_fees_eth": 0.00000519619602676,
    "previous_conversion_rate": 1.0371537463463845,
    "provider_fees_eth": 1.56781776669e-7,
    "rebate_eth": 0.000006264174837104,
    "rebate_lseth": 0.000006264174837104,
    "rewards_eth": 0.000038075574334017,
    "slashing_fees_eth": 1.34384380002e-7,
    "target_fee_rate": 0.08,
    "total_burns_lseth": 0.109,
    "total_dao_fees_eth": 4.39297316428e-7,
    "total_fees_eth": 0.000006936273417258,
    "total_gross_fees_eth": 0.000006264174837104,
    "total_gross_rewards_eth": 0.000006264174837104,
    "total_mints_lseth": 0.49174864225272147,
    "total_operator_fees_eth": 0.000006264174837104,
    "total_platform_fees_at_discount_rate_eth": 0.000006264174837104,
    "total_platform_fees_eth": 0.000005364051442679,
    "total_provider_fees_eth": 1.61846379739e-7,
    "total_rebate_eth": 0.000006264174837104,
    "total_rebate_lseth": 0.000006264174837104,
    "total_rewards_eth": 0.00003930554936445,
    "total_slashing_fees_eth": 1.38725468346e-7
  }
]