Agara

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.

ResourceWhat an open order doesWhat changes on execution
BUY collateralAdds 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 sharesReserves 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

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

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:

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

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

StepCash balanceRemaining BUY quantityBUY commitmentCapacity for another GTC/GTD BUY in this market, before fees
Before placement10000100
Order rests1001006040
40 shares fill at 0.6076603640
Cancellation of the remaining 60 is confirmed760076

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

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

Additional GTC BUYExisting commitmentNew notionalTotal requiredCollateral check
100 NO at 0.506050110Reject
80 NO at 0.506040100Pass

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

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

MarketOrderMarket commitment
ABUY 100 YES at 0.9090
BBUY 100 YES at 0.4040

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

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

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

OrderRemaining quantityLimit priceRemaining notional
A11000.4040
A21000.3030
A31000.2020

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

ActionRemaining Market A commitmentWithin the 60-unit balance?
Before cancellation90No
Cancel A3, removing 2070No
Cancel A2, removing 3040Yes

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

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

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.

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

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

StepHeld YESReserved YESAvailable YES
Before placement1000100
SELL rests1007030
20 shares fill805030
Remaining 50 are cancelled80080

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

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 for those operation states.

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:

StepCashHeld YESHeld NOReserved YESAvailable YES / NO
Initial state1000000 / 0
Split 30 collateral units703030030 / 30
Place a resting SELL for 20 YES7030302010 / 30
Merge 10 YES/NO pairs802020200 / 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

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

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:

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.

Reading balances and maintaining client state

API field or updateHow to use it
cash_balance_microCurrent trading cash. Resting BUY commitments have not been subtracted.
free_cash_microFor AGARA, currently equals cash_balance_micro. It is not cash minus all open BUYs.
shares_microTotal shares held for an outcome, including shares reserved for SELLs.
available_shares_microShares available after SELL reservations. Do not subtract those open SELL reservations a second time.
fillApply the executed quantity, price and fee once per fill_id.
order_cancelledRemove only the unfilled commitment or reservation. Preserve completed fills.

Use the portfolio summary, positions and complete order list 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. After an automatic collateral cancellation, recompute the budget before placing another order; adding funds does not automatically reopen the cancelled one.