Funding vs trading
Ledger balances have separate funding and trading buckets per asset.
- An external deposit can stop in funding or continue to trading, depending on its route
- Spot orders spend trading
- Move funding → trading on-chain (or via the Polyester UI), not through a ConnectRPC balance call
Balance component fields are scaled integer decimal strings (ledger u128). Format with format_ledger_u128 for display.
from polyester import format_ledger_u128
balances = await client.balances.list()
for b in balances.balances:
print(
b.asset_id,
format_ledger_u128(b.funding),
format_ledger_u128(b.trading),
format_ledger_u128(b.available),
)Optional scope: account={"sub_account_id": "..."} or sub_account_id=....
Held amounts come from each Asset's reserved balance in client.balances.list(). Individual hold
IDs and expiry times have no replacement.
Also on client.balances: get_balance_history, get_equity_history, and subscribe for live
updates. See Balances.
Account scope
Pass "main", "active", or {"sub_account_id": "..."} ("subaccountId" also works) on scoped
services, or set default_sub_account_id / default_account_id on the client. Private streams need
Account ID.
A sub-account ID string is its public ID, as the API returns it. An int, such as account={"sub_account_id": 42}, is the numeric ID. The SDK refuses a bool, a negative integer,
or one above 2**64 - 1 with PolyesterValidationError before sending. It refuses an explicit 0
too, because 0 means the main account on the wire: leave the sub-account out to act on the main
account. An int account_id passed to a subscribe method follows the same rules and subscribes
to that account's channel.
Subaccounts & policies
The Python SDK exposes subaccount reads (including members, invites, activity, and balances)
plus private subaccount streams. client.policies is subscribe-only. Create/update/delete and membership or
policy administration require the Polyester app/TypeScript session client.
A subaccount-scoped API key also needs its own attached API-key policy. Permit ledger reads for balance reads/streams and add the required trading actions for mutations. The API-key policy and subaccount policy are distinct and both constrain the request.
Profile & API keys
client.auth and client.api_keys cover identity and key metadata. Key-metadata reads
(list, get) need an interactive session and refuse an API key with PolyesterSessionRequiredError; the private administration stream works with an API key that has
the API-key administration permission. Creating keys is JWT/session-only.
Transfer history
client.transfers lists transfer history. Money movement mutations: Deposits & withdrawals.