Provider Historical Return

Retrieves a liquidity provider’s return in a time interval including fees earned, impermanent loss and related metadata.

👍

Protocols Supported

This endpoint only supports Uniswap v2.

👍

Blockchains Supported

This endpoint only supports data from ethereum-mainnet.

📘

Not specifying startDate and endDate

If the startDate and endDate query parameters are not provided, the API will return a 404 error as these are required parameters in order to retrieve the data.

🚧

Time Range Limit

The maximum time range (difference between endDate and startDate) is 731 days (2 years).

Potential Use-Cases

You can use the historical data for a liquidity provider’s return by plotting the day-to-day changes in impermanent loss in order to understand how their provided assets have performed over time. A visual representation is easy to digest/understand and quickly identify trends, spikes and patterns. For example, if impermanent loss seems to spike at certain times of the year, it might be tied to broader market movements or specific events.

Sample Visualization

The responses from this endpoint can be visualized like this

Response Data

FieldTypeDescription
payload.data[index].protocolstringThe name of the protocol, i.e. "uniswapv2".
payload.data[index].startstringTimestamp start of the query interval.
payload.data[index].endstringTimestamp end of the query interval.
payload.data[index].poolAddressstringThe address of the token, i.e. the address of the pair or liquidity pool.
payload.data[index].holderAddressstringThe address of the token holder, i.e. the address of the liquidity provider.
payload.data[index].token0AddressstringThe address of token0, i.e. the first token in the pool.
payload.data[index].token1AddressstringThe address of token1, i.e. the second token in the pool.
payload.data[index].token0IfHeldstringHow many units of token0 the liquidity provider holds at the end of the query interval if they simply held them in his wallet instead of providing liquidity.
payload.data[index].token1IfHeldstringHow many units of token1 the liquidity provider holds at the end of the query interval if they simply held them in his wallet instead of providing liquidity.
payload.data[index].token0LpstringHow many units of token0 the liquidity provider holds at the end of the query interval.
payload.data[index].token1Lpstringhow many units of token1 the liquidity provider holds at the end of the query interval.
payload.data[index].change0stringThe difference between tokens0Lp and Tokens0IfHeld less fees. change0 = tokens0IfHeld - (tokens0Lp - fees0Total)
payload.data[index].change1stringThe difference between tokens1Lp and Tokens1IfHeld less fees. change1 = tokens1IfHeld - (tokens1Lp - fees1Total)
payload.data[index].fees0TotalstringTotal units of token0 fees earned. fees0Total = fees0Unclaimed + fees0Claimed.
payload.data[index].fees1TotalstringTotal units of token1 fees earned. fees1Total = fees1Unclaimed + fees1Claimed.
payload.data[index].fees0UnclaimedstringTotal units of token0 fees the liquidity provider has claimed and removed from the pool.
payload.data[index].fees1UnclaimedstringTotal units of token1 the liquidity provider has claimed and removed from the pool.
payload.data[index].fees0ClaimedstringTotal units of token0 fees the liquidity provider has removed from the pool.
payload.data[index].fees1ClaimedstringTotal units of token1 fees the liquidity provider has claimed and removed from the pool.
payload.data[index].positionOpenbooleanIndicates if the LP's liquidity position is still active i.e. the LP has not burned ALL of their liquidity.
payload.data[index].feesnumberTotal fees earned in USD. fees = feesClaimed + feesUnclaimed.
payload.data[index].feesClaimednumberTotal fees claimed in USD.
payload.data[index].feesUnclaimednumberTotal fees unclaimed in USD.
payload.data[index].impermanentLossnumberLoss as a result of providing liquidity in USD.
payload.data[index].returnnumberReturn in USD.
Language
Authorization
Header
Click Try It! to start a request and see the response here!