Account Groups Message

Request list of Account Groups (Sub Accounts) under the authenticated user

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:

Request Fields

Field	Type	Required	Description
messageType	string	yes	Must be accountGroups. The message carries nothing else — the groups returned are those of the authenticated user on this connection, and there is no way to ask for another user’s.

---

Response Message Example

Response Fields

Field	Type	Required	Description
timestamp	integer (int64)	yes	Unix epoch milliseconds, UTC — when this message was built. The underlying list is cached briefly, so a group added moments ago may not appear immediately.
messageType	string	yes	Always accountGroups.
message	string	yes	Empty on success. On failure, the fixed sentence Please contact your desk support. — the cause is not disclosed here.
code	string	yes	Empty on success, RFS100016 on failure. Because an empty list is itself treated as a failure, this is the field to check: if it is set, the list below is empty and you should not conclude from it that you have no account groups.
accountGroups	array of object		Your account groups. Always present — an empty array on failure, never omitted. An empty array is never a successful answer: if we cannot reach the source, or it returns nothing, the response is marked failed with RFS100016 and the array comes back empty, so the two cases are indistinguishable from the wire. Retry rather than treating an empty list as authoritative.
accountGroups[].uuid	string	yes	The account group’s UUID — the value to send as accountGrpUuid on subscribe and order. It selects the spread, credit limit and trading permissions applied, so it decides both the price you are quoted and whether the request is permitted at all.
accountGroups[].name	string	yes	The label configured for the group, for display and reconciliation. It has no meaning to the protocol — never send it where a uuid is expected — and it can be changed without the uuid changing.

---

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:

Python

Python

# 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))

JavaScript

JavaScript

// 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.