Balance Updates

After the initial-balance snapshot, the server streams incremental balance-updated messages whenever an account matching your subscription changes. Apply each update on top of your baseline snapshot to keep your local balances current.

Each update reports the account's new balance and includes the underlying movements[] that caused the change, so you can both update state and reconcile the "why" behind it.

balance-updated message fields

movements[]

Each entry in movements[] uses the same schema as the REST endpoint GET /accounts/:account_id/movements. Refer to that endpoint for the complete, authoritative list of per-movement fields. Use the movements to reconcile exactly which debits/credits drove the new balance.

Example balance-updated message

{
  "messageType": "balance-updated",
  "body": {
    "participant_code": "ABC123",
    "account_group": "00SCXM",
    "account_label": "general",
    "account_type": "available",
    "asset": "USD",
    "balance": "10250.00",
    "run_id": "987655",
    "run_type": "settlement",
    "run_timestamp": "2026-07-10T14:32:05Z",
    "movements": [
      {
        "movement_id": "...",
        "amount": "250.00",
        "...": "see GET /accounts/:account_id/movements"
      }
    ]
  }
}

Applying updates correctly

• Balance is absolute, not a delta. The balance field is the account's new total — replace your stored value with it rather than adding to it. Use movements[] if you need the delta.
• Match on the account key. Update the record identified by participant_code + account_group + account_type + asset (+ account_label where used).
• Order by run_timestamp. If updates can arrive close together, use run_timestamp / run_id to apply them in the correct order and to ignore stale replays.
• Re-baseline on reconnect. After any disconnect, resubscribe and reload the fresh initial-balance snapshot before resuming update processing — you may have missed updates while disconnected.

Next steps

• Subscription Filters — scope which accounts emit updates
• Maintaining Subscription — the 20-second heartbeat
• Initial Subscription — the baseline snapshot