Real-Time Data via WebSocket

WebSockets let you open an interactive session so you can send messages to the server and receive event-driven responses without polling. The protocol uses the same request semantics as the REST API, adapted to the JSON format the standard WebSocket protocol expects. The current protocol is inherited from the SockJS protocol used in earlier versions.

Connecting to the WebSocket Server

Create a WebSocket instance using one of the real-time API URLs, with the wss:// protocol prefix in place of https://. For example, using the Demo URL:

wss://demo.tradovateapi.com/v1/websocket

Server Frames

The server communicates in frames. A frame is a single-character type prefix concatenated with an array of JSON data, and your client is responsible for deconstructing these messages. The server sends these frame types:

• 'o' — Open frame. Sent immediately whenever a new session is established. This is required so the client can distinguish a properly established connection from a broken one.
• 'h' — Heartbeat frame. Sent about every 2.5 seconds to keep connections from timing out behind load balancers. The client must reply with its own heartbeat: an empty array, stringified ('[]').
• 'a' — Array frame. A string containing an array of JSON-encoded messages, for example 'a[{"data": "value"}]'.
• 'c' — Close frame. Sent when the client requests data on a closed connection, which may happen multiple times. It contains a code and a reason, such as c[3000, "Go away!"].

Decoding Server Frames

The 'a' frame is the backbone of the message protocol. Here’s some example data:

a[{"s":200,"i":23,"d":{"id":65543,"name":"CLZ6","contractMaturityId":6727}}]
a[{"e":"props","d":{"entityType":"order","eventType":"Created","entity":{"id":210518,"accountId":25,"contractId":560901,"timestamp":"2016-11-04T00:02:36.626Z","action":"Sell","ordStatus":"PendingNew","admin":false}}}]

You can parse frames into more consumable data with a function such as prepareMsg, which turns the string message into a tuple you can destructure:

1
function prepareMsg(raw) {
2
    const T = raw.slice(0, 1)
3
    let payload = null
4
    const data = raw.slice(1)
5
    if (data) {
6
        payload = JSON.parse(data)
7
    }
8
    return [T, payload]
9
}
10
11
// usage:
12
mySocket.onmessage = msg => {
13
    // data may be null
14
    const [T, data] = prepareMsg(msg.data)
15
    switch (T) {
16
        case 'a': {
17
            // react to data
18
            break
19
        }
20
    }
21
}

Message Types

The socket servers interact with clients by sending messages whose data portion is always an array of JSON objects. There are two main categories: server events and responses to client requests.

Server Event Message

An event message has this structure:

1
{
2
  "e": "props",
3
  "d": {
4
    "entityType": "order",
5
    "eventType": "Created",
6
    "entity": {
7
      "id": 210518,
8
      "accountId": 25,
9
      "contractId": 560901,
10
      "timestamp": "2016-11-04T00:02:36.626Z",
11
      "action": "Sell",
12
      "ordStatus": "PendingNew",
13
      "admin": false
14
    }
15
  }
16
}

The "e" field specifies the event kind:

• "props" — An entity was created, updated, or deleted. The "d" field contains an "entityType" field, an "entity" field (whose JSON matches the entity returned by the corresponding entityType/item request), and an "eventType" field with the value "Created", "Updated", or "Deleted".
• "shutdown" — A notification before a graceful connection shutdown. The "d" field contains a "reasonCode" ("Maintenance", "ConnectionQuotaReached", or "IPQuotaReached") and an optional "reason" with a readable explanation.
• "md" and "chart" — Used by the market data feed only. See the Market Data API for the "d" field.
• "clock" — A Market Replay clock-synchronization message. See Market Replay.

Response Message

A response message is issued when a client makes a request. It mirrors a REST API response:

1
{
2
  "i": 26,
3
  "s": 200,
4
  "d": {
5
    "id": 478866,
6
    "name": "6EZ6",
7
    "contractMaturityId": 23574
8
  }
9
}

• "i" is the ID of the corresponding client request — it always matches the request that generated it.
• "s" is the HTTP status code of the response.
• "d" is the response content. For a 2xx status, this is the JSON response defined in the spec for that request; otherwise it’s a string representation of the error text.

Client Requests

SockJS doesn’t define framing for client requests, so a standard text protocol is used. Each frame contains exactly one request made up of four fields:

• An endpoint name as defined in the spec — any endpoint you could call from the REST API.
• A unique integer ID for the request, unique within the current connection. The server uses it to reference the request in response messages.
• An optional field with parameters, identical to the REST API’s query parameters.
• An optional field identical to a REST API body parameter.

Separate the four fields with the '\n' (newline) character.

executionReport/list
4

tradingPermission/ldeps
8
masterids=1

contract/rollcontract
33
{"name":"YMZ6","forward":true,"ifExpired":true}

Authorization

Because a WebSocket is a permanent connection, you only need to authorize it once per application instance. Send an authorize request with your access token in the message body:

authorize
2
uST01MhJMF3cR3lCs-gdQ9W0AzomYLaqsWcZ_GYgAspPRf-ZS-Wb7q3sW3pUafTm90ba4

Don’t forget the newline between parameters. A successful response shows the status code (s) and the request ID (i):

a[{"s":200,"i":2}]

User Synchronization

Once your real-time connection is open, synchronize your user data with the user/syncRequest endpoint. It returns updates for any data changes that pertain to your user — the foundation for digesting real-time data such as calculating profit and loss or getting a snapshot of current margins. This endpoint is intended for WebSocket use.

Market Replay

Market Replay follows the same trading and market data protocols as the regular services, over a dedicated host:

wss://replay.tradovateapi.com/v1/websocket

Set the session’s initial parameters right after a successful authorization, using a replay/initializeclock request:

• startTimestamp — the session’s start time.
• speed — the replay speed as a percentage, in the range 0–400.
• initialBalance — a dollar amount for the replay account, which is created automatically with that balance and discarded at the end of the session.

replay/initializeclock
3
{"startTimestamp":"2019-08-26T16:43:00.000Z","speed":20,"initialBalance":51000}

A response indicates whether the session started successfully:

a[{"s":200,"i":3,"d":{"ok":true}}]

Only one replay session is allowed per user; initializing a new one resets the running session. Multiple connections can join the same session, and a connection that sends no initialization request joins the existing one.

To keep the server-side replay clock and the client clock in sync, the server pushes periodic clock-sync event messages:

a[{"e":"clock","d":"{\"t\":\"2019-08-26T16:43:08.599Z\",\"s\":20}"}]

The d field holds a text representation of a JSON entity with t (the current replay timestamp) and s (the current replay speed). Use the clock event to determine whether the session has reached a certain time, or whether the server has limited your speed — in which case you’ll need to change it.

Control the replay speed with a replay/changespeed request, passing a speed parameter in the range 0–400 (where 400 is four times real-time speed):

replay/changespeed
49
{"speed":100}

Sometimes the server pauses your replay, in which case clock-sync messages continue with speed set to 0. Unpause by sending another replay/changespeed request. A session is discarded automatically when no connections are associated with it.

Client Heartbeats

As noted under Server Frames, the client must send a heartbeat every 2.5 seconds to avoid being closed for inactivity. A heartbeat is a frame whose text is "[]" (an empty array), sent with the WebSocket.send method.

When developing for the web, avoid relying on setInterval — browsers can throttle it and cause disconnections. Instead, record a timestamp with each received message, compare it against the previous message’s timestamp, and send a heartbeat once more than 2,500 ms have elapsed. The JavaScript tutorial shows an example.

Reference Implementations

Reference projects are available for both C# and JavaScript.