> For the complete documentation index, see [llms.txt](https://docs.pairity.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pairity.fi/protocol/volatility-amm.md).

# Volatility AMM

The Volatility AMM is a pair-wide utilization model. It does not behave like a constant-product pool of ERC-20 token balances. One `X/Y` state prices all active strikes and expiries in the pair.

## What X and Y mean

The AMM keeps two aggregate, quote-denominated pricing values:

```
X = baseImplicitValueX18
Y = optionImplicitValueX18
sigma = X / Y
```

`X` is the aggregate Base-side pricing value. `Y` is the aggregate option-side pricing value for the pair, covering both Call and Put activity. In the active state:

```
Y = totalLiquidityNAVX18 - X
X + Y = totalLiquidityNAVX18
```

Neither value is a direct ERC-20 wallet balance. They are the two sides of the engine's aggregate pricing state. The vault still owns the real underlying, quote and option inventory, and the inventory manager tracks those token amounts separately.

## Initial state

Each pair starts with a configured sigma and total liquidity. The initial state is split into X and Y so that:

```
X / Y = initial sigma
X + Y = configured total liquidity value
```

The protocol enforces configured sigma bounds and requires both sides to remain positive.

## Rebase after TVL changes

When total liquidity changes, the AMM does not infer X/Y from individual option balances. Instead it uses the previous sigma and the new TVL to calculate a fresh target:

```
targetX = TVL * sigmaBefore / (1 + sigmaBefore)
targetY = TVL - targetX
```

The new real Base, Call and Put valuations contribute to the NAV supplied by the vault. The AMM then derives the aggregate X/Y target directly from the old sigma and that new total value. It does not store separate actual and virtual reserve offsets.

This lets a deposit, withdrawal or other TVL change resize the pricing state while preserving the previous volatility level.

## Trade update

The engine solves for the post-trade sigma, then reconstructs the aggregate reserves from the unchanged trade NAV:

```
Xafter = NAV * sigmaAfter / (1 + sigmaAfter)
Yafter = NAV - Xafter
sigmaAfter = Xafter / Yafter
```

The trade equation is equivalent to changing the Base-side aggregate value by a signed delta while keeping `X + Y = NAV`. The sign depends on the instrument and direction. After execution, the engine stores the solved `Xafter` and `Yafter` values.

## Inventory-aware trade impact

The Pair Vault projects the real inventory transition before asking the engine for a quote. This matters because a user-facing option trade can take different routes:

| Route result                                           | Value used to move X/Y                                     |
| ------------------------------------------------------ | ---------------------------------------------------------- |
| Direct option inventory, with no Base change           | `option amount * option price at the candidate sigma`      |
| Route mints or retains Base while delivering an option | `Base inventory delta * Base price at the candidate sigma` |
| Base trade                                             | `Base amount * Base price at the candidate sigma`          |

For an option trade with a non-zero Base inventory delta, the engine uses the Base delta to solve sigma. This reflects the collateral that the Pair Vault actually retains or removes. It prevents the volatility move from being determined only by the option premium when the route creates a complete set and leaves Base inventory behind.

The option's displayed fair value is still calculated from the requested option's own before and after Call or Put prices. The inventory delta only determines how the pair-wide X/Y state moves.

## Iterative quote flow

The instrument price and the value delta are coupled: the price uses sigma, while the trade value changes sigma. The quote path resolves this with a before/after calculation:

```
1. sigmaBefore = Xbefore / Ybefore
2. priceBefore = BlackScholes(oracle, strike, expiry, sigmaBefore)
3. Select the route's inventory delta and solve the sigma equation
4. sigmaAfter  = Xafter / Yafter
5. priceAfter  = BlackScholes(oracle, strike, expiry, sigmaAfter)
6. fairPrice   = (priceBefore + priceAfter) / 2
```

The final quote includes fees. The transaction rechecks the same state transition on-chain, so a stale quote or a changed state can fail the deadline or slippage checks.

## Why this model exists

The ratio gives the protocol a single, predictable volatility state across series. A large Call or Put trade can move sigma either through the direct option-side value or through the Base inventory that the route creates or consumes. Real Base inventory is therefore economically important: it affects NAV, route availability, collateral risk and fees, and for inventory-aware routes its marked delta is also the AMM state transition input.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pairity.fi/protocol/volatility-amm.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.