EMAPI - Rev F

EMAPI Protocol
Rev F April 17, 2009
This document describes the semantics of the EMAPI protocol and the syntax
of the session related EMAPI messages.
Restricted External
Copyright 2008-2009 Cinnober Financial Technology AB. All rights

reserved.
Cinnober Financial Technology AB reserves the right to make changes to the
information contained herein without prior notice.
No part of this document may be reproduced, copied, published, transmitted,
or sold in any form or by any means without the expressed written permission
of Cinnober Financial Technology AB.
Cinnober and TRADExpress are trademarks or registered trademarks of
Cinnober Financial Technology AB in Sweden and other countries. Other
product or company names mentioned herein may be the trademarks of their
respective owners.
EMAPI Protocol
2 (55)
Cinnober Financial Technology AB
Restricted External
Table of Contents
1
Messages ......................................................................................10
1.1
Message Types....................................................................... 10
1.2
Message Header ..................................................................... 10
Session ........................................................................................12
2.1
Server Session Types ............................................................... 12
2.2
Session Establishment.............................................................. 12
2.2.1
Pre Logon........................................................................... 12
2.2.2
Logon ............................................................................... 13
2.3
Session Surveillance ................................................................ 14
2.4
Session Processing .................................................................. 14

2.4.1
Change Password.................................................................. 14
2.4.2
Several outstanding Requests ................................................... 15
2.4.3
On-behalf........................................................................... 15
2.5
Session Recovery .................................................................... 15
2.6
Session Termination ................................................................ 16
2.7
Session Message Sequences ....................................................... 16
2.5.1
2.7.1
Introduction ......................................................................... 17
3.1.1
Flows ................................................................................ 17
3.1.2
Subscription Group................................................................ 17
3.1.3
Sequence Number................................................................. 17
3.1.4
Filtering ............................................................................ 17
3.1.5
Information in Events ............................................................ 17
3.2
Subscription Establishment........................................................ 18
3.3
Subscription Surveillance .......................................................... 19
3.4
Subscription Processing ............................................................ 19
3.2.1
3.4.1
3.5
EMAPI Protocol
Session Establishment, Surveillance and Termination ...................... 16
Subscriptions.................................................................................17
3.1
Outstanding Requests ............................................................ 15
Current Value Framing ........................................................... 19
On-behalf........................................................................... 19
Subscription Recovery.............................................................. 19
3.5.1
Replay Framing .................................................................... 20
3.5.2
Replay Sequences ................................................................. 20
3.5.3
Synchronize Subscription/Replay ............................................... 21
3.6
Subscription Termination .......................................................... 21
3.7
Event Flows .......................................................................... 21
3.8
Subscription Message Sequences ................................................. 21

3.8.1
Current Value Subscription Establishment .................................... 21
3.8.2
Replay .............................................................................. 22
Reference Data ..............................................................................23

4.1
Event Flows .......................................................................... 23
4.2
Dissemination of Reference Data................................................. 23
4.3
Synchronizing the Reference Data Flow with Other Flows ................... 23
4.4
Reference Data object relations ................................................. 24

3 (55)
Restricted External
4.5
Members and Users ................................................................. 24
4.6
Trading Data and Trading Rules .................................................. 27
4.7
Markets and Instruments .......................................................... 32
Trading ........................................................................................37
5.1
Identifiers for Trading Objects ................................................... 37

5.1.1
Orders............................................................................... 37
5.1.2
Quotes .............................................................................. 37
5.2
Cancel on Logout ................................................................... 38
5.3
Event Flows .......................................................................... 38
5.4
Building a Public Shadow Order Book............................................ 40
5.3.1
5.5
Information in Events ............................................................ 40
5.4.1
Relevant EMAPI Messages ........................................................ 40
5.4.2
OrderEvent/QuoteEvent versus MarketByLevelEvent ....................... 41
5.4.3
Building a Shadow Order Book from Order/Quote Events .................. 41
5.4.4
Building a Shadow Order Book from Market-By-Level Events .............. 41
Building a Private Shadow Order Book .......................................... 42

5.5.1
Relevant EMAPI Messages ........................................................ 42
5.5.2
Order/Quote Key.................................................................. 42
5.6
Order History ........................................................................ 42
5.7
Message Sequences ................................................................. 44

5.7.1
OrderInsertReq/Rsp no Match ................................................. 44
5.7.2
Explicit Cancel of Order ......................................................... 44
5.7.3
Insert of FaK/FoK That do Not Match .......................................... 44
5.7.4
OrderInsertReq/Rsp Full Match Against Two Orders Residing in the Book

45
5.7.5
OrderUpdateReq/Rsp Updated Order Matches Fully Against Order in the
Book
46
5.7.6
QuoteInsertReq/Rsp no Match ................................................ 46
5.7.7
QuoteInsertReq/Rsp Partial Match Against Order Residing in Order Book

47
5.7.10
TradeReportReq/Rsp WaitForOtherSide=false.............................. 49
5.7.11
TradeReportReq/Rsp WaitForOtherSide=true .............................. 50
5.7.12
TradeUpdateReq/Rsp............................................................. 50
5.7.13
RequestForQuoteReq/Rsp (type=PRIVATE).................................... 51
Event Flows .......................................................................... 52

Event Flows .......................................................................... 53
Event Flows .......................................................................... 54
Historical Queries ...........................................................................55

9.1
EMAPI Protocol
MarketByLevel ..................................................................... 48
Surveillance and Clearing .................................................................54

8.1
5.7.9
Text Information from Operation Staff .................................................53

7.1
OrderInsertReq/Rsp full match against quote .............................. 47
Order Routing................................................................................52
6.1
5.7.8
Query types .......................................................................... 55

9.1.1
Historical Trades .................................................................. 55
9.1.2
Historical Orders .................................................................. 55
9.1.3
Historical RequestForQuotes .................................................... 55
4 (55)
Restricted External
9.2
EMAPI Protocol
Query Message Sequence .......................................................... 55
5 (55)
Restricted External
About this Document

Introduction
This document describes the semantics of the EMAPI protocol and the syntax
of the session related EMAPI messages. This and remaining syntax is described
in the related documents (EmapiTransactions.html and encoding documents
e.g. TagWire Specification).
The EMAPI protocol is one of the protocols used to access the TRADExpress
system.
The purpose of this document together with its related documents is to serve
as a specification of the EMAPI protocol when implementing an EMAPI client.
Messages/fields/constants are presented in the computer style font. The
numeric value for a constant is specified in (both) of the related documents
EmapiTransactions.html and EmapiTransactions.xml.
Intended Audience
The information in this document is aimed towards EMAPI client developers.
Related Documents
Name
Description
TagWire Specification
Contains the syntax of the tagged value text message

encoding used by the EMAPI Protocol.
EMAPITransactions.html
Contains the syntax of all EMAPI Protocol Messages.
EmapiTransactions.xml
An XML definition of all EMAPI Protocol Messages.
EmapiTransactions.xsd
An XML Schema that EmapiTransactions.xml conforms

to.
RFC 1950 ZLIB

Compressed Data Format
Specification
The compressed data format supported by EMAPI.
Revision State History

This document has been revised according to the table below:
Revision State
Author
Comment
Rev F Apr 17, 2009
Johan
Asplund
Updated sequence for updated order

matches fully, in 5.7.5.
Added chapter 9, describing historical
queries.
In section 2.2.1 and 2.2.3, added a note
that the client should send a message
shortly after connecting.
EMAPI Protocol
6 (55)
Restricted External
Revision State
Author
Comment
Rev E Mar 26, 2009
Cinnober
In the Introduction section removed the

sentence regarding version number and in
sections 2.2.1 and 2.2.2 instead refer to
the related documents
EmapiTransactions.xml/html.
Moved section 2.5.2 to become section 5.2
as this functionality is only applicable for
trading items.
In section 3.3 corrected the statement that
the subscription is terminated when a
SystemStatusEvent indicates
UNAVAILABLE and instead stated that The
subscriptions are however not terminated
on the concerned flow and subscription
group and the Server will continue to
deliver events where it stopped when the
Server regain its capability deliver events
for the concerned flow and subscription
group.
In section 5.2 changed from being the last
owning user session to the last acting user
(which acted last on the trading item) that
triggers cancellation. Also stated that
quotes are cancelled.
In section 7.1, specified that
SYSTEM_EVENTS_FLOW and
PRIVATE_EVENTS_FLOW support current
value (i.e. not replay).
EMAPI Protocol
7 (55)
Restricted External
Revision State
Author
Comment
Rev D Feb 24, 2009
Cinnober
In section 3.1.2, 3.1.3 and 3.1.5 clarified

that it is only on some flows that
TRADExpress sends events on different
subscription groups.
In sections 3.2 and 3.5 specified when
subscribing to/replaying from flows, on
which TRADExpress does not send events
on different subscription groups, the
subscription group field in the
subscription/replay request shall be set to
zero.
In sections that lists event flows (i.e. 3.7,
4.1, 5.3, 6.1, 7.1 and 8.1) specified if the
events on the concerned flows are or are
not published on different subscription
groups.
In section 5.3 marked the events that are
not provided in a current value.
In section 5.3 added ChatMessageEvent
and StateFreezeEvent to the
PUBLIC_ORDERBOOK_EVENT_FLOW and
WaitForSSNEvent to the MBL_L1_FLOW,
MBL_L2_FLOW and
PUBLIC_PRICE_LEVEL_FLOW.
Added section 5.3.1. Moved the
specification of the timeOfEvent field to
this section from section 3.1.5 and added a
specification of the sequenceIndicator
field.
In section 5.4.4 clarified that it is
guaranteed that the number of price levels
will never exceed the number of price
levels applicable for the flow.
Added section 5.7.9 that gives an example
of the message sequences on market by
level flows.
Added section 6 and moved order router
related flows/events to this section from
section 5.
In section 7.1 corrected the name of the
event to MarketMessage.
Rev C Dec 19, 2008
Cinnober
In section 3.1.5 removed the field

broadcastFlow and replaced timestamp
with timeOfEvent.
In section 5.3 removed event
OrderBookTradeHaltEvent and added event
AuctionEvent to
PUBLIC_ORDERBOOK_EVENT_FLOW.
In section 5.4.1 removed all mentioning of
OrderBookTradeHaltEvent and instead
described the event type HALT_EVENT for the
OrderBookStateChangeEvent.
EMAPI Protocol
8 (55)
Restricted External
Revision State
Author
Comment
Rev B Dec 11, 2008
Cinnober
In section 5.1 added the Private Quote Id and

rewritten some text.
In section 5.3:
-
added QuoteEventPrivate for the

PRIVATE_ORDERBOOK_EVENT_FLOW
corrected following names;

MblEvent => MarketByLevelEvent
MBL_FULL =>
PUBLIC_PRIVELEVEL_FLOW
In section 5.4.1 stated that also QuoteEvent

has an event type that shall be used.
In section Order/Quote Priority added the
properties Priority Group and Priority.
Added the section 5.4.4.
In section 5.5.1 added QuoteEventPrivate.
In sections 5.7.6 5.7.8 added
QuoteEventPrivate.
Rev A Nov 3, 2008
Cinnober
Initial version.
Terms and Acronyms

Term/Acronym
Description
Client
A client that connects to TRADExpress Servers using the

EMAPI protocol.
Order Book
Entity where trading takes place.
Server
TRADExpress Server that supports the EMAPI protocol. E.g.

the TAX (Trading Application Multiplexer) Server.
EMAPI Protocol
9 (55)
Restricted External
Messages
All interaction between a Client and a Server is done using messages.
1.1
Message Types
Following types of messages exists:
Request: Messages sent by a Client to a Server requesting TRADExpress

to perform something. Named <something>Req.
Response: Messages sent by a Server to a Client delivering the response to

a previous request. The response is either named <the same something
as the request message>Rsp or ResponseMessage.
All responses contain following information:
code:
Ok: Indicates that the Server has completed the processing of the
request successfully.
Warning: Used when the request is to perform several things and

TRADExpress has successfully performed some things and has
failed to perform the other things. Which things TRADExpress has
successfully performed resp. failed to be performed is signaled in
below subCode:s.
All other values are indicating that the Server has failed to
process the request.
subCode:s: Used when the request is to perform several things and

above code is Warning. The sub codes position corresponds to the
position of the things in the request message.
message: A text description explaining more in detail why the request

failed or resulted in a warning.
N.B. If the code is Ok the string will be Ok.
requestId: Unique identifier for the transaction assigned by the
Server.
Note: ResponseMessage
1.2
contains this and only this information.
Event: Messages sent by a Server to a Client to inform about events that

have taken place in TRADExpress. A Client only receives events that it
has subscribed to. See section 3.1.5 regarding what information all events
contain.
Message Header
Each message starts with a header.
Name
Position
Length
Content
magicSign
Shall be set to XMMA (0x58 0x4D 0x4D

0x41).
headerVersion
Shall be set to 10 (0x31 0x00).
msgSize
Message size in bytes excluding this header.

ASCII encoded. Example: 000100 means
that the length of the message excluding
this header is 100 bytes.
clientTxRef
12
Client assigned request id. Binary network

byte order.
EMAPI Protocol
10 (55)
Restricted External
Name
Position
Length
Content
A response sent back by Server will contain
the same value as set in the request.
In the special case the request is a
subscription request all events resulting
from this subscription (as well as the
subscription response) will contain the
same value as set in the subscription
request.
msgType
contentType
16
17
Message type:
R (0x52) = request sent by the

Client/response sent by the Server.
B (0x42) = event sent by the Server

that is not part of a snapshot or replay.
S (0x53) = event sent by the Server

that is part of a snapshot.
H (0x54) = event sent by the Server as

part of a replay.
Encoding used for the message body

following this message header:
W (0x57) = TagWire
The encodings are described in related
documents.
compressed
18
Compressed message body flag:
Y (0x59) = Compressed message body
(0x20) = Uncompressed message body

The compressed data format is as specified
in RFC1950 (see related Documents).
It is configurable per TRADExpress
installation if the Server compresses
some/all messages.
A Client is free to send in
uncompressed/compressed messages.
19
EMAPI Protocol
Reserved. Shall be set to (0x20)
11 (55)
Restricted External
Session
All EMAPI interaction between an EMAPI Client and an EMAPI Server is done
inside one or more user sessions (except when establishing a user session (see
section 2.2) and password change may be done outside a session (see section
2.4.1)).
The number of sessions and what session types a user is allowed to use is
provided by the organization responsible for the concerned TRADExpress
installation.
If the Servers are partitioned over several session types (see section 2.1)
and/or subscription groups (see section 3.1.2) a user may need to establish
several user sessions with different Servers.
2.1
Server Session Types

Following Server session types exist:
ORDERBOOK_TAX: Serves all requests and non-replay subscriptions for
private data.
1
MARKET_DATA_TAX: Serves primarily non-replay subscriptions for public
REPLAY_TAX: Serves primarily 2 replay subscriptions for public and/or
and/or private data.
private data.
Note:
2.2
A Server can be configured to be of several session types.
Session Establishment
A session is established by performing the steps described in this section.
2.2.1
Pre Logon
Note:
It is configurable per TRADExpress installation if this step is required.
To know which Server that a Client shall use for a user session, a pre logon
step shall be performed by the Client against one of the TCP/IP address
provided by the organization responsible for the concerned TRADExpress
installation.
After performing a TCP/IP connect the Client shall send in an
TaxPreLogonReq. The request contains:
member/user: Identification information provided by the organization
majorVersion/minorVersion/microVersion: The numeric revision of the
responsible for the concerned TRADExpress installation.
EMAPI protocol used in the TRADExpress installation which is specified in

the related documents EmapiTransactions.xml/html.
The response TaxPreLogonRsp 3 contains:
For each available Server:
ipPort/ipAddress: TCP port and IP address of the Server.
Which requests/responses/events a MARKET_DATA_TAX server type supports is

configurable per TRADExpress installation.
2
Which requests/responses/events a REPLAY_TAX server type supports is configurable
per TRADExpress installation.
3
In addition to what is provided in all responses see section 1.1.
EMAPI Protocol
12 (55)
Restricted External
2.2.2
loginTicket: Shall be used in the following TaxLogonReq. The ticket

expires after a time that is configurable per TRADExpress
installation.
sessionTypes: The session type(s) (see section 2.1) that is provided
subscriptionGroups: The subscription group(s) (see section 3.1.2)

that the Server serves subscriptions for.
by the Server.
Note:
One of the reasons for the pre logon step is to ensure a session load
balancing on the available Servers.
Note:
The TaxPreLogonReq should be sent immediately after the TCP/IP

connect, otherwise the session will be disconnected by the TRADExpress
system.
Logon
To know which Server that a Client shall use for a user session the above pre
logon step is used or if this step is not configured for the concerned
TRADExpress installation the Client shall use the TCP/IP address provided by
the organization responsible for the concerned TRADExpress installation.
After performing a TCP/IP connect the Client shall send in a TaxLogonReq.
The request should be sent immediately after the connect.
The request contains:
member/user: Identification information provided by the organization
password: Authentication information provided by the organization
ticket: Provided by the pre logon step see above section. N.B. Only
possDupSessId: See section 2.5.1.
majorVersion/minorVersion/microVersion: The numeric revision of the
applicable if the TRADExpress installation has been configured to require

pre logon.
EMAPI protocol used in the TRADExpress installation which is specified in

the related documents EmapiTransactions.xml/html.
The response TaxLogonRsp contains following information 4 :
logonAccepted: Indicates if the logon was successful.
loginStatus:
LOGIN_ACCEPTED: Set when (and only when) above logonAccepted is
set to true.
WRONG_VERSION: The Client and Server support different EMAPI

versions that are incompatible.
INITIAL_LOGIN: At initial logon, the password must be changed, see
section 2.4.1.
PASSWORD_EXPIRED: The password has expired and must be changed,
see section 2.4.1.
LOGIN_ACCESS_DENIED: The user does not have access to the logon
LOGIN_REJECTED: Invalid Member/UserName/Password.
service for this application.
EMAPI Protocol
13 (55)
Restricted External
USER_ACCOUNT_LOCKED: The user is locked (e.g. due too many

erroneous logon attempts or by the organization responsible for the
concerned TRADExpress installation).
USER_ACCOUNT_DISABLED: The user has been disabled by the
systemName/isTestSystem: The name of TRADExpress installation and
clientHbtInterval: See section 2.3.
maxLostHeartbeats: See section 2.3.
an indication whether the installation is a test system or not.
Note:
2.3
organization responsible for the concerned TRADExpress installation.
The TaxLogonReq should be sent immediately after the TCP/IP

connect, otherwise the session will be disconnected by the TRADExpress
system.
Session Surveillance
The Client is responsible for sending TaxHeartbeatReq after logging in. A
suggested interval (in seconds) is specified in TaxLogonRsp (see section
2.2.2).
The request contains:
userData: Client data that will be returned in the response.
The response TaxHeartbeatRsp contains the following information 5 :
timestamp: Current local time in the Server according to following ISO
userData: Client data specified in the request.
8601 format: YYYY-MM-DDThh:mm:ss.sTZD (e.g. 1997-0716T19:20:30.45+01:00).
Note:
Other EMAPI requests that are sent by the Client do not replace the
need to send TaxHeartbeatReq.
The Server starts a heartbeat timer after a successful logon. The timer value
is set to a value that is equal or greater than what is specified in
TaxLogonRsp; maxLostHeartbeats * clientHbtInterval. If this heartbeat
timer expires the Server will terminate the session and the TCP connection.
The Client shall initiate a failover when it does not receive a response to a
TaxHeartbeatReq within a configurable time (should be configured in the
Client).
The Server to failover is provided in the same way as at the initial logon, i.e.
by using the pre logon step (if this step is configured in the TRADExpress
installation) or by using one of the alternative addresses provided by the
organization responsible for the concerned TRADExpress installation.
2.4
Session Processing
This section contains session related information that is not part of
establishment, surveillance, recovery or termination.
2.4.1
Change Password
To change password (e.g. when the LoginStatus field in TaxLogonRsp (see
section 2.2.2) indicates INITIAL_LOGIN or when the password is soon
expiring) the Client shall send in ChangePasswordReq. This request contains:
EMAPI Protocol
14 (55)
Restricted External
memberId/userId: Identification information provided by the organization

oldPassword/newPassword: The current and the new password that shall
possDup: See section 2.5.1.
replace the current password.
The Server returns ResponseMessage 6 .

Note:
2.4.2
The user does not need to be logged in to change the password.
Several outstanding Requests

An outstanding request is a request that the Client has sent but has not
received any response for yet.
It is configurable if a user can have more than one outstanding request on a
session, and if so how many outstanding requests. That is, if a user can send
in more requests without waiting for the response of the previous requests
sent in.
To make it possible to match the responses received from the Server with the
sent requests the EMAPI header contains a clientTxRef field that is set by
the Client in the header of the request and is returned by the Server in the
header of the response.
Note:
2.4.3
The responses to the several outstanding requests might not be

received by the Client in the same order as the Client sent them in.
On-behalf
A user may be configured to send in some requests on-behalf of another user
of the same or other member. When doing so the user sets a member and/or
user field in the request.
2.5
Session Recovery
The session establishment at failover is done in the same way as initial
establishment, see section 2.2.
2.5.1
Outstanding Requests
A session may fail after the Client has sent in some request(s) but before the
Client has received the response(s) to these requests. In such case the Client
shall resend the concerned outstanding requests with the possDup (=possible
duplicate) field set.
Note:
There are some request that do not support possDup because they
relates to the session setup or similar.
When receiving a request with the possDup field set the Server compares the
request with saved requests. Following is compared:
member/possDupSessId (specified in TaxLogonReq)
request type
all request fields except the possDup field
If a request is found, which is equal to the resent request with the possDup
field set, the Server returns the response either immediately if the request
has already been completely served or when the ongoing request has been
completely served. That is, the Server will answer with the same response
See section 1.1 for content.
EMAPI Protocol
15 (55)
Restricted External
independently of if the Server has received or hasnt received the request

before.
Note:
Note:
The Client shall only set the possDup field on requests for which the
Client has not received any response on an earlier session
establishment. This due to that the possible duplicate checking in the
Server adds latency to the transaction.
The number of requests the Server keeps for a member and
possDupSessId combination to be used for possible duplicate checking
is limited. This number is provided by the organization responsible for

the concerned TRADExpress installation. A Client shall never send in
more outstanding requests (over all its sessions with the same
possDupSessId) than this number.
2.6
Session Termination
To terminate a session TaxLogoutReq shall be sent to the Server.
The response is a ResponseMessage 7 and after that has been received the
TCP connection shall be disconnected.
2.7
Session Message Sequences

This section contains message sequence examples.
2.7.1
Session Establishment, Surveillance and Termination

Client
Server
|-------------------- PreLogonReq
------------------->|
|<------------------- PreLogonRsp
--------------------|
|
|
|-------------------- LogonReq
------------------->|
|<------------------- LogonRsp
--------------------|
|
* Based upon the information received in
|
|
the pre-login.
|
:
:
:
:
|-------------------- TaxHeartbeatReq ------------------->|
|<------------------- TaxHeartbeatRsp --------------------|
:
* Sent at an interval after logon based upon
:
:
information received in the logon
:
:
:
:
:
|-------------------- TaxLogoutReq
------------------->|
|<------------------- ResponseMessage --------------------|
EMAPI Protocol
16 (55)
Restricted External
Subscriptions
To receive events from a Server a Client must set up subscriptions for the
concerned events and possible replay events.
3.1
Introduction
Following base concepts exists for the subscription/replay functionality.
3.1.1
Flows
TRADExpress sends events on several different flows. The flows that exist
are presented in respective sections that describe the functionality related to
the concerned flows.
For each flow it is defined which event types that may occur.
Note:
One event type may be sent on several flows.
A flow can support replay and/or current value. On a flow that supports:
3.1.2
Replay it is possible to replay all earlier events that has happened since
the TRADExpress instance was started see section 3.5.
Current Value it is possible to receive the current state (e.g. orders

currently residing in order books)
Subscription Group
On some flows TRADExpress sends events on different subscription groups.
Note:
3.1.3
The subscription groups that exist are provided in reference data - see
section 4.
Sequence Number
Each event has a sequence number that is unique on the concerned flow and
subscription group (if TRADExpress sends events on different subscription
groups for the concerned flow)
The sequence numbers are positive integers and are monotonically increasing
but are not always increasing by one. I.e. there will be gaps in the sequence
numbers (e.g. a user might not be allowed to receive certain events due to
authorization restrictions) 8 .
Note:
3.1.4
There exists one exception to above: Events that deliver the current
value (see section 3.2.1) have a non valid sequence number.
Filtering
A session can choose to only subscribe to events related to certain order
books in a subscription group.
3.1.5
Information in Events
All events contain following information:
sequenceNumber: See section 3.1.3.
subscriptionGroup: Present in events sent on flows on which

TRADExpress sends events on different subscription groups. See section
3.1.2.
8
This is no problem as TCP provides reliable, ordered delivery of a stream of bytes, i.e.
there is no need to detect sequence number gaps as this is already done by TCP.
EMAPI Protocol
17 (55)
Restricted External
Note:
3.2
Events that deliver the current value (see section 3.2.1) have a non
valid sequenceNumber.
Subscription Establishment
To subscribe to events the Client sends a TaxSnapshotSubscribeReq. The
request contains:
flow: See section 3.1.1.
key: The subscription group to subscribe to. If TRADExpress does not
publish events on any subscription group on the concerned flow this field
shall be set to zero. See also section 3.1.2.
requestType: The Client specifies one of following operations in the
request:
CURRENT_VALUE: The Server will only send events containing the

current value (framed according to section 3.2.1). N.B. Only
applicable for flows that supports current value.
SUBSCRIPTION: The Server will send real time events. Mainly used for
CURRENT_VALUES_AND_SUBSCRIPTION: The Server will send events

containing the current value first (framed according to section 3.2.1)
and then continue to send real time events. N.B. Only applicable for
flows that supports current value.
flows that supports replay but may also be used for flows that support
current value (if the Client isnt interested in the current value).
lastPollSequenceNumber: May only be set if requestType is

CURRENT_VALUE. If the Client only fetches current value at certain times
the Client shall set this field to the value of the pollSequenceNumber
field of the TaxEndSnapshot (see section 3.2.1) message previously
received. If the current value hasnt changed, since last time the Client
fetched the current value, no events will be received inside the current
value framing (see section section 3.2.1).
orderBookFilter: See section 3.1.4.
member: See section 3.4.1.
The response TaxSnapshotSubscribeRsp 9 contains:
handle: Used when unsubscribing see section 3.6
lastPublishedSeqNo: Only applicable for flows that supports replay. The

sequence number of the last event published before accepting this
subscription. Should be used when initiating a replay after the initiation
of the subscription see section 3.5.
To make it possible to match the events and framing messages received from
the Server with a subscription the EMAPI header contains a clientTxRef field
(see section 1.2) that is set by the Client in the header of the subscription
request and is returned by the Server in the header of resulting messages
(response, framing and event messages).
Note: TaxSnapshotSubscribeRsp
is returned to the Client by the Server
before any events is sent.

Note:
If the Client intends to receive all events on a flow that supports replay
it must always initiate a replay after/before initiating the subscription
see section 3.5.
EMAPI Protocol
18 (55)
Restricted External
Note:
3.2.1
If a Client has subscriptions (during the same time) that interleave, the
Client will receive some events that are identical (except possibly the
txClientRef field in the header).
Current Value Framing

A TaxStartSnapshot message precedes any current value events. This
message contains:
subscriptionGroup: See section 3.1.2.
A TaxEndSnapshot message succeeds any current value events. This message

contains:
code: Set to Ok if the Server has successfully delivered all events of the
current value. All other values are indicating that the Server has failed to
deliver all events of the current value.
message: A text description explaining more in detail why the Server has
failed to deliver all events of the current value. N.B. If the code is Ok the
string will be Ok.
3.3
pollSequenceNumber: If the Client only fetches current value at certain

times the Client shall use the value of this field when fetching the current
value next time. See field lastPollSequenceNumber field in the
TaxSnapshotSubscribeReq message (see section 3.2).
Subscription Surveillance
The Server sends information about the status for each flow and subscription
group using the SystemStatusEvent message. Following statuses exists:
AVAILABLE: Events are delivered as they are happening.
RECOVERY: The Server is failing over so the delivering of events is delayed.
UNAVAILABLE: The Server can not any longer deliver events for the
concerned flow and subscription group. Any subscriptions on the

concerned flow and subscription group are however not terminated and
the Server will continue to deliver events where it stopped when the
Server regain its capability deliver events for the concerned flow and
subscription group. The Client should try to subscribe to the concerned
flow and subscription group on another Server.
3.4
Subscription Processing
This section contains subscription related information that is not part of
establishment, surveillance, recovery or termination.
3.4.1
On-behalf
A user may be configured to be able to subscribe to private events that are
sent to another member. When doing so the user sets a member field in the
TaxSnapshotSubscribeReq.
3.5
Subscription Recovery
To recover events that have been sent by the Server during times when the
Client hasnt had any subscription, the Client requests the Server to replay
events.
Note:
EMAPI Protocol
Which Server that supports replay is configurable per TRADExpress

installation see section 2.1.
19 (55)
Restricted External
To replay events (on a flow that supports replay) the Client sends a
TaxReplayReq. The request contains:
flow: See section 3.1.1.
subscriptionGroup: The subscription group to replay from. If

TRADExpress does not publish events on any subscription group on the
concerned flow this field shall be set to zero. See also section 3.1.2.
sequenceNumber: The sequence number from (but exclusive this number)

where the replay will start. The Client shall specify a start sequence
number that shall either be:
Zero - if the Client hasnt received any events (e.g. at Client startup).
The sequence number of the last received event when the Client has
received events earlier (e.g. if the Client is recovering after a
failover).
The value of nextSequence field in TaxReplayEndEvent if the replay

events are delivered in several replays. See section 3.5.2.
endSequenceNumber: The sequence number to which the replay will be

done. E.g. the value of the lastPublishedSeqNo field in
TaxSnapshotSubscribeReq.
orderBookFilter: See section 3.1.4.
member: See section 3.4.1.
The response is a TaxReplayRsp that contains the same fields as

ResponseMessage 10 .
Note: The TaxReplayRsp
is returned to the Client by the Server before any
events are sent.

Note:
3.5.1
If a Client performs several replays (during the same time) that

interleave, the Client will receive some events that are identical
(except possibly the txClientRef field in the header).
Replay Framing
A TaxReplayStartEvent message precedes any events that are replayed. This
message contains:
A TaxReplayEndEvent message succeeds any replayed events. This message

contains:
3.5.2
code: Set to Ok if the Server has successfully replayed all events. All other
message: A text description explaining more in detail why the Server has
failed to replay all events. N.B. If the code is Ok the string will be Ok.
nextSequence: See section 3.5.2.
values are indicating that the Server has failed to replay all events.
Replay Sequences
It is configurable per TRADExpress installation how many events that can be
replayed as a result of one Client request.
If the number of events to be delivered is greater than this configuration the
Server will only deliver this configured number of events and set the
nextSequence field in the TaxReplayStartEvent message.
10
EMAPI Protocol

20 (55)
Restricted External
The Client shall then initiate a new replay setting the sequenceNumber field
in the TaxReplayReq message to the value of the field nextSequence in the
TaxReplayStartEvent message.
Note:
3.5.3
If the nextSequence field isnt set the Server has replayed all the
events that it knew of at the time when the replay was requested.
Synchronize Subscription/Replay
To avoid handling too much live and replayed data at the same time the
Client could:
1. Replay events until the nextSequence field isnt set in the
TaxReplayEndEvent message.
2. Setup the subscription.
3. If the lastPublishedSeqNo field in subscription response is greater than
the last sequence number received in the earlier replay, another replay is
initiated to get the missing events.
Restrictions
It is recommended to only replay from zero at client start up and during
extreme Client situations (e.g. Client is restarted clean). That is, if a Client
may be required to perform replay(s) it must:
3.6
Remember last received sequence number per subscription.
Setup subscriptions for flows that it may be required to perform replay(s)

as early as possible.
Subscription Termination
To terminate a subscription TaxRemoveSubscriptionReq shall be sent to the
Server. This message contains:
handle: The subscription handle received in TaxSnapshotSubscribeRsp.
A ResponseMessage 11 is returned by the Server.
3.7
Event Flows
Events on these flows are not published on any subscription groups (see also
section 3.1.2).
Flow
Current
Value/ Replay
Description and messages sent
SYSTEM_STATUS_FLOW
Current Value
Flow/subscription status events.
3.8
SystemStatusEvent
Subscription Message Sequences

3.8.1
Current Value Subscription Establishment

Client
|---------------|<--------------|
|<--------------|<---------------
11
EMAPI Protocol
Server
TaxSnapshotSubscribeReq --------------->|
TaxSnapshotSubscribeRsp ----------------|
|
TaxStartSnapshot
----------------|
<CurrentValue>Event
----------------|

21 (55)
Restricted External
|<--------------|<--------------:
:
|<--------------|<--------------|<--------------:
3.8.2
<CurrentValue>Event
<CurrentValue>Event
TaxEndSnapshot
<RealTime>Event
<RealTime>Event
----------------|
----------------|
:
:
----------------|
----------------|
----------------|
:
Replay
Client
Server
|---------------- TaxReplayReq
--------------->|
|<--------------- TaxReplayRsp
----------------|
|
|
|<--------------- TaxReplayStartEvent
----------------|
|<--------------- <Replayed>Event
----------------|
|<--------------- <Replayed>Event
----------------|
|<--------------- <Replayed>Event
----------------|
:
:
:
:
|<--------------- TaxReplayEndEvent
----------------|
|
|
|---------------- TaxReplayReq
--------------->|
|
* New replay based on information received in
|
|
previous TaxReplayEndEvent.
|
|
|
----------------|
|
|
|<--------------- TaxReplayStartEvent
----------------|
|<--------------- <Replayed>Event
----------------|
|<--------------- <Replayed>Event
----------------|
|<--------------- <Replayed>Event
----------------|
:
:
:
:
----------------|
EMAPI Protocol
22 (55)
Restricted External
Reference Data
The reference data is a set to static and semi-static data that contains the
necessary information for the trading system to operate.
The Reference Data Model is the object model used by servers in the trading
system. The reference data is also distributed to trading clients and it is
therefore necessary for a client to be aware of the reference data model.
This chapter describes the Reference Data Model. The model is divided into
three parts:
Members and Users. This section describes the relation between Members
and Users in the system.
Trading data and Trading rules. This part describes orderbooks, ticksize
tables and trading schedules.
Markets and Instruments. This part describes how the orderbooks relates
to instruments and markets. The division of orderbooks into Markets, Lists
and Segments are specific to the actual installation of the trading system.
Reference Data is distributed as broadcast events. For a client to be able to

receive reference data, it must setup a subscription on the reference data
event flow. This is described in the chapter Event Flows below.
4.1
Event Flows
section 3.1.2).
4.2
Flow
Current
Value/ Replay
Description
PUBLIC_GLOBAL_REFERENCE_DATA_FLOW
Current Value
Reference data
events.
Dissemination of Reference Data

The PUBLIC_GLOBAL_REFERENCE_DATA_FLOW is the flow on which all reference
data is disseminated. Thus all data is pushed out as unsolicited events.
User and Member data is however treated slightly different as compared to
other reference data.
The difference with User and Member data is that for a normal member, i.e.
non-service desk, it is not disseminated as a part of the normal
PUBLIC_GLOBAL_REFERENCE_DATA_FLOW reference data flow. Instead explicit
queries need to be used, QueryUsersReq/Rsp and QueryOwnMemberReq/Rsp
For service desk users User/Member data is however disseminated as a part of
the normal PUBLIC_GLOBAL_REFERENCE_DATA_FLOW.
4.3
Synchronizing the Reference Data Flow with Other Flows

As any other flow the PUBLIC_GLOBAL_REFERENCE_DATA_FLOW is
unsynchronized with other flows.
This constitutes a potential problem if for example an order book is hotinserted during the day. In such a case a client might receive an OrderEvent
referring to the newly created order book prior to receiving the corresponding
update of the reference data on the PUBLIC_GLOBAL_REFERENCE_DATA_FLOW.
In order to solve this problem a WaitForSSNEvent will be published on other
flows when required. This event contains information on which state sequence
EMAPI Protocol
23 (55)
Restricted External
number a client must wait for on the PUBLIC_GLOBAL_REFERENCE_DATA_FLOW

reference data flow prior to continuing processing messages on this flow.
For details regarding the state sequence number mechanism, see the
WaitForSSNEvent and respectively reference data event message description.
1)
4.4
If a specific client is not dependent on reference data for processing,

then WaitForSSNEvent:s can simply be ignored.
Reference Data object relations

The following chapters describe the different object domains that are used in
the reference data.
The table at the end of each object type section has four columns, Object,
Key Attribute, Unique Id and parentReference.
4.5
Object is the object name
Key Attribute is the attribute name within the object that is (can be)
used as key for this object type.
Unique Id defines if the Key Attribute is unique among all objects. If

the key is unique, it can be used immediately locate the object. If the key
is not unique, the object is unique only relative its parent.
parentReference defines, if the object is a child object, which

attribute that references the parent object.
Members and Users

This section describes the objects that define the member/user structure
used in the system.
Member
ServerGroup
AAA_TRADING
TAX_GRP_4
User
ServerProcess
CARL_TRADER
TAX2
UserPropertiesCategory
ServiceProfile
window_1
ALL_INSTRUMENTS
UserProperty
ServiceProfileEntry
Z4
PROFILE_1
== parentChild (solid line)

== reference (dashed line)
Figure 1 Members/Users relations to ServerGroups and ServiceProfiles.
Members and Users

Represents the member and user. A member can have a number of users
associated with it. Users within the same member can access each others
orders/quotes assuming they have adequate authorization. A user always has
a subset of the members authorization.
A client session is always established for a Member/User combination.
EMAPI Protocol
24 (55)
Restricted External
The Member/User object also contains a (comma separated) list of references

to one or more ServiceProfileGroup(s). A ServiceProfileGroup may be
used to map access to specific information flows for a Member/User.
Both the Member and User object contains an optional string reference to a
ServerGroup object. If defined, the ServerGroup reference may be used to
direct external transactions for all Users belonging to a Member, or just a
specific User, to a predefined group of gateway servers. If a reference to a
ServerGroup is specified for both a Member and a User, the user reference
has precedence.
The key attributes for a Member are:
memberId. This is the system unique member identifier.
memberType, typically one of TRADING_AND_CLEARING, TRADING_ONLY,

CLEARING_ONLY, INFORMATION_VENDOR, MEMBER_UNIT, and S_DMA. A
member type is associated with a set of rights which determines what

system services are available for a member of the specific type.
associatedMemberId. If the memberType is one of MEMBER_UNIT or S_DMA

(Sponsored Direct Market Access), the associatedMemberId contains the
id of the member to which this member is associated. Only

TRADING_AND_CLERARING and TRADING_ONLY members may have
MEMBER_UNITs and S_DMAs associated.
A MEMBER_UNIT is typically an organizational unit within a large organization,
for example, if SEB is a TRADING_AND_CLEARING member then Enskilda
Securities may be a MEMBER_UNIT associated to SEB.
An S_DMA is typically a large customer to a TRADING_AND_CLEARING or
TRADING_ONLY member that has been granted direct access to the
marketplace by the sponsoring member.
A member that has MEMBER_UNITs or S_DMAs normally has the right to acton-behalf and subscribe-on-behalf for private trade information for the
member(s) it sponsors. The right to act and subscribe on behalf is generally
restricted only to users that has been assigned SUPER_TRADER access.
UserPropertiesCategory:
This object to defines a common category for all UserProperties child objects
The category name is defined by the client and is not interpreted in any way
by the trading system.
UserProperties:
Holds client defined properties, these are not interpreted by the system in
any way. Typically used to store properties like client application window
layout, quoting parameters, other configuration parameters etc.
The properties are stored as name-value pairs and are furthermore
categorized. The categorization is also entirely client defined.
EMAPI Protocol
25 (55)
Restricted External
Member
memberId:
AAA_TRADING*
memberType:
TRADING_AND_CLEARING
assiciatedMemberId:
serverGroupId:
TAX_GRP_2
tradingAccessProfileList:
subscriptionAccessProfileList:
User
userId:
CARL_TRADER*
AAA_TRADING
memberId
serverGroupId:
tradingAccessProfileList:
subscriptionAccessProfileList:
categoryId: window_1
userId
CARL_TRADER
UserProperty
propertyId: Z4
userPropertiesCategoryId: window_1
Figure 2 Object relation for Members and Users.
The key attributes are listed in the table below.

Object
Key Attribute
Unique Id
parentReference
Member
memberId
yes
null
User
userId
yes
memberId
categoryId
no
userId
UserProperty
propertyId
no
userPropertyCategoryId
ServerGroup
The ServerGroup defines a group of servers. Each server is defined in the
child ServerProcess object. Each ServerProcess object may define a
serverType and which set of partitions that are handled by the
serverProcessId server. The set of partitions may be set to all, indicating
that the server can handle requests for all partitions (i.e concurrent server).
The serverProcessId contains the name of a system gateway process,
TAX1 for example.
The ServerGroup/ServerProcess objects are typically used to define a group
of gateway servers and are for load balancing. In this case, a Member/User is
assigned a ServerGroup that is used when connecting to the trading system.
ServerGroup
serverGruopId: TAX_GRP_4*
ServerProcess
serverProcessId: TAX7
serverGroupId:
TAX_GRP4
EMAPI Protocol
26 (55)
Restricted External
Figure 3 ServerGroup and ServerProcess object.

Object
Key Attribute
Unique Id
parentReference
ServerGroup
serverGroupId
yes
null
ServerProcess
name
no
serverGroupId
ServiceProfile
The ServiceProfile object contains an id and a collection of
ServiceProfileEntry child objects. The ServiceProfile holds information
on which flows a Member/User that references this profile is allowed to
subscribe to.
A ServiceProfile is referenced ById from a Member or User.
The ServiceProfieEntry contains information on information which
orderbooks that are available within this ServiceProfileEntry.
The totally allowed information flow(s) and available orderbooks for a
ServiceProfile is the sum of the information flows for all
ServiceProfileEntry childs.
ServiceProfile
serviceProfileId: ALL_INSTRUMENTS*
ServiceProfileEntry
profileEntryId: CFT_STOCK
parentId:
ALL_INSTRUMENTS
Figure 4 ServiceProfile and ServiceProfileEntry.
4.6
Object
Key Attribute
Unique Id
parentReference
ServiceProfile
serviceProfileId
yes
null
ServiceProfileEntry
profileEntryId
no
parentId
Trading Data and Trading Rules

The trading data/rules related objects contain information on orderbooks,
tick size trading schedules etc. An overview of the model can be seen below
EMAPI Protocol
27 (55)
Restricted External
OrderBookRuleGroup
OrderBookRuleGroupParameters
TradingSchedule
XCFT_L1_S1_1
SYSTEM_DEFAULT
NORMAL
OrderBookRoutingStrategy
SubscriptionGroup
orderInsert
47
StateTransition
PRE_OPEN
ProcessingSequence
OrderBook
TickSizeTable
AllowedRequestsGroup
PRE_OPEN
611
EUR
346
ProcessingSequenceOrderBookId
CombinationDefinitionLeg
TickSizeTableR ow
AllowedRequestsGroupRow
611
712
0-100
cancelOrder

Currency
EUR
Figure 5 Overview of the relations between orderboos and other trading related objects.
OrderbookRuleGroups and OrderBooks

The order book rule group is a collection of order books that share a common
set of trading characteristics. I.e. order books using the same market model
should be grouped together in the same order book rule group.
It should be noted that even though most of the market model parameters are
defined on the order book rule group some are on the individual order book.
ProcessingSequence:
When an order book rule group changes state the order books contained
within that order book rule group also changes state. It is however possible to
define the sequence and delays which with the order books contained in the
order book rule group changes state.
I.e. the order books themselves will change state after the order book rule
group has changed state.
If no processing sequence is defined then this implies that all order books
changes state immediately when the order book rule group changes state.
OrderBookRoutingStrategy: (system internal)
If defined, provides the possibility to configure how the Matching engine
handles requests. I.e. if an orderInsert request is received then a strategy
named orderInsert is looked up an executed.
It is possible to override this default mapping by modifying the order book
routing strategies reference data object. The default mappings is overridden
per order book rule group.
The default mapping is used for all order book rule groups that do not have an
explicit override entry in the order book routing strategies reference data
object.
Order book/Combination definition leg:
The order book is where the actual trading takes place. The order book is in
turn associated with an instrument.
Most market models are defined on order book rule group but some are
defined on the order book itself. An example of such a parameter is round lot.
An order book might represent an combination i.e. an trade in such an order
book actually represents several trades in the underlying order books. These
EMAPI Protocol
28 (55)
Restricted External
underlying order books are defined by adding combination definition leg

reference data object.
OrderBookRuleGroup
orderbookRuleGroupId: XCFT_L1_S1_1*
externalReference:
XCFT_L1_S1
orderbookRuleGroupParameters:
tickSizeTableId:
tradingScheduleId:
defaultSubscriptionGroup:
OrderBookRoutingStrategy
ProcessingSequence
serviceId:
orderInsert
orderbookRuleGroupId: XCFT_L1_S1_1
stateName:
PRE_OPEN
OrderBook
orderBookId:
611*
instrumentId: SE0000108656_ISIN_SEK_XCFT_DARK
subscriptionGroup:
tickSizeTableId:
orderbookParameters:
curreny:
ProcessingSequenceOrderBookId
orderBookId:
611
processingSequenceId: PRE_OPEN
CombinationDefinitionLeg
legOrderBookId: 712
orderBookId:
611
Figure 6OrderBookRuleGroup and its related child objects

Object
Key Attribute
Unique Id
parentReference
OrderBookRuleGroup
orderBookRuleGroupId
yes
null
OrderBookRoutingStrat
egy
serviceId
no
ProcessingSequence
stateName
no
OrderBook
orderBookId
yes
CombinationDefinition
Leg
legOrderBookId
no
orderBookId
TradingSchedule
Defines the cycle that an order book moves through during the trading
sessions. Example: Closed->Pre-call->Open
Each order book rule group is associated with the following schedules:
Closed (Used during closed days)
Half-day (Used during half-days)
Normal (Used during normal days)
Temp (Used when temporarily deviating from whatever schedule is being

used at the moment)
EMAPI Protocol
29 (55)
Restricted External
TradingSchedule
tradingScheduleId: 5*
displayName: NORMAL
StateTransition
name:
PRE_OPEN
5
tradingScheduleId:
allowedRequestsGroupId: 89
Figure 7 TradingSchedule andStateTransitions for that schedule.

Object
Key Attribute
Unique Id
parentReference
TradingSchedule
tradingScheduleId
yes
null
StateTransition
name
no
tradingScheduleId
SubscriptionGroup
A subscription group contains a collection of order books. When subscribing
for market data, subscriptions are setup using the identities of
SubscriptionGroups. The subscription group is the smallest unit for which it
is possible to enter a subscription. A SubscriptionGroup is also the smallest
unit that can be used for requesting retransmissions/recovery of market data
(i.e. all orderbooks within the requested subscription group will be retrieved).
Order books belonging to one OrderBookRule group may belong to different
subscription groups and subscription group can contain order books from
several order book rule groups.
SubscriptionGroup
subscriptionGroupId: 432*
Figure 8 SubscriptionGroup.

Object
Key Attribute
Unique Id
parentReference
SubscriptionGroup
subscriptionGroupId
yes
null
TickSizeTable
The tick-size table defines the smallest price increment on orders/ quotes.
Since the price increment varies with the price a table is needed.
TickSizeTable
tickSizeTableId: 77*
displayName:
EUR
TickSizeTableRow
lowerLimit:
100
tickSizeTableId: 77
Figure 9 TickSizeTable and TickSizeTableRow.
EMAPI Protocol
30 (55)
Restricted External
Object
Key Attribute
Unique Id
parentReference
TickSizeTable
tickSizeTableId
yes
null
TickSizeTableRow
lowerLimit
no
tickSizeTableId
Defines allowed requests for a certain state transition. This makes it possible
to define state transition based filter governing which requests that are
allowed.
allowedRequestsGroupId: 89*
displayName: PRE_OPEN_REQ
AllowedRequestsGroupRow
request:
cancelOrder
allowedRequestsGroupId: 89
Figure 10 AllowedRequestsGroup and AllowedRequestsGroupRow.

Object
Key Attribute
Unique Id
parentReference
allowedRequestsGrou
pId
yes
null
AllowedRequestsGroupR
ow
request
yes
allowedRequestsGrou
pId
Currency
Represents a currency.
Currency
currencyId: EUR*
Figure 11 Currency.

Object
Key Attribute
Unique Id
parentReference
Currency
currencyId
yes
null
DateCollention and CalendarDate

The DateCollection holds calendar information on CLOSED and HALF_DAY
trading dates for the system. Each date type holds a set of dates and an
optional calendar Id for which dates the market(s) (all or a part of) shall apply
the date type. The CLOSED/HALF_DAY information is used by the system to
select the appropriate trading schedule.
EMAPI Protocol
31 (55)
Restricted External
DateCollection
dateType: HALF_DAY*
displayName:
EUR
CalendarDate
dateKey: 2008-09-09_CFT_CALENDAR
dateType: HALF_DAY
Figure 12 DateCollection and CalendarDate.

Object
Key Attribute
Unique Id
parentReference
DateCollection
dateType
yes
null
CalendarDate
dateKey
yes
dateType
The OrderBookRuleGroupParameters object is referenced from the
OrderBookRuleGroup and hold parameters that are common for one or many
OrderBookRuleGroups.
parameterSetId:
SYSTEM_DEFAULT
tradingScheduleId: 5
calendarId:
CFT_CALENDAR
Figure 13 OrderBookRuleGroupParameters.

Object
Key Attribute
Unique Id
parentReference
parameterSetId
yes
null
OrderBookParameters
The OrderBookParameters object is referenced from the OrderBook and hold
parameters that are common for one or many OrderBook.
OrderBookParameters
parameterSetId:
SYSTEM_DEFAULT
Figure 14 OrderBookParameterse.
4.7
Object
Key Attribute
Unique Id
parentReference
OrderBookParameters
parameterSetId
yes
null
Markets and Instruments

The Market and Instrument related objects provide a navigation and
management model that resides on-top of the trading data model.
The Market and Instrument model is an optional part of the TRADExpress
system. Depending on system requirements, this part of the reference data
model may not be present.
EMAPI Protocol
32 (55)
Restricted External
The relations between the two object domains can be viewed in the picture
below.
View
Market
XCFt100
XCFT
1
n
1
n
Instrument
ERIC-B
ViewELement
MarketList
EIRC-B, EUR
L1
1
n
1
n
TradableInstrument
TradableInstrument
ERIC-B, SEK
ERIC-B, EUR
Segment
S1
Instruments and Markets
Trading Data
OrderbookRuleGroup
1
n
Orderbook
1
TradingSchedule
TickSizeTable
Orderbook
1
OrderbookRoutingStrategy

Figure 15 Overview figure on how Markets and Instruments relates to OrderBooks and trading
rules.
The Market and Instrument objects are described below.

Market, MarketList and Segment
The Market, MarketList and Segment are a simple object hierarchy that
provides a structure and management navigation for instrument management.
The Market/MarketList/Segment structure is defined by the organization
operating the installation.
Instruments reference a Market as their primary market.
TradableInstruments references a Segment.
On each level, a trading rule parameter block may be assigned. The assigned
trading parameters apply to all TradableInstruments within the
Market/MarketList/Segment. It is the parameter block assigned on the
lowest level that is used. All TradableInstruments within a Segment share
the same TradingSchedule.
EMAPI Protocol
33 (55)
Restricted External
Market
marketId: XCFT*
orderBookParameterSetId:
orderBookRuleGroupParameterSetId:
1
n
MarketList
internalMarketListId: XCFT_L1*
parentInternalId:
XCFT
marketListId:
L1
1
n
Segment
internalSegmentId: XCFT_L1_S1*
parentInternalId: XCFT_L1
segmentId:
S1
Figure 16 Market, MarketList and Segment.

Object
Key Attribute
Unique Id
parentReferenceAttribute
Market
marketId
yes
null
MarketList
internalMarketListId
yes
parentInternalId
Segment
internalSegmentId
yes
parentInternalId
Instrument and TradableInstruments

The Instrument hold basic background information for the instrument such
as:
primaryMarket, the marketplace where the instrument has its primary

listing. The referenced marketplace must be defines as a Market within
the system.
instrument and instrumentIdType. The combination of id and type
instrumentType. The type of instrument, typically one of EQUITY,

FUTURE, CALL_OPTION, PUT_OPTION, etc. The actual instrument types
uniquely identifies an instrument within the system. The instrument id

type is typically one of ISIN, CUSIP or SYMB.
are defined by the organization operating the trading system.
parentInstrument. This may be a reference to a the id of an (optional)

parent instrument for this instrument. For example, if this instrument
is a CALL_OPTION the parentInstsrument may reference the FUTURE
instrument that this option is based upon.
An instrument cannot be traded since it has no reference to an orderbook or

trading rules. These attributes are defined in TradableInstrument child
object(s). One instrument may have several TradableInstrument(s) defined.
Also, the TradableInstrument(s) need not belong to the same market as the
primary market for the instrument. Assuming instrument X with id 123
has XOME as primary market, but it is traded both at OMX and LSE (with the
same id), one TradableInstrument will be created for a Segment within the
EMAPI Protocol
34 (55)
Restricted External
XOME market and another TradableInstrument will be created for a Segment

within the LSE market.
A TradableInstrument defines a tradable instance of an Instrument, which
means that a TradableInstrument has a currency, lot size, and visibility
type. It is also assigned an OrderBook and a SubscriptionGroup. A
TradableInstrument references a Segment which means that the trading
rules that for the specified Segment applies to the TradableInstrument.
Please note that one Instrument may have several TradableInstruments,
each allocated to a different Segment.
n
Instrument
internalId:
instrumentId:
1 instrumentIdType:
type:
parentInternalId:
primaryMarketId:
shortName:
SE0000108656_ISIN*
SE0000108656
ISIN
EQUITY
null
XCFT
ERIC-B
TradableInstrument
internalId:
parentInternalId:
internalSegmentId:
tradableInstrumentId:
tradableInstrumentIdType:
marketId:
marketListId:
segmentId:
currencyId:
orderBookVisibilityType:
subscriptionGroupId:
orderBookId:
SE0000108656_ISIN_SEK_XCFT_DARK*
SE0000108656_ISIN
XCFT_L1_S1
SE0000108656
ISIN
XCFT
L1
S1
SEK
DARK
1
611
Figure 17 Instruments and Tradable Instruments

Object
Key Attribute
Unique
Id
Instrument
internalId
yes
null
TradableInstrument
internalId
yes
parentInternalId
Views and ViewElements

A View object references a Market and represents a View of the
TradableInstruments on that Market. The View object is used to group
TradableInstruments cross MarketLists/Segments.
The ViewElement holds a reference to a TradableInstrument.
EMAPI Protocol
35 (55)
Restricted External
View
viewId:
XCFT100*
marketId: XCFT
1
n
ViewElement
viewElementId:
SE0000108656_ISIN
parentInternalId: XCFT100
internalTradableInstrumentId: SE0000108656_ISIN_SEK_XCFT_DARK
Figure 18 The View and ViewElement. A View references one or many ViewElements which in
turn has a reference to a TradableInstrument.

Object
Key Attribute
Unique
Id
View
viewId
yes
null
ViewElement
viewElementId
yes
parentInternalId
EMAPI Protocol
36 (55)
Restricted External
Trading
This section describes the trading part of the EMAPI protocol.
5.1
Identifiers for Trading Objects
5.1.1
Orders
There are 2 identifiers associated with orders.
Private Order Id (privateOrderId)
Each order is assigned a private order id by the system that is guaranteed to
be unique within the system and over time. The id is provided both in the
interactive response when entering an order and in the private order events.
This id is used when managing the order and when building a private shadow
order book.
Public Order Id (publicOrderId)
In addition, each order is assigned a public order id by the system that is
guaranteed to be unique within the system and over time. The id is provided
both in the public order events and in the private order events.
This id is used when building a public shadow order book and when accepting
orders.
5.1.2
Quotes
There are 4 identifiers associated with quotes.
Quote Replace Id (quoteReplaceId)
The QuoteInsertReq message contains a quote replace id field that is
assigned by the user. Each quote in the QuoteInsertReq is assigned this quote
replace id.
This id is used when managing quotes as described below.
The quotes in a QuoteInsertReq will replace any existing quotes for the
member with the same quote replace id in the order books of the
QuoteInsertReqs quotes.
For an order book (specified in one or more quotes in the QuoteInsertReq)
the process is as follows:
1. Collect all residing members quotes in the order book that have a quote
replace id that matches the one specified in the QuoteInsertReq.
2. For each quote in the QuoteInsertReqs that is designated to the order
book:
a. Primarily reuse an earlier collected quote on the same side of the
order book. The quotes properties will be updated to reflect the new
quote but the quotes orderBook, isBid, quoteReplaceId, quoteId,
privateQuoteId and publicMember will not change.
b. Secondarily insert a new quote.
3. Remove all earlier collected quotes that have not been reused.
The mechanism above provides a tremendous amount of flexibility in terms of
how allowing members to design their quoting strategies.
Note:
EMAPI Protocol
A QuoteInsertReq will never affect any other order books than the
ones that are contained within the transaction.
37 (55)
Restricted External
Note:
There are no explicit quote cancel operations. To cancel one or several

quotes with the same quoteReplaceId in one or several order books a
Client sends in a QuoteInsertReq with the quoteReplaceId specified
and with quotes with volume 0 in the concerned order books.
Client Defined Quote Id (clientDefinedQuoteId)

Each quote in a QuoteInsertReq is assigned a client defined quote id by the
user.
This id is used to map a private trade event to a quote. That is, any private
trade event involving a quote will reference this quote id.
Private Quote Id (privateQuoteId)
Each quote is assigned a private order id by the system that is guaranteed to
be unique within the system and over time. The id is provided in the private
quote events.
This id is used building a private shadow order book.
Quote Id (quoteId)
Each quote is assigned a (public) quote id by the system that is guaranteed to
be unique within the system and over time. The id is provided both in the
public quote events and in the private quote events.
This id is used when building a public shadow order book.
5.2
Cancel on Logout
All orders with cancelOnLogout set to true and all quotes are cancelled
when the user, which last acted upon the item, does not have any live
sessions on the Server (e.g. when sessions have been terminated due that
Servers heartbeat time has expired (see section 2.3)).
Note:
5.3
This independently if the owning user or if there are other users, that
may act on-behalf of the owning user, do have live sessions in the
Server.
Event Flows
Events on these flows are published on different subscription groups (see also
section 3.1.2).
The events marked suffixed with (*) is not provided in a current value.
Flow
Current
Value/
Replay
PRIVATE_ORDERBOOK_EVENT_FLOW
Current
Value &
Replay
Private order book events.
EMAPI Protocol
ChatMessageEventPrivate(*)
MassUpdateEventPrivate(*)
OrderEventPrivate
QuoteEventPrivate
RequestForQuoteEventPrivate(*)
WaitForSSNEvent
38 (55)
Restricted External
Flow
Current
Value/
Replay
PUBLIC_ORDERBOOK_EVENT_FLOW
Current
Value &
Replay
Public order book events.
MBL_L1_FLOW
MBL_L2_FLOW
PUBLIC_PRICELEVEL_FLOW
PRIVATE_TRADE_FLOW
PUBLIC_TRADE_FLOW
EMAPI Protocol
Current
Value
Current
Value
Current
Value
Replay
Replay
AuctionEvent
ChatMessageEvent(*)
MarketByLevelEvent
OrderBookStateChangeEvent
OrderEvent
QuoteEvent
RequestForQuoteEvent(*)
StateFreezeEvent
WaitForSSNEvent
Public order book events but only

aggregated volumes at the best
bid/ask price.
AuctionEvent
MarketByLevelEvent
WaitForSSNEvent

aggregated volumes at the n best
bid/ask prices. Value n is
configurable per TRADExpress
installation.
AuctionEvent
MarketByLevelEvent
WaitForSSNEvent

aggregated volumes at the m best
bid/ask prices. Value m is
configurable per TRADExpress
installation.
AuctionEvent
MarketByLevelEvent
WaitForSSNEvent
Private trade events.
TradeEventPrivate
WaitForSSNEvent
Public trade events.
TradeEvent
WaitForSSNEvent
39 (55)
Restricted External
5.3.1
Information in Events
All events on these flows contain following information:
timeOfEvent: At what time the event occurred in TRADExpress.
sequenceIndicator: Indicates if the event is part of a sequence of events

that is sent out as a result of the same TRADExpress event (e.g. order
insert, state change etc.).
If set to true the event is the last event in a sequence of events that
occurred at the same time. If set to false the event is part of an event
sequence which last event will have this field set to true.
N.B. If there is only one event that occurred at the same time the only
event will have this field set to true.
N.B. It is configurable per TRADExpress installation if events on a certain
public flow are visible as sequences. If events on a public flow aren't
visible as sequences this field will not be set.
Note:
Events that deliver the current value (see section 3.2.1) have non valid
timeOfEvent and sequenceIndicator.
5.4
Note:
If any filtering is done (e.g. only subscribing to event relating to some

order books) the value of the sequenceIndicator can not be trusted.
Note:
The sequenceIndicator is currently only supported to be configured

on market by level flows (e.g. PUBLIC_PRICELEVEL_FLOW,
MBL_L1_FLOW, MBL_L2_FLOW).
Building a Public Shadow Order Book

A complete shadow order book contains information about the prices/volumes
as well as order book state/trade halt information.
5.4.1
Relevant EMAPI Messages

The following EMAPI messages needs to be honored when building public
shadow order books:
OrderEvent
The event type can be one of INSERT, UPDATE, CANCEL.
MarketByLevelEvent
QuoteEvent
If the state event type is STATE_CHANGE_OB,

STATE_CHANGE_OB_RULEGROUP or HALT_EVENT then the event
provides information about the order book state (Open, Closed etc.)
and/or trade halt information.
Note that these state event types do not directly affect the
orders/quotes in the shadow order book.
EMAPI Protocol
If the state event type is PUBLIC_ORDERBOOK_OBSOLETE then all

orders/quotes/aggregated price levels belonging to the specified
order book should be discarded. In other word all
orders/quotes/aggregated price levels are to be removed from the
public shadow order book.
40 (55)
Restricted External
5.4.2
Note that there are other state event types but these only provide
transient information that need not to be applied to a shadow order
book.
OrderEvent/QuoteEvent versus MarketByLevelEvent

The OrderEvent/QuoteEvent messages are used to disseminate public
individual order/quote information.
The MarketByLevelEvent message is used to disseminate aggregated
order/quote volumes per price level information.
On the PUBLIC_ORDERBOOK_EVENT_FLOW may both OrderEvent/QuoteEvent:s
and MarketByLevelEvent:s be sent. Typically is either
OrderEvent/QuoteEvent:s or MarketByLevelEvent:s used for a given trading
session (i.e. state), but this is dependent on the configuration of the
TRADExpress installation
A common example where both MarketByLevelEvent:s and
OrderEvent/QuoteEvent:s are used on the same flow although for different
trading session is a classical order driven market. Typical such a market starts
with a morning trading sessions where only MarketByLevelEvent:s are
disseminated, once in continuous trading the individual
OrderEvent/QuoteEvent:s are disseminated instead of the
MarketByLevelEvent:s.
5.4.3
Building a Shadow Order Book from Order/Quote Events

The key to be used for orders/quotes in the public shadow order book are the
ones described in section Public Order Id (publicOrderId) respectively
Quote Id (quoteId).
Note:
These identifiers are generated from the same source so a

publicOrderId/quoteId is unique when looking at both orders and
quotes.
Order/Quote Priority
Following orders/quotes properties is used, in the specified order, to decide
the priority of the order/quote amongst orders/quotes in the order book side:
1. Price. If the reference data (see section 4) indicates that an order book
uses:
normal sorting then a higher price implies higher priority for a bid
order/quote and a lower price implies higher priority for an ask
order/quote
reversed sorting then a lower price implies higher priority for a bid
order/quote and a higher price implies higher priority for an ask
order/quote
2. Priority Group (lower value implies higher priority)
3. Priority (lower value implies higher priority)0.
5.4.4
Building a Shadow Order Book from Market-By-Level Events

The key to be used for price levels in the public shadow order book consists of
following price level properties:
isBid
price
Note: It is guaranteed that the number of price levels will never
exceed the number of price levels applicable for the flow.

E.g. if there exists a price level on an order books buy
side and a new better buy price level is inserted, the first
EMAPI Protocol
41 (55)
Restricted External
price level is canceled on MBL_L1_FLOW (only one price level

is applicable for this flow) before the better price is
inserted.
Price Level Priority

Only the price is used when deciding the priority of the price level. What
priority a price level has is decided in the same way as for the price for
individual orders/quotes as described in section Order/Quote Priority.
5.5
Building a Private Shadow Order Book

A complete private shadow order book contains information about the
prices/volumes.
5.5.1
Relevant EMAPI Messages

The following EMAPI messages needs to be honored when building private
shadow order books:
OrderEventPrivate
QuoteEventPrivate
5.5.2
The event type can be one of INSERT, UPDATE, CANCEL

The event type can be one of INSERT, UPDATE, CANCEL
Order/Quote Key
The key to be used for orders/quotes in the public shadow order book are the
ones described in section Private Order Id (privateOrderId) respectively
Private Quote Id (privateQuoteId).
Note:
These identifiers are generated from the same source so a

privateOrderId/privateQuoteId is unique when looking at both
orders and quotes.
5.6
Order History
A private order event is tagged with the following attribute describing the
origin of an event.
Source of event, this is either USER or SYSTEM. USER indicates that the
source of the event is an explicit action taken by a user. SYSTEM indicates
that the source of the event is an action taken by the system.
Note that it is quite feasible that an initial USER event triggers a number
of SYSTEM events. This happens for example when a user by an explicit
update make an order so generous so that its matches.
Event type, one of INSERT, UPDATE, CANCEL. These are the base order
event types. The set of event types are unlikely to change in the future
and should thus always be used when building a shadow order book.
Sub event type, this is indicates with a greater level of detail the type of
event. The set of sub event types is likely to increase over time.
The valid combination of SubEventType/TypeOfEvent/SourceOfEvent is as

follows:
Table 1: Valid combinations: SubEventType / TypeOfEvent / SourceOfEvent
SubEventType
TypeOfEvent
SourceOfEvent
Description
RESTORE
INSERT
SYSTEM
Overnight orders are

restored by the system
in the morning.
EMAPI Protocol
42 (55)
Restricted External
SubEventType
TypeOfEvent
SourceOfEvent
Description
INSERT
INSERT
USER
User registers new

order.
PARTIALLYFILLED
UPDATE
SYSTEM
A partial fill of an
order occurs.
FILLED
UPDATE
SYSTEM
A complete fill of an
order occurred.
MASSUSPEND
UPDATE
USER/SYSTEM
Order was suspended

as a part of a mass
update transaction.
MASSACTIVATED
UPDATE
USER/SYSTEM
Order was activated as

a part of a mass
update transaction.
MASSCANCEL
CANCEL
USER/SYSTEM
Order was canceled as

a part of a mass
update transaction.
UPDATE
UPDATE
USER
User updated order
USERDISABLED
CANCEL
SYSTEM
Order was canceled

due to that the user
was disabled.
USERDELETED
CANCEL
SYSTEM
Order was canceled

due to that the user
was deleted.
USERDISCONNECTED
CANCEL
SYSTEM
Order was canceled

due since user was
disconnected. Orders
are individually
marked as being
eligible for
cancellation in case of
an disconnect.
EXPIRED
CANCEL
SYSTEM
Order expired.
CANCEL
CANCEL
USER/SYSTEM
User cancelled order.
SAVEDOVERNIGHT
CANCEL
SYSTEM
Order was cancelled

since it was saved
overnight. The order
will be restored next
trading day.
WOULDHAVECROSSED
CANCEL
SYSTEM
The system can

dependent on
configuration disallow
crosses within a
market participant.
PRICERECALCULATED
UPDATE
SYSTEM
Order was cancelled

due to peg order
recalculation.
CANCEL_DUE_TO
_PRICEBAND
CANCEL
SYSTEM
Order broke price band

criteria and was
cancelled.
SYSTEM
Order was changed

due to that a trigger
condition was met.
SYSTEM
Some type of
reference price used
by the order was not
ORDERCONDITION
NO_BASE_PRICE
EMAPI Protocol
CANCEL
43 (55)
Restricted External
SubEventType
TypeOfEvent
SourceOfEvent
Description
available. A typical
example is an order
pegged to an external
price reference.
A public order event only contains the TypeOfEvent field and does not
provide any information about SubEventType or SourceOfEvent.
Note:
5.7
The TypeOfEvent field might very well differ between a public and
private event originating from the same matcher event. This is
described in the coming chapters.
Message Sequences
5.7.1
OrderInsertReq/Rsp no Match
Interactive flow
Client
|--------------|<--------------
OrderInsertReq
OrderInsertRsp
Server
--------------->|
----------------|
Private flow
Client
Server
|<------------- OrderEventPrivate (INSERT) ---------------|
Public Flow
Client
|<--------------
5.7.2
OrderEvent
Server
----------------|
Explicit Cancel of Order

Interactive flow
Client
|--------------|<--------------
OrderCancelReq
OrderCancelRsp
Server
--------------->|
----------------|
Private flow
Client
Server
|<------------- OrderEventPrivate (CANCEL) ---------------|
Public flow
Client
|<--------------
5.7.3
OrderEvent (CANCEL)
Server
----------------|
Insert of FaK/FoK That do Not Match

Interactive flow
Client
|--------------|<--------------
OrderInsertReq
OrderInsertRsp
Server
--------------->|
----------------|
Private flow
Client
Server
|
* Shows order with the full volume
|
|
|
EMAPI Protocol
44 (55)
Restricted External
Public flow
N/A
5.7.4
OrderInsertReq/Rsp Full Match Against Two Orders Residing in the

Book
Interactive flow
Client
|--------------|<--------------
OrderInsertReq
OrderInsertRsp
Server
--------------->|
----------------|
Private flow participant owning the order being entered

Client
Server
|
* Shows order status prior to match i.e. full volume. |
|
|
|<------------- TradeEventPrivate
---------------|
|
* First trade against participant A
|
|
|
|<------------- OrderEventPrivate (UPDATE) ---------------|
|
* Order volume is decreased with the traded volume.
|
|
|
---------------|
|
* The remaining portion of the incoming order is now |
|
completely matched against participants B order
|
|
residing in the book.
|
|
|
|
* Shows order status post match, volume is zero since |
|
there was a complete match.
|
|
|
Private flow participant A owning order residing in the order book

Client
|<------------|<------------|
* Volume is
|
|<-------------
Server
TradeEventPrivate
---------------|
OrderEventPrivate (UPDATE) ---------------|
zero since order is completely traded
|
|
OrderEventPrivate (CANCEL) ---------------|
Private flow participant B owning order residing in the order book

Client
Server
---------------|
* Participants B order is only partially matched
Public flow
Client
Server
|<------------- TradeEvent
---------------|
|
* The trade against participant A
|
|
|
|<------------- OrderEvent (CANCEL)
---------------|
|
* Participant A:s order is now cancelled
|
|
|
|<------------- TradeEvent
---------------|
|
* The trade against participant B
|
|
|
|<------------- OrderEvent (UPDATE)
---------------|
|
* Participant B:s is updated order since it was only |
EMAPI Protocol
45 (55)
Restricted External
5.7.5
partially matched
OrderUpdateReq/Rsp Updated Order Matches Fully Against Order

in the Book
The basic principle is that the original update is sent out on the private flow
followed by the normal message sequence implied by whatever matching that
takes place.
Interactive flow
Client
|--------------|<--------------
OrderUpdateReq
OrderUpdateRsp
Server
--------------->|
----------------|
Private flow participant owning the order being updated

Client
Server
|
* Shows the order how it looks directly after
|
|
the update. In this case the price was updated so
|
|
that the order became eligible for matching.
|
|
|
---------------|
|
* The order is now completely matched
|
|
|
|<------------- OrderEventprivate(UPDATE) ---------------|
|
|
|
|
|
Private flow participant B owning order residing in the order book

Client
Server
---------------|
* Participants B order is only partially matched
Public flow
Client
Server
---------------|
|
* Participant A:s order is now cancelled
|
|
|
|<------------- TradeEvent
---------------|
|
* The updated order now matches against the order
|
|
residing in the order book.
|
|
|
|<------------- OrderEvent (UPDATE)
---------------|
|
* Participant B:s is updated order since it was only |
|
partially matched
|
5.7.6
QuoteInsertReq/Rsp no Match
Interactive flow
Client
|--------------|<--------------
QuoteInsertReq
QuoteInsertRsp
Server
--------------->|
----------------|
Private flow participant owning the quote being entered

Client
|<------------- QuoteEventPrivate
EMAPI Protocol
Server
----------------|
46 (55)
Restricted External
Public flow
Client
|<------------- QuoteEvent
5.7.7
Server
----------------|
QuoteInsertReq/Rsp Partial Match Against Order Residing in Order

Book
Interactive flow
Client
|--------------|<--------------
QuoteInsertReq
QuoteInsertRsp
Server
--------------->|
----------------|
Private flow participant owning the quote being entered

Client
Server
|<------------- QuoteEventPrivate (INSERT)----------------|
|
* Shows quotes status prior to match i.e. full volume.|
|
|
----------------|
|
|
|<------------- QuoteEventPrivate (UPDATE)----------------|
|
* Quote volume is decreased with the traded volume.
|
Private flow participant owning order residing in the order book

Client
Server
---------------|
* This order is completely traded
Public flow
Client
|<------------- TradeEvent
|<------------- QuoteEvent (INSERT)
5.7.8
Server
---------------|
---------------|
---------------|
OrderInsertReq/Rsp full match against quote

Interactive flow
Client
|--------------|<--------------
OrderInsertReq
OrderInsertRsp
Server
--------------->|
----------------|
Private flow participant owning the order being entered

Client
Server
|
* Shows order status prior to match i.e. full volume. |
|
|
---------------|
|
* Complete match against order residing in book
|
|
|
|
|
|
|
|
Private flow participant owning quote residing in the order book

Client
Server
---------------|
|<------------- QuoteEventPrivate (UPDATE) ---------------|
|
* Volume is zero since quote is completely traded
|
EMAPI Protocol
47 (55)
Restricted External
|<------------- QuoteEventPrivate (CANCEL) ---------------|

* This quote is completely traded
Public flow
Client
Server
|<------------- TradeEvent
---------------|
|<------------- QuoteEvent (CANCEL)
---------------|
* There is only one public quote event since
the entered order is completely matched and
is never inserted.
5.7.9
MarketByLevel
The below order requests are processed by TRADExpress. The concerned
trading session is configured to publish events on market by level flows (i.e.
MBL_L1_FLOW, MBL_L2_FLOW and PUBLIC_PRICELEVEL_FLOW) so the order
requests will result in MarketByLevelEvent:s sequences on respectively
market by level flow as presented below.
1. Insert at price 100.
5. Cancel at price 100.
Note:
All orders are simple limit orders with volume 10.
Note: MBL_L2_FLOW
is configured to publish 2 levels and
PUBLIC_PRICELEVEL_FLOW is configured to publish more than 2 levels.
See also section 5.4.4.

MBL_L1_FLOW
No Client
1.
|<--|
2.
|<--|
3.
|<--|
|<--|
4.
|
|
5.
|
|
6.
|<--|
|<--|
7.
|
|
8.
|<---
Server
MarketByLevelEvent (INSERT, price 100, vol 10) ---|
|
MarketByLevelEvent (UPDATE, price 100, vol 20) ---|
|
MarketByLevelEvent (CANCEL, price 100)
---|
|
|
|
|
|
|
---|
|
|
|
|
---|
MBL_L2_FLOW
Client
Server
|<--- MarketByLevelEvent (INSERT, price 100, vol 10) ---|
|
|
2.
|<--- MarketByLevelEvent (UPDATE, price 100, vol 20) ---|
1.
EMAPI Protocol
48 (55)
Restricted External
3.
4.
5.
6.
7.
8.
|
|<--|
|
|
|<--|
|<--|
|<--|
|<--|
|<---
|
|
|
|
|
---|
|
|
---|
|
---|
PUBLIC_PRICELEVEL_FLOW
1.
2.
3.
4.
5.
6.
7.
8.
Client
|<--|
|<--|
|<--|
|<--|
|<--|
|<--|
|<--|
|<---
Server
|
|
|
|
|
---|
|
---|
|
---|
5.7.10 TradeReportReq/Rsp WaitForOtherSide=false

Interactive flow of participant entering trade
Client
|--------------|<--------------
TradeReportReq
TradeReportRsp
Server
--------------->|
----------------|
Private flow participant entering trade

Client
Server
|<-------- TradeEventPrivate (TRADE_REPORT_HALF) ---------|
|
* This is just the trade half and not the real trade. |
|
Depending on system configuration this message may |
|
never come. Note that trade halves have there own
|
|
tradeId/dealId.
|
|
|
|<------------- TradeEventPrivate (NEW)
---------------|
Private flow participant of the trade report counterparty

Client
Server
|
* This is just the trade half and not the real trade.|
|
Depending on system configuration this message may |
|
never come.
|
|
|
---------------|
Public flow
Client
|<------------- TradeEvent
EMAPI Protocol
(NEW)
Server
---------------|
49 (55)
Restricted External
5.7.11 TradeReportReq/Rsp WaitForOtherSide=true

Interactive flow of participant entering trade half 1
Client
|--------------|<--------------
TradeReportReq
TradeReportRsp
Server
--------------->|
----------------|
Private flow participant entering trade half 1

Client
Server
|
* This is the trade half originating from the
|
|
TradeReportReq/Rsp which this participant entered. |
|
Note that trade halves have there own
|
|
tradeId/dealId.
|
|
|
|
* This is the trade half originating from the
|
|
TradeReportReq/Rsp which the counterparty
|
|
participant entered. Note that ownMember /
|
|
counterpartyMember is switched as compared to
|
|
the originating from the TradeReportReq/Rsp which
|
|
this participant entered by himself.
|
|
The receivingMember field will be set to indicate
|
|
that this event is the result of the counterparty
|
|
entering a trade report half. half i.e. this is
|
|
a copy of his trade report half.
|
|
|
---------------|
Interactive flow of participant entering trade half 2

Client
|--------------|<--------------
TradeReportReq
TradeReportRsp
Server
--------------->|
----------------|
Private flow participant entering trade half 2

Client
Server
|
* This is the trade half originating from
|
|
the TradeReportReq/Rsp which this participant
|
|
entered.
|
|
|
|
* This is the trade half originating from
|
|
the TradeReportReq/Rsp which the counterparty
|
|
participant entered. Note that ownMember /
|
|
counterpartyMember is switched as compared to
|
|
the event originating from the TradeReportReq/Rsp |
|
which this participant entered by himself.
|
|
The receivingMember field will be set to indicate |
|
that this event is the result of the counterparty |
|
entering a trade report half i.e. this is a copy of|
|
his trade report half.
|
|
|
---------------|
Public flow
Client
|<------------- TradeEvent
(NEW)
Server
---------------|
5.7.12 TradeUpdateReq/Rsp
Interactive flow of participant
Client
EMAPI Protocol
Server
50 (55)
Restricted External
|--------------|<--------------
TradeUpdateReq
TradeUpdateRsp
--------------->|
----------------|
Private flow participant

Client
Server
|<-------- TradeEventPrivate (TRADE_UPDATE)
---------|
* It is only private fields that can be updated.
Thus there will be only one private event. Note that
the updated trade event will have the same tradeId
as the original trade.
Public flow
N/A
5.7.13 RequestForQuoteReq/Rsp (type=PRIVATE)

Interactive flow of participant entering request for quote
Client
|--------------|<--------------
RequestForQuoteReq
RequestForQuoteRsp
Server
--------------->|
----------------|
Private flow participant entering request for quote

Client
Server
|<-------- RequestForQuoteEventPrivate
---------|
* The receivingMember field is set to null indicating
that this is just an acknowledgement of the request
for quote sent in by the member himself.
Private flow participant of the participant asked to provide a quote

Client
Server
|<-------- RequestForQuoteEventPrivate
---------|
* The receivingMember field is set to the id of
the member asked to provide a quote indicating that
the receiving member is expected to provide a quote.
The participants should now respond with a quote.
This is done by sending in trade halves representing
the quote. These trade halves differ from normal
trade halves in two ways: 1) they usually have
an expiry time attached to them, 2) are marked as
being a response to an RFQ. For a description of
how trade halves are reported see section 5.7.11.
Public flow
N/A
EMAPI Protocol
51 (55)
Restricted External
Order Routing
6.1
Event Flows
section 3.1.2).
Flow
Current Value/
Replay
ORDER_ROUTER_ORDER
Current Value &

Replay
Private order book routing events.
ORDER_ROUTER_TRADE
Replay
OrderEventPrivate
OrderBookStateChange-Event
Private trade routing events.
EMAPI Protocol
TradeEventPrivate
52 (55)
Restricted External
Text Information from Operation Staff

The operation staff of the TRADExpress installation may send out text
information.
7.1
Event Flows
section 3.1.2).
Flow
Current
Value/
Replay
SYSTEM_EVENTS_FLOW
Current
Value 12
Public text messages sent by the operation

staff of the TRADExpress installation.
PRIVATE_EVENTS_FLOW
Current
Value 13
MarketMessage
Private text messages sent by the operation

staff of the TRADExpress installation.
MarketMessage
12
The mechanism used is current value but what is received is actually a replay of all
earlier messages.
13
The mechanism used is current value but what is received is actually a replay of all
earlier messages.
EMAPI Protocol
53 (55)
Restricted External
Surveillance and Clearing

There are two special flows that are normally only used by special entities,
such as market surveillance or clearing applications. These flows are mainly
derived from other flows.
8.1
Event Flows
section 3.1.2).
Flow
Current
Value/ Replay
CONSOLIDATED_FLOW
Replay
Mainly all members private trading

events for all members. Typically
used by market surveillance tools.
INTERNAL_TRADE_FLOW
Replay
Events sent on
PRIVATE_ORDERBOOK_EVENT_
FLOW see section 5.3.
Events sent on
PRIVATE_TRADE_FLOW see
section 5.3.
Heartbeat
Mainly all members private trade

events. Typically used by clearing
houses.
EMAPI Protocol
Events sent on
PRIVATE_TRADE_FLOW see
section 5.3.
54 (55)
Restricted External
Historical Queries
Clients may request old private order and trade events by submitting a query
for historical data. The TRADExpress system stores old events for a
configurable number of days, and can return messages matching specific
search criteria.
Please note that the data stored depends on the configuration of the
TRADExpress system. It is, for example, possible that the system stores old
trades but not old orders.
In each case, the messages returned are the same as the messages that were
sent on the private event flows.
Messages for the current trading day may also be retrieved by using the
subscription recovery mechanism, although that requires that the sequence
numbers (rather than a selection criteria) be included in the request.
9.1
Query types
9.1.1
Historical Trades
Use the HsQueryTradesReq message to retrieve old trades. TRADExpress will
return TradeEventPrivate messages.
9.1.2
Historical Orders
Use the HsQueryOrdersReq message to retrieve old trades. TRADExpress will
return OrderEventPrivate messages.
9.1.3
Historical RequestForQuotes
Use the HsQueryRFQReq message to retrieve old trades. TRADExpress will
return RequestForQuoteEventPrivate messages.
9.2
Query Message Sequence

All historical queries follow the same message sequence:
1. The client sends the query request. The client may specify a desired
maximum number of results to be returned.
2. TRADExpress returns a SimpleRsp response. This response only contains a
result status.
3. TRADExpress returns all matching events (up to a maximum number of
messages), framed by TaxStartSnapshot and TaxEndSnapshot messages.
This is similar to the way messages are received when setting up a
subscription.
4. If the TaxEndSnapshot contains the status code
HsResultPossiblyTruncated, there may be more events matching the
criteria than are delivered in to the client. The client should use a narrower
search criteria in this case.
EMAPI Protocol
55 (55)

EMAPI - Rev F

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

EMAPI - Rev F

Uploaded by

Copyright:

Available Formats

EMAPI Protocol

Rev F April 17, 2009

Copyright 2008-2009 Cinnober Financial Technology AB. All rights

Message Header ..................................................................... 10

Server Session Types ............................................................... 12

Session Surveillance ................................................................ 14

Session Processing .................................................................. 14

Several outstanding Requests ................................................... 15

Session Recovery .................................................................... 15

Session Termination ................................................................ 16

Session Message Sequences ....................................................... 16

Information in Events ............................................................ 17

Subscription Surveillance .......................................................... 19

Subscription Processing ............................................................ 19

Session Establishment, Surveillance and Termination ...................... 16

Outstanding Requests ............................................................ 15

Current Value Framing ........................................................... 19

Replay Framing .................................................................... 20

Replay Sequences ................................................................. 20

Synchronize Subscription/Replay ............................................... 21

Subscription Termination .......................................................... 21

Event Flows .......................................................................... 21

Subscription Message Sequences ................................................. 21

Current Value Subscription Establishment .................................... 21

Reference Data ..............................................................................23

Event Flows .......................................................................... 23

Dissemination of Reference Data................................................. 23

Synchronizing the Reference Data Flow with Other Flows ................... 23

Reference Data object relations ................................................. 24

Members and Users ................................................................. 24

Trading Data and Trading Rules .................................................. 27

Markets and Instruments .......................................................... 32

Identifiers for Trading Objects ................................................... 37

Cancel on Logout ................................................................... 38

Event Flows .......................................................................... 38

Building a Public Shadow Order Book............................................ 40

Information in Events ............................................................ 40

Relevant EMAPI Messages ........................................................ 40

OrderEvent/QuoteEvent versus MarketByLevelEvent ....................... 41

Building a Shadow Order Book from Order/Quote Events .................. 41

Building a Shadow Order Book from Market-By-Level Events .............. 41

Building a Private Shadow Order Book .......................................... 42

Relevant EMAPI Messages ........................................................ 42

Order History ........................................................................ 42

Message Sequences ................................................................. 44

OrderInsertReq/Rsp no Match ................................................. 44

Explicit Cancel of Order ......................................................... 44

Insert of FaK/FoK That do Not Match .......................................... 44

OrderInsertReq/Rsp Full Match Against Two Orders Residing in the Book

OrderUpdateReq/Rsp Updated Order Matches Fully Against Order in the

QuoteInsertReq/Rsp no Match ................................................ 46

QuoteInsertReq/Rsp Partial Match Against Order Residing in Order Book

TradeReportReq/Rsp WaitForOtherSide=true .............................. 50

Event Flows .......................................................................... 52

Historical Queries ...........................................................................55

Surveillance and Clearing .................................................................54

Text Information from Operation Staff .................................................53

OrderInsertReq/Rsp full match against quote .............................. 47

Query types .......................................................................... 55

Historical Trades .................................................................. 55

Historical Orders .................................................................. 55

Historical RequestForQuotes .................................................... 55

Query Message Sequence .......................................................... 55