Balance Subscription

The balance subscription streams your zerohash account balances in real time over the Private WebSocket API. Instead of polling GET /accounts on the REST API, you open one authenticated connection and receive balances as they change — ideal for keeping ledgers, dashboards, and risk systems continuously in sync.

How it works

The balance subscription delivers data in two phases:

Snapshot — Immediately after you subscribe, the server sends an initial-balance message: a complete snapshot of every account that matches your subscription filter.
Incremental updates — From then on, the server sends balance-updated messages whenever a matching account's balance changes. Each update also includes the underlying movements[] that caused the change.

Together these let you build and maintain an accurate local view of balances: load the snapshot as your baseline, then apply each incremental update on top.

connect → subscribe (topic: balances) → initial-balance snapshot
        → balance-updated → balance-updated → …  (ongoing)
        → ping every 20s to keep the connection alive

Connection endpoints

Environment	WebSocket URL
Production	`wss://ws.zerohash.com`
Certification (testing)	`wss://ws.cert.zerohash.com`

Subscribing

Send a signed subscribe message on the balances topic. Every message must be authenticated — see Authentication.

Field	Type	Required	Description
`messageType`	string	✅	`subscribe`
`topic`	string	optional	`balances` for the balance feed
`useMultiChainAssetFormat`	boolean	optional	Include the chain in asset names. Defaults to `false`.
`key`	string	✅	Your API public key
`passphrase`	string	✅	Your API passphrase
`timestamp`	string	✅	Unix epoch seconds (same value used to sign)
`signature`	string	✅	Base64-encoded HMAC-SHA256 signature
`body`	object	✅	Filter object — must be present, but may be empty (`{}`) for all accounts

Example subscribe message:

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

Scoping what you receive

By default (an empty filter) you receive balances for all accounts you can access. To narrow the stream — for example, to a single participant, account group, account type, or asset — pass a filter object in the body. See Subscription Filters.

⚠️
The filter is part of the signed body. If you change the filter, recompute the signature over the new body.

Message types on this feed

`messageType`	Direction	Meaning
`subscribe`	client → server	Open the balances subscription
`initial-balance`	server → client	Full snapshot of matching accounts, sent once on subscribe
`balance-updated`	server → client	Incremental change to a matching account
`ping`	client → server	Heartbeat — required every 20 seconds

Keeping the subscription alive

Send a signed ping every 20 seconds or the server will close the connection. Because long-lived connections can drop due to network or ISP issues, build in a reconnection / resubscription routine — on reconnect, resubscribe and treat the fresh initial-balance snapshot as your new source of truth. See Maintaining Subscription.

Next steps

Initial Subscription — the subscribe request and initial-balance snapshot fields
Balance Updates — the balance-updated message fields
Subscription Filters — narrowing the stream
Authentication — signing every message

How it works

Connection endpoints

Subscribing

Scoping what you receive

The filter is part of the signed body. If you change the filter, recompute the signature over the new body.

Message types on this feed

Keeping the subscription alive

Next steps

The `filter` is part of the signed `body`. If you change the filter, recompute the signature over the new `body`.