The Private WebSocket API delivers real-time balance and price updates over a single, authenticated connection — so your systems react to changes as they happen instead of polling the REST API.
What you can subscribe to
Two independent feeds run over the same connection. You can use either or both.
| Feed | topic | What it delivers |
|---|---|---|
| Balances | balances | A full snapshot of your account balances on subscribe (initial-balance), followed by incremental updates (balance-updated) whenever a balance changes. |
| Prices | prices | RFQ liquidity bid/ask price levels (price-update) for each symbol you subscribe to, streamed as prices change. |
Connection endpoints
| Environment | WebSocket URL |
|---|---|
| Production | wss://ws.zerohash.com |
| Certification (testing) | wss://ws.cert.zerohash.com |
Connect over WSS (WebSocket over TLS). Do all integration and testing against certification first, then switch the URL for production — no other changes are required.
How it works — at a glance
Balances feed
connect → subscribe (topic: balances) → receive initial-balance snapshot
→ receive balance-updated messages → send ping every 20s
Prices feed
connect → (optional) info (available-symbols) → subscribe (topic: prices) per symbol
→ receive price-update messages → send ping every 20s
Three things to know before you build
-
Every message is authenticated. Unlike a public feed, every message you send —
subscribe,info, andping— must include your credentials and a fresh HMAC signature. See Authentication. -
You must send a heartbeat. A
pingmessage must be sent every 20 seconds, or the server will close the connection. See Maintaining Subscription. -
Build in reconnection. Long-lived TCP connections may experience network instability, timeouts, or ISP-related issues at any time. It is fundamental to have a reconnection / resubscription mechanism in place. On reconnect, re-authenticate, resubscribe, and treat the fresh
initial-balancesnapshot as your source of truth.
Price data is specific to the RFQ liquidity product. Pricing and available symbols on this feed relate only to the RFQ product — they do not reflect CLOB pricing or available instruments. For CLOB market data, use the dedicated CLOB endpoints.
Message envelope
Every message you send shares the same authenticated envelope:
| Field | Type | Description |
|---|---|---|
messageType | string | The action: subscribe, info, or ping |
topic | string | balances, prices, or available-symbols (context-dependent) |
body | object | Payload / filter object (required; may be {} on the balances feed) |
key | string | Your API public key |
passphrase | string | Your API passphrase |
timestamp | string | Unix epoch seconds — the same value used to compute the signature |
signature | string | Base64-encoded HMAC-SHA256 signature (see Authentication) |
Next steps
- Authentication — how to sign every message
- Initial Subscription — start the balances feed
- Subscribing to a Symbol — start the prices feed
- Maintaining Subscription — the 20-second heartbeat