WebSocket：统一账户频道

私有 WebSocket 频道，向单个用户推送实时 uniMMR、风险预警、reduce_only 转换与清算步骤。

连接地址

wss://api.ztdx.io/ws

鉴权使用 JWT（与 positions / orders / balance 频道一致）。可在 subscribe 消息内附带 token，或先发送 auth_token 消息完成鉴权后再订阅。

订阅

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

服务器响应：

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

推送频率

用户处于 unified 模式时，风控 Worker 每 2 秒发送一次 update 事件（即使状态无变化）， 前端可据此渲染实时 uniMMR 而无需轮询。状态转换或清算步骤会在同一 tick额外发送对应事件。

事件信封

{
    "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	触发时机	附加语义
update	每个 tick（约 2 秒）	心跳；reason 为 null
margin_call	进入 warning_1 或 warning_2	reason 说明旧 → 新状态
reduce_only	进入 reduce_only	orders_cancelled = 本次自动撤单数量
liquidating	进入 liquidating	常与该 tick 的第一个 liquidation_step 同时出现
liquidation_step	该 tick 平掉了一个仓位	reason 形如 "liquidated {symbol} {side} size_usd={...} pnl={...}"
status_change	其他状态转换（如恢复 normal）	—

字段说明

• uni_mmr 为字符串形式的 Decimal 以保留精度；无仓位时为 null
• orders_cancelled 仅在 reduce_only / liquidating 转换时填充，其他事件省略或为 null
• 服务器只将 data.user_address 等于连接鉴权地址的事件转发给该会话，客户端无需自行过滤

示例（Python）

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

# 1. 用钱包私钥登录拿到 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. 订阅
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())