# Collateral locking

> How BUY commitments and SELL share reservations affect order acceptance, fills, cancellations and available balances.

Agara checks collateral for BUY orders and reserves outcome shares for SELL
orders. These rules apply to Agara orders placed through both `/trade/v1` and
`/order/v1`.

| Resource       | What an open order does                                                                                                          | What changes on execution                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| BUY collateral | Adds its remaining limit-price notional to the account's BUY commitments in that market. Placing the order does not deduct cash. | Cash decreases by the executed notional and any applicable taker fee.                                                                      |
| SELL shares    | Reserves the unfilled quantity of that specific outcome. Reserved shares cannot back another SELL or a merge.                    | Both the total holding and its reserved quantity decrease by the filled quantity. Cash increases by the proceeds after any applicable fee. |

BUY commitments are checked **per market, across both outcomes**. The same cash
balance can support quotes in several markets. Acceptance therefore does not
guarantee that every open BUY can fill: spending cash in one market can cause
BUY orders in another market to be cancelled.

The examples below use collateral units and whole shares for readability.
They assume zero fees except in the fee example. Each example is independent,
all other order checks pass, and any stated fill is against another trader.
API amounts use integer micro units; one collateral unit or share is
`1_000_000` micro units.

## BUY collateral checks [#buy-collateral-checks]

For a new GTC or GTD LIMIT BUY, the collateral check is:

```text
existing_resting_buy_notional_in_market
  + new_order_limit_notional
  + new_order_maximum_fee
  <= cash_balance
```

Existing commitments include BUYs for both YES and NO in that market. They
use each order's remaining quantity at its own limit price. SELL orders and
the marked value of positions do not offset this requirement.

Group orders by market, not by outcome token or event. YES and NO have
different token IDs but share one market. Separate markets in the same
event have separate commitment checks.

For a FAK or FOK BUY, the check covers the new order's own notional and maximum
fee; it does not add existing resting BUY commitments. Such an order can
spend cash that also supports resting quotes. Those quotes are checked again
after execution.

For a Router MARKET BUY, `collateral_amount_micro` is a budget that already
includes fee headroom. Order Service supports LIMIT orders; use a FAK or FOK
with a price bound for immediate execution.

Calculate remaining LIMIT notional with integer arithmetic:

```text
remaining_shares_micro = original_size_micro - size_matched_micro
remaining_notional_micro = floor(price_micro * remaining_shares_micro / 1_000_000)
market_commitment_micro = sum(remaining_notional_micro for each resting BUY in that market)
```

Calculate each order's notional before summing. Do not use floating-point
rounding to decide whether a request fits the available balance.

### Example 1: one BUY, a partial fill and a cancellation [#example-1-one-buy-a-partial-fill-and-a-cancellation]

Start with 100 collateral units and place a GTC BUY for 100 YES at 0.60.
It initially rests without filling.

| Step                                          | Cash balance | Remaining BUY quantity | BUY commitment | Capacity for another GTC/GTD BUY in this market, before fees |
| --------------------------------------------- | ------------ | ---------------------- | -------------- | ------------------------------------------------------------ |
| Before placement                              | 100          | 0                      | 0              | 100                                                          |
| Order rests                                   | 100          | 100                    | 60             | 40                                                           |
| 40 shares fill at 0.60                        | 76           | 60                     | 36             | 40                                                           |
| Cancellation of the remaining 60 is confirmed | 76           | 0                      | 0              | 76                                                           |

The fill spends `40 × 0.60 = 24`. Cancellation removes the remaining
`60 × 0.60 = 36` commitment. It does not refund the 24 already spent or
increase the cash balance: the unfilled commitment was never deducted from
cash. The 40 acquired YES shares remain in the account.

On initial placement, a BUY can execute below its limit price. Cash is
debited at the execution price, while any resting remainder counts at its
limit price. For example, immediately buying 40 shares at 0.55 costs 22,
while a remaining 60 at a 0.60 limit commits 36.

### Example 2: YES and NO BUYs in the same market [#example-2-yes-and-no-buys-in-the-same-market]

Start with 100 collateral units and a resting BUY for 100 YES at 0.60.

| Additional GTC BUY | Existing commitment | New notional | Total required | Collateral check |
| ------------------ | ------------------- | ------------ | -------------- | ---------------- |
| 100 NO at 0.50     | 60                  | 50           | 110            | Reject           |
| 80 NO at 0.50      | 60                  | 40           | 100            | Pass             |

The two outcomes share one market commitment. Their requirements are added;
buying the opposite outcome does not cancel the first order's commitment.
These rows are alternative requests, not successive placements.

### Example 3: BUYs in different markets [#example-3-buys-in-different-markets]

Start with 100 collateral units. Both of these orders can rest:

| Market | Order               | Market commitment |
| ------ | ------------------- | ----------------- |
| A      | BUY 100 YES at 0.90 | 90                |
| B      | BUY 100 YES at 0.40 | 40                |

Each market's commitment is within the cash balance, even though the total
across markets is 130.

If the Market B order fills completely at 0.40, cash falls to 60. Market A's
90 commitment now exceeds that balance, so its remaining order is cancelled
with reason `INSUFFICIENT_COLLATERAL`. The Market B fill remains valid.

Maintain an additional aggregate limit in your client if all your quotes
must remain affordable together. For example, capping the sum of commitments
across markets at 100 would have prevented the 130-unit exposure above.
Include unresolved submissions and potential fees in that client-side limit.

## Automatic cancellation when collateral decreases [#automatic-cancellation-when-collateral-decreases]

Process `order_cancelled` events with reason `INSUFFICIENT_COLLATERAL`, even
when your client did not send a cancel request. BUY fills, splits and
withdrawals can reduce the cash supporting other resting orders.

For each market whose resting BUY commitment exceeds the updated cash balance,
orders are cancelled in this order:

1. Smallest remaining notional first, using limit price times remaining quantity.
2. For equal remaining notionals, the more recently accepted order first.
3. Continue until that market's remaining commitment fits the cash balance.

Cancellation removes an order's entire unfilled remainder. The order is not
resized to cover only the collateral shortfall. Other markets are checked
against the same updated cash balance independently.

### Example 4: which orders are cancelled [#example-4-which-orders-are-cancelled]

Start with 100 collateral units and three resting BUYs in Market A:

| Order | Remaining quantity | Limit price | Remaining notional |
| ----- | ------------------ | ----------- | ------------------ |
| A1    | 100                | 0.40        | 40                 |
| A2    | 100                | 0.30        | 30                 |
| A3    | 100                | 0.20        | 20                 |

The Market A commitment is 90. A fill in another market spends 40, reducing
cash to 60.

| Action                 | Remaining Market A commitment | Within the 60-unit balance? |
| ---------------------- | ----------------------------- | --------------------------- |
| Before cancellation    | 90                            | No                          |
| Cancel A3, removing 20 | 70                            | No                          |
| Cancel A2, removing 30 | 40                            | Yes                         |

A1 remains open. A2 is cancelled in full even though removing only 10 more
units would have covered the shortfall. If two candidate orders had the same
remaining notional, the newer one would be cancelled first.

### Example 5: an immediate BUY can displace a resting BUY [#example-5-an-immediate-buy-can-displace-a-resting-buy]

Start with 100 collateral units and a resting BUY for 300 YES at 0.30,
committing 90. Submit a FOK BUY for 100 YES at 0.40 in that same market,
with 100 shares offered by other traders at 0.40.

The incoming order's collateral check compares 40 with the 100-unit balance;
it does not require `90 + 40`. FOK must also be completely fillable. If it
fills for 40, cash becomes 60 and the resting 90-unit order is cancelled for
insufficient collateral.

A FAK has the same collateral-check distinction, but only its executed
quantity spends cash. Its unfilled remainder does not become a resting BUY
commitment.

## SELL share reservations [#sell-share-reservations]

A SELL requires available shares of the exact outcome being sold. Cash, NO
shares or shares from another market cannot back a SELL of YES in this market.

```text
available_shares = held_shares - shares_reserved_for_open_sells
```

The same shares cannot back two SELL orders. On a partial fill, both held and
reserved shares decrease by the filled quantity. Cancelling or expiring the
unfilled remainder releases its reservation. An unfilled FAK remainder is
released when that order finishes.

### Example 6: SELL reservation, partial fill and cancellation [#example-6-sell-reservation-partial-fill-and-cancellation]

Start with 100 YES shares and place a SELL for 70 YES at 0.60.

| Step                       | Held YES | Reserved YES | Available YES |
| -------------------------- | -------- | ------------ | ------------- |
| Before placement           | 100      | 0            | 100           |
| SELL rests                 | 100      | 70           | 30            |
| 20 shares fill             | 80       | 50           | 30            |
| Remaining 50 are cancelled | 80       | 0            | 80            |

While the order is resting, another SELL for 40 YES fails the share check,
even if the account has enough cash to buy those shares. After the 20-share
fill, the seller receives 12 collateral units before any applicable fee.
Cancellation releases the remaining 50 shares; it does not restore the 20
already sold.

## Splits, merges and withdrawals [#splits-merges-and-withdrawals]

A split exchanges one collateral unit for one YES and one NO. It reduces
cash and can therefore cause resting BUY cancellations. A merge consumes an
equal quantity of **available** YES and NO and returns collateral. Shares
reserved for SELL orders cannot be merged.

A withdrawal that reduces trading cash can also leave resting BUYs
underfunded. Treat withdrawal eligibility and completion separately from
order collateral: a balance or order acknowledgement does not confirm a
completed onchain transfer. See [account batches](/api-traders/account-batches)
for those operation states.

### Example 7: splitting collateral and merging unreserved shares [#example-7-splitting-collateral-and-merging-unreserved-shares]

Start with 100 collateral units, no shares, and a resting BUY commitment of
80\. Perform each step after confirming the preceding result:

| Step                            | Cash | Held YES | Held NO | Reserved YES | Available YES / NO |
| ------------------------------- | ---- | -------- | ------- | ------------ | ------------------ |
| Initial state                   | 100  | 0        | 0       | 0            | 0 / 0              |
| Split 30 collateral units       | 70   | 30       | 30      | 0            | 30 / 30            |
| Place a resting SELL for 20 YES | 70   | 30       | 30      | 20           | 10 / 30            |
| Merge 10 YES/NO pairs           | 80   | 20       | 20      | 20           | 0 / 20             |

The split reduces cash to 70, so the earlier 80-unit BUY is cancelled. After
the SELL reserves 20 YES, only 10 pairs are available to merge. Merging those
pairs returns 10 collateral units. It does not recreate the cancelled BUY.

Similarly, reducing cash from 100 to 70 through a withdrawal can cancel an
80-unit resting BUY commitment.

## Fee headroom [#fee-headroom]

An incoming LIMIT BUY must cover its limit notional plus the maximum
applicable taker fee. The extra headroom is an admission check, not an
immediate fee debit. Actual fees are charged on executions. A remainder that
rests contributes its remaining limit-price notional to the market commitment;
resting maker fills do not pay a maker fee.

Incoming post-only BUYs are subject to the same collateral admission check.

### Example 8: notional fits but the fee requirement does not [#example-8-notional-fits-but-the-fee-requirement-does-not]

Suppose cash is 100, the existing market commitment is 60, and a new GTC BUY
has notional 40. If that new order requires 0.50 in maximum fee headroom:

```text
60 + 40 + 0.50 = 100.50 > 100
```

The request fails the collateral check. Reduce its size, cancel another
commitment, or add sufficient collateral before submitting it again. The
0.50 is an illustrative fee requirement, not a published fee rate. See
[fee conventions](/conventions#fees).

## Reading balances and maintaining client state [#reading-balances-and-maintaining-client-state]

| API field or update      | How to use it                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------- |
| `cash_balance_micro`     | Current trading cash. Resting BUY commitments have not been subtracted.                               |
| `free_cash_micro`        | For AGARA, currently equals `cash_balance_micro`. It is not cash minus all open BUYs.                 |
| `shares_micro`           | Total shares held for an outcome, including shares reserved for SELLs.                                |
| `available_shares_micro` | Shares available after SELL reservations. Do not subtract those open SELL reservations a second time. |
| `fill`                   | Apply the executed quantity, price and fee once per `fill_id`.                                        |
| `order_cancelled`        | Remove only the unfilled commitment or reservation. Preserve completed fills.                         |

Use the [portfolio summary](/portfolio#summary),
[positions](/portfolio#positions) and complete
[order list](/orders#list-your-orders) together. A snapshot can lag recent
activity, and several requests can be in flight at once. Keep a local
allowance for submitted orders until their outcomes are known; the formulas
above describe trading checks, not a reservation created by reading REST.

Do not release a local allowance solely because an HTTP request timed out,
a read temporarily omitted an order, or a cancel request was sent. Resolve
the order and reconcile its fills first. Check `unavailable_exchanges` where
provided and retry incomplete AGARA reads, restarting paginated reads from
the first page.

For reconnects, uncertain responses and cancel-all timing, follow
[Order management](/best-practices/order-management). After an automatic
collateral cancellation, recompute the budget before placing another order;
adding funds does not automatically reopen the cancelled one.
