Bonds and Derrivatives MITS Market Data API
Bonds and Derrivatives MITS Market Data API
Exchange System
Interface Specification
Information Subscribers
Please note that documents could take the form of discussions, interviews, presentations, workshops,
white papers etc.
2. Version Control
The information contained in this document is the property of Securities and Trading Technology (Pty)
Ltd (STT from now on). This information is issued in confidence and must not be reproduced in whole
or in part or given or communicated to any third party without the prior written consent of STT.
Any advice given or statements or recommendations made shall not in any circumstances constitute or
be deemed to constitute a warranty by STT as to the accuracy of such advice, statements or
recommendations. STT shall not be liable for any loss, expense, damage or claim arising from advice
given or not given or statements made or omitted in connection with this document.
When product names known to be trademarks of STT and other companies appear in this document,
they are used purely for informational purposes and to the benefit of their respective trademark holders.
This document is intended for review by the relevant internal departments within the exchange as well
as external/market review by:
5. System Description
5.1 Introduction
The Exchange Trading System is an exchange layer of markets that allow for the trading and
dissemination of multiple product types using one system, through a common Application Program
Interface (API). These products can be diverse, each containing their own set of values. Products are
further separated into different markets.
Products do contain links between them to facilitate the trading of spreads and switches (also called
splits).
The programmer who wishes to use this API specification must first ensure that they can establish a
streamed TCP/IP permanent socket connection to the appropriate port.
From this point onwards, all communication is done using message packets. Every message packet,
either in or out, must carry a Transport Header, which consists of 4 bytes. A description of the transport
header can be found in Table 1: Transport Header
The transport header is followed by a Message Header. The message header contains the indication
of who the user is, the details of the transaction performed, etc. A description of the Message Header
can be found in Table 2: Message Header
4 M I T S
The system will validate the string only in this context using the byte 0 as the length.
• B: The field is made up of 1 or more bytes of type U
• C: Single character; ASCII equivalent
Time Format
• All times given in this document are given as 4 byte values in the following format:
Byte 0 = Hours
Byte 1 = Minutes
Byte 2 = Seconds
Byte 3 = 0
Date Format
• All Dates given in this document are 12 byte values which are provided as 3 integer values
representing:
Year
Month
Day
Please Note: Mandatory fields in this specification are market with an asterisk (*). All non-mandatory
fields which are not going to be filled in should be sent with 0 for numeric values, and empty strings or
padded with null (0) for alpha fields.
Data in the message portion of the packet will then follow the Message Header.
These defined groups contain message types that can be defined into two further groups:
• Private Messages
o These are messages that contain confidential information that is specific for an
individual dealer or an individual member firm. An example of this is the 123 Message
with deal update/insert indicator.
• Public messages
o These are non-confidential messages that contain information that is market specific
and available to all users who subscribe to public data. For example: a last price change
on a contract would be received by the whole market. Information Subscribers will be
key users of these messages.
Details of the GZIP decompression algorithm can be found at the following URL:
http://www.gzip.org/
https://www.gnu.org/software/gzip/
}
}
All Data Sections transmitted to users will have a maximum size of 5000 bytes. When the compressed
data buffer is greater than 5000 bytes the system will split this data buffer into a series of Data Sections.
These Data Sections will all have a length of 5000 bytes, except the last Data Section which will contain
the remainder of the data.
Each data section will then be sent with its own transport header, message header and message sub-
header. The message sub-header will indicate if this is the final message of a series. The data will
inevitably be in compressed format. Upon receipt of the final message, all Data Sections can be
appended and decompressed as a whole.
Only messages 36 (data retrieval), 99 (contract update) are compressed, all other messages are not
compressed.
In order to subscribe to a contract, the user would send a type 99 message. This message would contain
all the contracts for which the user would like to receive updates. In order to unsubscribe from a contract,
the user would send in a type 42 message. This message would contain a list of the contracts from
which the user would like to unsubscribe.
The result of sending a type 99 message is a type 59 message containing all the details of the
instruments the user subscribed to. When an order is added to the Instrument or any depth of the
instrument changes the user would receive a type 59 message on the instrument with the updated
details automatically. Thus the user only has to subscribe to the instrument once and thereafter they
would receive all updates to the instrument. This has to be done for each session.
Subscription to the Indices feed is based on a Boolean (true\false) field. This is done by sending a type
98 message with the flag set to true. In return this will send all Indices. To disable this feed after
subscription, simply send a further 98 message with the flag set to false.
In all these message types the Sequence Number in the message header is incremented by each send
to the specific socket.
The system allows for 2 levels of subscription for the screen update message (59).
• Level 1 – Best Bid or Offer (Allows the user to only see the top of the depth)
• Level 2 – Full Depth (Allows the user to see the full depth on a contract)
These levels are set up by the Exchange on the subscription profile of the user. The message received
by the user is the same in both cases, only the number of depth items changes.
A recommended solution to this would be to remove messages from the socket as soon as they arrive,
and create an application resident queue of messages. This application resident queue can then be
used to process messages. This will then send acknowledgement of receipt of the message to the
exchange system as soon as messages arrive, and avoid the potential of being disconnected.
The Display Update Messages (59’s) published on these instruments will be flagged as anonymous,
and the member codes previously displayed will not be published.
The member codes on these display updates will be replaced with uniquely identifiable numbers. Each
user will be assigned a number upon login, and this same number will be present in the display update
messages. This will allow users to identify their own orders in the market depth.
Price contributions will be identified by using the Instrument Type indicator which forms part of the
Instrument Data Download. Instruments with type number of 32 are Price Contribution Instruments. The
price contribution may, for example, have a short name of e.g. Q153 which may represent the R153
Government Bond. The mapping for this can be determined by the Display Name field on the instrument
data. For example an instrument with a short name of Q153 will have a Display Name of R153 to indicate
its relationship to the actual R153 tradable instrument.
The market depth data message (Display Update Message Type 59) currently contains a Global
Sequence Number. This is a sequential message for display updates per market shard.
The depth re-request message allows the user to re-request market depth data per market shard.
The market shard number in the re-request message will identify the market sub set on which particular
contracts can be found. This will match up with the market shard number on the Instrument Data
download, and therefore Instruments can be mapped accordingly to a particular market shard.
The API user must send a Heartbeat message to the system, if there has not been a message sent
from the user in the last 45 seconds, or a pre-configured amount of time set by the Exchange.
Data can be requested from the system by sending a request message (See Error! Reference source n
ot found.). A series of compressed message packets will be sent to the user in response to the request.
Each of these packets will be preceded with a Transport Header, Message Header and Request Data
Header.
In the Request Data Header the Data Type defines the structure of the data. The size of the
decompressed data will be a multiple of the size of the defined structure. This decompressed data can
therefore be type cast into a series of records.
Example:
1. Request data for MTM File (Type 16)
2. Received a complete data buffer of 576 bytes (After decompression).
3. Number of records contained = Length of Decompressed Buffer (576) / Size of MTM Structure
(64) = 9
4. 9 Records returned by Download.
Table 3: Possible Data Types contains a reference to data sets available for historical data retrieval.
These messages contain an integer field indicating the error number; this is followed by a byte field
indicating if the message is an error message or an information message. These fields are followed by
the messages in text format. The exact text of the message may vary as the message may include
contract information.
Updates or inserts are received intra-session with message type 123, which always contains only one
record.
When an input message 36 is sent; messages containing multiple records can be received.
The data set structure is available for retrieval as a Message 36 in Request Data Header – Message
Type 36 and 123.
• Member
- Members are 5 byte long Pascal type strings
- Example: ABCD
• Dealer
- Dealers are 4 byte long Pascal type strings
- Example: JOE
• Clients
- Clients are 7 byte long Pascal type strings. 3 Alpha, followed by 3 numeric characters
- Example: CLI001
• Sub-Accounts
- Sub-accounts are 6 byte long Pascal type strings, that do not end in ‘C’
- Example: SUB99
• Clearing Members
- Clearing members are 6 long Pascal type strings
- Clearing members always end with a character C in byte 5
- Example: ABCDC
Length: 48 bytes
Character Contract
F Future
E Equity
O Commodity
Y Option
Z Spread
X Split / Switch
G Bond
R Repo
Q Reverse Repo
W Nominal Switch
V Currency Per Point
Switch
S Swap
T Notional Swap
N Fixed Rate Derivative
7.1.1 Encryption
An asynchronous encryption method is used for connecting to the exchange. The public/private key pair
is generated on exchange. When the client connects to the server, an acknowledgement message is
sent to the client with the public key (Message Type 16). The public key will be used to encrypt the login
password only.
The encrypted password field allows for 312 bytes, and as the length of the password can vary, the
length of the encrypted password needs to be included in the first 4 bytes of the encrypted password
field. This leaves you with 308 bytes for the encrypted password itself.
• The public key is used to encrypt the data, which is then sent in the Encrypted Password
field.
• Similarly, if the user wishes to change their password, they would supply the new password
encrypted with the public key.
Re-Request of 59 messages. The Display Update (Message Type 59) contains the sequence
numbers required to facilitate this request. The From Sequence and To Sequence are both
inclusive in the result set. The exchange will reply in result sets of 100 sequences at a time, for
the supplied sequence number range.
When the user is disconnected, and re-connects, they are advised to re-request missing
messages starting with the last global sequence number received. This is to ensure that any
updates, to the last global sequence number received, are taken into account.
The user is also advised that live messages should be received in conjunction with the response
to re-requests. This is to avoid missing live messages whilst re-requests are being received.
It is also advised that if a sequence number is received out of order, the user should build
functionality that manages any triggers for re-request. This functionality could potentially make
use of a counter that only after 3 checks, triggers a re-request for a missing sequence number.
This will cater for the possibility that a sequence number is received out of order due to message
routing or other factors, and allow the user to ensure all data is received in good order.
The market shard number will identify the market sub set on which particular contracts can be
found. This will match up with the market shard number on the Instrument Data download, and
therefore Instruments can be mapped accordingly to a particular market shard.
To inform the system that the user no longer wants to receive Display Updates on a particular contract,
a user must send a Message Type 42 with the list of contracts that they wish to unsubscribe from. This
message caters for up to 40 contracts per message. To unsubscribe to all options on the market, the
message can be sent with a quantity of 1 and an empty list of contracts.
MITS – Exchange System Page 20 of 55
Interface Specification
Name Length Type Description Case Example Comment
Quantity* 2 I N n/a 3 Number of contracts
to unsubscribe from.
Contracts to 40*48 Contract AN U List of List of contracts
unsubscribe* contracts names to
unsubscribe from
Total Length 1920
Bytes
Sending this message type will result in the API user receiving Display Updates (Message Type 59)
on the contracts listed in the Option Contract Subscription Message.
• If the message contains the future contract – the user will be subscribed to all option strikes’
depths on the future expiry.
• If the message is empty all the options on the market on which an order has been placed, will
be subscribed to.
• If a single option is specified only this contract will be subscribed to.
When subscribing to a contract using the 67 message, further updates will be sent when activity is
recorded on that contract. To receive an initial state of the contract in terms of market statistics the
display file will contain the latest information for this contract. It is advised that the information in the
display data download is used as an initial state of the contract, and that the 67 message is used to
subscribe to further updates.
Sending this message type will result in the API user receiving Display Updates (Message Type 59)
on the contracts listed in the Future Contract Subscription Message. Up to 40 contracts are catered
for in this message.
The Option Statistics Request allows a user to receive a Display Update (Message Type 59) which will
include information for all option contracts traded since the beginning of the trading session. Therefore
statistics included in the Display Update Message such as volume, last price, day’s high and day’s low
will be filled with the details for option contracts traded.
When subscribing to an update on a contract, the resulting 59 message will contain a global sequence
number of the last global sequence number sent, and will not increment. Therefore 59 messages
received as a reply to a subscription message (message type 99) should not be used as part of any
global sequence number processing, as these updates do not fall in line with the normal sequence
number series. Any subsequent 59 messages after subscription has been processed will continue with
the normal global sequence number series.
The Request Data Retrieval Message allows users to request data from the system. The Data Type
field indicates what type of data should be returned. To download a specific record within a data set,
the Specific Record field is filled with the sequence number of the record required. The Download Date
field allows the user to request data for a specified date. This date can only be set to today or the
previous business day. If no data is available for the request, an empty data set will be returned.
The following is the structure for the Member Unique Numbers send with the login reply message.
Total Length: 96 + Number of Unique Members x 10 Bytes (Maximum size: 696 Bytes)
Auction Description
Value
0 Contract is open
1 Contract is in auction
2 Contract is closed
3 Contract is suspended
4 Contract in open order period
5 Contract is after open period
6 Contract instrument has been halted
Contract Description
Status
Value
0 Bid or Offer activity with no change to best bid or offer
1 Bid activity which has changed the best bid on this contract
2 Offer activity which has changed the best offer on this contract
3 Bid or Offer activity which has changed both the best bid and offer on this contract
4 Trade activity has been recorded on this contract with no change to the best bid or
offer, indicates that the close price has updated
5 Trade activity which has changed the best bid on this contract
6 Trade activity which has changed the best offer on this contract
7 Trade activity which has changed the best bid and offer on this contract
Type Description
0 Normal
1 Take or kill
2 Fill or kill
4 Iceberg
8 Stop order
**Please note that if the contract is Anonymous that the length byte will be 0
followed by 4 bytes indicating the Unique member number.
Included in the message are a number of the above Depth Data messages where the number is
“Number of depth” in the first part of the message.
• A display update message will be received with a unique global sequence number. If a 59
message is received as a result of a trade, then a further 59 message will be received as an
update to a particular global sequence number. This update message will contain the latest
open interest and volume figures for that contract. These are published as updates to a 59
message, and therefore may contain a global sequence number which you have already
received. Any 59 messages received with a global sequence number which you have already
processed should be treated as updates and processed as such. Multiple updates can be
received for a particular global sequence number. For example if a trade is captured for 100
contracts, and this is made up of 5 legs of 20 contracts each, 5 updates will be received on the
global sequence number for that trade. These updates are due to volume and open interest
updates.
• The depth received on the display update message will display all orders on the order book.
The top of the depth will indicate the order which is currently the best order on the market. There
may however be orders at the same price going down the depth. The discretion is up to the
user whether to cumulate the quantity on the top of the depth to indicate the total quantity
available at that price.
Please see section 10 for the details of the error messages. Please note that the Information and Error
return message is a variable length message, which defines a variable length Message field with a
maximum length of 251.
History Suffix
The following message will be sent on the event of a failure of the exchange trading system, or in the
event of the recovery of the exchange trading system.
The failover recovery response message will be published automatically to all connected users to
update their transactional data (Active Orders, Deals, Completed Orders, Positions and Unmatched) in
the event of the recovery of a Market Shard, post a failure. This message can be used to update any
transactional data which may have been affected by the recovery of a market shard.
The message definition is the same as the Download Data Response (Message 36), and should be
processed the same.
PLEASE NOTE: In the case of large data transmissions the flag “Another Set to Come” could be set to
true. In this case the normal download data request message 37 should be sent by the user to retrieve
the next set of data e.g.
The following structures are received when downloading data. An example of this process can be found
in Input Messages.
All these Messages are compressed when they are received in reply to a 36 message 123
messages received on the real time channel will not be compressed.
The Request Data Header will be attached to all 36 and 123 message received by the user. This
indicates the Data Type received. For 123 messages the Specific Record and Action fields are filled to
indicate the specific record received and the action to be taken.
The Instrument Group Sequence indicates to which group this instrument belongs to in a Series Spread
Margin grouping. The Group Margin field indicates the Series Spread Margin requirement for this
instrument in the Series Spread Grouping. The other instruments in this group can be determined by
going to the specified record in the Group Definition data to which this instrument points to in the
Instrument Group Sequence field.
The Fee details applicable to this instrument for Futures, Options and Deliveries are defined by going
to the appropriate record in the Fee Data record pointed to by the Future Fee Sequence, Option Fee
Sequence and Delivery Fee Sequence fields of this structure.
The Spread Margin Requirement for this expiry is defined in the Spread Margin field. The Initial Margin
Requirement is also defined in the Initial Margin field.
19 Could not create Contract name After entering a bid on The dealer who
strike specified for the a new strike (message sent the bid
option contract was type 56) message.
not valid.
20 Not a buy sell The buy sell indicator The dealer who
order specified was not sent the bid
valid, must be either B message.
or S
21 Invalid Order Order type parameter After sending a bid The dealer who
type in the bid message message (type 56) sent the bid
was incorrect. message.
22 Bid outside The bid placed was After sending a bid The dealer who
market limits outside the market message (type 56) sent the bid
limits for this contract message.
25 Order type not Order type parameter After sending a bid The dealer who
allowed in the bid message is message (type 56) sent the bid
not allowed on this message.
particular contract
29, 30 Invalid front end The version specified After sending a login The dealer who
version in the login message message sent the
is not supported by message.
the exchange
47 FOK/TOK order This message When a bid message is The dealer who
cannot be indicates that a Fill or received with the FOK, sent the bid
satisfied Kill, or Take or Kill or TOK flag set. The message.
order could not be bid is validated, and if
satisfied, since the unsuccessful, the error
quantity available on will be returned.
48 All or nothing not An all or nothing order After sending a bid The dealer who
allowed was entered for a message (message sent the bid
contract which does type 56) message.
not allow all or nothing
order
49 Trading on this Each contract has an When a bid message The dealer who
contract is open time and a close or suspend/cancel sent the bid or
closed time associated with message is received suspend/cancel
it. If the time at which and the current time is message.
a bid or suspend outside contract
message is received open/close, then this
is before the open message will be
time, or after the close returned immediately.
time, this message
will be sent.
50 Order quantity The contract has been After sending a bid The dealer who
below minimum setup with a lotsize, (message type 56) sent the bid
and the bid quantity is message.
below this
51 Bid on contract The bid was entered After sending a bid The dealer who
was not a for a contract which (message type 56) sent the bid
multiple of the was setup with a message.
lotsize lotsize, and the
quantity was not a
multiple of this.
52 Invalid spread Price of the spread or After sending a bid The dealer who
split order would message on a spread sent the bid
create orders on the or split contract message.
underlying which is
invalid
53 Odd Lots not This message is sent This message is sent The dealer who
allowed when when a bid message when a bid message is sent the bid
underlying in is received for an odd received for an odd lot message.
auction lot order, and that order and the contract
contract is in auction. is in auction. This error
message is then
returned immediately.
54 Not allowed to This dealer is not The dealer who
change authorised to change sent the
subscription subscription policy message.
60 Limits specified When setting limits for The dealer who
must be positive a dealer, the values sent the
specified can only be message.
positive
62 Principal Agency Principal Agency The dealer who
indicator is indicator entered was sent the
invalid invalid. Must be either message.
P or A
63 Cannot suspend Cannot suspend an The dealer who
an order 1 order after 1 minute sent the
minute before before the end of the message.
Open Order Period
121 Cannot delete a The certificate which After sending a delete The user on the
certificate which you are trying to silo certificate message socket
is ready for delete has already (136) connection
delivery or been delivered or is
delivered. ready for delivery.
1000 Generic
Exception
Term Definition
A Alpha only
ACK Acknowledgement
AN Alphanumeric
B The field is made up of 1 or more bytes of type U
C Single character ASCII equivalent
D Intel/IEEE floating point 8 byte format
FF Hex for 255
FOK Fill or Kill
I Intel Integer format; the length is defined
LZH Compressed file format
MTM Market to Market
N Numeric only - Default for types I.U.D
NACK Negative Acknowledgement
NOB Number of bids
P Pascal type string with leading length byte, maximum length is
the defined length – 1. All strings in Exchange System are
represented in this manner
TCP / IP Transmission Control Protocol / Internet Protocol
TOK Take or Kill
U Intel unsigned integer; the length is defined
URL Uniform Resource Locator
XOR Mathematical term for exclusive disjunction
Information Subscriber Those entities which will be subscribing to the public data for
their own use, and onward redistribution to their external clients.