Introduction

Version: 0.5

Welcome to BSDEX! This mini-guide is intended to help you connect to BSDEX's API.

Now you should be able to create orders via the web app.

API connectivity

The following are base URLs

Base URL: https://api-public.bsdex.de/

Basic information

This section provides basics information about authentication, pagination, relevant request and response headers and anything which is relevant for integrating with the BSDEX API.

Authentication

In order to use the API, you need add the following headers in your HTTP requests:

• "Date" should contain the current date in rfc7231 format. Such as "Tue, 07 Jul 2020 14:16:19 UTC". Let's call it "DATE".
• "ApiKey" is your API key.
• "Authorization" is of format 'hmac username="$BSDEX_API_KEY", algorithm="hmac-sha1", headers="date", signature="$SIGNATURE"' where

You can calculate the value of $SIGNATURE by sha1 HMAC of the string "date: $DATE" in base 64.

Example:

#!/bin/bash
BSDEX_API_KEY=put-your-api-key-here
BSDEX_API_SECRET=put-your-api-secret-here
DATE="`date -u '+%a, %d %b %Y %T %Z'`"
# The signature is in fact HMAC signature of a few fields, currently only "date", using your API secret.
AUTHORIZATION="hmac username=\"$BSDEX_API_KEY\", algorithm=\"hmac-sha1\", headers=\"date\", signature=\"`/bin/echo -n "date: ${DATE}" | openssl sha1 -binary -hmac "${BSDEX_API_SECRET}" | base64 `\""
curl -v \
    -H "Date: $DATE" \
    -H "ApiKey: $BSDEX_API_KEY" \
    -H "Authorization: $AUTHORIZATION" \
    -X GET "https://api-public.bsdex.de/api/v1/balance"

And you'll receive a response such as:

[
  {
    "asset_id": "btc",
    "available": "0",
    "locked": "0"
  },
  {
    "asset_id": "eur",
    "available": "34163",
    "locked": "123"
  }
]

For all API requests, "Date", "ApiKey" and "Authorization" headers must be present.

Note on Self-Trades

If self-trade prevention is enabled for your account, the trading engine prevents two ordrs of the same user to match. This is done by cancelling the aggressive order. The 'cancelled_reason' field of the cancelled order will be set to "self_trade". Note that the aggressive order can be partially filled before being cancelled due to self trade.

Auctions and Phases

Phases

At any point in time, a BSDEX market operates within a phase. By subscribing to the phases channel for a market, you get the current phase as well as changes to the phase:

{
  "type": "subscribe",
  "chan_name": "phases",
  "subchan_name": "btc-eur"
}

And the server responds with:

{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "subscribed"
}
{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "online"
}
{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": {
    "name": "continuous-trading",
    "start_ts": 1723456449279064870
  }
}

Which means the market is in continuous trading phase at the moment. See section Trading Phases for an explanation of each trading phase. For more details about the phases channels behavior see section Phases Channel.

You can get the same payload by calling the current phase's HTTP endpoint:

GET /api/v1/btc-eur/phases/current

For more details about this REST API endpoint see section Get current market phase.

Auction and Phases

In continuous trading phase, orders continuously get matched. However in certain situations, the market enters an auction. This could happen when:

• Market opens.
• Market resumes from 'tradinghalt' or 'suspended' phases.
• A trade causes a volatility interruption.

In such case, the market enters auction "call" phase. During an auction, no trade takes place and the orderbook may be crossed.

A message is sent to the phases channel:

{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": {
    "name": "auction-call",
    "start_ts": 1723456534127110500
  }
}

Auction "call" phases has a fixed duration after which, the market enters auction "price" phase, which has a random length. During auction call and price phase, the auction channel provides information on the current state of the auction.

If the orderbook is crossed, this channel receives the hypothetical auction price with volume and surplus values:

{"chan_name":"auction","subchan_name":"btc-eur","type":"data","data":{"auction_price":"9500.50", "auction_volume":"20.2", "surplus": "0.8", "surplus_side":"buy", "market": "btc-eur"}}

This means that if the auction were to end at the hypoehtical auction price of 9500.50, 20.20 worth of base asset will be traded and "0.8" worth of base asset in surplus will remain outstanding. Auction volume and surplus will continually reflect the liquidity that's being added or removed during the auction call and price phases. Note that a "surplus_side" of "none" means there is no surplus.

On the other hand, if the orderbook is not crossed, this channel receives information on top of the book:

{"chan_name":"auction","subchan_name":"btc-eur","type":"data","data":{"buy_price":"9500.00", "buy_volume":"20.2", "sell_price": "9510.10", "sell_volume":"1.11", "market": "btc-eur"}}

Trading Phases

• continuous-trading - Clients can post orders and orders get matched continuously. Orderbook will always be uncrossed.
• auction-call - The auction starts in the "auction-call" phase. Clients can post orders but orders do not match. Consequently, the orderbook may be crossed at times. The length of auction call phase is fixed and once it ends, the "auction-price" phase starts.
• auction-price - The "auction-price" phase behaves similarly to auction-call phase except that it has a random but bounded length. At the end of "auction-price" phase, if the orderbook is not crossed, the market enters the "continuous-trading" phase. However, if the orderbook is crossed (i.e. there are orders to martch), the auction price will be determined as the price with highest turnover and lowest surplus. If the auction price is within an acceptable band around of the asset's price in other markets, the auction ends with the execution of orders and it enters the "continuous-trading" phase. If the auction price is not within an acceptable band of the asset's price, the market enters "auction-recall" phase.
• auction-recall - In this phase, having entered from the "auction-price" phase with a crossed order book but without an acceptable price, clients can post orders and as soon as the would-be auction price is within the acceptable range, or the order book is uncrossed, the "auction-recall" phase goes back to the "auction-price" phase.
• system-down - Clients can post orders but orders does not match. The "system-down" phase ends into the "auction-call" phase when the market reopens.
• suspended - Market is suspended and all orders are deleted from the system. Clients cannot post orders.
• trading-halt - Market is temporarily halted. Clients can post orders but orders does not match. The "trading-halt" phase ends into the "auction-call" phase when the market resumes.

Recommended Quoting Behavior During Different Phases

• Quote during the continuous-trading phase.
• Quoted during the auction-call, auction-price and auction-recall phases. The client may adjust the volume of the quote based on the amount of surplus reported in the auction WebSocket channel.
• Cancel the existing orders and stop quoting when entering trading-halt and system-down phases.
• Do not quote nor attempt to cancel quotes during the suspended phase, as orders have already been cancelled.

General guidelines on Error Handling

Specific endpoint errors are described under specific endpoints, some errors are common to all requests.

Authentication Errors

In case the HMAC authentication does not work, you might receive the following errors:

Trading API Errors

Below are lists of REST API error codes of the Trading API, and an explanation of what these errors mean.

Response-Level

Response level errors are present when the HTTP response payload will be structured like this:

{
  "id": "09ae20b4bcdf13da88558fb5bb8b0399",
  "status": 418,
  "code": "I'm a teapot",
  "detail": "still a teapot", // optional
  "source": {
    "field": "fld",
    "message": "msg"
  } // optional
}

Each error object contains "id", which is the internal bsdex request id associated with the HTTP request, "status" the string representation of http status code or an internal service level key, "code" the string representation of the http status code. The object also contains optional field "detail", which explains the actual error. 400 Bad request errors contain the sub object "source", which contains the "field" with the invalid value & "message" that explains it.

Response-Level Error Codes

WebSockets API

BSDEX offers a WebSockets API to subscribe to real-time data. You need to authenticate similar to HTTP endpoints.

The following example uses a command line tool "websocat". Please download the tool to run the examples below.

#!/bin/bash
BSDEX_API_KEY=put-your-api-key-here
BSDEX_API_SECRET=put-your-api-secret-here
DATE="`date -u '+%a, %d %b %Y %T %Z'`"
AUTHORIZATION="hmac username=\"$BSDEX_API_KEY\", algorithm=\"hmac-sha1\", headers=\"date\", signature=\"`/bin/echo -n "date: ${DATE}" | openssl sha1 -binary -hmac "${BSDEX_API_SECRET}" | base64 `\""
websocat wss://api-public.bsdex.de/api/v1/ws -H "Date: $DATE" -H "ApiKey: $BSDEX_API_KEY" -H "Authorization: $AUTHORIZATION"

If the connection and authentication are successful, you're given an interactive shell. Try subscribing to the orderbook channel:

{"type":"subscribe","chan_name":"orderbook","subchan_name":"btc-eur"}

Which subsequently you'll receive a full orderbook folllowed by real-time changes to the orderbook:

{"chan_name":"orderbook","subchan_name":"btc-eur","type":"subscribed"}
{"chan_name":"orderbook","subchan_name":"btc-eur","type":"online"}
{"chan_name":"orderbook","subchan_name":"btc-eur","type":"data","data":[{"price":"53119.54","side":"sell","size":"0.001","market":"btc-eur","order_count":1},{"price":"52794.86","side":"buy","size":"0.001","market":"btc-eur","order_count":1}],"meta":{"dti":"4H95J0R2X","asset_name":"Bitcoin","price_curr":"BTC/EUR","price_nota":"MONE","quantity_nota":"UNIT","venue":"XDEX","system":"HYBR","published_at":"2024-08-08T14:20:42.452792Z"}}
{"chan_name":"orderbook","subchan_name":"btc-eur","type":"data","data":[{"price":"53119.54","side":"sell","size":"0","market":"btc-eur","order_count":0},{"price":"53103.44","side":"sell","size":"0.001","market":"btc-eur","order_count":1},{"price":"52794.86","side":"buy","size":"0.001","market":"btc-eur","order_count":1}],"meta":{"dti":"4H95J0R2X","asset_name":"Bitcoin","price_curr":"BTC/EUR","price_nota":"MONE","quantity_nota":"UNIT","venue":"XDEX","system":"HYBR","published_at":"2024-08-08T14:20:54.022131Z"}}

Ping Pong

Client can ping server to determine whether connection is alive, server responds with pong. This is an application level ping as opposed to default ping in websockets standard which is server initiated It is ideal to use ping to avoid disconnection if no messages are received within the configured idle timeout

{"type": "ping"}

Response:

{"type": "pong"}

Connection Limits

See this section for details.

To limit load there is a hard limit of 400 websocket connections which can simultaneosly be opened per user account. Once this limit is reached any new connection will receive the below error message, after which the connection is terminated from server-side.

# Error Message
{
  "type": "error",
  "data": {
    "message": "maximum amount of websocket connections reached"
  }
}

Due to replication and routing in some edge cases this message can already occur on new connection creation from 200 active connections onwards.

Session Management

Clients can use the session message to manage the current websocket session.

Below flags are currently supported

1. enable_cancel_on_disconnect: Enables or disables batch cancellation of all open orders if the users websocket session is disconnected. Default: false
2. idle_timeout: Time interval in seconds until the gateway disconnects the session if no data has been exchanged between server and client. Default: 60s

To avoid automatic disconnects after idle_timeout, the client should send periodic ping messages as described above.

{
  "type": "session",
  "data": {
    "enable_cancel_on_disconnect": true,
    "idle_timeout": 60
  }
}

Channels and Subchannels

The real-time feed is organised in hierarchy of "channels" and "subchannels". A channel is a category of real-time data which contains multiple subchannels.

Available channels and subchannels:

Orderbook Channel

Provides orderbook state and changes per subscribed market.

• btc-eur
• eth-eur
• [ other markets ]

The first message of type data after subscribing will contain a complete snapshot of the current orderbook. Followup messages are delta updates that a client should apply to the internal orderbook representation in order to keep it up-to-date.

# Subscribe via
{
  "type": "subscribe",
  "chan_name": "orderbook",
  "subchan_name": "btc-eur",
  "params": {
      #optional flag to avoid disconnect when feed goes offline during auction
      #false by default. Set true to avoid disconnection
      "keep_alive_when_offline": true
  }
}
# Response
{
  "chan_name": "orderbook",
  "subchan_name": "btc-eur",
  "type": "subscribed"
}
{
  "chan_name": "orderbook",
  "subchan_name": "btc-eur",
  # feed status -- online or offline
  "type": "online"
}
# Orderbook Message
{
  "chan_name": "orderbook",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": [
    {
      "price": "61812.91",
      "side": "buy",
      "size": "1",
      "market": "btc-eur",
      "order_count": 3
    },
    {
      "price": "62012.3",
      "side": "sell",
      "size": "0.15",
      "market": "btc-eur"
      "order_count": 1
    }
  ],
  "meta": {
    "dti": "4H95J0R2X",
    "asset_name": "Bitcoin",
    "price_curr": "BTC/EUR",
    "price_nota": "MONE",
    "quantity_nota": "UNIT",
    "venue": "XDEX",
    "system": "HYBR",
    "published_at": "2023-07-17T16:34:09.783483Z"
  }
}

Quote Channel

Contains real-time changes to top of the books

• btc-eur
• eth-eur
• [ other markets ]

# Subscribe via
{
  "type": "subscribe",
  "chan_name": "quote",
  "subchan_name": "btc-eur"
}
# Response
{
  "chan_name": "quote",
  "subchan_name": "btc-eur",
  "type": "subscribed"
}
{
  "chan_name": "quote",
  "subchan_name": "btc-eur",
  "type": "online"
}
# Quote message
{
  "chan_name": "quote",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": {
    "buy_price": "48649.27",
    "buy_volume": "0.01",
    "sell_price": "48701.74",
    "sell_volume": "0.01",
    "market": "btc-eur"
  }
}

Phases Channel

Contains information about phase changes, such as "continuous-trading", "auction-call" or "auction-price". The start timestamp start_ts is given in nanoseconds since Unix epoch. After successful subscription, an initial message stating the currently active phase is sent. The start timestamp of this initial phase is typically further in the past since it started before the client subscribed to the channel. All other phase messages represent live updates and therefore typically carry a more recent timestamp.

• btc-eur
• eth-eur
• [ other markets ]

# Subscribe
{
  "type": "subscribe",
  "chan_name": "phases",
  "subchan_name": "btc-eur"
}
# Subscription response
{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "subscribed"
}
{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "online"
}
# Initial phase active during subscribe request (start_ts is typically further in the past since the phase started before the client subscribed)
{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": {
    "name": "continuous-trading",
    "start_ts": 1723456449279064870
  }
}
# 1st phase update after subscribing (start_ts is more recent)
{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": {
    "name": "auction-call",
    "start_ts": 1723456534127110500
  }
}
# 2nd phase update after subscribing (start_ts is more recent)
{
  "chan_name": "phases",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": {
    "name": "auction-price",
    "start_ts": 1723456547141235724
  }
}

Public Trade Channel

Contains information about public trades.

• btc-eur
• eth-eur
• [ other markets ]

# Subscribe via
{
  "type": "subscribe",
  "chan_name": "public_trade",
  "subchan_name": "btc-eur"
}
# Response
{
  "chan_name": "public_trade",
  "subchan_name": "btc-eur",
  "type": "subscribed"
}
{
  "chan_name": "public_trade",
  "subchan_name": "btc-eur",
  "type": "online"
}
# Public Trade message
{
  "chan_name": "public_trade",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": [
    {
      "id": "98a831b0-b48a-4444-b926-fa0cec5a8974",
      "executed_at": "2023-07-17T16:34:09.123456Z",
      "local_ts": 1616393143567786800,
      "quantity": "0.01",
      "price": "48677.73",
      "market": "btc-eur",
    }
  ],
  "meta": {
    "dti": "4H95J0R2X",
    "asset_name": "Bitcoin",
    "price_curr": "BTC/EUR",
    "price_nota": "MONE",
    "quantity_nota": "UNIT",
    "venue": "XDEX",
    "published_at": "2023-07-17T16:34:09.783483Z"
  }
}

Auction Channel

Contains auction information, including real-time hypothetical auction price.

• btc-eur
• eth-eur
• [ other markets ]

# Subscribe via
{
  "type": "subscribe",
  "chan_name": "auction",
  "subchan_name": "btc-eur"
}
# Response
{
  "chan_name": "auction",
  "subchan_name": "btc-eur",
  "type": "subscribed"
}
{
  "chan_name": "public_trade",
  "subchan_name": "btc-eur",
  "type": "online"
}
# Auction message
{
  "chan_name": "auction",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": {
    "auction_price": "61905.12",
    "auction_volume": "0.0104",
    "surplus": "0.98960001",
    "surplus_side": "buy",
    "local_ts": 1616396326042637300,
    "market": "btc-eur"
  },
  "meta": {
    "dti": "4H95J0R2X",
    "asset_name": "Bitcoin",
    "price_curr": "BTC/EUR",
    "price_nota": "MONE",
    "quantity_nota": "UNIT",
    "venue": "XDEX",
    "system": "HYBR",
    "published_at": "2023-07-17T16:34:09.783483Z"
  }
}

Private Order Channel

Contains changes to an authenticated user's own orders.

• btc-eur
• eth-eur
• [ other markets ]

# Subscribe via
{
  "type": "subscribe"
  "chan_name": "order",
  "subchan_name": "btc-eur",
}
# Response
{
  "chan_name": "order",
  "subchan_name": "btc-eur",
  "type": "subscribed"
}
{
  "chan_name": "order",
  "subchan_name": "btc-eur",
  "type": "online"
}
# Order message
{
  "chan_name": "order",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": [{
    "id": "98a831b0-b48a-4444-b926-fa0cec5a8974",
    "client_id": "X_1",
    "side": "sell", # values can be "sell" or "buy"
    "type": "limit", # values can be "limit", "market"
    "quantity": "0.1",
    "price": "45000",
    "order_status": "open", # values can be "open", "closed", "cancelled", "rejected"
    "fill_status": "unfilled", # values can be "unfilled", "partially_filled", "filled"
    "created_at": 1616396326042637300,
    "market": "btc-eur"
    # additional fields received for market buy order
    "quote_quantity": "25679.50",
    "quote_filled": "12500",
    # additional fields received when order was cancelled
    "cancelled_at": 1616396326042637600,
    "cancelled_reason": "cancelled_by_user", # values can be "cancelled_by_user", "cancelled_by_market", "self_match"
    # additional fields received for stop order
    "stop_price": "44500",
    # additional fields received when stop order is triggered
    "triggered_at": 1616396326042637450,
    "triggered_price": "44650",
    "triggered_reason": "last_traded_price", # values can be "last_traded_price", "highest_buy", "lowest_sell"
    # additional fields received after the first fill
    "recent_fill_quantity": "0.05", # most recently filled quantity
    "recent_fill_price": "45000" # price of most recent fill
  }],
  "params": {
      "user_id": "X"
  }
}

Private Trades Channel

Contains own trades, with more information than public_trades

• btc-eur
• eth-eur
• [ other markets ]

# Subscribe via
{
  "type": "subscribe"
  "chan_name": "trade",
  "subchan_name": "btc-eur",
}
# Response
{
  "chan_name": "trade",
  "subchan_name": "btc-eur",
  "type": "subscribed"
}
{
  "chan_name": "trade",
  "subchan_name": "btc-eur",
  "type": "online"
}
# Private Trades message
{
  "chan_name": "trade",
  "subchan_name": "btc-eur",
  "type": "data",
  "data": {
    "id": "98a831b0-b48a-4444-b926-fa0cec5a8974",
    "local_ts": 1616396326042637300,
    "quantity": "0.01",
    "price": "48677.73",
    "side": "buy",
    "order_id": "98a831b0-b48a-4444-b926-fa0cec5a8974",
    "client_order_id": "X_1",
    "fee": "4.99",
    "market": "btc-eur"
  },
  "params": {
      "user_id": "X"
  }
}

Private Balance Channel

Contains changes to the balance, including amounts locked for open orders.

• btc
• eth
• eur
• [ other assets ]

# Subscribe via
{
  "type": "subscribe",
  "chan_name": "balance"
  "subchan_name": "btc",
}
# Response
{
  "chan_name": "balance",
  "subchan_name": "btc",
  "type": "subscribed"
}
{
  "chan_name": "balance",
  "subchan_name": "btc",
  "type": "online"
}
# Balance Update message
{
  "chan_name": "balance",
  "subchan_name": "btc",
  "type": "data",
  "data": {
    "asset_id": "btc",
    "available": "0.102",
    "locked": "1.1",
  },
  "params": {
      "user_id": "X"
  }
}

Channel Availability

Clients receive the availability of a certain real-time feed via status messages. The current status of a channel, subchannel feed is received immediately after subscription. Clients are responsible for implementing their own rules when feed status messages are received. For example, clearing cached orderbook data when the orderbook channel goes offline.

{
  "chan_name": "orderbook",
  "subchan_name": "btc-eur",
  "type": "online" # values can be "online", "offline"
}

Keep Alive flag

To enforce clearing of context/data cached for a websocket connection, the gateway disconnects clients who are subscribed to a channel that goes offline. To keep the connection alive, without the above disconnection, please set the keep_alive_when_offline optional flag to true, in the subscribe message.

{
  "type": "subscribe",
  "chan_name": "orderbook",
  "subchan_name": "btc-eur",
  "params": {
      "keep_alive_when_offline": true
  }
}

FIX API

Version 0.6 (beta)

BSDEX provides a FIX API for order management. The specification is based on FIX 4.4.

The FIX API:

• Supports order entry operations for creating, canceling and querying orders.
• Supports market data subscription for listening on aggregated orderbook changes and trades.
• Support for Cancel-On-Disconnect is currently only implemented for WebSocket connections but might be added to the FIX API in a future releases.
• Supports ResendRequest.

Connectivity

The FIX endpoint for prelive (sandbox) is listed below. Fix on live environment is not active yet but will be activated when ready.

General Components

Supported messages are defined in the sections below. Messages are based on Fix 4.4. with some custom adaptions. For example, a field that is optional in the Fix standard can be mandatory here and the other way around. The table below gives an overview about the meaning of the Req column.

Header

Subsequent header tags must exist in every message.

Trailer

Subsequent trailer tags must exist in every message.

Error Handling

SessionMessageReject (3) and BusinessMessageReject (j) are two message types used for error handling and rejection of messages. When a reject message is sent, it provides details about the rejection reason, allowing the receiver to diagnose and address the session-level issue and/or application-level issue.

Session Message Reject (3)

The Session Message Reject (3) should be issued when a message is received but cannot be properly processed due to a session-level rule violation.

Business Message Reject (j)

The Business Message Reject (j) message can reject an application-level message which fulfills session level rules and can't be rejected via any other means. Note if the message fails a session-level, a session-level reject messages should be issued.

Session Messages

Logon (A)

The Logon message is used by clients to authenticate after the TCP/TLS session has been established. It must be sent and processed successfully before any business related messages can be sent or received.

The authentication mechanism works similar as described in Basic information, section Authentication. A base64 encoded HMAC signature needs to be generated by the client. When using the fix API this signature is transferred in field RawData(96).

The signature is composed as follows:

hmac username="BSDEX_API_KEY", algorithm="hmac-sha1", headers="date", signature="SIGNATURE"

BSDEX_API_KEY needs to be replaced by the clients API key and SIGNATURE needs to be generated as follows:

• Create a date string with format date: DATE where DATE is the current date as specified in standard header field SendingTime(56) but using RFC7231 format, such as Tue, 07 Jul 2020 14:16:19 UTC
• Generate an SHA1 HMAC from the date string using your API secret.
• Encode the HMAC in base64 format.

The completed signature must be written to field RawData(96). Please make sure that the standard header fields SendingTime(52) and SenderCompID(49) are set. SendingTime(52) must use the same timestamp as used for generating the HMAC (but the format in the header field uses the standard FIX UTC timestamp format).

For a bash script example on how to generate a valid signature, see Basic information, section Authentication.

Heartbeat (0)

The Heartbeat (0) monitors the status of the communication link and identifies when the last of a string of messages was not received.

Test Request (1)

The Test Request (1) message forces a heartbeat from the opposing application. The Test Request (1) message checks sequence numbers or verifies communication line status. The opposite application responds to the Test Request (1) with a Heartbeat (0) containing the TestReqID (112).

Resend Request (2)

The Resend Request (2) is sent by the receiving application to initiate the retransmission of messages. This function is utilized if a sequence number gap is detected, if the receiving application lost a message, or as a function of the initialization process.

Reset Sequence (4)

The Sequence Reset (4) message has two modes: Gap Fill mode and Reset mode.

Logout (5)

The Logout message is used by clients to gracefully terminate a Fix connection. After logout, no business related messages can be sent or received until another logon happens.

Order Entry Messages

New Order Single (D)

The New Order Single message can be used by clients to submit a new order to the exchange. The client needs to have enough funds to place the order.

Depending on the order type and side, some conditional fields are required while others are not. Please see the table below for an overview which conditional fields must be set. Note that other conditional fields must be omitted.

Response

If the message cannot be processed a Business Message Reject (j) will be sent to the client. This can happen due to insufficient funds, missing fields or other reasons. In case of successful order creation, the client will receive an Execution Report (8) containing the provided client order ID and status new.

Order Cancel Request (F)

Order Cancel can be sent by clients to cancel a single order that has not been completely filled yet. Note that one of both IDs must be specified. Either the OrigClOrdID as specified by the client during order creation or the OrderID that was assigned by the exchange. If both are present, OrigClOrdID will take precedence and OrderID may be ignored.

Response

In case of successful order cancellation, the client will receive an Execution Report (8) containing the provided client order ID and status canceled. If the order cancellation fails, an Order Cancel Reject (9) message will be issued. This could occur if the order is unknown or due to other factors.

Order Cancel Reject (9)

The Order Cancel Reject (9) message is sent when an Order Cancel Request is unsuccessful.

Order Mass Cancel Request (q)

Order Mass Cancel Request can be sent by clients to cancel a single market orders or cancel all orders from all markets.

Response

The OrderMassCancelReport (r) is used to acknowledge an Order Mass Cancel Request. Note that each affected order that is canceled is acknowledged with a separate Execution Report (8).

Order Mass Cancel Report (r)

Bulk Order (U1)

The Bulk Order request is a custom message that is specified by MsgType U1 and not defined by the Fix standard. It allows clients to cancel and create up to 10 orders each with a single message. Note that the client needs to have enough funds to have new orders funded momentarily even before canceled orders are taken into account. If new orders are specified, the conditional fields to specify depend on the order type and side. Please see message New Order Single (D) for details about conditional new order fields. The requirements are the same here.

Response

If the message cannot be processed a Business Message Reject (j) will be sent to the client. This can happen due to insufficient funds, missing fields or other reasons. In case of successful order creation / cancellation, the client will receive an Execution Report (8) for each created and cancelled order containing the related (client) order ID and status new or canceled.

Order Status Request (H)

Order Status Request can be sent by clients to retrieve the current state of an order. Note that one of both IDs must be specified. Either the OrigClOrdID as specified by the client during order creation or the OrderID that was assigned by the exchange.

Response

If the message cannot be processed a Business Message Reject (j) will be sent to the client. This can happen due to unknown orders or other reasons. In case of success the client will receive an Execution Report (8) with the specified (client) order ID, order status request ID (if specified) and ExecType (150) I (OrderStatus).

Execution Report (8)

Execution Report messages are sent to the client when the status of created orders changes, e.g. for newly created, rejected, cancelled or filled orders. Moreover, an Execution Report will be sent when a Status Request from the client has been received.

Market Data Messages

Market Data Request (V)

Market Data Request can be sent by clients who wish to subscribe to orderbook state and trades. A repeating symbol group is used to specify one or more markets to subscribe to when setting SubscriptionRequestType (263) 1. There can only be one subscription per client at a time. A new subscription will replace the previous one. If markets shall be added or removed from the current subscription, clients can simply send a new Market Data Request specifying the updated complete list of wanted markets (symbols). It is recommended to unsubscribe market data with SubscriptionRequestType (263) 2 when it is no longer needed. This will stop market data subscription for all markets.

Response

If the message cannot be processed a Market Data Request Reject (Y) will be sent to the client. In case of success the client will receive a Market Data Snapshot / Full Refresh (W) message per subscribed market (symbol) providing an initial orderbook snapshot. Afterwards, Market Data Incremental Refresh (X) messages will be sent to communicate orderbook changes and trades.

Market Data Request Reject (Y)

Market Data Request Reject will be sent to the client if a Market Data Request (V) cannot be processed correctly. A description of the specific error can be found in the Text (58) field.

Market Data Snapshot / Full Refresh (W)

Market Data Snapshot / Full Refresh will be sent to the client once per requested market (symbol) after successful subscription. Each message contains a complete orderbook for a specific market. After the initial snapshot, clients will usually receive Market Data Incremental Refresh (X) messages. However, additional snapshot messages may occur occasionally due to exchange internal processes. Clients must be able to handle this and treat new snapshots as a new starting point for incorporating following Market Data Incremental Refresh (X) messages. The orderbook is aggregated. Therefore, each price level may consist of multiple orders.

Market Data Incremental Refresh (X)

Market Data Incremental Refresh will be sent to subscribed clients for communicating orderbook changes or trades after the initial Market Data Snapshot / Full Refresh (W). A Market Data Incremental Refresh message will contain either aggregated orderbook levels or trades, not both. While multiple entries are possible and to be expected, a single message will reference a single market (symbol) only. Note that MDUpdateAction (279) is always 0 (new) for trades and always 1 (change) for orderbook levels. New orderbook levels can be identified by new MDEntryPx (270) values while removed orderbook levels will state MDEntrySize (271) 0.

Markets

Orders