Tutorials
Protect & CapitalExplorerPrimeUser & Technical Guides
Start typing to search…

Wallet Information

Querying balances and holdings for your sub-accounts

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

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

Response (200 OK)

{
  "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

FieldTypeDescription
idUUIDUnique identifier
clientAccountIdUUIDParent client account
typeenumTYPE_MAIN, TYPE_SUB, TYPE_CUSTODY
venueenumVENUE_MARKETPLACE or VENUE_OTC
namestringHuman-readable name
pairs[]UUIDAllowed 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

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.

Endpoint-specific parameters:

ParameterTypeDescription
pnlQuotationIdUUIDInstrument ID for P&L calculation (optional)

Supported filters: instrument_id, exclude_zero_balances

Response (200 OK)

{
  "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

FieldTypeDescription
idUUIDBalance identifier
clientAccountIdUUIDClient account ID
subAccountIdUUIDSub-account ID
instrumentIdUUIDInstrument ID
availabledecimalAvailable for trading/withdrawal
ordersReserveddecimalLocked in open orders
withdrawalsReserveddecimalLocked in pending withdrawals
creditdecimalAmount owed by the sub-account
exposureOverdraftdecimalAmount that must be settled by the account
exposureReserveddecimalAmount requiring settlement after execution
profitAndLossdecimal (optional)Percent change over the last day
createdAttimestampCreation time
updatedAttimestampLast 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

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)

{
  "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

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)

{
  "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

FieldTypeDescription
idUUIDBalance history identifier
balanceIdUUIDParent balance ID
clientAccountIdUUIDClient account ID
subAccountIdUUIDSub-account ID
instrumentIdUUIDInstrument ID
availabledecimalAvailable amount at this point
ordersReserveddecimalOrders reserved at this point
withdrawalsReserveddecimalWithdrawals reserved at this point
creditdecimalAmount owed by the sub-account at this point
exposureOverdraftdecimalExposure overdraft at this point
exposureReserveddecimalExposure reserved at this point
createdAttimestampWhen this history entry was created
updatedAttimestampWhen 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

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

ParameterTypeRequiredDescription
quotationIdUUIDYesInstrument ID for valuation (e.g., CHF, USD)
fromtimestampYesStart of time range
totimestampYesEnd of time range

Response (200 OK)

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

Aggregate Fields

FieldTypeDescription
periodStartDatetimestampStart of the aggregation period
valuedecimalTotal portfolio value at this time

Error Scenarios

StatusCodeDescription
401UNAUTHENTICATEDInvalid or expired token
403PERMISSION_DENIEDNo access to sub-account
404NOT_FOUNDSub-account or balance not found

Related

Updated 5 days ago



  © 2025 Taurus SA. All rights reserved.