Positions

Outcome tokens enter or leave your account through trading or two explicit position operations:

• Split locks collateral and mints one unit of each binary outcome per collateral unit.
• Merge burns equal quantities of both outcomes and returns collateral.

Every AGARA market is binary. Neg-risk events group binary member markets; a member uses the same split and merge paths as a standalone market.

Split and merge are refused after a market is resolved. Supported standalone markets use automatic redemption after resolution.

Asynchronous lifecycle

For an AGARA market, both endpoints return 201 with an account-batch hash:

{
  "batch_hash": "0x2174…",
  "status": "PENDING",
  "as_of": "2026-07-20T11:00:00.000Z"
}

Poll GET /trade/v1/batches/{batch_hash}. PENDING means only that the request was accepted. SETTLED means the operation succeeded. For an isolated FAILED batch, do not reuse provisional inventory until unwound_at is set. FAILED_DIVERGENT requires review: keep mutations paused. A higher batch closed after a lower FAILED_DIVERGENT batch is a further exception: its unwound_at alone does not prove inventory was restored. Follow the stranded-sequence recovery rule.

Operations queue per account and run in the order you started them, so a second split, merge, or withdrawal is accepted while the first is still settling. The queue has a limit; past it you get a 409 until one finishes.

Neither request has a client idempotency key. If a response is lost, the batch may exist but you also lose its server-generated batch_hash. Treat the outcome as unknown and do not resubmit automatically. Pause position mutations for that market and reconcile the account stream, positions, and portfolio summary. Do not trust a positions response while unavailable_exchanges includes AGARA; retry that read before using it as evidence. If the outcome remains uncertain, retain the request time and any request_id for investigation.

Split

POST /trade/v1/portfolio/positions/split

{
  "condition_id": "0x2174…",
  "collateral_amount_micro": "10000000"
}

collateral_amount_micro must be positive. 10000000 locks ten collateral units and mints ten units of each outcome.

Merge

POST /trade/v1/portfolio/positions/merge

{
  "condition_id": "0x2174…",
  "shares_micro": "5000000"
}

shares_micro is burned from each outcome. 5000000 burns five units of both legs and returns five collateral units. Merge converts a complete pair at one collateral unit per pair; it does not use the orderbook midpoint.

If you split 100 units and later sell 50 units of each outcome, the remaining 50-unit complete pair can be merged. A single unmatched outcome cannot be merged alone.

Errors

This table is the AGARA request contract. Do not apply its retry guidance to a condition served by another exchange.

This table covers the immediate HTTP response. After a 201, poll the batch: a later terminal failure can report insufficient_shares or another account-batch failure.

Cross-match settlement

Position tokens can also be created or burned when orders match:

The fill's settlement_mode reports the path. SELL orders always require and reserve actual outcome shares; complementary BUY orders can create inventory from collateral during a match.