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

# Balances & transfers

> How funds are organized into wallet, perps, options, and spot buckets on OCX, and how to deposit, transfer, and withdraw.

Your account funds are held as **USDC** and organized into four **buckets**. Funds only ever move by an explicit action — depositing, withdrawing, or transferring between buckets. There are no hidden cross-bucket sweeps.

## The four buckets

| Bucket    | Purpose                                                                              |
| --------- | ------------------------------------------------------------------------------------ |
| `wallet`  | Settlement bucket. Deposits land here, and **withdrawals are drawn only from here**. |
| `perps`   | Collateral available to the perpetuals and dated-futures venue.                      |
| `options` | Collateral available to the options venue.                                           |
| `spot`    | Per-asset spot inventory (USDC plus any traded assets).                              |

Trading in a venue draws on that venue's bucket. You fund a venue by transferring `wallet → perps`, `wallet → options`, or `wallet → spot`, and you free up funds for withdrawal by transferring back to `wallet` first.

<Note>
  All balance and settlement endpoints require an authenticated session. See [Authentication](/getting-started/authentication).
</Note>

## Check your balances

```bash theme={null}
curl -b cookies.txt "https://<api-host>/wallet/balance"
```

```json theme={null}
{
  "onchainDepositTotal": "0",
  "walletBalance": "0",
  "perpsBalance": "0",
  "optionsBalance": "0",
  "pendingWithdrawalTotal": "0"
}
```

<ResponseField name="walletBalance" type="string">
  USDC in the settlement bucket — the only bucket you can withdraw from.
</ResponseField>

<ResponseField name="perpsBalance / optionsBalance" type="string">
  Collateral currently allocated to each trading venue.
</ResponseField>

<ResponseField name="pendingWithdrawalTotal" type="string">
  Amount debited from `wallet` and awaiting on-chain settlement.
</ResponseField>

Per-asset spot inventory is separate:

```bash theme={null}
curl -b cookies.txt "https://<api-host>/wallet/assets"
# -> [{ "asset": "...", "bucket": "spot", "available": "...", "locked": "...", "total": "..." }, ...]
```

## The money lifecycle

<Steps>
  <Step title="Deposit on-chain">
    Send USDC to your OCX deposit address on the supported network. The exchange watches the chain and credits your `wallet` bucket only after the deposit reaches the required number of confirmations (reorg-safe). Until confirmed, a deposit shows as pending and is not spendable. Each on-chain transaction is credited exactly once.
  </Step>

  <Step title="Transfer into a venue">
    Move funds from `wallet` into `perps`, `options`, or `spot` to trade there.
  </Step>

  <Step title="Trade">
    Place orders — collateral is drawn from the relevant venue bucket.
  </Step>

  <Step title="Transfer back and withdraw">
    Return funds to `wallet`, then request an on-chain withdrawal.
  </Step>
</Steps>

## Transfer between buckets

```bash theme={null}
curl -b cookies.txt -X POST "https://<api-host>/wallet/transfer" \
  -H "Content-Type: application/json" \
  -d '{ "from": "wallet", "to": "perps", "amount": "100" }'
```

```json theme={null}
{ "walletBalance": "1500.00", "perpsBalance": "500.00", "optionsBalance": "0" }
```

<ParamField body="from" type="string" required>
  Source bucket — one of `wallet`, `perps`, `options`, `spot`.
</ParamField>

<ParamField body="to" type="string" required>
  Destination bucket, distinct from `from`.
</ParamField>

<ParamField body="amount" type="string" required>
  Positive amount, no greater than the source bucket's available balance.
</ParamField>

Transfers are **atomic** and double-entry ledgered — a matching debit and credit — so bucket balances are always reconstructable from history.

## Withdraw

```bash theme={null}
curl -b cookies.txt -X POST "https://<api-host>/wallet/withdraw" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "50" }'
```

```json theme={null}
{ "withdrawalId": "..." }
```

<Warning>
  Withdrawals draw **only** from the `wallet` bucket. If your funds are in `perps`, `options`, or `spot`, transfer them back to `wallet` first — otherwise the request is rejected. The amount is immediately debited from `wallet` into `pendingWithdrawalTotal`, and the on-chain payout is processed asynchronously.
</Warning>

## History and settlement tracking

<CodeGroup>
  ```bash Ledger history theme={null}
  curl -b cookies.txt "https://<api-host>/wallet/history"
  ```

  ```bash Settlements theme={null}
  curl -b cookies.txt "https://<api-host>/wallet/settlements?kind=withdraw&status=confirmed&limit=100"
  ```

  ```bash One settlement theme={null}
  curl -b cookies.txt "https://<api-host>/wallet/settlements/<id>"
  ```
</CodeGroup>

Settlement `status` values you may see: `pending`, `processing`, `sent`, `confirmed`, `failed`, `insufficient_liquidity`.

<Tip>
  For live account updates, subscribe to the [portfolio balances stream](/api-reference/streaming) instead of polling — it pushes a snapshot on connect and an update whenever your cross-bucket balances change.
</Tip>