Initial Subscription

The initial subscription is the first step of the balance subscription. You send one signed subscribe message on the balances topic, and the server immediately responds with an initial-balance
The initial subscription is the first step of the balance subscription. You send one signed subscribe message on the balances topic, and the server immediately responds with an initial-balance message — a complete snapshot of every account that matches your filter. This snapshot is your baseline; every later balance-updated message is applied on top of it.

Subscribe request

Send a signed subscribe message. Every message must be authenticated — see Authentication.

Example request:

{
  "messageType": "subscribe",
  "topic": "balances",
  "useMultiChainAssetFormat": false,
  "key": "API_PUBLIC_KEY",
  "passphrase": "API_PASSPHRASE",
  "timestamp": "1720000000",
  "signature": "base64_encoded_hmac",
  "body": { "filter": {} }
}

Use the body.filter object to scope the snapshot to a specific participant, account group, account type, or asset. An empty filter ({}) returns all accounts you can access. See Subscription Filters.

initial-balance response

On a successful subscription, the server sends an initial-balance message containing a snapshot record for each match

Example response:

{
  "messageType": "initial-balance",
  "body": {
    "account_id": "abc123",
    "participant_code": "ABC123",
    "account_group": "00SCXM",
    "account_label": "general",
    "account_type": "available",
    "asset": "USD",
    "balance": "10000.00",
    "run_id": 987654,
    "run_type": "settlement"
    "run_type": "settlement"
  }
}

Handling the snapshot

• Treat it as your baseline. Load every initial-balance record into your local state before processing incrementa
• Re-request on reconnect. After any disconnect, resubscribe and replace your local state with the fresh initial-balance snapshot — do not assume the old state is still accurate.
• Then stream updates. Once the snapshot is loaded, apply each [balance-updated](https://docs.zerohash.com/refereas it arrives, and keep the connection alive with a ping every 20 seconds (MaintainingSubscription).

Next steps

• Balance Updates — the balance-updated message fields
• Subscription Filters — scoping the snapshot and updat
• Maintaining Subscription — the 20-second heartbeat