> This page is for Taurus PRIME.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://taurushq.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://taurushq.ferndocs.com/_mcp/server.

# Wallet Information

# Funds and Wallet Information

This guide covers retrieving balance and wallet information for your sub-accounts.

## Overview

Wallet information is organized by sub-account (portfolio). Each sub-account maintains its own balances across multiple instruments.

## Prerequisites

* Authenticated session (JWT or API key)
* `CanRead` permission
* Access to at least one sub-account

## Step 1: List Your Sub-Accounts

First, retrieve the sub-accounts you have access to.

**Endpoint:** `GET /api/rest/v1/sub-accounts/mine`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/sub-accounts/mine" \
  -H "Authorization: Bearer <access-token>"
```

### Response (200 OK)

```json
{
  "result": [
    {
      "id": "7376524e-6b6b-4137-9719-7e07a7709804",
      "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
      "type": "TYPE_MAIN",
      "venue": "VENUE_MARKETPLACE",
      "name": "Main Trading Account",
      "pairs": [],
      "createdAt": "2023-06-01T10:00:00Z",
      "updatedAt": "2023-06-01T10:00:00Z"
    },
    {
      "id": "9e68ec8c-c978-4ea2-b511-98d4df38f353",
      "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
      "type": "TYPE_SUB",
      "venue": "VENUE_OTC",
      "name": "OTC Portfolio",
      "pairs": ["btc-chf-pair-uuid", "eth-chf-pair-uuid"],
      "createdAt": "2023-07-15T14:00:00Z",
      "updatedAt": "2023-07-15T14:00:00Z"
    }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "first": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "last": "",
      "next": "",
      "previous": ""
    }
  }
}
```

### Sub-Account Fields

| Field             | Type    | Description                             |
| ----------------- | ------- | --------------------------------------- |
| `id`              | UUID    | Unique identifier                       |
| `clientAccountId` | UUID    | Parent client account                   |
| `type`            | enum    | `TYPE_MAIN`, `TYPE_SUB`, `TYPE_CUSTODY` |
| `venue`           | enum    | `VENUE_MARKETPLACE` or `VENUE_OTC`      |
| `name`            | string  | Human-readable name                     |
| `pairs`           | \[]UUID | Allowed pair IDs (empty = all pairs)    |

## Step 2: Get Balances for a Sub-Account

Retrieve all balances for a specific sub-account.

**Endpoint:** `GET /api/rest/v1/balances/by-sub-account/{subAccountId}`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/balances/by-sub-account/7376524e-6b6b-4137-9719-7e07a7709804" \
  -H "Authorization: Bearer <access-token>"
```

### Query Parameters

This endpoint supports [standard pagination, sorting, and filtering](/prime/docs/api-gett-making-requests#pagination).

**Endpoint-specific parameters:**

| Parameter        | Type | Description                                   |
| ---------------- | ---- | --------------------------------------------- |
| `pnlQuotationId` | UUID | Instrument ID for P\&L calculation (optional) |

**Supported filters:** `instrument_id`, `exclude_zero_balances`

### Response (200 OK)

```json
{
  "result": [
    {
      "id": "cc452f44-718c-46ab-8fd7-682363d1ef04",
      "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
      "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
      "instrumentId": "7a3fae7e-5a17-4931-821c-54b021f643da",
      "available": "1.25000000",
      "ordersReserved": "0.25000000",
      "withdrawalsReserved": "0.00000000"
    },
    {
      "id": "dd563f55-829d-57bc-9ae8-793474e2fa15",
      "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
      "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
      "instrumentId": "8b4abf8f-6b28-5042-932d-65c132a754eb",
      "available": "45000.00",
      "ordersReserved": "5000.00",
      "withdrawalsReserved": "0.00"
    }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "first": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "last": "",
      "next": "",
      "previous": ""
    }
  }
}
```

### Balance Fields

| Field                 | Type               | Description                                 |
| --------------------- | ------------------ | ------------------------------------------- |
| `id`                  | UUID               | Balance identifier                          |
| `clientAccountId`     | UUID               | Client account ID                           |
| `subAccountId`        | UUID               | Sub-account ID                              |
| `instrumentId`        | UUID               | Instrument ID                               |
| `available`           | decimal            | Available for trading/withdrawal            |
| `ordersReserved`      | decimal            | Locked in open orders                       |
| `withdrawalsReserved` | decimal            | Locked in pending withdrawals               |
| `credit`              | decimal            | Amount owed by the sub-account              |
| `exposureOverdraft`   | decimal            | Amount that must be settled by the account  |
| `exposureReserved`    | decimal            | Amount requiring settlement after execution |
| `profitAndLoss`       | decimal (optional) | Percent change over the last day            |
| `createdAt`           | timestamp          | Creation time                               |
| `updatedAt`           | timestamp          | Last update time                            |

## Step 3: Get Specific Balance

Query a single balance by its ID.

**Endpoint:** `GET /api/rest/v1/balances/by-sub-account/{subAccountId}/{id}`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/balances/by-sub-account/7376524e-6b6b-4137-9719-7e07a7709804/cc452f44-718c-46ab-8fd7-682363d1ef04" \
  -H "Authorization: Bearer <access-token>"
```

### Response (200 OK)

```json
{
  "result": {
    "id": "cc452f44-718c-46ab-8fd7-682363d1ef04",
    "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
    "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
    "instrumentId": "7a3fae7e-5a17-4931-821c-54b021f643da",
    "available": "1.25000000",
    "ordersReserved": "0.25000000",
    "withdrawalsReserved": "0.00000000"
  }
}
```

## Step 4: Get Balance History

Retrieve historical movements for a specific balance.

**Endpoint:** `GET /api/rest/v1/balances/by-sub-account/{subAccountId}/{balanceId}/history`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/balances/by-sub-account/7376524e-6b6b-4137-9719-7e07a7709804/cc452f44-718c-46ab-8fd7-682363d1ef04/history" \
  -H "Authorization: Bearer <access-token>"
```

### Response (200 OK)

```json
{
  "result": [
    {
      "id": "history-uuid-1",
      "balanceId": "cc452f44-718c-46ab-8fd7-682363d1ef04",
      "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
      "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
      "instrumentId": "7a3fae7e-5a17-4931-821c-54b021f643da",
      "available": "1.20000000",
      "ordersReserved": "0.25000000",
      "withdrawalsReserved": "0.00000000",
      "credit": "0.00000000",
      "exposureOverdraft": "0.00000000",
      "exposureReserved": "0.00000000",
      "createdAt": "2024-01-15T12:00:00Z",
      "updatedAt": "2024-01-15T12:00:00Z"
    }
  ],
  "pagination": {
    "cursors": {
      "self": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "first": "eyJTb3J0cyI6W10sIkZpbHRlcnMiOltdLCJJc0ZpcnN0Ijp0cnVlfQ==",
      "last": "",
      "next": "",
      "previous": ""
    }
  }
}
```

### Balance History Fields

| Field                 | Type      | Description                                  |
| --------------------- | --------- | -------------------------------------------- |
| `id`                  | UUID      | Balance history identifier                   |
| `balanceId`           | UUID      | Parent balance ID                            |
| `clientAccountId`     | UUID      | Client account ID                            |
| `subAccountId`        | UUID      | Sub-account ID                               |
| `instrumentId`        | UUID      | Instrument ID                                |
| `available`           | decimal   | Available amount at this point               |
| `ordersReserved`      | decimal   | Orders reserved at this point                |
| `withdrawalsReserved` | decimal   | Withdrawals reserved at this point           |
| `credit`              | decimal   | Amount owed by the sub-account at this point |
| `exposureOverdraft`   | decimal   | Exposure overdraft at this point             |
| `exposureReserved`    | decimal   | Exposure reserved at this point              |
| `createdAt`           | timestamp | When this history entry was created          |
| `updatedAt`           | timestamp | When this history entry was updated          |

## Step 5: Get Historical Aggregates

Get aggregated balance snapshots over time for a sub-account.

**Endpoint:** `GET /api/rest/v1/balances/by-sub-account/{subAccountId}/histagg`

### Request

```bash
curl -X GET "https://api.t-dx.com/api/rest/v1/balances/by-sub-account/7376524e-6b6b-4137-9719-7e07a7709804/histagg?quotationId=chf-instrument-uuid&from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer <access-token>"
```

### Query Parameters

| Parameter     | Type      | Required | Description                                  |
| ------------- | --------- | -------- | -------------------------------------------- |
| `quotationId` | UUID      | Yes      | Instrument ID for valuation (e.g., CHF, USD) |
| `from`        | timestamp | Yes      | Start of time range                          |
| `to`          | timestamp | Yes      | End of time range                            |

### Response (200 OK)

```json
{
  "result": [
    {
      "periodStartDate": "2024-01-01T00:00:00Z",
      "value": "100000.00"
    },
    {
      "periodStartDate": "2024-01-15T00:00:00Z",
      "value": "150000.00"
    }
  ]
}
```

### Aggregate Fields

| Field             | Type      | Description                        |
| ----------------- | --------- | ---------------------------------- |
| `periodStartDate` | timestamp | Start of the aggregation period    |
| `value`           | decimal   | Total portfolio value at this time |

## Error Scenarios

| Status | Code                | Description                      |
| ------ | ------------------- | -------------------------------- |
| 401    | `UNAUTHENTICATED`   | Invalid or expired token         |
| 403    | `PERMISSION_DENIED` | No access to sub-account         |
| 404    | `NOT_FOUND`         | Sub-account or balance not found |

## Related

* [Trading Data](/prime/docs/api-usec-04-trading-data) - Market data and trading information
* [Deposits & Withdrawals](/prime/docs/api-usec-06-deposits-withdrawals) - Managing deposits and withdrawals
* [Domains: Assets](/prime/docs/api-doma-asse-assets) - Instrument and balance documentation