Risk channel
/ws/risk is the primary programmatic surface. It is bidirectional: the server
pushes state, and you can act on the same socket instead of falling back to
REST.
Nothing is pushed until you Subscribe to the
topics you want.
Frames the server pushes
Section titled “Frames the server pushes”| Frame | Carries |
|---|---|
Account-State-Update |
The account’s aggregate state. |
Balance-Update / Margin-Update / Funding-Update / Risk-Update |
Balance, margin, funding, and risk as they change. |
Position-Update / Position-Removed / Position-Snapshot |
Live position state; the snapshot seeds your view. |
Open-Orders-Update |
The working-order book for the account. |
Order-Intent / Order-Intent-Update |
Order lifecycle, from composed to terminal. |
Order-Update / Trade-Update |
Order state and closed round trips, in the external vocabulary. |
Fill |
One frame per execution — never coalesced, so nothing is collapsed away. |
Account-Event |
Lifecycle events on the account. |
Account-Suspension-Update |
The account was blocked, and why — and again, with suspended: false, when the block is lifted. The block frame is sent before the forced flatten, so it arrives ahead of the Position-Removed frames that closing the positions produces. |
Prop-Account-Update |
Challenge progress and per-rule state on a prop account. |
Prop-Account-Status-Changed, Prop-Account-Promoted, Prop-Account-Payout, Prop-Account-Claim-Settled, Prop-Account-Collateral |
The challenge transitions, one frame per kind. Same topic as the update above. |
Companion-Event |
Derived risk / position / rule notes from the trading companion. |
Feature-Flags-Updated |
Your tenant’s feature flags changed. Carries no topic gate — it arrives on any authenticated socket. |
Market-Data-Policy-Updated |
Your tenant’s market-data policy — enabled venues and per-venue symbol filters — changed. Re-mint your market-feed token: the one you hold was minted under the old policy. Carries no topic gate. |
Trade-History-Result |
Reserved for Request-Trade-History, which is not implemented: the server does not send it. |
Blocking-Update, IP-Update, LoggedOff |
Session-level notices. |
Resync-Required |
Invalidate local readiness and re-snapshot after a replay gap, outbox overflow or cross-instance bus reconnect. |
Account-State-Update
Section titled “Account-State-Update”One frame per venue the account trades on, sent on subscribe and again on
every change — fills, adjustments, and mark price moves. Use it for live
equity and P&L; GET /api/v1/accounts/{id}/state does not move with price.
{ "type": "Account-State-Update", "seq": 42, "accountId": "<account id>", "accountNumber": "<account number>", "venue": "paper", "exchange": "paper", "equityUsd": "10125.400000000000000000", "balanceUsd": "10000.000000000000000000", "marginUsedUsd": "512.000000000000000000", "marginAvailableUsd": "9613.400000000000000000", "unrealizedPnlUsd": "125.400000000000000000", "source": "be_canonical", "at": "2026-11-05T18:13:15.250Z"}Amounts are decimal strings. For the account total across venues, sum the latest frame of each venue.
There is no server-pushed bracket frame. TP/SL leg state reaches you through
Open-Orders-Update and Order-Intent-Update like any other working order.
After Resync-Required, reconnect or issue fresh correlated Subscribe,
Get-Position-Update, Get-open-orders, Get-Balance and Get-Margin
requests. Only positive Result acknowledgements for every request establish
readiness: Subscribe includes the account-state snapshot. Keep unresolved
financial commands and their idempotency keys; a resync is not a rejection or
permission to submit them again with new keys. The cross-instance reconnect
notice repairs a detected Pub/Sub gap; it is not a continuous Redis health signal.
Frames you can send
Section titled “Frames you can send”Read requests — Get-Margin, Get-Balance, Get-Position-Update,
Get-open-orders — plus
Subscribe / Unsubscribe to change topics and scope, and Resume to replay
after a gap.
Write frames mirror the REST OMS: only
Cancel-Order-Intent and Replace-Order-Intent are handled. Each is
tier-gated.
These frames are accepted by the parser but not implemented: they answer
Result { ok: false, error: "not_implemented" }. Use REST instead.
| Frame | Instead |
|---|---|
Bracket-Insert, Bracket-Modify, Bracket-Cancel |
POST /api/v1/oms/brackets/attach |
Get-Risk-Update |
Get-Margin and Get-Balance |
Request-Trade-History |
The REST trade and fill reads under /api/v1/accounts/{accountId}/* |
Position-Close (paper) |
POST /api/v1/oms/flatten |
There is no place-order frame. New orders start at
POST /api/v1/oms/intents; the socket carries everything that happens to the
order afterwards. Acting on an open order over the socket saves a round trip on
a hot path; REST is fine everywhere else and easier to retry safely.
Order-Sign-Result and Position-Close are for live accounts, which are in
development: every account trades paper today. See
Paper-only mode.
Sequence numbers — detect a gap
Section titled “Sequence numbers — detect a gap”Every pushed frame that leaves the per-socket outbox carries a monotonic
integer seq, starting at 1 for the life of the connection.
if (frame.seq !== undefined) { if (lastSeq !== null && frame.seq !== lastSeq + 1) { onGap(lastSeq) // a frame was dropped or coalesced away } lastSeq = frame.seq}A gap means one or more frames were dropped or coalesced — the server
merges rapid updates for the same key under load. Send
Resume { lastSeq } with the last seq you applied: the server replays what
it still holds (about the last 250 frames of this socket). If the gap is
older than that, it answers Resync-Required instead — then re-request the
relevant Get-* snapshot rather than trying to reconstruct the missing step.
Resume works only on the socket that produced the frames. After a drop,
follow Reconnecting.
Pong and Authenticated carry no seq: they never consume a number and
never create a gap.
Everything else that reaches you is sequenced, including every Result —
they go out through the same outbox as the push frames, just without waiting
for a flush. So the first frame that carries a number is usually the Result
of your first Subscribe, at seq: 1, and the account-state snapshot that
follows it is seq: 2. Seed
lastSeq from whatever arrives rather than special-casing the handshake, and
only assert contiguity over frames that actually carry seq. A new connection
restarts the lane at 1.
Tracking an order to its outcome
Section titled “Tracking an order to its outcome”Subscribe { topics: ["Order-Intent-Changed"] }before you place, so no transition happens while you are unsubscribed.POST /api/v1/oms/intentsreturns an intent id.Order-Intent-Updatecarries the venue order id, then the fills, then the terminal state. The stream is account-scoped, not per-intent — there is nointent.<id>topic — so match each frame on the intent id you were handed.
This is the intended pattern — polling an order endpoint in a loop will always lag the socket and costs you rate limit.