Connecting
This API serves one WebSocket channel. Market data does not come from it — see Market data.
Endpoint: wss://api.troncharts.xyz. POST /api/auth/bootstrap also hands you
a fully-qualified endpoint per channel, and it may name a different host
than the REST base URL. Connect to data.riskEngineWss.endpoint exactly as
returned rather than building the URL yourself; see
Base URLs.
Authenticate
Section titled “Authenticate”/ws/risk needs authentication.
-
Mint a handshake token —
POST /api/auth/bootstrapreturns{ success, data }, wheredata.riskEngineWssis{ endpoint, token, expiresAt }. Market data does not go through this bootstrap: it comes from Nuntius (see Market data). -
Open the socket.
-
Send
Authenticateas the first message, usingdata.riskEngineWss.token:{ "type": "Authenticate", "token": "<ws-token>" } -
Wait for the reply before sending anything else. Authentication resolves asynchronously, and the socket keeps processing frames while it does — so a client that pipelines
PingorSubscribeimmediately afterAuthenticategets them answerednot_authenticatedfirst, and seesAuthenticatedarrive after the rejections. Nothing is broken when that happens; the frames simply have to be sent again. -
The reply is
Authenticated, carrying the scope the socket ended up with:{"type": "Authenticated", "id": null, "ok": true,"scope": {"sessionId": "apiclient:<id>","accountId": "<the account this socket is bound to>","walletAddress": null,"isAdmin": false},"resumeTicket": "<ticket>","resumeTicketExpiresAt": 1767225600000}resumeTicketandresumeTicketExpiresAtappear only when you asked forresumeinAuthenticateand the deployment issues tickets (see Resume ticket). Without them the reply carries justscope.scope.accountIdis worth reading rather than assuming — it is the account whose frames you will receive.On failure it is
Result { ok: false }with one of three codes:token_requiredwhen the frame carries no token,token_invalidwhen the token is unknown, already consumed, or expired, andnot_authenticatedon any other frame that arrives before authentication has completed.token_invalidalso covers a quote token (qt_) sent to/ws/riskand an API key that was revoked or is no longer valid. The server logs the exact reason; if you report atoken_invalid, include the UTC time the socket opened so support can find it.
Each token is single-use and lives 60 seconds; the socket that consumes it burns it. Bootstrap again for every reconnect — the mint is rate-limited to 10 requests per minute per API key, which is ample for reconnect backoff but not for a hot loop. The limit is per credential: each API key has its own budget.
Send Authenticate as soon as the socket opens. A socket that has not
authenticated 10 seconds after open is closed with
1008 authentication_timeout. Once authenticated, the session does not
expire: the 60-second lifetime applies only to using the token. The socket
stays open until it drops, misses the heartbeat, the server restarts, or the
credential is revoked or changed (LoggedOff with admin_force).
Connections per credential
Section titled “Connections per credential”The credential’s concurrencyPolicy decides how many sockets it may hold:
| Policy | Sockets | A new socket… |
|---|---|---|
strict-single (default) |
1 | closes the previous one with 1008 replaced_by_new_session. |
multi-session-allowed |
up to 20 | beyond the 20th, is closed with 1008 too_many_sessions. |
There is no per-tenant connection limit. Sockets opened by a browser cookie session — the embed, for example — are not counted against an API credential, so an embed and your server can watch the same account without replacing each other.
Browser sessions rooted in a cookie authenticate automatically; sending the frame anyway is harmless and keeps client code uniform.
The sample below uses the TypeScript SDK; any WebSocket client drives the socket just as well.
import { RiskEngineClient } from '@tronchartsxyz/api-client'
const ws = new RiskEngineClient({ url: bootstrap.data.riskEngineWss.endpoint, token: bootstrap.data.riskEngineWss.token, onFrame: (frame) => apply(frame),})await ws.connect()ws.send({ type: 'Subscribe', topics: ['Position-Changed', 'Order-Intent-Changed'] })Heartbeat
Section titled “Heartbeat”Send Ping every 30 seconds; the server replies Pong { serverTime }. The
socket’s idle timeout closes it after 60 seconds of inbound silence, and the
Ping resets it. (Alive resets it too, but acks with Result { ok: true }
instead of a Pong — legacy; new code should use Ping/Pong.) Both are exempt
from the per-frame rate limit, so a heartbeat is never dropped.
Subscribe to topics
Section titled “Subscribe to topics”/ws/risk pushes nothing until you subscribe. A fresh socket carries an
empty topic set, and every push frame is gated on its topic — authenticate,
subscribe to nothing, and the socket stays silent for its whole life.
{ "type": "Subscribe", "topics": ["Position-Changed", "Order-Intent-Changed"] }topics is required and must be non-empty; a Subscribe without it comes back
as Result { ok: false, error: "invalid_frame" }. The explicit Get-*
requests answer regardless of what you subscribed to — topics gate pushes, not
replies.
| Topic | Unlocks |
|---|---|
Account-State-Changed |
Account-State-Update — plus an immediate snapshot on subscribe. |
Position-Changed |
Position-Update, Position-Removed. |
Order-Intent-Changed |
Order-Intent, Order-Intent-Update. |
Order-Changed |
Order-Update. |
Open-Orders |
Open-Orders-Update. |
Fill |
Fill — one frame per execution, never coalesced. |
Trade-Changed |
Trade-Update (closed round trips). |
Balance-Changed |
Balance-Update. |
Margin-Changed |
Margin-Update. |
Funding-Changed |
Funding-Update. |
Risk-Changed |
Risk-Update. |
Blocking-Changed |
Blocking-Update. |
Account-Event-Changed |
Account-Event. |
Account-Suspension-Changed |
Account-Suspension-Update — sent the moment the account is blocked, before its positions are flattened. |
Prop-Account-Changed |
Prop-Account-Update and the Prop-Account-* transition frames. |
Companion-Event-Changed |
Companion-Event. |
IP-Changed |
IP-Update. |
Unsubscribe { topics } removes them again.
What a socket receives
Section titled “What a socket receives”Beyond topics, a socket only receives frames for the accounts in its scope:
| Credential | Scope |
|---|---|
| API credential (bootstrap token) | The one account it is bound to. Subscribe { topics, accountId } re-scopes to another account the credential owns — an unowned id is rejected account_forbidden; one active account at a time. |
| Cookie session | Every account the signed-in user owns. |
Scope is enforced at the socket, not filtered client-side. You cannot receive another tenant’s frames, and if your access is revoked mid-connection the socket is torn down rather than left alive until the next reconnect.
Tier enforcement, per frame
Section titled “Tier enforcement, per frame”The credential tier is checked on every inbound frame, but the socket draws a single line — read versus write:
| Frame | Tiers allowed |
|---|---|
Authenticate, Ping, Alive, Resume, Subscribe, Unsubscribe, Get-* |
readonly, liquidation, fullTrading |
Cancel-Order-Intent, Replace-Order-Intent |
liquidation, fullTrading |
Bracket-Insert, Bracket-Modify, Bracket-Cancel, Request-Trade-History,
Get-Risk-Update and Position-Close are not implemented: they answer
Result { ok: false, error: "not_implemented" }. Attach brackets over REST
(POST /api/v1/oms/brackets/attach). See Frames you can send.
A readonly credential is rejected with
Result { ok: false, error: "tier_readonly" } — the socket stays open. Admin
read-only impersonation sessions are barred from the write frames the same way.
The socket gate is coarser than the REST one: /api/v1/oms/* splits
liquidation (cancel, cancel-all, flatten) from fullTrading (everything that
opens or re-prices exposure), while /ws/risk lets any non-readonly
credential send every write frame. If you are issuing a liquidation
credential to a third-party risk system, that difference is the thing to
account for.
Frames rejected for other reasons carry their own code — invalid_json,
invalid_frame, rate_limited, account_forbidden, intent_not_found,
no_account, partial_close_unsupported, and so on. Always branch on
error, never on a message string.
Encoding
Section titled “Encoding”Frames are JSON text in both directions. There is no binary encoding.
Reconnecting
Section titled “Reconnecting”On a drop: mint a fresh bootstrap token, reconnect, re-authenticate,
re-Subscribe, then re-request state with the Get-* frames rather than
assuming your cached view survived. Topics live on the connection, so a new
socket starts silent again. If the server decides your view is stale it sends
Resync-Required — treat it as an instruction to drop local state and
re-snapshot.
The Resume frame does not survive a drop. It replays recent frames on the
same socket after a gap in seq (see Sequence numbers);
a new socket starts its own seq at 1 and has nothing to replay. To skip the
new bootstrap on reconnect, see Resume ticket.
Frames are coalesced server-side under load: you may receive one merged update instead of several. Always apply a frame as the current truth for its key, never as a delta on top of what you had.
Resume ticket
Section titled “Resume ticket”The plain reconnect above always works. A resume ticket lets an API-credential session reconnect without a new bootstrap; without asking for it, no frame changes.
Send { "type": "Authenticate", "token": "<ws-token>", "resume": true }. When
the deployment issues tickets, the Authenticated reply carries resumeTicket
and resumeTicketExpiresAt (epoch ms), and the server sends
LoggedOff { reason: "server_restart", retryAfterMs } before a planned restart.
When it does not, the reply simply omits them: fall back to the plain reconnect.
To reconnect, send { "type": "Authenticate", "resumeTicket": "<ticket>" }
instead of a token, then re-Subscribe and re-request state as above. Every
Authenticated brings the next ticket: keep only the latest and never log it.
A ticket is spent by the reconnect that uses it; if that reply never reached
you, the same ticket is accepted once more within a short window. Refusals come
as Result { ok: false }:
error |
Do |
|---|---|
resume_ticket_invalid, resume_ticket_reused |
Bootstrap again and authenticate with a token. |
resume_ticket_unverified, auth_unavailable |
The ticket was not spent: retry once after a few seconds, then bootstrap. |
The ticket restores the session, not missed frames: anything pushed while you were away is not replayed, so always re-read state after reconnecting.