Tick Charts

Request and process tick-level chart data over the WebSocket protocol.

View as Markdown

Tick charts use the same process as the Market Data API: open and authorize a WebSocket first, then request chart data. The difference is in the chart description.

If you’re following the JavaScript tutorial, see the tick chart examples.

Requesting Tick Charts

Build a request body with the symbol, chartDescription, and timeRange fields, as you would for any chart. For tick data, lock elementSize to 1 and set underlyingType to "Tick":

1{
2  "symbol": "ESU9",
3  "chartDescription": {
4    "underlyingType": "Tick",
5    "elementSize": 1,
6    "elementSizeUnit": "UnderlyingUnits"
7  },
8  "timeRange": {
9    // ...
10  }
11}

Then call the standard md/getChart endpoint with this request. The server responds with the standard chart-data schema. Because unsubscribing requires the real-time subscription ID returned with the response, store the ID of each subscription you create so you can unsubscribe later.

Data Stream Messages

A tick data stream message has the following structure. Tick prices and timestamps are stored relative to each packet’s base values, so you reconstruct actual values by adding the tick’s relative value to the packet’s base:

1{
2  "charts": [                     // array of packets
3    {
4      "id": 16335,                // subscription ID (historical or real-time, from the request response)
5      "s": "db",                  // source of packet data
6      "td": 20210718,             // trade date YYYYMMDD
7      "bp": 11917,                // base price of the packet (in integer contract tick sizes);
8                                  // tick prices are relative to this
9      "bt": 1563421179735,        // base timestamp of the packet;
10                                  // tick timestamps are relative to this
11      "ts": 0.25,                 // tick size of the contract
12      "tks": [                    // array of ticks in this packet
13        {
14          "t": 0,                 // tick relative timestamp; actual = packet.bt + tick.t
15          "p": 0,                 // tick relative price (in tick sizes); actual = packet.bp + tick.p
16          "s": 3,                 // tick size (tick volume); not the contract tick size (packet.ts)
17          "b": -1,                // bid relative price (optional); actual = packet.bp + tick.b
18          "a": 0,                 // ask relative price (optional); actual = packet.bp + tick.a
19          "bs": 122.21,           // bid size (optional)
20          "as": 28.35,            // ask size (optional)
21          "id": 11768401          // tick ID
22        }
23      ]
24    },
25    {
26      "id": 16335,
27      "eoh": true                 // end-of-history flag: historical ticks are loaded,
28                                  // and further packets will contain real-time ticks
29    }
30  ]
31}

Processing the Tick Stream

The following snippet converts a data stream message’s packets into a list of actual ticks for consumption. Because tick stream data can arrive out of chronological order, it’s the client’s responsibility to store and sort the relevant portions of this data.

1function processTickChartMessage(msg) {
2    const result = [];
3    if (msg.charts && msg.charts.length) {
4        for (let i = 0; i < msg.charts.length; ++i) {
5            const packet = msg.charts[i];
6            if (packet.eoh) { // end-of-history: historical ticks are loaded
7            }
8            else if (packet.tks && packet.tks.length) {
9                for (let j = 0; j < packet.tks.length; ++j) {
10                    const tick = packet.tks[j];
11
12                    const timestamp = packet.bt + tick.t;   // actual tick timestamp
13                    const price = packet.bp + tick.p;       // actual tick price
14
15                    const bid = tick.bs && (packet.bp + tick.b);    // actual bid price (if bid size defined)
16                    const ask = tick.as && (packet.bp + tick.a);    // actual ask price (if ask size defined)
17
18                    result.push({
19                        id: tick.id,
20                        timestamp: new Date(timestamp),
21
22                        price: price * packet.ts,           // tick price as contract price
23                        size: tick.s,                       // tick size (tick volume)
24
25                        bidPrice: bid && (bid * packet.ts), // bid price as contract price
26                        bidSize: tick.bs,
27
28                        askPrice: ask && (ask * packet.ts), // ask price as contract price
29                        askSize: tick.as,
30                    });
31                }
32            }
33        }
34    }
35    return result;
36}