# Inventory

> How binary YES and NO tokens are minted, reserved, and merged when you provide liquidity.

Every Agara market is binary. Each unit of collateral can be split into one
YES token plus one NO token, and an equal YES/NO pair can be merged back into
one unit of collateral.

The key quoting rule is simple: **SELL orders require outcome inventory.**
The platform reserves the actual shares when it accepts a SELL. Collateral cannot
stand in for missing SELL inventory.

<Callout type="info" title="API order placement">
For API trading, use [pre-signed orders](/docs/api-traders/pre-signed-orders).
Server-side signing may slow order ingestion. Follow the
[one-time setup](/docs/api-traders/pre-signed-orders#one-time-setup) and grant
`orders:place_signed` for signed single-order and batch submissions.
</Callout>

## Settlement modes [#settlement-modes]

| Match                 | Mode     | What happens                                                                    |
| --------------------- | -------- | ------------------------------------------------------------------------------- |
| YES SELL with YES BUY | `NORMAL` | YES moves to the buyer; collateral moves to the seller                          |
| NO SELL with NO BUY   | `NORMAL` | NO moves to the buyer; collateral moves to the seller                           |
| YES BUY with NO BUY   | `MINT`   | Both buyers supply collateral; a fresh pair is minted and each receives one leg |
| YES SELL with NO SELL | `MERGE`  | Both sellers supply shares; the pair is burned and collateral is returned       |

Mint settlement lets a cash-only maker quote complementary **BUY YES and BUY
NO** orders. It does not let a cash-only maker place a SELL. A conventional
two-sided BUY/SELL quote needs inventory for the SELL leg.

The fill's `settlement_mode` reports which path was used.

See [Cross-orderbook matching](/docs/cross-orderbook-matching) for worked
examples of each mode, execution prices, and matching priority.

## When to split [#when-to-split]

Use [split](/docs/on-chain/positions#split) when you need YES and NO shares for
SELL quotes. For example, splitting 1,000 collateral units creates 1,000 YES plus 1,000
NO. You can then reserve either token in resting SELL orders.

Split is useful when:

* Seeding a new book with BUY and SELL depth.
* Replenishing an outcome whose available shares are below your next SELL
  ladder.
* Converting collateral into balanced inventory before one-sided flow.

AGARA neg-risk group members are ordinary binary CTF conditions, so the
same split operation applies to them.

## When to merge [#when-to-merge]

[Merge](/docs/on-chain/positions#merge) burns equal quantities of YES and NO and
returns one collateral unit per pair. It has no midpoint or price-discovery step.

If you hold 200 YES and 200 NO but need only 100 of each for quoting, merge
the surplus 100 pairs. If your balances are unequal, only the smaller common
quantity is mergeable; the remainder is directional exposure.

Neg-risk group members merge through the same Conditional Tokens contract as
other AGARA markets. Group membership does not change the binary pair.

## Automating position operations [#automating-position-operations]

Split and merge accept PATs with the `positions:split` and
`positions:merge` scopes. A self-custody client holding the owner key can
combine independent split, merge, and withdrawal operations in an
[account batch](/docs/api-traders/account-batches), subject to composition and pre-batch
coverage rules. Supported standalone binary AGARA markets use
[automatic redemption](/docs/automatic-redemption); neg-risk members are not yet
included.

## Reservation math [#reservation-math]

Suppose you want to quote 100 shares of YES at a 0.30 bid and 0.32 ask:

| Quote                   | Required inventory                                   |
| ----------------------- | ---------------------------------------------------- |
| `BUY YES @ 0.30 × 100`  | 30 collateral units, plus the worst-case fee reserve |
| `SELL YES @ 0.32 × 100` | 100 available YES tokens                             |

With no YES tokens, the SELL is rejected. Either reduce the SELL size, acquire
YES, or split collateral first.

The portfolio cash balance is not reduced by resting BUYs. Before placing
another BUY, account for the unfilled notional and worst-case fee of existing
BUY commitments. Before placing another SELL, subtract open SELL quantities
from the corresponding outcome balance. See
[`POST /trade/v1/orders/list`](/docs/orders#list-your-orders) for the complete
order lifecycle, [`/trade/v1/portfolio/open-orders/list`](/docs/portfolio#open-orders)
for resting liquidity,
[`POST /trade/v1/portfolio/positions/list`](/docs/portfolio#positions) for each
outcome balance, and [`/trade/v1/portfolio/summary`](/docs/portfolio#summary)
for collateral. Do not size an AGARA SELL from a positions response while
`unavailable_exchanges` includes `AGARA`; retry that unpaginated read first.

BUY commitments are checked per market. A conservative strategy
should also cap total exposure across every market it quotes.

When a placement reports `insufficient_balance` or `insufficient_shares`, do
not retry unchanged. Follow the code-specific reconciliation steps in
[Errors, retries, and recovery](/docs/api-traders/recovery#ordinary-orders).