> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adipredictstreet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Balances

> available + locked columns, append-only ledger, and how to read them.

## Model

```typescript theme={null}
interface Balance {
  token: string;
  available: string;
  unsettled: string;
  locked: string;
  quarantined: string;
}
```

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

## Reading balances

```http theme={null}
GET /api/me/balances
X-Api-Key: ps_live_<keyId>_<secret>  # integrators — needs `portfolio:read`
```

Response:

```json theme={null}
{
  "walletAddress": "0x...",
  "balances": [
    { "token": "USDC", "available": "1248.22", "unsettled": "0", "locked": "75.00", "quarantined": "0" }
  ]
}
```

<Note>
  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`.
</Note>

## How `locked` moves

| Event                          |   `available`   |  `locked` |
| ------------------------------ | :-------------: | :-------: |
| Order placed (BUY)             |    -notional    | +notional |
| Order placed (SELL)            |        0        |     0     |
| Order cancelled                |    +residual    | -residual |
| Trade executed (BUY)           |        0        | -notional |
| Trade executed (SELL)          | +proceeds − fee |     0     |
| Order rejected                 |      +full      |   -full   |
| Market resolved                |    +residual    | -residual |
| Withdrawal requested           |     -amount     |  +amount  |
| Withdrawal confirmed on-chain  |        0        |  -amount  |
| Withdrawal rejected / reverted |     +amount     |  -amount  |

<Note>
  **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`.
</Note>

## 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)`

<Tip>
  **`GET /api/me/balance-events`** returns the full append-only ledger
  for the authenticated wallet:

  ```json theme={null}
  {
    "walletAddress": "0x...",
    "events": [
      {
        "id": "evt-...",
        "token": "USDC",
        "deltaAvailable": "-5.000000",
        "deltaLocked": "5.000000",
        "reason": "lock",
        "orderId": "ord-...",
        "tradeId": null,
        "createdAt": "2026-04-30T12:34:56.789Z"
      }
    ]
  }
  ```

  `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.
</Tip>