Skip to main content
The broker data stream delivers events for accounts belonging to your broker through one authenticated connection. It is intended for monitoring and supervision and does not accept trading actions.

Access and connection

Contact Orderly to enable broker stream access and obtain the broker WebSocket endpoint for your environment. Use your configured broker admin account ID and an Orderly Key associated with that account. An ordinary user account cannot open a broker stream. Orderly supplies the full connection base URL, including the stream path configured for your environment. Append the admin account ID as its final path segment:
Replace <broker-host> and <configured-stream-path> with the host and path provided by Orderly. The stream path is configurable; do not infer it from the account-level private endpoint. The final path parameter is the admin’s account ID, not a broker ID or the account ID of a user you want to monitor. The server derives the broker from the configured admin account. You do not supply a broker ID to select another broker’s data.

Authentication

Use the WebSocket authentication signature scheme:
  1. Generate a current Unix timestamp in milliseconds.
  2. Sign the timestamp’s decimal string using the admin account’s Orderly secret key and Ed25519. Do not append an HTTP method, path, or body.
  3. Encode the signature as base64url.
  4. Supply all three URL authentication parameters when opening the broker connection, then subscribe after the connection succeeds.
The timestamp must be within five minutes of the server’s current time. Use the full ed25519:<public-key> value for orderly_key. Only send the public key, timestamp, and signature; keep the secret key local.

Authenticate in the connection URL

Append orderly_key, timestamp, and sign to the connection URL. URL-encode the parameter values. Provide all three parameters together so authentication is performed while opening the connection; a successful URL authentication does not require a separate auth message.
The values above are placeholders. Generate a fresh timestamp and signature for each connection. Never put the secret key in the URL.

Subscribe and unsubscribe

Use the plain topic name in subscription requests. The server scopes the subscription to your broker automatically.
Send a separate request for each topic. Do not prefix subscription topics with a broker ID or account ID. To unsubscribe, put the topic names in a nonempty params array. Changing only event in a subscribe request is not sufficient:
The response lists the topics actually removed:
An already removed topic is omitted from this response array. Broker subscriptions do not support the params.symbol filter shown on the account-level execution report page; filter received events in your application.

Event topics

Broker forwarding is available for the following event types. Access also depends on the topics enabled for your environment; confirm availability with Orderly when enabling the stream. Other private topics, including account, wallet, settle, notifications, liquidatorliquidations, and queuedorder, are not forwarded through this broker stream. A successful subscription acknowledgment alone does not establish that a topic produces broker events.

Message envelope

Broker events use this envelope: The linked account-level pages describe each event’s business fields. Broker payloads preserve the following wire-format details:
  • algoexecutionreport.data is an array, including when it contains one report. algoexecutionreportv2.data is an object with optional nested childOrders.
  • executionreport.data.averageExecutedPrice is the cumulative average execution price. The payload also includes the avgPrice alias; do not expect the avgExecutedPrice spelling shown in the account-level example.
  • executionreport.data.matchId is a JSON number. Algo reports use a string-valued matchId. Do not expect the snake-case match_id field from the account-level execution report example.
  • liquidationsaccount.data is a single liquidation object containing liquidationId, timestamp, transferAmountToInsuranceFund, and a positionsByPerp array. The array wrapper in the account-level example does not apply to broker events.
  • position.data.positions is an array. Each position uses updatedTime for its update timestamp and includes marginToken for its margin asset, defaulting to USDC. Use updatedTime instead of the updated_time spelling in the account-level example.
  • balance.data.balances is keyed by token. Broker balance entries do not include averageOpenPrice or pnl24H; those fields in the account-level example are not part of the broker balance payload.
  • Optional fields with null values can be omitted. Examples on account-level pages do not require every field to be present in every broker event.
Algo report versions use different type values: The MARKET value in the linked account-level v1 example does not apply to broker v1 reports. Parse each topic using its own values. A v2 event is emitted only when the upstream message contains a new-format report with a positive algoOrderId; do not assume every v1 event has a corresponding v2 event. For example, a balance update for a user under example_broker is:
The example shows selected balance fields. Use accountId to keep each user’s state separate. Do not route events to the admin account or assume the received topic equals the subscription string.

Liquidation event example

A broker liquidation event contains one liquidation object. Its positionsByPerp array lists the affected perpetual positions:

Position information

The positioninfo payload contains account-level risk settings and collateral information. Its positions object is keyed by token, such as USDC; it is not the perpetual position list delivered by position. Each entry in data.positions contains numeric fields holding, outstandingHolding, pendingExposure, interest, breakEvenPrice, realisedPnl, settledPnl, markPx, liquidPx, fee24H, frozen, staked, unbonding, and vault.

Errors and reconnecting

An unrecognized broker admin account is rejected when the connection is opened. Invalid credentials supplied in the URL also cause rejection and connection closure. Authentication and subscription command failures return success: false; broker stream error details are carried in data:
If access fails, verify the environment-specific endpoint, configured admin account, key ownership, signature encoding, and timestamp. A successful authentication does not replace broker access configuration. Send a JSON ping regularly while connected, for example every 10 seconds:
The server responds with event: "pong", success: true, and a millisecond ts. Do not rely on the server sending a ping every 10 seconds; idle timeout behavior depends on the broker endpoint’s configuration. After reconnecting, authenticate again and restore your subscriptions. Treat the stream as live events: do not assume a subscription sends an initial snapshot or replays events missed during a disconnection. Reconcile state through the appropriate authorized REST APIs. Newly registered users may not appear in the broker stream until their account-to-broker mapping has refreshed; do not rely on immediate coverage after registration.