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:

​
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.

​
Getting testnet balance

The faucet is not an endpoint on the partner API surface. Mint testnet USDC by calling the MockCollateral contract’s public mint(address, uint256) method directly, or use the operator-run faucet web UI: After minting, deposit normally via vault.depositERC20(...) — the faucet flow does not credit /api/me/balances until you deposit. See Environments — getting testnet USDC for the full step-by-step.