Skip to content

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.

/ws/risk needs authentication.

  1. Mint a handshake token — POST /api/auth/bootstrap returns { success, data }, where data.riskEngineWss is { endpoint, token, expiresAt }. Market data does not go through this bootstrap: it comes from Nuntius (see Market data).

  2. Open the socket.

  3. Send Authenticate as the first message, using data.riskEngineWss.token:

    { "type": "Authenticate", "token": "<ws-token>" }
  4. 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 Ping or Subscribe immediately after Authenticate gets them answered not_authenticated first, and sees Authenticated arrive after the rejections. Nothing is broken when that happens; the frames simply have to be sent again.

  5. 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
    }

    resumeTicket and resumeTicketExpiresAt appear only when you asked for resume in Authenticate and the deployment issues tickets (see Resume ticket). Without them the reply carries just scope. scope.accountId is 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_required when the frame carries no token, token_invalid when the token is unknown, already consumed, or expired, and not_authenticated on any other frame that arrives before authentication has completed. token_invalid also covers a quote token (qt_) sent to /ws/risk and an API key that was revoked or is no longer valid. The server logs the exact reason; if you report a token_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).

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'] })

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.

/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.

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.

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.

Frames are JSON text in both directions. There is no binary encoding.

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.

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.