Every Main Account and every Subaccount has two balance areas for each Asset:
- Funding is the on-chain Funding Account on Polyester Chain. It receives deposits and sends Funding transfers and withdrawals.
- Trading is the Unified Trading Account: the off-chain balance used by orders, triggers, fills, fees, Trading withdrawals, and internal transfers.
Moving value between them is a transfer. See Internal transfers.
Read balances
LedgerReadService.GetBalances (GET /v1/balances) returns one row for every supported
Asset, including zero balances. Pass subaccountId to read a Subaccount. Session callers need a role
on that Subaccount. API keys need READ_BALANCES and follow their scope. Without subaccountId, a
Subaccount-scoped API key reads its bound Subaccount, and every other caller reads its Main Account.
Each row carries the Asset's total Trading balance (trading), the part of it committed to open
orders, triggers, or pending movements (reserved), what a new order, transfer, or withdrawal can
use now (available), and the Funding balance (funding). tradingRevision versions trading, reserved, and available together; fundingRevision versions funding. Field schemas are in the
API reference.
ConnectRPC carries amounts as U128 at a fixed 18-decimal scale and identifies the Asset by assetId. That scale does not depend on the Asset's quantity_scale, which applies to order
quantities and the fields that name it, not to balances. REST renders decimal strings and the Asset symbol. See Scaled integers.
Use available as returned. Do not derive it from trading minus reserved. When you merge a REST
snapshot with realtime updates, keep the copy with the higher revision. Revision 0 means no state
has been observed yet.
Available and reserved
When an action commits funds, Polyester reserves them in Trading. The reserve leaves available immediately, so the same funds cannot back two actions. Any unused part returns to available when
the action fills, is canceled, completes, or fails.
| Source of a reserve | What is reserved |
|---|---|
| Open sell order | The remaining base quantity. |
| Open buy order | The remaining quote cost, plus a fee allowance when the fee is paid in quote. |
| Standalone stop-loss or take-profit | Funds for the child order, reserved at creation. See Stop-loss and take-profit. |
| Trading withdrawal | The gross withdrawal amount until the withdrawal settles, fails, or is refunded. |
| Internal transfer | The transfer amount while the transfer completes. |
A request that available cannot cover is rejected with INSUFFICIENT_FUNDS. Preview order checks admissibility without
reserving anything.
Polyester does not publish a per-hold read: individual holds, their identifiers, and their expiry
times are not part of the public API. Use each Asset's reserved from GetBalances for the total
held, and your order, trigger, and movement records for the cause.
Equity
Equity values balances in USDT using market prices.
| Method | Use |
|---|---|
GetEquityHistorySeries | One account's equity over a range, grouped by balance area or by Asset. |
GetPortfolioEquitySnapshot | Current equity across the Main Account and every owned Subaccount. |
GetPortfolioEquityHistorySeries | Portfolio equity history across owned accounts. |
GetBalanceHistory | Balance series per Asset and balance area. |
REST routes: GET /v1/equity/history/series, GET /v1/equity/portfolio/snapshot, GET /v1/equity/portfolio/history/series,
and GET /v1/balances/history.
Ranges run from one day to 365 days. Equity values are USDT scaled by 1e4; balance-history points
are scaled by 1e7. The two portfolio methods need an interactive Main Account session; API keys are
refused with AUTH_SESSION_KIND_NOT_ALLOWED.
Ledger history
ListTransfers (GET /v1/transfers) lists finalized ledger transfers for
one account: deposits, withdrawals, trade legs, fees, rebates, internal transfers, and moves between
Funding and Trading. Each transfer has a debit and a credit leg that share transferId.
transferCodegives the reason, such asDEPOSIT,TRADE_BASE,TAKER_FEE,INTERNAL_TRANSFER, orTRADING_TO_FUNDING.account(ConnectRPCaccountCode) is the balance area the row affects, andbalanceAfteris that area's balance after the transfer.isDebittells the debit leg from the credit leg.sourceanddestinationare display sides. Private counterparties and system accounts are never identified.flowIdlinks deposits and withdrawals to their lifecycle flow.
Filter by Asset (ledger) and by an inclusive time range in microseconds (timestampMin and timestampMax;
ConnectRPC tsMinUs and tsMaxUs). ConnectRPC also filters by transferCode. Rows are oldest
first unless you set reversed to true. Page with pageToken; limit defaults to 100 and allows
up to 1000. API keys need READ_INTERNAL_TRANSFERS (or INTERNAL_TRANSFER) to call it.
transferId, the balance area, and isDebit together as the identity of one leg. A realtime update with the
same identity replaces the earlier copy, for example when a deposit leg gains its flowId.Realtime balance and transfer updates are available over WebSocket JSON and WebSocket Protobuf. Field schemas are in the API reference, and error codes under Balances and transfer history.