WebSocket: Unified Account Channel

Private WebSocket channel that pushes live uniMMR updates, margin calls, reduce-only transitions, and liquidation steps to a single user.

Endpoint

wss://api.ztdx.io/ws

Authentication is JWT (same as positions / orders / balance channels). Subscribe with a token inline or after a prior auth_token message.

Subscribe

{ "type": "subscribe", "channel": "unified_account", "token": "<JWT>" }

Server replies with:

{ "type": "subscribed", "channel": "unified_account" }

Push Cadence

While the user is in unified mode, the risk worker emits one update event per 2 s (even when nothing changes) so the front-end can render live uniMMR without polling. Status transitions and liquidation steps are emitted in addition to the regular update in the same tick.

Event Envelope

{
    "channel": "unified_account",
    "event": "<event_name>",
    "data": {
        "user_address": "0x...",
        "event": "<event_name>",
        "uni_mmr": "1.85",
        "total_equity": "52000.00",
        "available_balance": "2000.00",
        "account_status": "warning_1",
        "reason": "uniMMR=1.85 status: normal → warning_1",
        "orders_cancelled": null,
        "timestamp": 1712678400000
    }
}

Event kinds

event	Trigger	Extra semantics
update	Every tick (~2 s)	Baseline heartbeat; reason is null
margin_call	Transition into warning_1 or warning_2	reason names old → new status
reduce_only	Transition into reduce_only	orders_cancelled = number of orders auto-cancelled
liquidating	Transition into liquidating	May coincide with the first liquidation_step
liquidation_step	One position force-closed in this tick	reason contains "liquidated {symbol} {side} size_usd={...} pnl={...}"
status_change	Any other transition (e.g. recovering to normal)	—

Field notes

• uni_mmr is the decimal value as a string to preserve precision; may be null if the user has no positions.
• orders_cancelled is only populated on reduce_only / liquidating transitions; otherwise omitted or null.
• Per-user fan-out: the server only forwards events where data.user_address matches the subscribed session's authenticated address, so clients do not need to filter.

Example (Python)

import asyncio, json, websockets
from eth_account import Account
from eth_account.messages import encode_typed_data
import requests

# 1. Log in with a wallet private key to obtain a JWT.
acct = Account.from_key("<PRIVATE_KEY>")
addr = acct.address.lower()
typed = requests.get(f"https://api.ztdx.io/api/v1/auth/nonce/{addr}").json()["typed_data"]
signable = encode_typed_data(full_message=typed)
sig = "0x" + acct.sign_message(signable).signature.hex()
ts = int(typed["message"]["timestamp"])
jwt = requests.post(
    "https://api.ztdx.io/api/v1/auth/login",
    json={"address": addr, "signature": sig, "timestamp": ts},
).json()["token"]

# 2. Subscribe.
async def run():
    async with websockets.connect("wss://api.ztdx.io/ws") as ws:
        await ws.send(json.dumps({"type": "auth_token", "token": jwt}))
        await ws.send(json.dumps({
            "type": "subscribe",
            "channel": "unified_account",
            "token": jwt,
        }))
        async for msg in ws:
            m = json.loads(msg)
            if m.get("channel") == "unified_account":
                d = m["data"]
                print(f"[{m['event']}] uniMMR={d['uni_mmr']} "
                      f"status={d['account_status']} reason={d.get('reason')}")

asyncio.run(run())