> 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/developer-guide/integration.md).

# Integrate Pairity

This guide is for developers building a trading interface, keeper, portfolio tool or other integration on top of Pairity.

## Architecture

The main protocol components are:

* **Factory**: creates pairs and series and exposes market configuration.
* **Pair Vault**: owns the market's underlying, quote and series-token inventory.
* **Router**: accepts user trade requests, selects a route and coordinates token movement.
* **Quoter**: exposes read-only trade previews and detailed fee information.
* **Series Vault**: represents one strike and expiry and owns its Base, Call and Put tokens.
* **Virtual AMM Engine**: maintains pair-wide X/Y pricing state and sigma.
* **Market Price Oracle**: supplies the underlying/quote spot and update time.

Use the deployment addresses for the selected chain. Do not hardcode addresses across networks.

## Read market state

An integration should discover and validate:

1. Chain ID and deployment addresses.
2. Pair underlying, quote asset and current sigma.
3. Allowed strikes and expiries.
4. Series addresses and their Base, Call and Put token addresses.
5. Oracle price and update timestamp.
6. Vault NAV, real token balances and option inventory.

The backend API can be used for indexed lists and history. On-chain reads remain the source of truth immediately before submitting a transaction.

## Quote before trading

Use the router or quoter preview for the selected pair, series and amount. A detailed quote should expose:

* Fair value before fees
* Before and after sigma
* Before and after Base, Call and Put marks
* Trading fee
* Base, Call and Put inventory fees
* Total quote amount
* Selected inventory or conversion route

The fair value uses the requested instrument's before and after prices. The AMM state transition can use a different marked delta when the Pair Vault route creates or consumes Base inventory. Integrations should display the returned quote rather than reconstructing price impact locally.

## Buying and selling

The general flow is:

1. Resolve the Pair Vault and Series Vault from the selected pair and series terms.
2. Request a preview for Base, Call or Put.
3. Approve the Router for the payment token, if needed.
4. Submit the matching Router buy or sell call with a minimum output or maximum payment, deadline and receiver.
5. Wait for the transaction receipt and refresh balances from chain state.

For an option route, the Pair Vault may use direct inventory, mint a complete set, merge matching Base and option tokens, or use the configured conversion fallback. The route is part of the quote and can change with inventory.

Do not treat a frontend-calculated payment as authoritative. The transaction must enforce the user's slippage and deadline constraints on-chain.

## Series lifecycle

Before expiry, a series can be active for trading if it is allowed and has valid oracle and liquidity state. At expiry, the series enters its end state and minting/trading stops.

At expiry the values are:

```
Base = min(spot, strike)
Call = max(spot - strike, 0)
Put  = max(strike - spot, 0)
```

## Liquidation and settlement

Settlement is performed against a complete Base and option pair. A keeper or other caller can batch liquidation items after the series has reached its end state:

1. Read the current settlement price and observed timestamp.
2. Build liquidation items with the pair type, amount, Base holder and option holder.
3. Call `previewLiquidateBatch` to calculate quote input, keeper reward, underlying reward and settlement price.
4. Approve quote if the selected liquidation mode requires quote payment.
5. Call `liquidateBatch` with `maxQuoteIn` and a non-zero `rewardReceiver`.
6. Index each `PairLiquidated` event and refresh the Pair Vault inventory.

The liquidation result depends on whether the series is a Put or Call, the settlement price relative to the strike, the holders' available quote, and the selected keeper route. Never assume every Call settlement has the same payer or payout direction.

`previewLiquidateBatch` is the read-only preview. `liquidateBatch` is the state-changing execution and should be protected by a reasonable maximum quote input and a current deadline policy in the keeper.

## Indexing settlement

A settlement transaction can contain multiple liquidation legs. Index each `PairLiquidated` event as its own record using at least:

* Transaction hash
* Log index
* Series
* Pair type
* Amount
* Settlement price
* Payout fields
* Liquidation cost or keeper reward

Do not collapse all legs into one transaction row. The same transaction hash can legitimately produce separate Base and option settlement records for a user's position.

## Liquidity integration

Deposits and withdrawals use the Pair Vault and share token. NAV includes quote, underlying and active series inventory. The AMM's X/Y values are aggregate pricing-state values:

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

An integration should read real balances for collateral availability and inventory, and read the engine for sigma and pricing state. These values answer different questions.


---

# 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/developer-guide/integration.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.