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 encumber the outcome shares in vault_erc1155_locks 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 now 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 — sum of open SELL orders’ unfilled quantity + active signedOp locks for the same (vault, tokenId). Always equals quantity − availableQuantity.

​
Append-only ledger

Every balance change is mirrored to an append-only balance_events table 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 full append-only ledger for the authenticated wallet:
reason is one of lock, terminal_refund, withdrawal_confirmed, match_failed_refund, fee_settled, plus a few internal kinds. Pair with the WS vault_positions channel for live deltas — the REST endpoint is the canonical reconciliation source after a reconnect or any time you need to walk history.