Subaccounts

client.sub_accounts contains API-key-safe subaccount reads and private streams. Mutations and member/invite administration are JWT/session-only and are not included.

• list(): List visible subaccounts
• get(...): Get one subaccount with optional related data
• list_members(...): Members of a subaccount
• list_invites(direction=...): Incoming/outgoing invites
• list_activity(..., page_token=...): Paginated audit activity
• subscribe(account_id=...): Subaccount state stream
• subscribe_api_keys(account_id=...): API-key metadata stream

subs = await client.sub_accounts.list()
for subaccount in subs.subaccounts:
    print(subaccount.id, subaccount.label, subaccount.status)

detail = await client.sub_accounts.get(
    sub_account_id="123",
    include_members=True,
    include_policy=True,
    include_balances=True,
)
for row in detail.balances.balances if detail.balances else []:
    print(row.asset_id, row.trading, row.available)

get(..., include_balances=True) also returns the subaccount's current balances, a BalancesList in the shape of client.balances.list(). Without it, balances is None. It needs the READ_BALANCES action on the subaccount (its role, its attached policy, and the key's policy), or the call raises AUTH_SUBACCOUNT_ACCESS_DENIED. An API key bound to a subaccount reads only that one; a root-scoped API key cannot read a subaccount's balances. When balances cannot be read right now the call raises AUTH_TEMPORARILY_UNAVAILABLE, which is_retryable_error(err) reports as retryable: retry, or omit include_balances for the rest of the view.

A member call that targets the subaccount's owner raises PolyesterSubaccountOwnerRoleLockedError. The request changed nothing and is not retryable.

Use default_sub_account_id on the client, account={"sub_account_id": "..."}, or a method sub_account_id argument to scope trading calls. Subaccount IDs are venue IDs, not the root Account ID used in private channel names. A string is the public ID; an int in the account dictionary is the numeric ID. An explicit 0, a bool, or an integer outside uint64 raises PolyesterValidationError; omit the sub-account to act on the main account. The Accounts & balances guide lists the full rules.

List activity tokens are opaque and must be replayed unchanged. Private subscribe methods require API key + root Account ID.

Related: Accounts & balances, Streaming.

Related Topics