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:<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:- Generate a current Unix timestamp in milliseconds.
- 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.
- Encode the signature as base64url.
- Supply all three URL authentication parameters when opening the broker connection, then subscribe after the connection succeeds.
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
Appendorderly_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.
Subscribe and unsubscribe
Use the plain topic name in subscription requests. The server scopes the subscription to your broker automatically.params array. Changing only event in a subscribe request is not sufficient:
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.datais an array, including when it contains one report.algoexecutionreportv2.datais an object with optional nestedchildOrders.executionreport.data.averageExecutedPriceis the cumulative average execution price. The payload also includes theavgPricealias; do not expect theavgExecutedPricespelling shown in the account-level example.executionreport.data.matchIdis a JSON number. Algo reports use a string-valuedmatchId. Do not expect the snake-casematch_idfield from the account-level execution report example.liquidationsaccount.datais a single liquidation object containingliquidationId,timestamp,transferAmountToInsuranceFund, and apositionsByPerparray. The array wrapper in the account-level example does not apply to broker events.position.data.positionsis an array. Each position usesupdatedTimefor its update timestamp and includesmarginTokenfor its margin asset, defaulting toUSDC. UseupdatedTimeinstead of theupdated_timespelling in the account-level example.balance.data.balancesis keyed by token. Broker balance entries do not includeaverageOpenPriceorpnl24H; 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.
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:
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. ItspositionsByPerp array lists the affected perpetual positions:
Position information
Thepositioninfo 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 returnsuccess: false; broker stream error details are carried in data:
ping regularly while connected, for example every 10 seconds:
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.