> For the complete documentation index, see [llms.txt](https://docs.symm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.symm.io/options-protocol-architecture/technical-architecture/intent-based-trading-system.md).

# Intent-Based Trading System

### Intent states

| State           | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| PENDING         | Initial state when PartyA creates the intent                   |
| LOCKED          | Intent reserved by a PartyB                                    |
| FILLED          | Intent executed and trade created                              |
| EXPIRED         | Intent passed its expiration time                              |
| CANCELLED       | Intent cancelled by PartyA before filling                      |
| CANCEL\_PENDING | PartyA cancelled a locked intent, awaiting PartyB confirmation |

### Trading lifecycle

<figure><img src="/files/Xx8fBIQJPfZHuuJhy0pE" alt=""><figcaption></figcaption></figure>

#### Step 1: send open intent

PartyA opens an intent by calling:

```solidity
function sendOpenIntent(
address[] calldata partyBsWhiteList,
uint256 symbolId,
uint256 price,
uint256 quantity,
uint256 strikePrice,
uint256 expirationTimestamp,
uint256 mm,
TradeSide tradeSide,
MarginType marginType,
ExerciseFee memory exerciseFee,
uint256 deadline,
address feeToken,
address affiliate,
bytes memory userData
) external returns (uint256 intentId)
```

PartyA pays three fees: the protocol fee, the affiliate fee, and the solver fee. Funds are locked depending on the side:

* **Buy options:** PartyA locks the option premium, `premium = option_price × quantity`. The premium transfers to PartyB when the trade settles.
* **Sell options:** PartyA locks the required maintenance margin.

The intent is stored with `PENDING` status and becomes visible to eligible PartyB accounts.

#### Step 2: lock open intent

A PartyB can lock the intent when:

* The intent is `PENDING` and hasn't expired.
* PartyB's address is in `partyBsWhiteList`.
* PartyB has enough balance to meet its obligations.
* PartyB accepts the terms.

```solidity
function lockOpenIntent(uint256 intentId) external onlyPartyB
```

The intent moves from `PENDING` to `LOCKED` and is reserved for the locking PartyB.

#### Step 3: fill open intent

```solidity
function fillOpenIntent(uint256 intentId, uint256 quantity, uint256 price) external
```

* **Buy options:** the locked premium is debited from PartyA and credited to PartyB, to be paid out after settlement.
* **Sell options:** the locked maintenance margin is added to PartyA's total maintenance margin for solvency checks, PartyB pays the premium to PartyA, a new trade is created with `OPENED` status, and the intent moves from `LOCKED` to `FILLED`.

#### Step 4: close position

#### 4.1 Early close (before expiration)

PartyA can close a position early by sending a close intent:

```solidity
function sendCloseIntent(
uint256 tradeId,
uint256 quantity,
uint256 price,
uint256 deadline
) external
```

* **Buy positions:** the premium is paid to PartyB, PartyA sells the option back to PartyB, and PartyB pays PartyA the PnL: `PnL = (closePrice − openPrice) × quantity`. If `PnL < 0`, PartyA pays the loss to PartyB.
* **Sell positions:** the maintenance margin is released to PartyA, and PartyA pays PartyB the PnL (same formula). If `PnL < 0`, PartyB pays the loss to PartyA.

#### 4.2 Settlement at expiration

```solidity
function executeTrade(
uint256 tradeId,
SettlementPriceSig memory settlementPriceSig
) external
```

PartyB keeps the premium it already received (for trades where PartyA was the buyer).

* **In-the-money (ITM):** the settlement price comes from the oracle, `PnL = (settlementPrice − strikePrice) × quantity`, and the seller pays the positive PnL to the buyer (or the reverse if negative).
* **Out-of-the-money (OTM):** the option expires worthless, and any maintenance margin locked by the PartyA seller is released.


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.symm.io/options-protocol-architecture/technical-architecture/intent-based-trading-system.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.