Definition

Liquidity Pools are the engine(s) that drive DeFi. Liquidity Pools (pools) are used for several things including adding liquidity to them to generate fees, removing liquidity to claim those same fees and swapping one asset for another (WBTC for WETH, for example). In addition to liquidity pool data, this section also talks about our impermanent loss endpoints in the Portfolio and Returns section. In total there are 7 endpoints; 3 for liquidity pools and 4 for impermanent loss.

Details

Liquidity Pool Endpoints:
At Amberdata we give users two views into pools; from the pool point of view and the provider point of view. The pool point of view is exactly what it sounds like, a view of every liquidity provider in a particular pool. For example, the DAI_WETH pool on uniswapV2 has 1000’s of liquidity providers and we show everyone of their addresses, how much of the pool they own (in % terms), the number of LP tokens they have (in WEI) and when the last liquidity event was for the provider. This is a great way to understand how large and therefore how liquid a pool is. The other point of view we show is that of the liquidity provider, ie, every pool an address has added liquidity into. This includes how much of the pool they own (in % terms), the number of LP tokens they own (in WEI) and when the last liquidity event was for the provider, just like the pool point of view. In addition to the two views into pools, we also have an Events endpoint that shows all of the mint (add liquidity), burn (remove liquidity) and swap events that have happened for a particular address. This endpoint is a great way to keep track of what an address did and when it did it.

Impermanent Loss:
Impermanent loss is both extremely important to understand and somewhat difficult to understand. In the simplest terms, impermanent loss (IL) is similar to unrealized capital gains in traditional finance but applied to DeFi. Amberdata is one of (if not the only company) that is providing an event-level look at a liquidity provider’s IL in a particular pool. To fully understand what IL is, let’s look at an example.

Provider A adds $100 worth of assets to the DAI_WETH uniswapV2 pool on day 1. On day 2, they decide to remove $50 of assets from the pool. Later on day 2 they put the $50 of assets back into the pool. Therefore, at the end of day 1 and day 2, they have the same liquidity position and should have generated the same amount of fees per day. We say should have because if we only looked at end-of-day values, did the math with the pool fee %, we’d incorrectly report the IL for this provider. This is where the Amberdata methodology comes into play. We look at the event level for a liquidity provider in a pool instead of end-of-day aggregations. This way we provide the correct IL. Developing this was considerably more difficult and time-consuming but we needed to provide accurate numbers for our customers.

You’ll notice there are four different IL endpoints.

Provider Return Since Inception shows the IL of an LP from the initial liquidity event (when they added the liquidity) to a date the user chooses. You can think of this endpoint as the macro look at a position.

Provider Historical Return shows an up to 731 day look at an LP’s IL in a pool. You can think of this endpoint as the micro look at a position.

Pool Total Return shows the IL of a pool aggregated across all LPs in the pool. This will show the same parameters that the other two endpoints show like fees earned (by token and total in USD), whether the fees were claimed or unclaimed, the IL, and the overall return among others. Unlike the other two endpoints, the numbers are considerably larger because they represent every LP in the pool since its inception.

Impermanent Loss & DEX Returns is Amberdata's newest impermanent loss endpoint and differs slightly from the three above. First, this new endpoint currently only supports Uniswap V3, with plans to add protocol coverage throughout 2024. Secondly, this endpoint has differing response data from the other three endpoints. An LP's impermanent loss is calculated similarly to the Liquidity Provider Return endpoint above, but the results are displayed as the change in impermanent loss on a daily basis. Additionally, to remove any price anomalies since liquidity was provided, this endpoint does not show IL in US dollars and instead shows it as a ratio.

API Endpoints

/market/defi/liquidity-positions/pairs/{pair}/latest
//market/defi/liquidity-positions/providers/{address}/latest
/market/defi/liquidity/providers/{providerAddress}/events
//market/defi/liquidity/providers/return-since-inception/{address}
/market/defi/liquidity/providers/historical-return/{address}
/market/defi/liquidity/pool/daily-return/{address}
/market/defi/dex/wallets/{walletAddress}/returns

Availability

Our DeFi Liquidity Pool endpoints are available via REST API for the pool point of view, provider point of view and provider events. Our Impermanent Loss endpoint are available for the macro view (from the initial liquidity event to a user chosen date), micro view (any time period up to 731 days per query), the LP aggregated point of view (every liquidity provider combined) and the newest version of our IL endpoints exclusively for uniswapV3.

Since we maintain our own nodes, we have every event from the Genesis (Ethereum for example) block forward which enables us to provide the complete historical dataset for all the protocols we support.

Frequently Asked Questions

What is the difference between a mint, burn and swap in the Events endpoint?

• Mint, Burn and Swap are the three events we display for a particular address in a pool. The 'Mint' event is when an address has added liquidity to a liquidity pool, like DAI_WETH on uniswapV2. The 'Burn' event is when liquidity is removed from a liquidity pool. A 'Swap' event is when one token is exchanged or swapped for the other in a pool, like swapping DAI for WETH or vice versa. By showing all three events, we give you a more complete picture about what interactions an address has had with a liquidity pool.