Skip to main content

​
Model

Total holdings = available + locked. unsettled and quarantined are reserved for future settlement modes and currently always zero.

​
Reading balances

Response:
All USDC amounts (available, unsettled, locked, quarantined) are decimal strings floored to 6 dp — USDC’s native on-chain precision. They are never 18-scale wei and never carry more than 6 fraction digits, so you can parse them directly as USDC units. The same 6-dp formatting applies to the cash breakdown in GET /api/me/overview.

​
How locked moves

SELL orders don’t move USDC balances — they reserve the outcome shares you are selling instead. After you place a SELL, your available and locked USDC are unchanged; what does change is the available-to-promise outcome-share balance for the underlying token. When the SELL fills on-chain, USDC proceeds land in available per the table above.Inspect outcome-share balances via GET /api/me/positions. Each position row carries three quantity fields:
  • quantity — mirror total (matches on-chain ERC-1155 balance). Use for “what do I own”.
  • availableQuantity — post-encumbrance, the amount you can currently sell or burn. Use for “what can I trade”.
  • encumberedQuantity — shares reserved by your open SELL orders and pending co-signed vault operations (such as a merge or convert) on the same (vault, tokenId). null when nothing has ever been reserved on that token. Read availableQuantity directly rather than computing quantity − encumberedQuantity: it is floored at 0.

​
Append-only ledger

Every balance change is recorded in an append-only balance-event ledger on the platform side. The conservation invariant holds for any (user, token): SUM(deltaAvailable) + SUM(deltaLocked) === current(available) + current(locked)
GET /api/me/balance-events returns the append-only ledger for the authenticated wallet, newest first, one page at a time (limit default 100, max 500). Pass the response’s nextCursor back as ?cursor= until it is null to walk the full history. Event id and orderId are UUIDs; tradeId is a numeric string:
reason is a machine-readable tag — for example deposit, lock, terminal_refund, withdrawal_lock, withdrawal_confirmed, chain_fill_settled_buyer_drain, chain_fill_settled_seller_credit, chain_match_failed_buyer_taker_refund, position_redeemed_credit. The list grows over time; treat unknown values as opaque. Pair with the WS vault_activity channel (on-chain fills, deposits, withdrawals and exchange_balance_synced balance updates for your vault) for live updates — the REST endpoint is the canonical reconciliation source after a reconnect or any time you need to walk history.