Market Data

Access quotes, DOM, charts, and histograms over the WebSocket protocol.
View as Markdown

The Market Data API provides access to market data such as quotes, DOM, charts, and histograms. It uses JSON for request bodies and response data, exchanged over the WebSocket protocol.

Example projects are available in C# and JavaScript.

Subscribing to Market Data

A typical market data scenario follows these steps:

  1. Acquire an access token. Use the standard authentication procedure.

  2. Open a WebSocket and authorize it. Open a connection and send your access token using the WebSocket authorization procedure.

  3. Build a request. Request parameters are a JSON object. Every real-time request requires a symbol parameter identifying the contract — either the contract symbol string or the contract ID integer:

    1{ "symbol": "ESM7" }   // by contract symbol
    2{ "symbol": 123456 }   // by contract ID

  4. Subscribe. Send the request to the server, specifying an endpoint such as md/subscribeQuote. The server replies with a response message. On success, the subscription is activated and you begin receiving data; on error, perform error handling. A client can hold a single subscription of each type (quotes, DOM, or charts) per contract, so it’s your responsibility to track the contracts you’ve subscribed to in order to unsubscribe later.

Handling Market Data

Market data arrives asynchronously as event messages of type md or chart. For example:

1{
2  "e": "md",
3  "d": {
4    "quotes": [
5      {
6        "timestamp": "2021-04-13T04:59:06.588Z",
7        "contractId": 123456,
8        "entries": {
9          "Bid": { "price": 4205.25, "size": 12 },
10          "TotalTradeVolume": { "size": 841200 },
11          "Offer": { "price": 4205.50, "size": 8 },
12          "LowPrice": { "price": 4195.25 },
13          "Trade": { "price": 4205.25, "size": 3 },
14          "OpenInterest": { "size": 2415600 },
15          "OpeningPrice": { "price": 4198.75 },
16          "HighPrice": { "price": 4210.50 },
17          "SettlementPrice": { "price": 4201.00 }
18        }
19      }
20    ]
21  }
22}

Unsubscribing from Market Data

To unsubscribe, build request parameters as you did to subscribe, specify the matching unsubscribe endpoint such as md/unsubscribeQuote, and send it. On success, the server deactivates the subscription and stops sending real-time data.

Request Reference

Subscribe Quote

Endpoint: md/subscribeQuote

Parameters:

1{ "symbol": "ESM7" } // or { "symbol": 123456 }

Data message:

1{
2  "e": "md",
3  "d": {
4    "quotes": [ // "quotes" may contain multiple quote objects
5      {
6        "timestamp": "2021-04-13T04:59:06.588Z",
7        "contractId": 123456,
8        "entries": {
9          "Bid": { "price": 4205.25, "size": 12 },
10          "TotalTradeVolume": { "size": 841200 },
11          "Offer": { "price": 4205.50, "size": 8 },
12          "LowPrice": { "price": 4195.25 },
13          "Trade": { "price": 4205.25, "size": 3 },
14          "OpenInterest": { "size": 2415600 },
15          "OpeningPrice": { "price": 4198.75 },
16          "HighPrice": { "price": 4210.50 },
17          "SettlementPrice": { "price": 4201.00 }
18        }
19      }
20    ]
21  }
22}

Unsubscribe Quote

Endpoint: md/unsubscribeQuote

Parameters:

1{ "symbol": "ESM7" } // or { "symbol": 123456 }

Subscribe DOM

Endpoint: md/subscribeDOM

Parameters:

1{ "symbol": "ESM7" } // or { "symbol": 123456 }

Data message:

1{
2  "e": "md",
3  "d": {
4    "doms": [ // "doms" may contain multiple DOM objects
5      {
6        "contractId": 123456,
7        "timestamp": "2021-04-13T11:33:57.488Z",
8        "bids": [ // depth may vary depending on available data
9          { "price": 4205.25, "size": 34 },
10          { "price": 4205.00, "size": 758 }
11        ],
12        "offers": [
13          { "price": 4205.50, "size": 255 },
14          { "price": 4205.75, "size": 467 }
15        ]
16      }
17    ]
18  }
19}

Unsubscribe DOM

Endpoint: md/unsubscribeDOM

Parameters:

1{ "symbol": "ESM7" } // or { "symbol": 123456 }

Subscribe Histogram

Endpoint: md/subscribeHistogram

Parameters:

1{ "symbol": "ESM7" } // or { "symbol": 123456 }

Data message:

1{
2  "e": "md",
3  "d": {
4    "histograms": [ // "histograms" may contain multiple histogram objects
5      {
6        "contractId": 123456,
7        "timestamp": "2017-04-13T11:33:57.412Z",
8        "tradeDate": { "year": 2022, "month": 4, "day": 13 },
9        "base": 2338.75,
10        "items": { // number of items may depend on data
11          "-14": 5907,
12          "2": 1235
13        },
14        "refresh": false
15      }
16    ]
17  }
18}

Unsubscribe Histogram

Endpoint: md/unsubscribeHistogram

Parameters:

1{ "symbol": "ESM7" } // or { "symbol": 123456 }

Get Chart

A client may hold multiple charts for the same contract, so the response to md/getChart contains subscription IDs you use to track and unsubscribe from a real-time chart.

Endpoint: md/getChart

Parameters:

1{
2  "symbol": "ESM7", // or 123456
3  "chartDescription": {
4    "underlyingType": "MinuteBar", // Tick, DailyBar, MinuteBar, Custom, DOM
5    "elementSize": 15,
6    "elementSizeUnit": "UnderlyingUnits", // Volume, Range, UnderlyingUnits, Renko, MomentumRange, PointAndFigure, OFARange
7    "withHistogram": true
8  },
9  "timeRange": {
10    // all fields are optional, but at least one is required
11    "closestTimestamp": "2017-04-13T11:33Z",
12    "closestTickId": 123,
13    "asFarAsTimestamp": "2017-04-13T11:33Z",
14    "asMuchAsElements": 66
15  }
16}

Response: The response contains two subscription IDs, historicalId and realtimeId. Store realtimeId so you can cancel the real-time chart subscription with md/cancelChart.

1{
2  "s": 200,
3  "i": 13,
4  "d": {
5    "historicalId": 32,
6    "realtimeId": 31
7  }
8}

Data message:

1{
2  "e": "chart",
3  "d": {
4    "charts": [ // "charts" may contain multiple chart objects
5      {
6        "id": 9, // matches historicalId or realtimeId from the response
7        "td": 20170413, // trade date as YYYYMMDD
8        "bars": [ // "bars" may contain multiple bar objects
9          {
10            "timestamp": "2017-04-13T11:00:00.000Z",
11            "open": 2334.25,
12            "high": 2334.5,
13            "low": 2333,
14            "close": 2333.75,
15            "upVolume": 4712,
16            "downVolume": 201,
17            "upTicks": 1334,
18            "downTicks": 83,
19            "bidVolume": 2857,
20            "offerVolume": 2056
21          }
22        ]
23      }
24    ]
25  }
26}

Cancel Chart

Endpoint: md/cancelChart

Parameters:

1{
2  "subscriptionId": 123456 // the historical chart subscription ID from the md/getChart response
3}