> For the complete documentation index, see [llms.txt](https://docs.turbine.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.turbine.exchange/reference/technical/liquidity-pools-in-depth.md).
# Liquidity Pools in Depth
## Swap price and fee tier
Turbine Pools always swap at current market mid-price plus the pool's fee.
For example, if the current price of a USDC/USDT pair is 1.00, and the pool's fee tier is 1%, you can swap 100 USDC into 99 USDT, or 100 USDT into 99 USDC.
## Two modes of providing liquidity
### Providing liquidity in pool ratio
At any point in time, each Turbine Pool has some ratio of its reserves. For example, if a pool holds 10,000 DAI and 2 WETH, its reserves ratio is 5000:1.
In *pool ratio* mode, you specify *maximum* amounts of tokens to provide in your intent submitted to Turbine.
After your intent passes the speedbump, Turbine executes the intent. It provides liquidity on your behalf in the *current* pool ratio, without exceeding the specified maximum amounts.
The pool ratio can change between the time you submit your intent and the time Turbine executes it.
Turbine gives you a certain amount of LP token, specific to the pool, that represents your share in it. For example, if you provided 1,000 DAI to a pool that held 9,000 DAI (so the pool now holds 10,000 DAI and you own 10% of it), you receive an amount of LP token that represents 10% of its total supply. (The amount of the second token provided is not relevant, because the ratio is the same either way.)
To provide liquidity in pool ratio, specify `exact: false` in the intent submitted to `POST /api/add_liquidity` (see the [Swagger UI](https://api.turbine.exchange/api/swagger-ui/)).
### Providing liquidity in any ratio
You can provide any amounts of both tokens to a pool, regardless of the current reserve ratio, for a fee.
Providing liquidity in any ratio is equivalent to first making a swap on the pool to bring the pool's reserves and your provided amounts to the same ratio, then providing in pool ratio.
**Paying the fee:** When you provide liquidity in a ratio different from the pool ratio, you pay the swap fee on the amount the protocol must swap to align reserves with your provided amounts. The fee is subtracted from the LP tokens you receive.
Mathematical Foundation
**Notation**
* `r0`, `r1`: Current reserves of token0 and token1
* `p0`, `p1`: Amounts user wants to provide
* `Rr = r0/r1`: Pool reserve ratio
* `Rp = p0/p1`: Provision ratio
* `mp`: Mid-price (token0 in terms of token1, units are \[token1/token0])
* `f`: Swap fee (as a multiplier, e.g., 0.99 for 1% fee)
* `emp`: Effective mid-price (accounts for fee)
* `s0`, `s1`: Swapped amounts (amounts that the user **gets** in a virtual swap)
> **Conclusion:**
>
> All tokens provided by the user are added to pool reserves.
>
> The amount of liquidity tokens minted is calculated as `lp_total_supply * (emp*p0 + p1) / (emp*r0 + r1)`, where `emp = mp/f` if `Rp < Rr` and `emp = mp*f` if `Rp > Rr`.
To provide liquidity in a ratio different from the pool, the protocol first performs a virtual swap to bring the provided amounts and pool reserves to the same ratio. When making this swap, the pool charges a fee. Then equal ratio provision logic is applied.
The following mathematical derivations calculate the final amount of liquidity tokens to mint, as if the virtual swap happened before provision in equal ratio.
1. **Determine swap direction:**
* If `Rp < Rr`, swap token1 to token0.\
`s1` is given, and `s0` is unknown.\
Calculate `s0` applying swap fee: `s0 = -s1 / mp * f`, so `s1 = -s0 * mp / f`
* If `Rp > Rr`, swap token0 to token1.\
`s0` is given, and `s1` is unknown.\
Calculate `s1` applying swap fee: `s1 = -s0 * mp * f`
* This can be simplified to one case by introducing *effective mid-price* `emp`:
```
s1 = -s0 * emp
emp = mp/f if Rp < Rr
mp*f if Rp > Rr
```
2. **Calculate swapped amounts:**
* User's provided amounts after swap: `p0 + s0` and `p1 + s1` i.e. `Rp*p1 + s0` and `p1 - emp*s0`
* Reserves after swap: `r0 - s0` and `r1 - s1` i.e. `Rr*r1 - s0` and `r1 + emp*s0`
* We want the ratio of reserves after swap to equal the ratio of provided amounts after swap. Solving for `s0`:
```
(r0 - s0) / (r1 - s1) = (p0 + s0) / (p1 + s1)
(r0 - s0)(p1 + s1) = (p0 + s0)(r1 - s1)
(r0 - s0)(p1 - emp*s0) = (p0 + s0)(r1 + emp*s0)
p1*r0 - emp*r0*s0 - p1*s0 + emp*s0*s0 = p0*r1 + emp*p0*s0 + r1*s0 + emp*s0*s0
p1*r0 - emp*r0*s0 - p1*s0 = p0*r1 + emp*p0*s0 + r1*s0
p1*r0 - p0*r1 = emp*p0*s0 + r1*s0 + emp*r0*s0 + p1*s0
s0(emp*p0 + r1 + emp*r0 + p1) = p1*r0 - p0*r1
s0 = (p1*r0 - p0*r1) / (emp*p0 + emp*r0 + p1 + r1)
```
3. **Calculate amount of liquidity tokens to mint:**
* Reserve of token0 after swap (before provision):\
`r0 - s0 = r0 - (p1*r0 - p0*r1) / (emp*p0 + emp*r0 + p1 + r1)`
* Provided amount of token0 after swap:\
`p0 + s0 = p0 + (p1*r0 - p0*r1) / (emp*p0 + emp*r0 + p1 + r1)`
* Ratio of provided amount to reserve (this, times liquidity token total supply, is the amount of liquidity token that needs to be minted):
```
provided_to_reserve_ratio = (p0 + s0) / (r0 - s0) =
p0 + (p1*r0 - p0*r1) / (emp*p0 + emp*r0 + p1 + r1)
= -------------------------------------------------- =
r0 - (p1*r0 - p0*r1) / (emp*p0 + emp*r0 + p1 + r1)
```
Multiplying numerator and denominator by `emp*p0 + emp*r0 + p1 + r1`, we get:
```
emp*p0*p0 + emp*p0*r0 + p0*p1 + p0*r1 + p1*r0 - p0*r1
= ----------------------------------------------------- =
emp*p0*r0 + emp*r0*r0 + p1*r0 + r0*r1 + p0*r1 - p1*r0
emp*p0*p0 + emp*p0*r0 + p0*p1 + p1*r0
= ----------------------------------------------------- =
emp*p0*r0 + emp*r0*r0 + r0*r1 + p0*r1
emp*p0*(p0 + r0) + p1*(p0 + r0)
= ------------------------------- =
emp*r0*(p0 + r0) + r1*(p0 + r0)
emp*p0 + p1
= -----------
emp*r0 + r1
```
* To avoid numerical integer divisions, assuming that effective mid-price is a fraction `emp = emp_num / emp_den`, we can multiply numerator and denominator by effective mid-price's denominator:
```
(emp*p0 + p1) * emp_den
provided_to_reserve_ratio = ----------------------- =
(emp*r0 + r1) * emp_den
emp_num*p0 + p1*emp_den
= -----------------------
emp_num*r0 + r1*emp_den
```
* Finally, the amount of LP tokens to mint is:
```
lp_to_mint = lp_total_supply * (emp_num*p0 + p1*emp_den) / (emp_num*r0 + r1*emp_den)
```
## See also
{% columns %}
{% column %}
{% content-ref url="/spaces/gxFOZ85U3R3v2cPka9gM/pages/u7zWyMUKXDnn1eSGg3BW" %}
[Broken mention](broken://spaces/gxFOZ85U3R3v2cPka9gM/pages/u7zWyMUKXDnn1eSGg3BW)
{% endcontent-ref %}
{% endcolumn %}
{% column %}
{% content-ref url="/spaces/usbDsiWDhwRR4sob2ROl/pages/nTwimP6eLkw1g057D6fT" %}
[Broken mention](broken://spaces/usbDsiWDhwRR4sob2ROl/pages/nTwimP6eLkw1g057D6fT)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.turbine.exchange/reference/technical/liquidity-pools-in-depth.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.