Get Account Balance Information

Retrieve account balances across all account groups (sub-accounts). Returns balances for each currency held within each account group, along with balance buckets.

⚠️
Recommendation: Always include filterZeroBalanceAccounts: true in your request body. Without this filter, the response returns all supported currencies (100+), most with zero balances. Filtering significantly reduces response size and improves readability.

⚠️
Deprecation Notice: The Wallets and Secondary_Wallets fields in the response are legacy and should no longer be used. Retrieve balances from the Account_Groups array instead, which provides balances broken down by account group.

Request

Body Parameters

Parameter	Type	Required	Default	Description
filterZeroBalanceAccounts	Boolean	No	false	When true, only returns currencies with non-zero balances. Strongly recommended.
accountGroupUuid	String	No	-	Filter results to a specific account group (sub-account) UUID

Example Request

Recommended (filtered):

{
  "filterZeroBalanceAccounts": true
}

Filter by account group:

{
  "filterZeroBalanceAccounts": true,
  "accountGroupUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8"
}

Response

Success Response (200 OK)

{
  "data": {
    "Created": "2025-02-12 09:39:19",
    "Language": "en_US",
    "Login": "user@example.com",
    "Rights": [
      "trade",
      "withdraw",
      "get_info"
    ],
    "Wallets": {},
    "Secondary_Wallets": {},
    "Account_Groups": [
      {
        "AccountGroup_Uuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
        "AccountGroup_Name": "Default",
        "Owner_Uuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
        "Owner_Name": "user@example.com",
        "Owner_Shortcode": "CLIENTCODE",
        "Natural": true,
        "Accounts": {
          "BTC": {
            "Balance": {
              "displayShort": "2.34 BTC",
              "valueInt": "233581881",
              "currency": "BTC",
              "display": "2.33581881 BTC",
              "value": "2.33581881"
            },
            "Available_Balance": {
              "displayShort": "0.00 BTC",
              "valueInt": "0",
              "currency": "BTC",
              "display": "0.00000000 BTC",
              "value": "0.00000000"
            },
            "Brokerage_Available_Balance": {
              "displayShort": "0.01 BTC",
              "valueInt": "1000000",
              "currency": "BTC",
              "display": "0.01000000 BTC",
              "value": "0.01000000"
            },
            "Unsettled_Sell_Balance": {
              "displayShort": "0.13 BTC",
              "valueInt": "12769904",
              "currency": "BTC",
              "display": "0.12769904 BTC",
              "value": "0.12769904"
            },
            "Unsettled_Buy_Balance": {
              "displayShort": "2.45 BTC",
              "valueInt": "245351785",
              "currency": "BTC",
              "display": "2.45351785 BTC",
              "value": "2.45351785"
            },
            "ccy": "BTC",
            "Owner_Uuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
            "Uuid": "3c8c14ac-a8a6-4052-8857-c35719a189bf"
          },
          "USDC": {
            "Balance": {
              "displayShort": "430,094.49 USDC",
              "valueInt": "43009448630600",
              "currency": "USDC",
              "display": "430,094.48630600 USDC",
              "value": "430094.48630600"
            },
            "Available_Balance": {
              "displayShort": "0.00 USDC",
              "valueInt": "0",
              "currency": "USDC",
              "display": "0.00000000 USDC",
              "value": "0.00000000"
            },
            "Brokerage_Available_Balance": {
              "displayShort": "78,834.01 USDC",
              "valueInt": "7883400788000",
              "currency": "USDC",
              "display": "78,834.00788000 USDC",
              "value": "78834.00788000"
            },
            "Unsettled_Sell_Balance": {
              "displayShort": "10,000.00 USDC",
              "valueInt": "1000000000000",
              "currency": "USDC",
              "display": "10,000.00000000 USDC",
              "value": "10000.00000000"
            },
            "Unsettled_Buy_Balance": {
              "displayShort": "361,260.48 USDC",
              "valueInt": "36126047842600",
              "currency": "USDC",
              "display": "361,260.47842600 USDC",
              "value": "361260.47842600"
            },
            "ccy": "USDC",
            "Owner_Uuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
            "Uuid": "3bce6bba-2cc1-4590-b1fa-f659febde4cc"
          }
        }
      },
      {
        "AccountGroup_Uuid": "afe6280e-163a-4652-a795-34e963063b06",
        "AccountGroup_Name": "SubAccount1",
        "Owner_Uuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
        "Owner_Name": "user@example.com",
        "Owner_Shortcode": "CLIENTCODE",
        "Natural": false,
        "Accounts": {
          "HKD": {
            "Balance": {
              "displayShort": "32,714.08 HKD",
              "valueInt": "3271408000",
              "currency": "HKD",
              "display": "32,714.08000 HKD",
              "value": "32714.08000"
            },
            "Available_Balance": {
              "displayShort": "0.00 HKD",
              "valueInt": "0",
              "currency": "HKD",
              "display": "0.00000 HKD",
              "value": "0.00000"
            },
            "Brokerage_Available_Balance": {
              "displayShort": "16,357.04 HKD",
              "valueInt": "1635704000",
              "currency": "HKD",
              "display": "16,357.04000 HKD",
              "value": "16357.04000"
            },
            "Unsettled_Sell_Balance": {
              "displayShort": "0.00 HKD",
              "valueInt": "0",
              "currency": "HKD",
              "display": "0.00000 HKD",
              "value": "0.00000"
            },
            "Unsettled_Buy_Balance": {
              "displayShort": "16,357.04 HKD",
              "valueInt": "1635704000",
              "currency": "HKD",
              "display": "16,357.04000 HKD",
              "value": "16357.04000"
            },
            "ccy": "HKD",
            "Owner_Uuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8",
            "Uuid": "eae35b24-14fe-4210-ac87-618fb3da7613"
          }
        }
      }
    ]
  },
  "userUuid": "db25fe1f-4be3-4a30-bed4-456a8e82a9b0",
  "timestamp": "1770888183656",
  "resultCode": "OK"
}

Response Fields

Root Object

Field	Type	Description
data	Object	Account data container
userUuid	String	Unique identifier for the API user
timestamp	String	Unix timestamp of the response (milliseconds)
resultCode	String	Result status (`OK` on success)

Data Object

Field	Type	Description
Created	String	Account creation date
Language	String	Account language locale
Login	String	API user login email
Rights	Array	List of permissions on the API user: `trade`, `withdraw`, `get_info`
Wallets	Object	⚠️ Legacy — do not use. Use `Account_Groups` instead.
Secondary_Wallets	Object	⚠️ Legacy — do not use. Use `Account_Groups` instead.
Account_Groups	Array	Array of account group objects containing balances

Account Group Object

Field	Type	Description
AccountGroup_Uuid	String	Unique identifier for the account group
AccountGroup_Name	String	Account group name (e.g., "Default", sub-account names)
Owner_Uuid	String	UUID of the account owner
Owner_Name	String	Owner (Parent) email address
Owner_Shortcode	String	Client shortcode identifier
Natural	Boolean	`true` for the primary (default) account group, `false` for sub-accounts
Accounts	Object	Map of currency codes to account balance objects

Account Balance Object

Each currency within an account group contains the following balance fields:

Field	Type	Description
Balance	Object	Total balance including unsettled amounts
Available_Balance	Object	Balance available for withdrawal
Brokerage_Available_Balance	Object	Balance available for trading
Unsettled_Sell_Balance	Object	Pending sell trade amounts awaiting settlement
Unsettled_Buy_Balance	Object	Pending buy trade amounts awaiting settlement
ccy	String	Currency code
Owner_Uuid	String	UUID of the account owner
Uuid	String	Unique identifier for this account

Balance Detail Object

Each balance field (Balance, Available_Balance, etc.) contains:

Field	Type	Description
displayShort	String	Abbreviated formatted balance (e.g., `"2.34 BTC"`)
valueInt	String	Integer representation of the balance (smallest unit)
currency	String	Currency code
display	String	Full precision formatted balance (e.g., `"2.33581881 BTC"`)
value	String	Decimal string value of the balance

Understanding Balance Types

Balance Type	Description
Balance	Total balance across all states. Includes unsettled amounts.
Available_Balance	Funds available for immediate withdrawal.
Brokerage_Available_Balance	Funds available for placing new trades.
Unsettled_Sell_Balance	Amount pending from sell trades not yet settled.
Unsettled_Buy_Balance	Amount pending from buy trades not yet settled.

Note: Balance = settled funds + Unsettled_Buy_Balance - Unsettled_Sell_Balance. Negative balances on unsettled balances indicate unsettled obligations (i.e. trade is unsettled)

Account Groups (Sub-Accounts)

Balances are organised by account group (optional). Each account group represents either the primary account or a sub-account. All users will always have a 'Default' account group and can optionally request additional sub-accounts to split their balances.

Field Value	Meaning
Natural: true	Primary (default) account group
Natural: false	Sub-account

Code Examples

Python

import json
import hmac
import hashlib
import time
import requests

# Configuration
api_key = "your_api_key"
api_secret = "your_api_secret"
base_url = "https://trade-uk.sandbox.zodiamarkets.com"

# Request body
body = {
    "filterZeroBalanceAccounts": true
}
body_json = json.dumps(body)

# Generate signature
path = "api/3/account"
tonce = str(int(time.time() * 1000000))
message = f"{path}\0{body_json}"
signature = hmac.new(
    api_secret.encode(),
    message.encode(),
    hashlib.sha512
).hexdigest()

# Make request
headers = {
    "Rest-Key": api_key,
    "Rest-Sign": signature,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{base_url}/{path}",
    headers=headers,
    data=body_json
)

# Process response
if response.status_code == 200:
    data = response.json()
    for group in data['data']['Account_Groups']:
        print(f"\nAccount Group: {group['AccountGroup_Name']} ({'Primary' if group['Natural'] else 'Sub-account'})")
        print(f"  UUID: {group['AccountGroup_Uuid']}")
        for ccy, account in group['Accounts'].items():
            print(f"  {ccy}:")
            print(f"    Balance: {account['Balance']['display']}")
            print(f"    Available for Trading: {account['Brokerage_Available_Balance']['display']}")
            print(f"    Unsettled Buy: {account['Unsettled_Buy_Balance']['display']}")
            print(f"    Unsettled Sell: {account['Unsettled_Sell_Balance']['display']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

JavaScript (Node.js)

const crypto = require('crypto');
const axios = require('axios');

// Configuration
const apiKey = 'your_api_key';
const apiSecret = 'your_api_secret';
const baseUrl = 'https://trade-uk.sandbox.zodiamarkets.com';

// Request body
const body = {
  filterZeroBalanceAccounts: true
};
const bodyJson = JSON.stringify(body);

// Generate signature
const path = 'api/3/account';
const tonce = Date.now() * 1000;
const message = `${path}\0${bodyJson}`;
const signature = crypto
  .createHmac('sha512', apiSecret)
  .update(message)
  .digest('hex');

// Make request
const headers = {
  'Rest-Key': apiKey,
  'Rest-Sign': signature,
  'Content-Type': 'application/json'
};

axios.post(`${baseUrl}/${path}`, body, { headers })
  .then(response => {
    response.data.data.Account_Groups.forEach(group => {
      const type = group.Natural ? 'Primary' : 'Sub-account';
      console.log(`\nAccount Group: ${group.AccountGroup_Name} (${type})`);
      console.log(`  UUID: ${group.AccountGroup_Uuid}`);
      Object.entries(group.Accounts).forEach(([ccy, account]) => {
        console.log(`  ${ccy}:`);
        console.log(`    Balance: ${account.Balance.display}`);
        console.log(`    Available for Trading: ${account.Brokerage_Available_Balance.display}`);
      });
    });
  })
  .catch(error => {
    console.error('Error:', error.response?.status);
    console.error(error.response?.data);
  });

cURL

curl -X POST https://trade-uk.sandbox.zodiamarkets.com/api/3/account \
  -H "Rest-Key: your_api_key" \
  -H "Rest-Sign: your_hmac_signature" \
  -H "Content-Type: application/json" \
  -d '{
    "filterZeroBalanceAccounts": true
  }'

Common Use Cases

Get Balances for a Specific Account Group

response = make_api_request('POST', 'api/3/account', {
    'filterZeroBalanceAccounts': true,
    'accountGroupUuid': '2073252c-81ed-41be-bf4d-d51b8f2246b8'
})

for group in response['data']['Account_Groups']:
    for ccy, account in group['Accounts'].items():
        print(f"{ccy}: {account['Balance']['display']}")

Check Available Trading Balance

response = make_api_request('POST', 'api/3/account', {
    'filterZeroBalanceAccounts': true
})

for group in response['data']['Account_Groups']:
    print(f"\n{group['AccountGroup_Name']}:")
    for ccy, account in group['Accounts'].items():
        brokerage = float(account['Brokerage_Available_Balance']['value'])
        if brokerage > 0:
            print(f"  {ccy}: {account['Brokerage_Available_Balance']['display']} available for trading")

Find All Sub-Accounts with Balances

response = make_api_request('POST', 'api/3/account', {
    'filterZeroBalanceAccounts': true
})

sub_accounts = [
    group for group in response['data']['Account_Groups']
    if not group['Natural']
]

for group in sub_accounts:
    print(f"\nSub-account: {group['AccountGroup_Name']}")
    print(f"  UUID: {group['AccountGroup_Uuid']}")
    for ccy, account in group['Accounts'].items():
        print(f"  {ccy}: {account['Balance']['display']}")

Get Total Balance Across All Account Groups

from collections import defaultdict

response = make_api_request('POST', 'api/3/account', {
    'filterZeroBalanceAccounts': true
})

totals = defaultdict(float)
for group in response['data']['Account_Groups']:
    for ccy, account in group['Accounts'].items():
        totals[ccy] += float(account['Balance']['value'])

for ccy, total in sorted(totals.items()):
    print(f"{ccy}: {total}")