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 has our impermanent loss endpoints. In total there are 6 endpoints; 3 for liquidity pools and 3 for impermanent loss.

Details

Liquidity Pool Endpoints:
Here at Amberdata we give you two views into pools; from the pool point of view and from 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.

Uniswap V3 Liquidity Distribution:
One of the big advantages of uniswapV3 vs uniswapV2 is the ability for the liquidity provider to choose where on the price curve their liquidity gets added. This is huge improvement from V2 where added liquidity was spread out across the entire price curve, which is less than ideal for a stable coin pool that trades in a narrow range. By allowing the user to determine at which price range the liquidity is added, this allows you to see how much liquidity is added throughout the price curve. You can think of this as a pseudo order book, which is unique in DeFi. This Amberdata endpoint allows the user to query uniswapV3 pools by token (0 or 1) and see how much liquidity is in a given price range by seeing the different ticks. In addition, we give you the option to see the Active Tick to know exactly where the market is for most recent block. This is a great way for liquidity providers to see the optimal range for adding liquidity as well as giving traders a view into the "order book" of a pool on uniswapV3.

Impermanent Loss:
Impermanent loss is one of those topics in DeFi that is both extremely important to understand and somewhat difficult to understand at the same time. 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 it was necessary for us to provide accurate numbers for our customers.

You’ll notice there are three different IL endpoints.

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

Liquidity Provider Total Return 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.

Liquidity Pool Total Return shows the IL of a pool aggregated across all LP’s 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.

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/{address}
/market/defi/liquidity/providers/daily-return/{address}
/market/defi/liquidity/pool/daily-return/{address}

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 micro view (any time period up to 30 days per query), macro view (from the initial liquidity event to a user chosen date) and the LP aggregated point of view (every liquidity provider combined).

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.