emapi - rev f

7/23/2019 EMAPI - Rev F

1/55

EMAPI ProtocolRev F April 17, 2009

This document describes the semantics of the EMAPI protocol and the syntaxof the session related EMAPI messages.

7/23/2019 EMAPI - Rev F

2/55

Restricted External

Copyright 2008-2009 Cinnober Financial Technology AB. All rightsreserved.

Cinnober Financial Technology AB reserves the right to make changes to theinformation 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 permissionof Cinnober Financial Technology AB.

Cinnober and TRADExpress are trademarks or registered trademarks ofCinnober Financial Technology AB in Sweden and other countries. Otherproduct or company names mentioned herein may be the trademarks of theirrespective owners.

EMAPI Protocol 2 (55)

Rev F April 17, 2009 Cinnober Financial Technology AB

7/23/2019 EMAPI - Rev F

3/55

Restricted External

Table of Contents

1 Messages......................................................................................10

1.1 Message Types....................................................................... 10

1.2 Message Header ..................................................................... 102 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........................................................................... 152.5 Session Recovery.................................................................... 15

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

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

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

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

3 Subscriptions.................................................................................17

3.1 Introduction ......................................................................... 17

3.1.1 Flows................................................................................ 17

3.1.2 Subscription Group................................................................ 17

3.1.3 Sequence Number................................................................. 173.1.4 Filtering ............................................................................ 17

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

3.2 Subscription Establishment........................................................18

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

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

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

3.4.1 On-behalf........................................................................... 19

3.5 Subscription Recovery.............................................................. 19

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

3.5.2 Replay Sequences................................................................. 203.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

4 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................... 234.4 Reference Data object relations ................................................. 24



7/23/2019 EMAPI - Rev F

4/55

Restricted External

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

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

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

5 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.3.1 Information in Events ............................................................ 40

5.4 Building a Public Shadow Order Book............................................ 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

5.5 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 theBook 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.8 OrderInsertReq/Rsp full match against quote .............................. 47

5.7.9 MarketByLevel..................................................................... 48

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).................................... 516 Order Routing................................................................................52

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

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

7.1 Event Flows .......................................................................... 53

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

8.1 Event Flows .......................................................................... 54

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

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

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

9.1.2 Historical Orders .................................................................. 559.1.3 Historical RequestForQuotes .................................................... 55



7/23/2019 EMAPI - Rev F

5/55

Restricted External

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



7/23/2019 EMAPI - Rev F

6/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 describedin the related documents (EmapiTransactions.html and encoding documents e.g. TagWire Specification).

The EMAPI protocol is one of the protocols used to access the TRADExpresssystem.

The purpose of this document together with its related documents is to serveas a specification of the EMAPI protocol when implementing an EMAPI client.

Messages/fields/constants are presented in the comput er st yl efont. Thenumeric value for a constant is specified in (both) of the related documentsEmapiTransactions.html and EmapiTransactions.xml.

Intended AudienceThe information in this document is aimed towards EMAPI client developers.

Related Documents

Name Description

TagWire Specification Contains the syntax of the tagged value text messageencoding 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 conformsto.

RFC 1950 ZLIBCompressed Data FormatSpecification

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 historicalqueries.

In section 2.2.1 and 2.2.3, added a notethat the client should send a messageshortly after connecting.



7/23/2019 EMAPI - Rev F

7/55

Restricted External


Rev E Mar 26, 2009 Cinnober In the Introduction section removed thesentence regarding version number and insections 2.2.1and 2.2.2instead refer tothe related documents

EmapiTransactions.xml/html.Moved section 2.5.2 to become section 5.2as this functionality is only applicable fortrading items.

In section 3.3corrected the statement thatthe subscription is terminated when a

Syst emSt at usEvent indicates

UNAVAI LABLE and instead stated that Thesubscriptions are however not terminatedon the concerned flow and subscriptiongroup and the Server will continue todeliver events where it stopped when theServer regain its capability deliver eventsfor the concerned flow and subscription

group.

In section 5.2changed from being the lastowning user session to the last acting user(which acted last on the trading item) thattriggers cancellation. Also stated thatquotes are cancelled.

In section 7.1, specified that

SYSTEM_EVENTS_FLOWand

PRI VATE_EVENTS_FLOWsupport currentvalue (i.e. not replay).



7/23/2019 EMAPI - Rev F

8/55

Restricted External


Rev D Feb 24, 2009 Cinnober In section 3.1.2, 3.1.3and 3.1.5clarifiedthat it is only on some flows thatTRADExpress sends events on differentsubscription groups.

In sections 3.2and 3.5specified whensubscribing to/replaying from flows, onwhich TRADExpress does not send eventson different subscription groups, thesubscription group field in thesubscription/replay request shall be set tozero.

In sections that lists event flows (i.e. 3.7,4.1, 5.3, 6.1, 7.1and 8.1) specified if theevents on the concerned flows are or arenot published on different subscriptiongroups.

In section 5.3marked the events that arenot provided in a current value.

In section 5.3added Chat MessageEvent

and Stat eFreezeEvent to the

PUBLI C_ORDERBOOK_EVENT_FLOW and

Wai t For SSNEvent to the MBL_L1_FLOW,

MBL_L2_FLOWand

PUBLI C_PRI CE_LEVEL_FLOW.

Added section 5.3.1. Moved the

specification of the t i meOf Event field tothis section from section 3.1.5and added a

specification of the sequenceI ndi cator

field.In section 5.4.4clarified that it isguaranteed that the number of price levelswill never exceed the number of pricelevels applicable for the flow.

Added section 5.7.9that gives an exampleof the message sequences on market bylevel flows.

Added section 6and moved order routerrelated flows/events to this section fromsection 5.

In section 7.1corrected the name of theevent to Mar ket Message.

Rev C Dec 19, 2008 Cinnober In section 3.1.5removed the field

br oadcast Fl owand replaced t i mest ampwith t i meOf Event .

In section 5.3removed event

Or der BookTr adeHal t Event and added eventAuct i onEvent toPUBLI C_ORDERBOOK_EVENT_FLOW.

In section 5.4.1removed all mentioning of

Or der BookTr adeHal t Event and insteaddescribed the event type HALT_EVENT for theOr derBookStat eChangeEvent .



7/23/2019 EMAPI - Rev F

9/55

Restricted External


Rev B Dec 11, 2008 Cinnober In section 5.1added the Private Quote Id andrewritten some text.

In section 5.3:

- added QuoteEvent Pri vat efor the

PRI VATE_ORDERBOOK_EVENT_FLOW- corrected following names;

Mbl Event => Market ByLevel Event MBL_FULL=>PUBLI C_PRI VELEVEL_FLOW

In section 5.4.1stated that also Quot eEvent has an event type that shall be used.

In section Order/Quote Priority added theproperties Priority Group and Priority.

Added the section 5.4.4.

In section 5.5.1added QuoteEvent Pr i vat e.

In sections 5.7.6 5.7.8added

QuoteEvent Pri vat e.Rev A Nov 3, 2008 Cinnober Initial version.

Terms and Acronyms

Term/Acronym Description

Client A client that connects to TRADExpress Servers using theEMAPI protocol.

Order Book Entity where trading takes place.

Server TRADExpress Server that supports the EMAPI protocol. E.g.the TAX (Trading Application Multiplexer) Server.



7/23/2019 EMAPI - Rev F

10/55

Restricted External

1 Messages

All interaction between a Client and a Server is done using messages.

1.1

Message TypesFollowing types of messages exists:

Request: Messages sent by a Client to a Server requesting TRADExpressto perform something. Named Req.

Response: Messages sent by a Server to a Client delivering the response toa previous request. The response is either named Rsp or ResponseMessage.

All responses contain following information:

code:

Ok: Indicates that the Server has completed the processing of the

request successfully. War ni ng: Used when the request is to perform several things and

TRADExpress has successfully performed some things and hasfailed to perform the other things. Which things TRADExpress hassuccessfully 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 codeis Warni ng. The sub codes position corresponds to theposition 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 Okthe string will be Ok.

r equest I d:Unique identifier for the transaction assigned by theServer.

Note: ResponseMessagecontains this and only this information.

Event: Messages sent by a Server to a Client to inform about events thathave taken place in TRADExpress. A Client only receives events that ithas subscribed to. See section 3.1.5regarding what information all eventscontain.

1.2 Message Header

Each message starts with a header.

Name Position Length Content

magi cSi gn 0 4 Shall be set to XMMA (0x58 0x4D 0x4D0x41).

headerVersi on 4 2 Shall be set to 10 (0x31 0x00).

msgSi ze 6 6 Message size in bytes excluding this header.ASCII encoded. Example: 000100 meansthat the length of the message excludingthis header is 100 bytes.

cl i ent TxRef 12 4 Client assigned request id. Binary networkbyte order.



7/23/2019 EMAPI - Rev F

11/55

Restricted External

Name Position Length Content

A response sent back by Server will containthe same value as set in the request.

In the special case the request is asubscription request all events resultingfrom this subscription (as well as the

subscription response) will contain thesame value as set in the subscriptionrequest.

msgType 16 1 Message type:

R (0x52) = request sent by theClient/response sent by the Server.

B (0x42) = event sent by the Serverthat is not part of a snapshot or replay.

S (0x53) = event sent by the Serverthat is part of a snapshot.

H (0x54) = event sent by the Server aspart of a replay.

cont ent Type 17 1 Encoding used for the message bodyfollowing this message header:

W (0x57) = TagWire

The encodings are described in relateddocuments.

compressed 18 1 Compressed message body flag:

Y (0x59) = Compressed message body

(0x20) = Uncompressed message body

The compressed data format is as specifiedin RFC1950 (see related Documents).

It is configurable per TRADExpress

installation if the Server compressessome/all messages.

A Client is free to send inuncompressed/compressed messages.

19 1 Reserved. Shall be set to (0x20)



7/23/2019 EMAPI - Rev F

12/55

Restricted External

2 Session

All EMAPI interaction between an EMAPI Client and an EMAPI Server is doneinside 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 section2.4.1)).

The number of sessions and what session types a user is allowed to use isprovided by the organization responsible for the concerned TRADExpressinstallation.

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 establishseveral user sessions with different Servers.

2.1 Server Session Types

Following Server session types exist:

ORDERBOOK_TAX: Serves all requests and non-replay subscriptions forprivate data.

MARKET_DATA_TAX: Serves primarily1non-replay subscriptions for publicand/or private data.

REPLAY_TAX: Serves primarily2replay subscriptions for public and/orprivate data.

Note: A Server can be configured to be of several session types.

2.2 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 logonstep shall be performed by the Client against one of the TCP/IP addressprovided by the organization responsible for the concerned TRADExpressinstallation.

After performing a TCP/IP connect the Client shall send in an

TaxPreLogonReq. The request contains:

member /user : Identification information provided by the organizationresponsible for the concerned TRADExpress installation.

maj orVersi on/mi norVersi on/mi croVersi on: The numeric revision of theEMAPI protocol used in the TRADExpress installation which is specified inthe related documents EmapiTransactions.xml/html.

The responseTaxPreLogonRsp3contains:

For each available Server:

i pPor t / i pAddr ess: TCP port and IP address of the Server.

1Which requests/responses/events a MARKET_ DATA_TAXserver type supports isconfigurable per TRADExpress installation.2

Which requests/responses/events a REPLAY_TAXserver type supports is configurableper TRADExpress installation.3In addition to what is provided in all responses see section 1.1.



7/23/2019 EMAPI - Rev F

13/55

Restricted External

l ogi nTi cket : Shall be used in the followingTaxLogonReq. The ticketexpires after a time that is configurable per TRADExpressinstallation.

sessi onTypes: The session type(s) (see section 2.1) that is providedby the Server.

subscr i pt i onGr oups: The subscription group(s) (see section 3.1.2)that the Server serves subscriptions for.

Note: One of the reasons for the pre logon step is to ensure a session loadbalancing on the available Servers.

Note: TheTaxPreLogonReqshould be sent immediately after the TCP/IPconnect, otherwise the session will be disconnected by the TRADExpresssystem.

2.2.2

Logon

To know which Server that a Client shall use for a user session the above prelogon step is used or if this step is not configured for the concernedTRADExpress installation the Client shall use the TCP/IP address provided bythe organization responsible for the concerned TRADExpress installation.

After performing a TCP/IP connect the Client shall send in aTaxLogonReq.The request should be sent immediately after the connect.

The request contains:

member /user : Identification information provided by the organizationresponsible for the concerned TRADExpress installation.

passwor d: Authentication information provided by the organizationresponsible for the concerned TRADExpress installation.

t i cket : Provided by the pre logon step see above section. N.B. Onlyapplicable if the TRADExpress installation has been configured to require

pre logon.

possDupSess I d: See section 2.5.1.

maj orVersi on/mi norVersi on/mi croVersi on: The numeric revision of theEMAPI protocol used in the TRADExpress installation which is specified inthe related documents EmapiTransactions.xml/html.

The responseTaxLogonRspcontains following information4:

l ogonAccept ed: Indicates if the logon was successful.

l ogi nSt at us:

LOGI N_ACCEPTED: Set when (and only when) above l ogonAccept edisset to true.

WRONG_VERSI ON: The Client and Server support different EMAPIversions that are incompatible.

I NI TI AL_LOGI N: At initial logon, the password must be changed, seesection 2.4.1.

PASSWORD_EXPI RED: The password has expired and must be changed,see section 2.4.1.

LOGI N_ACCESS_DENI ED: The user does not have access to the logonservice for this application.

LOGI N_REJ ECTED: Invalid Member/UserName/Password.

4In addition to what is provided in all responses see section 1.1.



7/23/2019 EMAPI - Rev F

14/55

Restricted External

USER_ACCOUNT_LOCKED: The user is locked (e.g. due too manyerroneous logon attempts or by the organization responsible for theconcerned TRADExpress installation).

USER_ACCOUNT_DI SABLED: The user has been disabled by theorganization responsible for the concerned TRADExpress installation.

syst emName/ i sTest Syst em: The name of TRADExpress installation andan indication whether the installation is a test system or not.

cl i ent Hbt I nt er val : See section 2.3.

maxLost Heart beat s: See section 2.3.

Note: TheTaxLogonReqshould be sent immediately after the TCP/IPconnect, otherwise the session will be disconnected by the TRADExpresssystem.

2.3 Session Surveillance

The Client is responsible for sendingTaxHear t beatReqafter logging in. A

suggested interval (in seconds) is specified inTaxLogonRsp(see section

2.2.2).

The request contains:

user Dat a: Client data that will be returned in the response.

The responseTaxHear t beat Rspcontains the following information5:

t i mest amp: Current local time in the Server according to following ISO8601 format: YYYY-MM-DDThh:mm:ss.sTZD (e.g. 1997-07-16T19:20:30.45+01:00).

user Dat a: Client data specified in the request.

Note: Other EMAPI requests that are sent by the Client do not replace the

need to sendTaxHear t beat Req.The Server starts a heartbeat timer after a successful logon. The timer valueis set to a value that is equal or greater than what is specified in

TaxLogonRsp; maxLost Heart beat s* cl i ent Hbt I nt er val . If this heartbeattimer 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

TaxHear t beat Reqwithin a configurable time (should be configured in theClient).

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 TRADExpressinstallation) 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 ofestablishment, surveillance, recovery or termination.

2.4.1

Change Password

To change password (e.g. when the Logi nSt at usfield inTaxLogonRsp(see

section 2.2.2) indicates I NI TI AL_LOGI Nor when the password is soon

expiring) the Client shall send in ChangePasswor dReq. This request contains:




7/23/2019 EMAPI - Rev F

15/55

Restricted External

member I d/user I d: Identification information provided by the organizationresponsible for the concerned TRADExpress installation.

ol dPassword/newPasswor d: The current and the new password that shallreplace the current password.

possDup: See section 2.5.1.

The Server returns ResponseMessage6.

Note: The user does not need to be logged in to change the password.

2.4.2

Several outstanding Requests

An outstanding request is a request that the Client has sent but has notreceived any response for yet.

It is configurable if a user can have more than one outstanding request on asession, and if so how many outstanding requests. That is, if a user can sendin more requests without waiting for the response of the previous requestssent in.

To make it possible to match the responses received from the Server with the

sent requests the EMAPI header contains a cl i ent TxReffield that is set bythe Client in the header of the request and is returned by the Server in theheader of the response.

Note: The responses to the several outstanding requests might not bereceived by the Client in the same order as the Client sent them in.

2.4.3

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 RecoveryThe session establishment at failover is done in the same way as initialestablishment, see section 2.2.

2.5.1

Outstanding Requests

A session may fail after the Client has sent in some request(s) but before theClient has received the response(s) to these requests. In such case the Client

shall resend the concerned outstanding requests with the possDup(=possibleduplicate) field set.

Note: There are some request that do not support possDupbecause theyrelates to the session setup or similar.

When receiving a request with the possDupfield set the Server compares therequest with saved requests. Following is compared:

member /possDupSess I d (specified inTaxLogonReq)

request type

all request fields except the possDup field

If a request is found, which is equal to the resent request with the possDupfield set, the Server returns the response either immediately if the requesthas already been completely served or when the ongoing request has beencompletely served. That is, the Server will answer with the same response

6See section 1.1 for content.



7/23/2019 EMAPI - Rev F

16/55

Restricted External

independently of if the Server has received or hasnt received the requestbefore.

Note: The Client shall only set the possDupfield on requests for which theClient has not received any response on an earlier sessionestablishment. This due to that the possible duplicate checking in theServer adds latency to the transaction.

Note: The number of requests the Server keeps for a member and

possDupSessI dcombination to be used for possible duplicate checkingis limited. This number is provided by the organization responsible forthe concerned TRADExpress installation. A Client shall never send inmore outstanding requests (over all its sessions with the same

possDupSessI d) than this number.

2.6 Session Termination

To terminate a sessionTaxLogout Reqshall be sent to the Server.

The response is a ResponseMessage7and 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

Cl i ent Ser ver| - - - - - - - - - - - - - - - - - - - - Pr eLogonReq - - - - - - - - - - - - - - - - - - - >|| || || ||

7/23/2019 EMAPI - Rev F

17/55

Restricted External

3

Subscriptions

To receive events from a Server a Client must set up subscriptions for theconcerned events and possible replay events.

3.1

IntroductionFollowing base concepts exists for the subscription/replay functionality.

3.1.1

Flows

TRADExpress sends events on several different flows. The flows that existare presented in respective sections that describe the functionality related tothe 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:

Replayit is possible to replay all earlier events that has happened sincethe TRADExpress instance was started see section 3.5.

Current Valueit is possible to receive the current state (e.g. orderscurrently residing in order books)

3.1.2

Subscription Group

On some flows TRADExpress sends events on different subscription groups.

Note: The subscription groups that exist are provided in reference data - seesection 4.

3.1.3

Sequence Number

Each event has a sequence number that is unique on the concerned flow andsubscription group (if TRADExpress sends events on different subscriptiongroups for the concerned flow)

The sequence numbers are positive integers and are monotonically increasingbut are not always increasing by one. I.e. there will be gaps in the sequencenumbers (e.g. a user might not be allowed to receive certain events due toauthorization restrictions)8.

Note: There exists one exception to above: Events that deliver the currentvalue (see section 3.2.1) have a non valid sequence number.

3.1.4

Filtering

A session can choose to only subscribe to events related to certain orderbooks in a subscription group.

3.1.5

Information in Events

All events contain following information:

sequenceNumber : See section 3.1.3.

subscr i pt i onGr oup: Present in events sent on flows on whichTRADExpress sends events on different subscription groups. See section3.1.2.

8This 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.



7/23/2019 EMAPI - Rev F

18/55

Restricted External

Note: Events that deliver the current value (see section 3.2.1) have a non

valid sequenceNumber .

3.2 Subscription Establishment

To subscribe to events the Client sends aTaxSnapshotSubscr i beReq. The

request contains:

f l ow: See section 3.1.1.

key: The subscription group to subscribe to. If TRADExpress does notpublish events on any subscription group on the concerned flow this fieldshall be set to zero. See also section 3.1.2.

r equest Type: The Client specifies one of following operations in therequest:

CURRENT_VALUE: The Server will only send events containing thecurrent value (framed according to section 3.2.1). N.B. Onlyapplicable for flows that supports current value.

SUBSCRI PTI ON: The Server will send real time events. Mainly used forflows that supports replay but may also be used for flows that supportcurrent value (if the Client isnt interested in the current value).

CURRENT_VALUES_AND_SUBSCRI PTI ON: The Server will send eventscontaining the current value first (framed according to section 3.2.1)and then continue to send real time events. N.B. Only applicable forflows that supports current value.

l ast Pol l SequenceNumber : May only be set if r equest Typeis

CURRENT_VALUE. If the Client only fetches current value at certain times

the Client shall set this field to the value of the pol l SequenceNumber

field of theTaxEndSnapshot (see section 3.2.1) message previouslyreceived. If the current value hasnt changed, since last time the Clientfetched the current value, no events will be received inside the currentvalue framing (see section section 3.2.1).

or der BookFi l t er : See section 3.1.4.

member : See section 3.4.1.

The responseTaxSnapshotSubscr i beRsp9contains:

handl e: Used when unsubscribing see section 3.6

l ast Publ i shedSeqNo: Only applicable for flows that supports replay. Thesequence number of the last event published before accepting thissubscription. Should be used when initiating a replay after the initiationof the subscription see section 3.5.

To make it possible to match the events and framing messages received fromthe Server with a subscription the EMAPI header contains a cl i ent TxReffield(see section 1.2) that is set by the Client in the header of the subscriptionrequest and is returned by the Server in the header of resulting messages(response, framing and event messages).

Note: TaxSnapshotSubscr i beRspis returned to the Client by the Serverbefore any events is sent.

Note: If the Client intends to receive all events on a flow that supports replayit must always initiate a replay after/before initiating the subscription see section 3.5.




7/23/2019 EMAPI - Rev F

19/55

Restricted External

Note: If a Client has subscriptions (during the same time) that interleave, theClient will receive some events that are identical (except possibly the

t xCl i ent Reffield in the header).

3.2.1

Current Value Framing

ATaxStar t Snapshot message precedes any current value events. Thismessage contains:

subscr i pt i onGr oup: See section 3.1.2.

ATaxEndSnapshot message succeeds any current value events. This messagecontains:

code: Set to Okif the Server has successfully delivered all events of thecurrent value. All other values are indicating that the Server has failed todeliver 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 Okthestring will be Ok.


pol l SequenceNumber : If the Client only fetches current value at certaintimes the Client shall use the value of this field when fetching the current

value next time. See field l ast Pol l SequenceNumber field in the

TaxSnapshot Subscr i beReqmessage (see section 3.2).

3.3 Subscription Surveillance

The Server sends information about the status for each flow and subscription

group using the Syst emSt at usEvent message. Following statuses exists:

AVAI LABLE: Events are delivered as they are happening.

RECOVERY: The Server is failing over so the delivering of events is delayed.

UNAVAI LABLE: The Server can not any longer deliver events for theconcerned flow and subscription group. Any subscriptions on theconcerned flow and subscription group are however not terminated andthe Server will continue to deliver events where it stopped when theServer regain its capability deliver events for the concerned flow andsubscription group. The Client should try to subscribe to the concernedflow and subscription group on another Server.

3.4 Subscription Processing

This section contains subscription related information that is not part ofestablishment, 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

TaxSnapshotSubscr i beReq.

3.5 Subscription Recovery

To recover events that have been sent by the Server during times when theClient hasnt had any subscription, the Client requests the Server to replayevents.

Note: Which Server that supports replay is configurable per TRADExpressinstallation see section 2.1.



7/23/2019 EMAPI - Rev F

20/55

Restricted External

To replay events (on a flow that supports replay) the Client sends a

TaxRepl ayReq. The request contains:

f l ow: See section 3.1.1.

subscr i pt i onGr oup: The subscription group to replay from. IfTRADExpress 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 sequencenumber that shall either be:

Zero - if the Client hasnt received any events (e.g. at Client start-up).

The sequence number of the last received event when the Client hasreceived events earlier (e.g. if the Client is recovering after afailover).

The value of nextSequencefield inTaxRepl ayEndEvent if the replayevents are delivered in several replays. See section 3.5.2.

endSequenceNumber : The sequence number to which the replay will bedone. E.g. the value of the l ast Publ i shedSeqNo field in

TaxSnapshot Subscr i beReq.

or der BookFi l t er : See section 3.1.4.

member : See section 3.4.1.

The response is aTaxRepl ayRsp that contains the same fields as

ResponseMessage10.

Note: The TaxRepl ayRspis returned to the Client by the Server before anyevents are sent.

Note: If a Client performs several replays (during the same time) thatinterleave, the Client will receive some events that are identical

(except possibly the t xCl i ent Reffield in the header).

3.5.1

Replay Framing

ATaxRepl ayStar t Event message precedes any events that are replayed. Thismessage contains:


ATaxRepl ayEndEvent message succeeds any replayed events. This messagecontains:

code: Set to Okif the Server has successfully replayed all events. All othervalues are indicating that the Server has failed to replay all events.

message: A text description explaining more in detail why the Server has

failed to replay all events. N.B. If the code is Okthe string will be Ok.


nextSequence: See section 3.5.2.

3.5.2

Replay Sequences

It is configurable per TRADExpress installation how many events that can bereplayed as a result of one Client request.

If the number of events to be delivered is greater than this configuration theServer will only deliver this configured number of events and set the

nextSequence field in theTaxRepl ayStar t Event message.

10See section 1.1 for content.



7/23/2019 EMAPI - Rev F

21/55

Restricted External

The Client shall then initiate a new replay setting the sequenceNumber field

in theTaxRepl ayReqmessage to the value of the field nextSequencein the

TaxRepl ayStar t Event message.

Note: If the nextSequence field isnt set the Server has replayed all theevents that it knew of at the time when the replay was requested.

3.5.3

Synchronize Subscription/Replay

To avoid handling too much live and replayed data at the same time theClient could:

1. Replay events until the nextSequencefield isnt set in the

TaxRepl ayEndEvent message.

2. Setup the subscription.

3. If the l ast Publ i shedSeqNofield in subscription response is greater thanthe last sequence number received in the earlier replay, another replay isinitiated to get the missing events.

Restrictions

It is recommended to only replay from zero at client start up and duringextreme Client situations (e.g. Client is restarted clean). That is, if a Clientmay be required to perform replay(s) it must:

Remember last received sequence number per subscription.

Setup subscriptions for flows that it may be required to perform replay(s)as early as possible.

3.6 Subscription Termination

To terminate a subscriptionTaxRemoveSubscr i pt i onReqshall be sent to theServer. This message contains:

handl e: The subscription handle received inTaxSnapshot Subscr i beRsp.

A ResponseMessage11is returned by the Server.

3.7 Event Flows

Events on these flows are not published on any subscription groups (see alsosection 3.1.2).

Flow CurrentValue/ Replay

Description and messages sent

SYSTEM_STATUS_FLOW Current Value Flow/subscription status events.

Syst emStat usEvent

3.8 Subscription Message Sequences

This section contains message sequence examples.

3.8.1

Current Value Subscription Establishment

Cl i ent Ser ver| - - - - - - - - - - - - - - - - TaxSnapshotSubscr i beReq - - - - - - - - - - - - - - - >||

7/23/2019 EMAPI - Rev F

22/55

Restricted External

|

7/23/2019 EMAPI - Rev F

23/55

Restricted External

4

Reference Data

The reference data is a set to static and semi-static data that contains thenecessary information for the trading system to operate.

The Reference Data Model is the object model used by servers in the tradingsystem. The reference data is also distributed to trading clients and it istherefore necessary for a client to be aware of the reference data model.

This chapter describes the Reference Data Model. The model is divided intothree parts:

Members and Users. This section describes the relation between Membersand Users in the system.

Trading data and Trading rules. This part describes orderbooks, ticksizetables and trading schedules.

Markets and Instruments. This part describes how the orderbooks relatesto 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 toreceive reference data, it must setup a subscription on the reference dataevent flow. This is described in the chapter Event Flows below.

4.1 Event Flows

Events on these flows are not published on any subscription groups (see alsosection 3.1.2).

Flow CurrentValue/ Replay

Description

PUBLI C_GLOBAL_REFERENCE_DATA_FLOW Current Value Reference dataevents.

4.2 Dissemination of Reference Data

The PUBLI C_GLOBAL_REFERENCE_DATA_FLOWis the flow on which all referencedata is disseminated. Thus all data is pushed out as unsolicited events.

User and Member data is however treated slightly different as compared toother 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

PUBLI C_GLOBAL_REFERENCE_DATA_FLOWreference data flow. Instead explicit

queries need to be used, Quer yUser sReq/ Rspand Quer yOwnMember Req/ Rsp

For service desk users User/Member data is however disseminated as a part of

the normal PUBLI C_GLOBAL_REFERENCE_DATA_FLOW.

4.3 Synchronizing the Reference Data Flow with Other Flows

As any other flow the PUBLI C_GLOBAL_REFERENCE_DATA_FLOWisunsynchronized with other flows.

This constitutes a potential problem if for example an order book is hot-inserted during the day. In such a case a client might receive an OrderEventreferring to the newly created order book prior to receiving the corresponding

update of the reference data on the PUBLI C_GLOBAL_REFERENCE_DATA_FLOW.

In order to solve this problem a Wai t For SSNEvent will be published on otherflows when required. This event contains information on which state sequence



7/23/2019 EMAPI - Rev F

24/55

Restricted External

number a client must wait for on the PUBLI C_GLOBAL_REFERENCE_DATA_FLOWreference data flow prior to continuing processing messages on this flow.

For details regarding the state sequence number mechanism, see the

Wai t For SSNEvent and respectively reference data event message description.

1)

If a specific client is not dependent on reference data for processing,

then Wai t For SSNEvent :s can simply be ignored.

4.4

Reference Data object relations

The following chapters describe the different object domains that are used inthe reference data.

The table at the end of each object type section has four columns, Object,Key Attribute, Unique Id and parentReference.

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. Ifthe key is unique, it can be used immediately locate the object. If the keyis not unique, the object is unique only relative its parent.

parentReference defines, if the object is a child object, whichattribute that references the parent object.

4.5 Members and Users

This section describes the objects that define the member/user structureused in the system.

MemberAAA_TRADI NG

UserCARL_TRADER

ServerGroupTAX_GRP_4

ServerProcessTAX2

ServerGroupTAX_GRP_4

ServerProcessTAX2

UserPropertiesCategorywi ndow_1

UserPropertyZ4

ServiceProfileALL_I NSTRUMENTS

ServiceProfileEntryPROFI LE_1

ServiceProfileALL_I NSTRUMENTS

ServiceProfileEntryPROFI LE_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 usersassociated with it. Users within the same member can access each othersorders/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.



7/23/2019 EMAPI - Rev F

25/55

Restricted External

The Member/User object also contains a (comma separated) list of references

to one or more Ser vi cePr of i l eGr oup(s). A Ser vi cePr of i l eGr oupmay beused to map access to specific information flows for a Member/User.

Both the Member and User object contains an optional string reference to a

Ser verGr oupobject. If defined, the Ser verGr oupreference may be used todirect external transactions for all Users belonging to a Member, or just aspecific User, to a predefined group of gateway servers. If a reference to a

Ser verGr oupis specified for both a Member and a User, the user referencehas precedence.

The key attributes for a Member are:

member I d. This is the system unique member identifier.

member Type, typically one ofTRADI NG_AND_CLEARI NG,TRADI NG_ONLY,

CLEARI NG_ONLY, I NFORMATI ON_VENDOR, MEMBER_UNI T, and S_DMA. Amember type is associated with a set of rights which determines whatsystem services are available for a member of the specific type.

associ at edMember I d. If the member Typeis one of MEMBER_UNI Tor S_DMA

(Sponsored Direct Market Access), the associ at edMember I dcontains theid of the member to which this member is associated. Only

TRADI NG_AND_CLERARI NGandTRADI NG_ONLYmembers may have

MEMBER_UNI Ts and S_DMAs associated.

A MEMBER_UNI Tis typically an organizational unit within a large organization,

for example, if SEB is aTRADI NG_AND_CLEARI NGmember then Enskilda

Securities may be a MEMBER_UNI Tassociated to SEB.

An S_DMAis typically a large customer to aTRADI NG_AND_CLEARI NGor

TRADI NG_ONLYmember that has been granted direct access to themarketplace by the sponsoring member.

A member that has MEMBER_UNI Ts or S_DMAsnormally has the right to act-

on-behalf and subscribe-on-behalf for private trade information for themember(s) it sponsors. The right to act and subscribe on behalf is generallyrestricted only to users that has been assigned SUPER_TRADER access.

UserPropertiesCategory:

This object to defines a common category for all UserProperties child objectsThe category name is defined by the client and is not interpreted in any wayby the trading system.

UserProperties:

Holds client defined properties, these are not interpreted by the system inany way. Typically used to store properties like client application windowlayout, quoting parameters, other configuration parameters etc.

The properties are stored as name-value pairs and are furthermorecategorized. The categorization is also entirely client defined.



7/23/2019 EMAPI - Rev F

26/55

Restricted External

MembermemberId: AAA_TRADING*

memberType: TRADING_AND_CLEARING

assiciatedMemberId:

serverGroupId: TAX_GRP_2tradingAccessProfileList:

subscriptionAccessProfileList:

UseruserId: CARL_TRADER*

memberId AAA_TRADING

serverGroupId:

tradingAccessProfileList:subscriptionAccessProfileList:

UserPropertiesCategorycategoryId: window_1

userId CARL_TRADER

UserPropertypropertyId: 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

UserPr oper t i esCategor y categoryId no userId

UserPropert y propertyId no userPropertyCategoryId

ServerGroup

The Ser ver Gr oupdefines a group of servers. Each server is defined in the

child Server Process object. Each ServerProcess object may define a

server Typeand which set of partitions that are handled by the

ser ver Pr ocessI dserver. The set of partitions may be set to all, indicatingthat the server can handle requests for all partitions (i.e concurrent server).

The ser ver Pr ocessI dcontains the name of a system gateway process,TAX1 for example.

The Server Gr oup/ Server Process objects are typically used to define a groupof gateway servers and are for load balancing. In this case, a Member/User is

assigned a Ser verGr oupthat is used when connecting to the trading system.

ServerGroupserverGruopId: TAX_GRP_4*

ServerProcessserverProcessId: TAX7

serverGroupId: TAX_GRP4



7/23/2019 EMAPI - Rev F

27/55

Restricted External

Figure 3 ServerGroup and ServerProcess object.



Ser verGr oup serverGroupId yes null

Server Process name no serverGroupId

ServiceProfile

The Servi ceProf i l eobject contains an id and a collection of

Ser vi cePr of i l eEnt r ychild objects. The Servi ceProf i l eholds informationon which flows a Member/User that references this profile is allowed tosubscribe to.

A Servi ceProf i l eis referenced ById from a Member or User .

The Ser vi cePr of i eEnt r ycontains information on information which

orderbooks that are available within this Ser vi cePr of i l eEnt r y.

The totally allowed information flow(s) and available orderbooks for aServiceProfile is the sum of the information flows for all

Ser vi cePr of i l eEnt r ychilds.

ServiceProfileserviceProfileId: ALL_INSTRUMENTS*

ServiceProfileEntryprofileEntryId: CFT_STOCK

parentId: ALL_INSTRUMENTS

Figure 4 ServiceProfile and ServiceProfileEntry.



Servi ceProf i l e serviceProfileId yes null

Ser vi ceProf i l eEnt r y profileEntryId no parentId

4.6 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



7/23/2019 EMAPI - Rev F

28/55

Restricted External

OrderBookRuleGroupXCFT_L1_S1_1

OrderBook611

ProcessingSequencePRE_OPEN

OrderBookRoutingStrategyorder I nsert

ProcessingSequenceOrderBookId611

CombinationDefinitionLeg712

TradingScheduleNORMAL

StateTransitionPRE_OPEN

TradingScheduleNORMAL

StateTransitionPRE_OPEN

TickSizeTableEUR

TickSizeTableRow0-100

TickSizeTableEUR

TickSizeTableRow0-100

SubscriptionGroup47

CurrencyEUR

AllowedRequestsGroup346

AllowedRequestsGroupRowcancel Or der

OrderBookRuleGroupParametersSYSTEM_DEFAULT





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 commonset of trading characteristics. I.e. order books using the same market modelshould be grouped together in the same order book rule group.

It should be noted that even though most of the market model parameters aredefined 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 containedwithin that order book rule group also changes state. It is however possible todefine the sequence and delays which with the order books contained in theorder book rule group changes state.

I.e. the order books themselves will change state after the order book rulegroup has changed state.

If no processing sequence is defined then this implies that all order bookschanges state immediately when the order book rule group changes state.

OrderBookRoutingStrategy: (system internal)

If defined, provides the possibility to configure how the Matching enginehandles requests. I.e. if an orderInsert request is received then a strategynamed orderInsert is looked up an executed.

It is possible to override this default mapping by modifying the order bookrouting 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 anexplicit override entry in the order book routing strategies reference dataobject.

Order book/Combination definition leg:

The order book is where the actual trading takes place. The order book is inturn associated with an instrument.

Most market models are defined on order book rule group but some aredefined 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



7/23/2019 EMAPI - Rev F

29/55

Restricted External

underlying order books are defined by adding combination definition legreference data object.

OrderBookRuleGrouporderbookRuleGroupId: XCFT_L1_S1_1*

externalReference: XCFT_L1_S1orderbookRuleGroupParameters:

tickSizeTableId:

tradingScheduleId:

defaultSubscriptionGroup:

OrderBookorderBookId: 611*

orderbookRuleGroupId: XCFT_L1_S1_1

instrumentId: SE0000108656_ I SI N_SEK_XCFT_DARKsubscriptionGroup:

tickSizeTableId:orderbookParameters:

curreny:

ProcessingSequencestateName: PRE_OPEN


OrderBookRoutingStrategyserviceId: orderInsert


ProcessingSequenceOrderBookIdorderBookId: 611

processingSequenceId: PRE_OPEN

CombinationDefinitionLeglegOrderBookId: 712

orderBookId: 611

Figure 6OrderBookRuleGroup and its related child objects



Or der BookRul eGr oup orderBookRuleGroupId yes null

Or der BookRout i ngStr ategy

serviceId no orderBookRuleGroupId

Processi ngSequence stateName no orderBookRuleGroupId

Or derBook orderBookId yes orderBookRuleGroupId

Combi nat i onDef i ni t i onLeg

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 beingused at the moment)



7/23/2019 EMAPI - Rev F

30/55

Restricted External

TradingScheduletradingScheduleId: 5*

di spl ayName: NORMAL

StateTransitionname: PRE_OPENtradingScheduleId: 5

allowedRequestsGroupId: 89

Figure 7 TradingSchedule andStateTransitions for that schedule.



Tr adi ngSchedul e tradingScheduleId yes null

St at eTr ansi t i on name no tradingScheduleId

SubscriptionGroup

A subscription group contains a collection of order books. When subscribingfor market data, subscriptions are setup using the identities of

Subscr i pt i onGr oups. The subscription group is the smallest unit for which it

is possible to enter a subscription. A Subscr i pt i onGr oupis also the smallestunit 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 Or der BookRul egroup may belong to differentsubscription groups and subscription group can contain order books fromseveral order book rule groups.

SubscriptionGroupsubscriptionGroupId: 432*

Figure 8 SubscriptionGroup.



Subscr i pt i onGr oup subscri pt i onGr oupI d 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.

TickSizeTabletickSizeTableId: 77*

di spl ayName: EUR

TickSizeTableRowlowerLimit: 100

tickSizeTableId: 77

Figure 9 TickSizeTable and TickSizeTableRow.




7/23/2019 EMAPI - Rev F

31/55

Restricted External


Ti ckSi zeTabl e t i ckSi zeTabl eI d yes null

Ti ckSi zeTabl eRow lowerLimit no t i ckSi zeTabl eI d

AllowedRequestsGroup

Defines allowed requests for a certain state transition. This makes it possibleto define state transition based filter governing which requests that areallowed.

AllowedRequestsGroupallowedRequestsGroupId: 89*

di spl ayName: PRE_OPEN_REQ

AllowedRequestsGroupRowrequest: cancelOrder

al l owedRequest sGr oupI d: 89

Figure 10 AllowedRequestsGroup and AllowedRequestsGroupRow.



Al l owedRequest sGr oup al l owedRequest sGr oupI d

yes null

Al l owedRequest sGr oupRow

request yes al l owedRequest sGr oupI d

Currency

Represents a currency.

CurrencycurrencyId: EUR*

Figure 11 Currency.



Curr ency currencyId yes null

DateCollention and CalendarDate

The Dat eCol l ecti onholds calendar information on CLOSEDand HALF_DAYtrading dates for the system. Each date type holds a set of dates and anoptional calendar Id for which dates the market(s) (all or a part of) shall applythe date type. The CLOSED/HALF_DAY information is used by the system toselect the appropriate trading schedule.



7/23/2019 EMAPI - Rev F

32/55

Restricted External

DateCollectiondateType: HALF_DAY*

di spl ayName: EUR

CalendarDatedateKey: 2008-09-09_CFT_CALENDAR

dateType: HALF_DAY

Figure 12 DateCollection and CalendarDate.



Dat eCol l ecti on dateType yes null

Cal endar Dat e dateKey yes dateType

OrderBookRuleGroupParameters

The Or derBookRul eGr oupParamet er sobject is referenced from the

Or der BookRul eGr oupand hold parameters that are common for one or many

Or derBookRul eGr oups.

OrderBookRuleGroupParametersparameterSetId: SYSTEM_DEFAULT

tradingScheduleId: 5

calendarId: CFT_CALENDAR

Figure 13 OrderBookRuleGroupParameters.



OrderBookRuleGroupParameters parameterSetId yes null

OrderBookParameters

The Or der BookParamet er sobject is referenced from the Or derBookand hold

parameters that are common for one or many Or derBook.

OrderBookParametersparameterSetId: SYSTEM_DEFAULT

Figure 14 OrderBookParameterse.



OrderBookParameters parameterSetId yes null

4.7 Markets and Instruments

The Market and Instrument related objects provide a navigation andmanagement 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 datamodel may not be present.



7/23/2019 EMAPI - Rev F

33/55

Restricted External

The relations between the two object domains can be viewed in the picturebelow.

MarketXCFT

MarketListL1

SegmentS1

1

n

1

n

1

n

1

n

1

1

n

n

Orderbook

OrderbookRuleGroup

1

Orderbook

n

1 1

n

n

Orderbook

OrderbookRuleGroup

1

Orderbook

nn

Orderbook

n

Orderbook

OrderbookRuleGroup

1

OrderbookRuleGroup

1

Orderbook

n

Orderbook

n

1

InstrumentERI C-B

1

TradableInstrumentERIC- B, EUR

n

TradableInstrumentERIC- B, EUR

n

TradableInstrumentERI C-B, SEK

n

TradableInstrumentERI C-B, SEK

n

11

OrderbookRoutingStrategy

TickSizeTable

TradingSchedule

1

1

1


TickSizeTable

TradingSchedule


TickSizeTable

TradingSchedule

1

1

1

Trading Data

Instruments and Markets

n 1

ViewXCFt100

ViewELementEI RC- B, EUR

1

n

1

n





Figure 15 Overview figure on how Markets and Instruments relates to OrderBooks and tradingrules.

The Market and Instrument objects are described below.

Market, MarketList and Segment

The Market, MarketLi st 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 organizationoperating the installation.

Instruments reference a Market as their primary market.

Tr adabl eI nst r umentsreferences a Segment.

On each level, a trading rule parameter block may be assigned. The assigned

trading parameters apply to allTr adabl eI nst r umentswithin theMarket/MarketList/Segment. It is the parameter block assigned on the

lowest level that is used. AllTr adabl eI nst r umentswithin a Segment share

the sameTr adi ngSchedul e.



7/23/2019 EMAPI - Rev F

34/55

Restricted External

MarketmarketId: XCFT*

orderBookParameterSetId:orderBookRuleGroupParameterSetId:

MarketListinternalMarketListId: XCFT_L1*

parentInternalId: XCFT

mar ket Li stI d: L1orderBookParameterSetId:orderBookRuleGroupParameterSetId:

SegmentinternalSegmentId: XCFT_L1_S1*

parentInternalId: XCFT_L1

segment I d: S1orderBookParameterSetId:orderBookRuleGroupParameterSetId:

1

n

1

n

1

n

1

n

Figure 16 Market, MarketList and Segment.


Object Key Attribute Unique Id parentReferenceAttribute

Mar ket marketId yes null

Mar ket Li st internalMarketListId yes parentInternalId

Segment internalSegmentId yes parentInternalId

Instrument and TradableInstruments

The Instrument hold basic background information for the instrument suchas:

pr i maryMarket , the marketplace where the instrument has its primarylisting. The referenced marketplace must be defines as a Market withinthe system.

i nst r ument and i nst r ument I dType. The combination of id and typeuniquely identifies an instrument within the system. The instrument idtype is typically one of ISIN, CUSIP or SYMB.

i nst r ument Type. The type of instrument, typically one of EQUI TY,

FUTURE, CALL_OPTI ON, PUT_OPTI ON, etc. The actual instrument typesare defined by the organization operating the trading system.

par ent I nst r ument . This may be a reference to a the id of an (optional)parent instrument for this instrument. For example, if this instrumentis a CALL_OPTION the parentInstsrument may reference the FUTUREinstrument 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 inTr adabl eI nst r ument child

object(s). One instrument may have severalTr adabl eI nst r ument (s) defined.

Also, theTr adabl eI nst r ument (s) need not belong to the same market as theprimary 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 thesame id), oneTr adabl eI nst r ument will be created for a Segment within the



7/23/2019 EMAPI - Rev F

35/55

Restricted External

XOME market and another TradableInstrument will be created for a Segmentwithin the LSE market.

ATr adabl eI nst r ument defines a tradable instance of an Instrument, which

means that aTr adabl eI nst r ument has a currency, lot size, and visibility

type. It is also assigned an Or derBookand a Subscr i pt i onGr oup. A

Tr adabl eI nst r ument references a Segment which means that the tradingrules that for the specified Segment applies to theTr adabl eI nst r ument .

Please note that one Instrument may have severalTradabl eI nst r uments,each allocated to a different Segment.

TradableInstrumentinternalId: SE0000108656_ISIN_SEK_XCFT_DARK*

parentInternalId: SE0000108656_ISINinternalSegmentId: XCFT_L1_S1t radabl eI nst r ument I d: SE0000108656

t radabl eI nst r ument I dType: I SI NmarketI d: XCFTmar ketLi st I d: L1segment I d: S1currencyId: SEK

order BookVi si bi l i t yType: DARKsubscriptionGroupId: 1orderBookId: 611

InstrumentinternalId: SE0000108656_ISIN*

instrumentId: SE0000108656i nst r umentI dType: I SI Ntype: EQUI TYparentI nt er nal I d: nul l

primaryMarketId: XCFTshor t Name: ERI C- B

n

1

Figure 17 Instruments and Tradable Instruments


Object Key Attribute UniqueId

parentReferenceAttribute

I nst r ument internalId yes null

Tr adabl eI nst r ument internalId yes parentInternalId

Views and ViewElements

A View object references a Market and represents a View of the

Tr adabl eI nst r umentson that Market. The View object is used to group

Tr adabl eI nst r umentscross MarketLists/Segments.

The Vi ewEl ement holds a reference to aTradabl eI nst r ument .



7/23/2019 EMAPI - Rev F

36/55

Restricted External

ViewviewId: XCFT100*

marketId: XCFT

ViewElementviewElementId: SE0000108656_ISIN

parentInternalId: XCFT100internalTradableInstrumentId: SE0000108656_ISIN_SEK_XCFT_DARK

1

n

1

n

Figure 18 The View and ViewElement. A View references one or many ViewElements which inturn has a reference to a TradableInstrument.


Object Key Attribute UniqueId

parentReferenceAttribute

Vi ew viewId yes null

Vi ewEl ement viewElementId yes parentInternalId



7/23/2019 EMAPI - Rev F

37/55

Restricted External

5

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 tobe unique within the system and over time. The id is provided both in theinteractive response when entering an order and in the private order events.

This id is used when managing the order and when building a private shadoworder book.

Public Order Id (publicOrderId)

In addition, each order is assigned a public order id by the system that isguaranteed to be unique within the system and over time. The id is providedboth in the public order events and in the private order events.

This id is used when building a public shadow order book and when acceptingorders.

5.1.2

Quotes

There are 4 identifiers associated with quotes.

Quote Replace Id (quoteReplaceId)

The Quot eI nsert Req message contains a quote replace id field that is

assigned by the user. Each quote in the QuoteI nser t Reqis assigned this quotereplace id.

This id is used when managing quotes as described below.

The quotes in a QuoteI nser t Reqwill replace any existing quotes for themember with the same quote replace id in the order books of the

QuoteI nser t Reqs quotes.

For an order book (specified in one or more quotes in the QuoteI nser t Req)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 QuoteI nser t Req.

2.

For each quote in the QuoteI nser t Reqs that is designated to the orderbook:

a. Primarily reuse an earlier collected quote on the same side of theorder book. The quotes properties will be updated to reflect the new

quote but the quotes orderBook, i sBi d, quoteRepl aceI d, quot eI d,

pr i vat eQuot eI dand publ i cMember 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 ofhow allowing members to design their quoting strategies.

Note: A QuoteI nser t Reqwill never affect any other order books than the

ones that are contained within the transaction.



7/23/2019 EMAPI - Rev F

38/55

Restricted External

Note: There are no explicit quote cancel operations. To cancel one or several

quotes with the same quoteRepl aceI din one or several order books a

Client sends in a QuoteI nser t Reqwith the quoteRepl aceI dspecifiedand with quotes with volume 0 in the concerned order books.

Client Defined Quote Id (clientDefinedQuoteId)

Each quote in a QuoteI nser t Reqis assigned a client defined quote id by theuser.

This id is used to map a private trade event to a quote. That is, any privatetrade 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 tobe unique within the system and over time. The id is provided in the privatequote 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 tobe unique within the system and over time. The id is provided both in thepublic 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 cancel OnLogout set to trueand all quotes are cancelledwhen the user, which last acted upon the item, does not have any livesessions on the Server (e.g. when sessions have been terminated due thatServers heartbeat time has expired (see section 2.3)).

Note: This independently if the owning user or if there are other users, thatmay act on-behalf of the owning user, do have live sessions in theServer.

5.3 Event Flows

Events on these flows are published on different subscription groups (see alsosection 3.1.2).

The events marked suffixed with (*) is not provided in a current value.

Flow CurrentValue/Replay

Description and messages sent

PRI VATE_ORDERBOOK_EVENT_FLOW CurrentValue &Replay

Private order book events.

ChatMessageEvent -Pri vat e( *)

MassUpdat eEvent -Pri vat e( *)

Or derEvent Pri vat e

QuoteEvent Pr i vat e

Request ForQuot eEvent -Pri vat e( *)

Wai t ForSSNEvent



7/23/2019 EMAPI - Rev F

39/55

Restricted External

Flow Current Description and messages sentValue/Replay

PUBLI C_ORDERBOOK_EVENT_FLOW CurrentValue &Replay

Public order book events.

Auct i onEvent

Chat MessageEvent ( *)

MarketByLevel Event

Or derBookStat eChange-Event

Or der Event

QuoteEvent

Request ForQuot eEvent ( *)

St ateFr eezeEvent

Wai t ForSSNEvent

MBL_L1_FLOW Current

Value

Public order book events but only

aggregated volumes at the bestbid/ask price.

Auct i onEvent

MarketByLevel Event


Wai t For SSNEvent

MBL_L2_FLOW CurrentValue

Public order book events but onlyaggregated volumes at the nbestbid/ask prices. Value nisconfigurable per TRADExpress

installation. Auct i onEvent

MarketByLevel Event


Wai t For SSNEvent

PUBLI C_PRI CELEVEL_FLOW CurrentValue

Public order book events but onlyaggregated volumes at the mbestbid/ask prices. Value misconfigurable per TRADExpressinstallation.

Auct i onEvent MarketByLevel Event


Wai t ForSSNEvent

PRI VATE_TRADE_FLOW Replay Private trade events.

Tr adeEventPr i vat e

Wai t For SSNEvent

PUBLI C_TRADE_FLOW Replay Public trade events.

Tr adeEvent

Wai t For SSNEvent



7/23/2019 EMAPI - Rev F

40/55

Restricted External

5.3.1

Information in Events

All events on these flows contain following information:

t i meOf Event : At what time the event occurred in TRADExpress.

sequenceI ndi cator : 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. orderinsert, state change etc.).

If set to truethe event is the last event in a sequence of events that

occurred at the same time. If set to f al sethe 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 onlyevent will have this field set to true.

N.B. It is configurable per TRADExpress installation if events on a certainpublic flow are visible as sequences. If events on a public flow aren'tvisible as sequences this field will not be set.

Note: Events that deliver the current value (see section 3.2.1) have non valid

t i meOf Event and sequenceI ndi cator .

Note: If any filtering is done (e.g. only subscribing to event relating to some

order books) the value of the sequenceI ndi cator can not be trusted.

Note: The sequenceI ndi cator is currently only supported to be configured

on market by level flows (e.g. PUBLI C_PRI CELEVEL_FLOW,

MBL_L1_FLOW, MBL_L2_FLOW).

5.4 Building a Public Shadow Order Book

A complete shadow order book contains information about the prices/volumesas well as order book state/trade halt information.

5.4.1

Relevant EMAPI MessagesThe following EMAPI messages needs to be honored when building publicshadow order books:

Or derEvent

The event type can be one of I NSERT, UPDATE, CANCEL.

QuoteEvent


MarketByLevel Event


Or derBookStat eChangeEvent

If the state event type is STATE_CHANGE_OB,

STATE_ CHANGE_OB_RULEGROUP or HALT_EVENTthen the eventprovides information about the order book state (Open, Closed etc.)and/or trade halt information.

Note that these state event types do not directly affect theorders/quotes in the shadow order book.

If the state event type is PUBLI C_ORDERBOOK_OBSOLETEthen allorders/quotes/aggregated price levels belonging to the specifiedorder book should be discarded. In other word allorders/quotes/aggregated price levels are to be removed from thepublic shadow order book.



7/23/2019 EMAPI - Rev F

41/55

Restricted External

Note that there are other state event types but these only providetransient information that need not to be applied to a shadow orderbook.

5.4.2

OrderEvent/QuoteEvent versus MarketByLevelEvent

The Or der Event / Quot eEvent messages are used to disseminate publicindividual order/quote information.

The Market ByLevel Event message is used to disseminate aggregatedorder/quote volumes per price level information.

On the PUBLI C_ORDERBOOK_EVENT_FLOWmay both Or der Event / Quot eEvent :s

and Market ByLevel Event :s be sent. Typically is either

Or der Event / Quot eEvent :s or Market ByLevel Event :s used for a given tradingsession (i.e. state), but this is dependent on the configuration of theTRADExpress installation

A common example where both Market ByLevel Event :s and

Or der Event / Quot eEvent :s are used on the same flow although for differenttrading session is a classical order driven market. Typical such a market starts

with a morning trading sessions where only Market ByLevel Event :s aredisseminated, once in continuous trading the individual

Or der Event / Quot eEvent :s are disseminated instead of the

Market ByLevel Event :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 theones described in section Public Order Id (publicOrderId) respectivelyQuote Id (quoteId).

Note: These identifiers are generated from the same source so a

publ i cOr der I d/quot eI dis unique when looking at both orders and

quotes.

Order/Quote Priority

Following orders/quotes properties is used, in the specified order, to decidethe 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 bookuses:

normal sorting then a higher price implies higher priority for a bidorder/quote and a lower price implies higher priority for an askorder/quote

reversed sorting then a lower price implies higher priority for a bidorder/quote and a higher price implies higher priority for an askorder/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 offollowing price level properties:

i sBi d

pr i ce

Note: I t i s guar ant eed t hat t he number of pr i ce l evel s wi l l never

exceed t he number of pr i ce l evel s appl i cabl e f or t he f l ow.E. g. i f t her e exi st s a pr i ce l evel on an or der book s buysi de and a new bet t er buy pr i ce l evel i s i nser t ed, t he f i r st



7/23/2019 EMAPI - Rev F

42/55

Restricted External

pr i ce l evel i s cancel ed on MBL_L1_FLOW ( onl y one pr i ce l eveli s appl i cabl e f or t hi s f l ow) bef or e t he bet t er pr i ce i si nser t ed.

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 forindividual 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 theprices/volumes.

5.5.1

Relevant EMAPI Messages

The following EMAPI messages needs to be honored when building privateshadow order books:

Or derEvent Pri vat e

The event type can be one of I NSERT, UPDATE, CANCEL

QuoteEvent Pr i vat e

The event type can be one of I NSERT, UPDATE, CANCEL

5.5.2

Order/Quote Key

The key to be used for orders/quotes in the public shadow order book are theones described in section Private Order Id (privateOrderId) respectivelyPrivate Quote Id (privateQuoteId).

Note: These identifiers are generated from the same source so a

pr i vat eOr der I d/pr i vat eQuot eI dis unique when looking at bothorders and quotes.

5.6 Order History

A private order event is tagged with the following attribute describing theorigin of an event.

Source of event, this is either USER or SYSTEM. USER indicates that thesource of the event is an explicit action taken by a user. SYSTEM indicatesthat 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 numberof SYSTEM events. This happens for example when a user by an explicitupdate make an order so generous so that its matches.

Event type, one of INSERT, UPDATE, CANCEL. These are the base orderevent types. The set of event types are unlikely to chan