Balance changes

Real-time balance ledger movements — the push counterpart of GET /v1/customers/{code}/transactions. Requires authentication.

Pushed whenever a balance moves: deposits, withdrawals, trades, funding, and remarking. The channel is broker-scoped — an authenticated connection receives movements for every customer under its broker. A movement may be pushed more than once as it transitions through its status lifecycle.

Subscribe

{"op": "subscribe", "args": ["balance-changes"]}

Topic format: balance-changes (per-broker, not per-symbol).

Update Message

A trade movement is a single message whose total_amount is the net of realised PnL and fee; the breakdown rides along as realised_pnl and fee (signed; total_amount = realised_pnl - fee). There is no separate "trade fee" message.

{
  "channel": "balance-changes",
  "type": "update",
  "code": "5f0a3c21-0000-4000-8000-000000000000",
  "customer_code": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
  "transaction_type": "trade",
  "currency": "USDC",
  "total_amount": "-0.64514306",
  "realised_pnl": "-0.6164",
  "fee": "0.02874306",
  "status": "completed",
  "balance": "999.35485694",
  "balance_as_of": "2026-06-01T13:02:01Z",
  "reference_id": "client-order-7",
  "timestamp": "2026-06-01T13:02:01Z"
}

Field	Description
code	Identifier of the underlying ledger entry — equal to the code of the matching GET /transactions row, and (for trade movements) the /trades and trades WS code. Use it to join a balance change back to its ledger entry.
customer_code	Customer the movement belongs to
transaction_type	Ledger transaction type (mirrors the type field of GET /transactions): deposit, withdrawal, trade, funding, or remarking
currency	Currency of the movement
total_amount	Authoritative signed movement: positive = credit (money in), negative = debit (money out). There is no separate direction field
status	pending, completed, or cancelled
balance	Resulting end balance for this currency. Present only on completed events
balance_as_of	Time the balance is effective as of. Present only on completed events
realised_pnl	Realised PnL component of a trade movement (signed). Trade movements only
fee	Fee component of a trade movement (signed). Trade movements only
reference_id	Client order id. Trade movements only
symbol	Internal DLT instrument symbol. Funding and remarking movements only
mark_price	Mark price. Remarking movements only
funding_rate	Funding rate. Funding movements only
timestamp	Server-side event time (the movement's transact time)

Notes:

• There is no initial snapshot on subscribe — use REST GET /transactions for current state.
• balance/balance_as_of ride along only on the transition into completed. Because delivery is unordered, keep the snapshot with the greatest balance_as_of per (customer, currency).