Powered by

Market Data Protocol Specification

The CryptoStruct market data protocol uses JSON arrays for every message: requests, responses, and events. The first element of the array is always an integer message type; the rest is type-specific.

[
  msgType,
  ...
]

Requests

Login

Login is required before subscribing to any instrument.

Request

[
  13, 
  organization,
  application_name,
  application_version,
  process_id
]
Field Type Description
msgType integer Always 13
organization string Name of your organization or company
application_name string Name or type of your application
application_version string Version of your application
process_id string ID to identify the instance of your application 
[
  13,
  "ACME",
  "MyApp",
  "1.2.3",
  "MyApp_Tokyo"
]

Response

[
  14,
  process_id,
  application_version,
  protocol,
  capabilities
]
Field Type Description
msgType integer Always 14
process_id string Instance ID of the market data service
application_version string Service version
protocol string Version of the protocol
capabilities json object Information about available market data topics 
[
  14,
  "bitmex-master-a",
  "1.23.4",
  "5",
  {
    "depthTopic": {
      "eventIdType": "ORDERED",
      "exchangeTimestampType": "UNKNOWN",
      "exchangeTimestampPrecision": "MILLIS"
    },
    "topOfBookTopic": null,
    "tradesTopic": null,
    "crossTopicBookEventId": true
  }
]

Subscription

[
  11,
  instrument,
  options
]
Field Type Description
msgType integer Always 11
instrument long Instrument ID
options json object (Optional) Configuration for topics and features

Options (defaults shown):

{
  "depthTopic": true,
  "tradesTopic": true,
  "topOfBookTopic": true,
  "indexPriceTopic": true,
  "markPriceTopic": true,
  "fundingRateTopic": true,
  "liquidationsTopic": false,
  "topOfBookCoalescing": false
}
  • Topic flags: pick which market-data topics to subscribe to.
  • topOfBookCoalescing: when enabled, the Market Data Adapter drops outdated top-of-book updates during bursts or under load and publishes only the latest event.
 
[
  11,
  22,
  {
    "depthTopic": false
  }
]

Behaviour:

  • On a successful subscription, the first message received is an initial snapshot of the order book, followed by other initial data and events.

  • If the subscription fails, an error state event is received for the instrument.

  • An instrument cannot be subscribed multiple times.

Unsubscription

[
  12,
  instrument
]
Field Type Description
msgType integer Always 12
instrument long Instrument ID 
[
  12,
  22
]

Events

Common

Every event except Instrument State uses the same shell:

Common Event Structure
[
  msgType,
  instrument,
  prevEventId,
  eventId,
  adapterTimestamp,
  exchangeTimestamp,
  data
]

Common fields:

Field Type Description
msgType integer Message type (see table below)
instrument long Instrument ID
prevEventId string ID of the previous event (potentially empty/null)
eventId string ID of this event
adapterTimestamp long Receive timestamp (ns since epoch) at MDA; not guaranteed to be increasing
exchangeTimestamp long Timestamp (ns since epoch) reported by exchange; 0 if not available
data json Event-specific data

Message types:

msgType Event
0 Snapshot
1 Book update
2 Trades
5 Instrument state
6 Top-of-Book
7 Mark price
8 Index price
9 Funding rate
17 Liquidations

Snapshot

A snapshot is the full state of the order book.

The Snapshot event differs from other events in one way: the trailing data slot is replaced by two top-level fields, the levels array and a forceReset boolean.

[
  [side, price, quantity, ordercount],
  [side, price, quantity, ordercount],
  ...
],
forceReset
Field Type Description
side integer Book side: 0 (BID) or 1 (ASK)
price string Price
quantity string Quantity
ordercount integer Currently not used, always 1
forceReset boolean Reset the local book unconditionally, even if prevEventId does not match the last accepted event ID 
[
  0,
  123456,
  "12345678-1",
  "12345678-2",
  1580143531008103451,
  1580143530031129024,
  [
    [
      0,
      "7098.25",
      "10",
      1
    ],
    [
      1,
      "7099.25",
      "20",
      1
    ]
  ],
  true
]

Book Update

A book update is a level-based change to the order book.

[
  [side, price, quantity, ordercount],
  [side, price, quantity, ordercount],
  ...
]
Field Type Description
side integer Book side: 0 (BID) or 1 (ASK)
price string Price
quantity string Quantity
ordercount integer Currently not used, always 1 
[
  1,
  123456,
  "12345678-1",
  "12345678-2",
  1580143531008103451,
  1580143530031129024,
  [
    [
      0,
      "7098.25",
      "10",
      1
    ],
    [
      1,
      "7099.25",
      "20",
      1
    ]
  ]
]

Trades

A list of trades that occurred.

[
  [side, price, quantity, tradeId, exchangeTradeTimestamp],
  ...
]
Field Type Description
side integer Aggressive side: 0 (BID) or 1 (ASK)
price string Trade price
quantity string Trade quantity
tradeId string Exchange trade ID (potentially empty/null)
exchangeTradeTimestamp integer Timestamp (ns since epoch) of trade; can differ from the message's exchangeTimestamp 
[
  2,
  123456,
  "12345678-2",
  "12345679-3",
  1580143531008103451,
  1580143530031129024,
  [
    [
      0,
      "7098.25",
      "10",
      "6as78d678asdf78as789fas",
      11580143530031129024
    ]
  ]
]

Top-of-Book

An array with up to two levels (the top level per side).

[
  [side, price, quantity, ordercount],
  [side, price, quantity, ordercount]
]
Field Type Description
side integer Book side: 0 (BID) or 1 (ASK)
price string Price
quantity string Quantity
ordercount integer Currently not used, always 1

Behaviour:

  • If one side is empty, the array carries one element (the non-empty side).

  • If both sides are empty, the array is empty.

  • Bid and ask order is undefined.

 
[
  6,
  123456,
  "12345678-1",
  "12345678-2",
  1580143531008103451,
  1580143530031129024,
  [
    [
      0,
      "7098.25",
      "10",
      1
    ],
    [
      1,
      "7099.25",
      "20",
      1
    ]
  ]
]

Mark Price

Mark price for the instrument. Option instruments also publish Greeks and implied volatilities; non-option instruments leave those fields null.

markPrice, delta, gamma, vega, theta, markVolatility, bidVolatility, askVolatility
Field Type Description
markPrice string Mark price
delta string Sensitivity to underlying price (null if N/A)
gamma string Rate of delta change (null if N/A)
vega string Sensitivity to volatility (null if N/A)
theta string Time decay (null if N/A)
markVolatility string Mark implied volatility (null if N/A)
bidVolatility string Bid implied volatility (null if N/A)
askVolatility string Ask implied volatility (null if N/A) 
[
  7,
  123456,
  "12345678-1",
  "12345678-2",
  1580143531008103451,
  1580143530031129024,
  "123.456",
  null,
  null,
  null,
  null,
  null,
  null,
  null
]
 
[
  7,
  123456,
  "12345678-1",
  "12345678-2",
  1640995200300000000,
  1640995200200000000,
  "62604.69",
  "-0.9999672034",
  "0.0000000002",
  "0.0000114332",
  "28.2649858387",
  "0.3675503331",
  "0.36",
  "0.375"
]

Index Price

Index price for the instrument.

price
Field Type Description
price string Index price 
[
  8,
  123456,
  "12345678-1",
  "12345678-2",
  1580143531008103451,
  1580143530031129024,
  "456.789"
]

Funding Rate

Last funding rate, time of next funding, and the predicted next funding rate.

[
  lastFundingRate,
  nextFundingTime,
  nextFundingRate
]
Field Type Description
lastFundingRate string Last funding rate
nextFundingTime long Timestamp (ns since epoch) of next funding
nextFundingRate string Predicted next funding rate 
[
  9,
  123456,
  "12345678-1",
  "12345678-2",
  1580143531008103451,
  1580143530031129024,
  [
    "0.123",
    1580163530031129024,
    "0.123"
  ]
]

Liquidations

A list of liquidation orders.

[
  [side, price, quantity, exchangeLiquidationTimestamp],
  ...
]
Field Type Description
side integer Side: 0 (BID) or 1 (ASK)
price string Bankruptcy price
quantity string Liquidation quantity
exchangeLiquidationTimestamp integer Timestamp (ns since epoch) of liquidation; can differ from the message's exchangeTimestamp 
[
  17,
  123456,
  "12345678-2",
  "12345679-3",
  1580143531008103451,
  1580143530031129024,
  [
    [
      0,
      "7098.25",
      "10",
      11580143530031129024
    ]
  ]
]

Instrument State

The state of the instrument. Moves to ERROR when the connection to the exchange drops or when the subscription fails (e.g. unknown instrument).

[
  msgType,
  instrument,
  adapterTimestamp,
  state,
  message
]
Field Type Description
msgType integer Always 5
instrument long Instrument ID
adapterTimestamp long System timestamp (ns since epoch) at state event occurrence
state string Market data state of the instrument: "ERROR" or "READY"
message string Error details (potentially empty) 
[
  5,
  123456,
  1580143531008103451,
  "ERROR",
  "connection lost"
]

Market Data Capabilities

Available capabilities depend on the exchange and on the Market Data Adapter version. Capabilities describe which data feeds are available and how they behave.

Capability structure

{
  "depthTopic": {
    "eventIdType": "ORDERED",
    "exchangeTimestampType": "UNKNOWN",
    "exchangeTimestampPrecision": "MILLIS"
  },
  "topOfBookTopic": {
    "eventIdType": "ORDERED",
    "exchangeTimestampType": "UNKNOWN",
    "exchangeTimestampPrecision": "MILLIS"
  },
  "tradesTopic": {
    "eventIdType": "UNORDERED",
    "exchangeTimestampType": "MATCHING_ENGINE",
    "exchangeTimestampPrecision": "MICROS"
  },
  "fundingRateTopic": null,
  "markPriceTopic": null,
  "indexPriceTopic": null,
  "liquidationsTopic": null,
  "crossTopicBookEventId": true,
  "predictedFundingRate": false
}

Topic fields

Each *Topic field describes a market-data topic. If the topic isn't available, the field is null. Available topic fields: depthTopic, topOfBookTopic, tradesTopic, markPriceTopic, indexPriceTopic, fundingRateTopic, liquidationsTopic.

Event ID Type

The nature of the event ID.

Value Description
ORDERED Event ID is an ever-increasing sequence number
UNORDERED Event ID is a hash

Exchange Timestamp Type

Where the exchange timestamp comes from.

Value Description
NONE No exchange timestamp available
UNKNOWN Exchange timestamp is present, but its origin is not documented
MATCHING_ENGINE Timestamp is set in the matching engine
EXCHANGE_OUT Timestamp is set when an event is published to the client

Exchange Timestamp Precision

Precision of the exchange timestamp. null when exchangeTimestampType is NONE.

Value Description
MILLIS Millisecond precision
MICROS Microsecond precision
NANOS Nanosecond precision

Cross-Topic Book Event ID

Field: crossTopicBookEventId

  • Type: Boolean.
  • Description: if true, depthTopic and topOfBookTopic use ordered event IDs and share the same exchange-side sequence. The event ID can be used to determine whether depth data or top-of-book data is more recent.

Predicted Funding Rate

Field: predictedFundingRate

  • Type: Boolean.
  • Description: if true, the exchange supports the predicted funding rate.

See Also