Account Groups

Retrieve the list of account groups (sub-accounts) associated with your authenticated user. Account group UUIDs are required when placing orders. Typically most setups will have a single 'default' account group but some setups may have multiple account groups that allow Zodia Markets clients to have multiple 'funds' setup to segregate their trading activity and funding.

Use this message to get your account group UUID for order placement

Request Message

Send this message to request your account groups:

{
    "messageType": "accountGroups"
}

Request Fields

Field	Required	Type	Description
`messageType`	Yes	String	Must be `accountGroups`

Response Message Example

{
    "chanId": "",
    "timestamp": 1728374758421,
    "messageType": "accountGroups",
    "message": "",
    "code": "",
    "accountGroups": [
        {
            "uuid": "dcbb114e-8dfe-4eb8-9a6a-f267b7980b34",
            "name": "Default"
        },
        {
            "uuid": "7f6d661d-f45f-4dde-8633-749c709a724e",
            "name": "Subaccount_1"
        }
    ]
}

Response Fields

Field	Required	Type	Description
`chanId`	No	String	Channel identifier (reserved for future use)
`timestamp`	Yes	Long	Unix timestamp in milliseconds
`messageType`	Yes	String	Always `accountGroups`
`message`	Yes	String	Human-readable message (empty on success)
`code`	Yes	String	Error code (empty on success)
`accountGroups`	No	Array	List of account groups (absent on error)

Account Group Object

Each account group in the array contains:

Field	Required	Type	Description
`uuid`	Yes	String	Unique identifier for the account group - to be sent on subscription and order messages
`name`	Yes	String	Display name of the account group

Usage Examples

Python

import json

# Send account groups request
request = {
    "messageType": "accountGroups"
}
ws.send(json.dumps(request))

# Handle response
response = json.loads(ws.recv())

if response['code'] == '':
    # Success - store account groups
    account_groups = response['accountGroups']
    
    print("Available account groups:")
    for group in account_groups:
        print(f"  {group['name']}: {group['uuid']}")
    
    # Use the default account for trading
    default_account = account_groups[0]['uuid']
else:
    # Error occurred
    print(f"Error: {response['message']} (Code: {response['code']})")

Example - Store for Order Placement

Cache the account group UUIDs for use in order requests:

# Global account groups cache
ACCOUNT_GROUPS = {}

def handle_account_groups_response(response):
    """Store account groups for order placement"""
    global ACCOUNT_GROUPS
    
    for group in response['accountGroups']:
        ACCOUNT_GROUPS[group['name']] = group['uuid']
    
    print(f"Loaded {len(ACCOUNT_GROUPS)} account groups")

def place_order(side, quantity, account_name='Default'):
    """Place order using cached account group UUID"""
    account_uuid = ACCOUNT_GROUPS.get(account_name)
    
    if not account_uuid:
        raise ValueError(f"Account group '{account_name}' not found")
    
    order = {
        "messageType": "order",
        "accountGroupUuid": account_uuid,
        "side": side,
        "quantity": quantity,
        # ... other fields
    }
    ws.send(json.dumps(order))

// Global account groups cache
const accountGroups = {};

function handleAccountGroupsResponse(response) {
    // Store account groups for order placement
    response.accountGroups.forEach(group => {
        accountGroups[group.name] = group.uuid;
    });
    
    console.log(`Loaded ${Object.keys(accountGroups).length} account groups`);
}

function placeOrder(side, quantity, accountName = 'Default') {
    // Place order using cached account group UUID
    const accountUuid = accountGroups[accountName];
    
    if (!accountUuid) {
        throw new Error(`Account group '${accountName}' not found`);
    }
    
    const order = {
        messageType: 'order',
        accountGroupUuid: accountUuid,
        side: side,
        quantity: quantity,
        // ... other fields
    };
    ws.send(JSON.stringify(order));
}

Understanding Account Groups

Default Account

Every user has at least one account group named "Default". This is your primary trading account.

'Sub Account' Account Groups

Sub accounts allow you to:

Segregate funds for different strategies or purposes
Fund accounts separately
Request settlement grouped by sub accounts.
Manage team member access (i.e, Trader A could have access to Account Group 1 and 2, whilst Trader B only has access to Account Group 2)

Account Group Scope

When you place an order, you must specify which account group to use:

{
    "messageType": "order",
    "accountGroupUuid": "dcbb114e-8dfe-4eb8-9a6a-f267b4980b34",
    "side": "BUY",
    "quantity": "1.5",
    ...
}

Trades and balances are isolated per account group.

Notes

Account groups can only be configured on request to your Relationship Manager
API keys may have access to a subset of all account groups. The user creating the API key should have access to all Account Groups required.