LMAX TRADER

API
REFERENCE
GUIDE
Effective Date: 16 January 2011
Version: 1.2. Beta
T able of c ontents

Effective Date: 16 January 2011 ...............................................................................................................................0

Version: 1.2. Beta .....................................................................................................................................................0
Table of contents ..................................................................................................................................................1
Revision History ....................................................................................................................................................5
LMAX Trader API Reference Guide ...........................................................................................................................7
Effective date: 29 November 2010 .......................................................................................................................7
1. OVERVIEW ................................................................................................................................................7

1.1. INTERACTION MODEL ...........................................................................................................................7

1.2. COMMUNICATION MECHANICS ...........................................................................................................7

1.3. REQUEST HEADER PARAMETERS ..........................................................................................................8

1.4. MESSAGE STRUCTURE ..........................................................................................................................8

1.5. MAKING REQUESTS ..............................................................................................................................9

1.6. MESSAGE RESPONSES...........................................................................................................................9

1.7. EVENT BATCHES ....................................................................................................................................9

1.8. MAPPING BETWEEN JSON AND XML CONTENT .................................................................................11

2. API SERVICES REFERENCE .......................................................................................................................13

2.1. ENDPOINT URL....................................................................................................................................13

2.2. AUTHORISATION INFORMATION ........................................................................................................13

2.3. SESSION MANAGEMENT.....................................................................................................................14

2.3.1. Login ...............................................................................................................................................14

2.3.2. Logout .............................................................................................................................................15

2.3.3. GET longPollKey ..............................................................................................................................16

2.3.4. POST longPoll ..................................................................................................................................16

2.3.5. POST stream ...................................................................................................................................17

2.3.6. Heartbeat ........................................................................................................................................17

2.4. ORDER MANAGEMENT .......................................................................................................................18

1
2.4.1. Place Order .....................................................................................................................................18

2.4.1.1. Supported Order Types ..............................................................................................................20

2.4.2. Cancel Order ...................................................................................................................................21

2.5. MARKET DATA MANAGEMENT...........................................................................................................22

2.6. SUBSCRIPTION MANAGEMENT ..........................................................................................................22

2.6.1. Subscribe request ...........................................................................................................................23

2.6.2. Unsubscribe Request ......................................................................................................................24

2.7. PUSH EVENTS ......................................................................................................................................25

2.7.1. exchangeRate event .......................................................................................................................26

2.7.2. Account events ...............................................................................................................................26

2.7.2.1. accountState event .....................................................................................................................26

2.7.2.2. orderState event .........................................................................................................................27

2.7.2.2.1. Order Execution Update .............................................................................................................29

2.7.2.2.2. Order Cancellation Update .........................................................................................................29

2.7.2.3. position event .............................................................................................................................30

2.7.2.4. instructionRejected event ..........................................................................................................31

2.7.2.5. heartbeat event ..........................................................................................................................31

2.8. MARKET DATA EVENTS .......................................................................................................................32

2.8.1. orderbookStatus event ...................................................................................................................32

2.8.2. orderBook event .............................................................................................................................32

3. ERROR CODES .........................................................................................................................................35

3.1. AUTHORISATION FAILURE REASONS ..................................................................................................35

3.2. LOGIN FAILURE CODES .......................................................................................................................35

3.3. ORDER REJECTION REASONS ..............................................................................................................35

4. API SCHEMAS ..........................................................................................................................................37

4.1. userLogin-request ...............................................................................................................................37

4.2. userLogin-response ............................................................................................................................37

2
4.3. getLongPollKey-request ......................................................................................................................37

4.4. getLongPollKey-response ...................................................................................................................37

4.5. heartbeat-request ..............................................................................................................................38

4.6. heartbeat-response ............................................................................................................................38

4.7. logout-request ....................................................................................................................................38

4.8. logout-response ..................................................................................................................................38

4.9. placeOrder-request ............................................................................................................................38

4.10. placeOrder-response ......................................................................................................................39

4.11. cancelOrder-request .......................................................................................................................39

4.12. cancelOrder-response ....................................................................................................................40

4.13. subscribe-request ...........................................................................................................................40

4.14. subscribe-response .........................................................................................................................40

4.15. unsubscribe-request .......................................................................................................................40

4.16. unsubscribe-response.....................................................................................................................40

4.17. exchangeRate-event .......................................................................................................................41

4.18. accountState-event ........................................................................................................................41

4.19. orderState-event ............................................................................................................................41

4.20. position-event.................................................................................................................................44

4.21. instructionRejected-event ..............................................................................................................45

4.22. heartbeat-event ..............................................................................................................................46

4.23. orderBookStatus-event...................................................................................................................46

4.24. orderBook Event .............................................................................................................................46

4.25. public-datatypes .............................................................................................................................48

4.26. tfx-datatypes...................................................................................................................................49

4.27. tfx-request ......................................................................................................................................51

4.28. tfx-response ....................................................................................................................................51

4.29. enumerations .................................................................................................................................53

3
4.30. public-enumerations ......................................................................................................................53

4.31. primitives ........................................................................................................................................54

4
R evis ion His tory
Version Date Changes
1.0 - Draft 10/09/2010 Initial Draft

1.1 08/11/2010 Version 1.1 – Beta of LMAX Trader API for Beta API program.
1.1 30/11/2010 Corrected version of Version 1.1 – Beta of LMAX Trader
API for Beta API program.
Section 2.1 - Added the URL link to the test environment.
Sections 1.8, 2.3.1, 2.3.6, 2.4.1, 2.6.1 – Corrected Request
example to include <body> element
Section 2.7.1 – Corrected <to> and <from> elements to be
small script
Section 2.7.2.5 – Corrected event example to contain <type>
element
Section 2.3.3 – Corrected Description field for the
longPollKey element.
1.2 15/12/2010 Section 1.7 – Changed events parent <batch> element to
<events>;
Section 1.7 – Changed the structure of <PushEventType>
element referenced in the <events> element;
Section 1.7 – Updated events description to say: ”No events
will be resent if the connection was lost and re-established. In case
of disconnection the sequence number will be reset to 1. “The batch
body contains one or more events occurred between the last batch
sent and the current batch. The element name identifies the nature of
the event (for example orderCancelled, orderBookStatus, etc). Only
events that user has subscribed to will be listed”;
Section 1.7 – Updated <events> example to comply with the
current structure of the schema;
Section 2.3.1 – Added product type parameter for the test
environment login;
Section 2.4.1 – Removed <side> element from the schema;
Section 2.4.1 – Added text to the Supported Values column
of the <quantity> element;
Section 2.4.1 – Updated description to say: “When Execution
occurs in the event of matching – event of type orderState is
generated following the structure of the orderState message with the
execution element ;When Execution occurs in the event of order
cancelation – event of type orderState is generated following the
structure of the orderState message with the orderCancelled element
“
Section 2.4.1 –Updated Place market Sell Order request
example to comply with the current structure of the schema;
Section 2.4.1.1 –Updated GoodUntill Cancelled Limit Buy
Order request Example to comply with the current structure
of the schema;
Section 2.6.1 – Added orderBookStatus subscription
Section 2.7.1–Removed <sequenceNumber> element from
the exchangeRate event message schema;
Section 2.7.1–Updated Message Example to comply with
the current structure of the exchangeRate event message
schema;
Section 2.7.2.1–Removed <sequenceNumber> element from
the accountState event message schema;

5
 Section 2.7.2.1–Updated Message Example to comply with
the current structure of the accountState event schema;
Section 2.7.2.2–Replaced parent <orders> element from the
orderState event message schema with <order> element;
Section 2.7.2.2–Removed <side>, <stopLossCost>,
<stopBuffer> , < closedCost>, < closedQuantity >, <
realisedProfit >, <volumeWeightedAvgPrice> elements from
the orderState event message schema;
Section 2.7.2.2–Added < cumulativeCost> element to the
orderState event message schema;
Section 2.7.2.2–renamed <matched>, <openedCost>,
<openedQuantity>, <cancel>, element to <matchedQuantity<,
<openCost >, < openQuantity>, <cancelledQuantity >in the
orderState event message schema;
Section 2.7.2.2–Updated Message Example to comply with
the current structure of the orderState event schema;
Section 2.7.2.3–Replaced parent <positions> element from
the position event message schema with <position> element;
Section 2.7.2.3–Removed <sequenceNumber> element from
the position event message schema;
Section 2.7.1.3–Updated Message Example to comply with
the current structure of the position event message schema;
Section 2.7.1.4–Updated Message Example to comply with
the current structure of the instructionRejected event schema;
Section 2.7.1.5–Updated Message Example to comply with
the current structure of the heartbeat event message schema;
Section 2.8.1–Updated Message Example to comply with
the current structure of the orderBookStatus event message
schema;
Section 2.8.2–Updated Message Example to comply with
the current structure of the orderBook event message
schema;
Section 3.3–Removed UNKNOWN code from the list of order
rejection reasons
Section 4 – Added sections 4.1-4.31 (API Schemas)
1.3 07/01/2011 Corrected Effective Date

6
LMAX Trader API Reference
Guide
E ffec tive date: 29 November 2010
1. OVERVIEW

This document outlines the services that are available via the LMAX Application Programmers
Interface (API) 1.1 - Beta. This API is an easy-to-use, standards-based, programming-language-
independent interface to Web Services that enables access to the functionality of LMAX Trader by
programs and allows a program to perform transactions on the Exchange.
Please note that currently LMAX Trader API is in Beta stage and is subject to enhancements and
changes. This document provides description of the current API functionality and is likely to be
changed/enhanced to reflect any changes applied to the API .Any changes or additional functionality
due to be applied to the API will be published on LMAX Broker website in advance.

1.1. INTERACTION MODEL

The LMAX Trader API supports asynchronous event push behaviour where your application is notified
of relevant events as they occur.

If user would like to get updates for the particular events, he has to make a subscription request for
this event updates. A request will result in a response, and may be followed by one or more events
which occur asynchronously as a result of the original request, for example an order being placed may
be followed by a number of order state events as the unmatched order becomes matched.

A specific set of subscription requests is also provided to allow you to register interest in a number of
topics, such as market prices, which may generate events without any activity on user’s part.
Subscriptions remain enabled for the session or until explicitly disabled or session logout.

A typical client dialogue will progress through the following steps:

• Login
• Request a subscription: market data information, order book information, account state, executions
• Interact (e.g. place , cancel orders)
• Receive and respond to the events
• Logout

1.2. COMMUNICATION MECHANICS

The programming interface to the LMAX Trader API is implemented as a collection of messages sent
to a secure web server over HTTP. Messages can be sent in JSON and XML formats.

7
XML (Extensible Markup Language) is a set of rules for encoding documents in machine-readable
form. It is defined in the XML 1.0 Specification produced by the W3C, and several other related
specifications, all gratis open standards.

JSON (JavaScript Object Notation) is a lightweight data interchange format. JSON is easy to read
and write; you can parse it using any programming language, and its structures map directly to data
structures used in most programming languages.

The example mapping between XML and JSON is provided is section, however all the further
message examples in this document are given in XML format.

The LMAX Trader exposes a collection of operations that may be invoked upon it, and publishes a
collection of events that will be sent to clients to keep them informed of changes in their position and in
the state of their account.

The API is designed to be minimal, and to present concise and timely information in a clear, and easily
interpretable form.

The exchange is asynchronous in nature and so many of the calls do not return the data or result
requested. The response will come as an event on the asynchronous channel.

The asynchronous channel can work in one of two ways.

• Long Poll: suitable for JavaScript in browsers drawing down a batch of events as soon as they are
available.
• Streaming: uses chunked transfer encoding to send up batches of events to the API client as soon
as available.

1.3. REQUEST HEADER PARAMETERS

The content type of the message sent or requested must be set in the Content-Type HTTP Header.

• XML: Content-Type: text/xml - sending, and Accept: text/xml - accepting

• JSON: Content-Type: application/json – sending, Accept: application/json - accepting

1.4. MESSAGE STRUCTURE

Messages take one of three forms. Each message is one of a Request (<req>), a Response (<res>),
or an Event (<event>).

Requests are instructions sent to the Exchange, and are intended to invoke some behaviour within it.
Responses are messages sent in response to specific Requests. Every Request will have a matching
Response.

Events are messages sent directly to a client from the LMAX Trader. These messages will be sent in
response to some internal event within the exchange rather than directly in response to any specific
request. For example if a match occurs for your account within the exchange, due to some other
account holder placing orders, you will be informed of the change to your position asynchronously. If
the status of an instrument in which you have registered an interest changes, you will be informed.
To maximise throughput, events are pushed back to the client in batches. Each batch may contain
multiple events of more than one type.

8
 1.5. MAKING REQUESTS

The activity of the LMAX Trader that may be invoked by API clients is represented as a separate URI
which ends in a name that represents the action being invoked.

e.g. https://.... /public/login

Messages are based on a simple structure; requests are identified by a <req> block containing a
<body> which in-turn contains any relevant parameters for the message. This means that an empty
message will take the following form:

<req>
<body/>
</req>

1.6. MESSAGE RESPONSES

Message responses also have a common simple structure. They consist of a <res> block containing a
<header> and a <body>.

The <header> will contain the status of the message, whatever the nature of the request that invoked
this Response. This will be one of ‘OK’, ‘WARN’ or ‘ERROR’.

The <body> will contain data pertinent to the Requesting message, if there is any. If not an empty
<body> will be returned. This means that a minimal response message will take the form:

<res>
<header>
<status>OK</status>
</header>
<body/>
</res>

Example Response: Login (successful)

<res>
<header>
<status>OK</status>
</header>
<body>
<username>user9001</username>
<currency>GBP</currency>
<accountId>9001</accountId>
<AccountType>STANDARD_TRADER</AccountType>
<productType>CFD_LIVE</productType>
<fundingDisallowed>False</fundingDisallowed>
</body>
</res>

1.7. EVENT BATCHES

Each event batch has the same overall structure:

9
 <events>
<header>
<seq/>
</header>
</body>
</events>

The events batch header contains a contiguous sequence number which is incremented for every
events batch sent from LMAX to your application during a single session. Any gap in the sequence
indicates a missed message, and it is your responsibility to reinitiate any local state and subscriptions
if this occurs. No events will be resent if the connection was lost and re-established. In case of
disconnection the sequesnce number will be reset to 0.

The batch body contains one or more events occurred between the last batch sent and the current
batch. The element name identifies the nature of the event (for example orderCancelled,
orderBookStatus, etc). Only events that user has subscribed to will be listed.

Each event body within the events batch contains the full details of the event, which are documented
in the following sections. An example of a complete events batch with number of events listed is
shown below.

<events>
<header>
<seq>3</seq>
</header>
<body>
<accountState>
<accountId>10000</accountId>
<balance>1000.00000</balance>
<exposure>-50.00000</exposure>
<availableFunds>950.00000</availableFunds>
<availableToWithdraw>950.00000</availableToWithdraw>
<wallets>
<wallet>
<currency>USD</currency>
<balance> 1842080.1</balance>
</wallet>
<wallet>
<currency>JPY</currency>
<balance> 1042080.0</balance>
</wallet>
<wallet>
<currency>GBP</currency>
<balance> 142080.5</balance>
</wallet>
</wallets>
</accountState>

<orderBookStatus>
<id>4001</id>
<status>Opened</status>
</orderBookStatus>

<orderBookStatus>
<id>4008</id>

10
 <status>Opened</status>
</orderBookStatus>

<orderCancelled>
<id>4001</id>
<accountId>123</accountId>
<quantity>10</quantity>
</orderCancelled>

<position>
<page>
<position>
<accountId>100000</accountId>
<instrumentId>4008</instrumentId>
<valuation>-30366480</valuation>
<shortUnfilledCost>0</shortUnfilledCost>
<longUnfilledCost>0</longUnfilledCost>
<openQuantity>-603</openQuantity>
<cumulativeCost>-340039750</cumulativeCost>
<openCost>-465101250</openCost>
</position>
<position>
<accountId>100000</accountId>
<instrumentId>4001</instrumentId>
<valuation>-228558</valuation>
<shortUnfilledCost>0</shortUnfilledCost>
<longUnfilledCost>0</longUnfilledCost>
<openQuantity>-105</openQuantity>
<cumulativeCost>-1259650</cumulativeCost>
<openCost>-1259650</openCost>
</position>
</page>
<hasMoreResults>false</hasMoreResults>
<correlationId>0-0</correlationId>
</position>

</body>
</events>

1.8. MAPPING BETWEEN JSON AND XML CONTENT

The JSON message structure will have exactly the same content as the XML messages described
above. Below are the examples of the request and response message formatted using JSON.

Request Example

{
"req":[
{
"subscription":[
{
"orderBook":"100101"
}
],

11
 "subscription":[
{
"exchangeRate":[
{
"from":"EUR",
"to":"GBP"
}
]
}
],
"longPollKey":"1"
}
]
}
Response Example

{
"res": [
{
"$":"",
"header":[
{
"$":"",
"status":[
"OK"
]
}
],
"body":[
""
]
}
]
}

Examples of the same messages formatted in XML.

Request Example 1

<req>
<body>
<subscription>
<orderBook>4008</orderBook>
</subscription>
<subscription>
<orderBook>4007</orderBook>
</subscription>
</body>
</req>

Response Example 1

<res>
<header>
12
 <status>OK</status>
</header>
<body/>
</res>

Request Example 2

<req>
<body>
<subscription>
<exchangeRate>
<from>JPY</From>
<to>GBP</To>
</exchangeRate>
</subscription>
<subscription>
<exchangeRate>
<from>USD</From>
<to>GBP</To>
</exchangeRate>
</subscription>
</body>
</req>

Response Example 2

<res>
<header>
<status>OK</status>
</header>
<body/>
</res>

2. API SERVICES REFERENCE

This chapter contains descriptions of each of the methods supported by the LMAX Trader API.

2.1. ENDPOINT URL

The access point to LMAX API over HTTPS interface is:

Production environment: https://api.lmaxtrader.com/

Test environment: https://testapi.lmaxtrader.com/

2.2. AUTHORISATION INFORMATION

/public/* accessible without logging in

/secure/* must be authenticated to access

/secure/read/* read only access

/secure/trade/* access to trading functionality

13
 2.3. SESSION MANAGEMENT

2.3.1. Login

The login establishes a session-level login that will remain active while messages are being
exchanged and that will timeout if traffic ceases for a prolonged period.
Responses to the Request message will either indicate a successful login or failure to login with no
details of the nature of the failure.
A successful login will authenticate the session so that subsequent requests with the JSESSIONID
cookie set will be identified as this user. The client must submit the session id with each request.
URI: public/security/login

Request

Supported
Element Required Description
values
username Yes Valid user name
password Yes Valid password
CFD_LIVE(live
environment
only)
productType Yes Type of the product for the user
CFD_DEMO(test
environment
only)

Request Example

<req>
<body>
<username>user9001</username>
<productType>CFD_LIVE</productType>
<password>password</password>
</body>
</req>
Please note: The order of the elements in the Login call is not important.

Response

Element Description

status The status of the request, eg. OK (successful) , WARN ( Unsuccessful),

ERROR(System error occurred)
username Logged in user's username.
currency Logged in user's currency
accountID Logged in user's account id.
accountType Type of the account

14
FundingDisallowed true or false
productType Type of the product
Sent in case when login fails. Please see Login Failure Codes section
failureType
for more details.

Response Example

<res>
<header>
<status>OK</status>
</header>
<body>
<username>user9001</username>
<currency>GBP</currency>
<accountId>9001</accountId>
<AccountType>STANDARD_TRADER</AccountType>
<productType>CFD_LIVE</productType>
<fundingDisallowed>False</fundingDisallowed>
</body>
</res>

2.3.2. Logout

Ending a session logs the user out of the LMAX Trader. It is recommended that you explicitly call the
API Logout service when your application shuts down.
Logout takes no parameters and will deactivate the current session.

URI: public/security/logout

Request

Element Required Description

none

Request Example

<req>
<body/>
</req>

Response

Element Description

The status of the request, eg. OK (successful) , WARN ( Unsuccessful),

status
ERROR(System error occurred)

Response Example

15
 <res>
<header>
<status>OK</status>
</header>
<body/>
</res>

2.3.3. GET longPollKey

URI: secure/longPollKey

Request

Element Required Description

none

Response

Element Description

longPollKey longPollkey that must be submitted in the Request header of all the
longPoll calls to the API throughout current session.

Response Example

<res>
<header>
<status>OK</status>
</header>
<body>
<longPollKey>0</longPollKey>
</body>
</res>
2.3.4. POST longPoll

longPoll call will result in an asynchronous batch response that contains the event updates for the
period between the previous response to a longPoll call and the time when the last longPoll request
received.

URI: push/longPoll

Request

Element Required Description

none

16
2.3.5. POST stream

Stream call will enable a single persistent connection that allows a server to push all real time updates
to a client, without the client explicitly requesting it. These events are incrementally handled and
interpreted on the client side every time the server sends a new event, with neither side closing the
connection.

URI: push/stream

Request

Element Required Description

none
2.3.6. Heartbeat

If a user wishes to maintain a logged-in session his software should send messages regularly to keep
the session alive. Whenever the application calls the API, the timer is reset. Any message activity is
sufficient, however the heartbeat request is provided specifically to be used when your application
generates no ‘natural’ activity.

The system does not send heartbeat events automatically; it will only respond to the users heartbeat
requests. The heartbeat returns a synchronous response and echoes a heartbeat event, which serves
to maintain the socket connection on the asynchronous push channel. The heartbeat also includes a
client token which allows the client application to match responses to requests in an asynchronous
fashion.

User needs to subscribe to the heartbeat events prior to sending a HTTP heartbeat request with the
string token. If a user is subscribed to heartbeat events, the same string token will be returned via a
heartbeat event in the event channel (i.e. event pushed to the user using either long poll or stream).

The LMAX Trader does not perform any uniqueness checking or de-duplication of tokens.
An event of type heartbeat will be emitted every time the system registers a heartbeat request as valid
account activity. The same message structure applies to the body of the event.

URI: secure/read/heartbeat

Request

Supported
Element Required Type Description
values
token Yes

Request Example

<req>
<body>
<token>ABC123</token>
</body>
</req>

17
Response

Element Description

status The status of the request, eg. OK (successful) , WARN ( Unsuccessful),

ERROR(System error occurred)

Response Example

<res>
<header>
<status>OK</status>
</header>
<body>
<heartbeat>
<accountId>10209</accountId>
<token>ABC123</token>
</heartbeat>
</body>
</res>

2.4. ORDER MANAGEMENT

2.4.1. Place Order

Clients can request new orders for execution on the LMAX MTF. In response the LMAX Trader will
indicate that that order has been successfully received, and will return an identifier unique to that
order.

Order placement will result in a sequence of one or more of the following asynchronous events being
sent from the exchange over the lifetime of the order. Not every order will generate the same events –
for example an unmatched order that would (but is yet to) reduce the exposure of a matched position
will not generate an accountState event.

• When position change occurs – event of type position is generated following the structure of the
position message
• When Execution occurs in the event of matching – event of type orderState is generated
following the structure of the orderState message with the execution element
• When Execution occurs in the event of order cancelation – event of type orderState is
generated following the structure of the orderState message with the orderCancelled
element
• When account state change occurs – event of type accountState is generated following the
structure of the accountState message
• When order book change for an instrument occurs – event of type orderBook is generated
following the structure of the orderBook message

An event of type order will be emitted every time a match occurs. The message structure that applies
to the body of the event is described below.

URI: secure/trade/placeOrder

18
Request

Supported
Element Required Description
Values
order Request type

instrumentId Yes The LMAX instrument in which the order is

to be placed

price Yes The least favourable per-unit price at which

the order should match.
Not if
Market

quantity Yes If quantity is Requested quantity for the order.

negative
number –
sell order

If quantity is
positive
number –
buy order

stopLossOffset No Stop loss offset

stopProfitOffset No Stop profit offset

goodUntil No Immediate Specifies the lifespan of the order. Valid

values are as follows:
Cancelled
 Immediate – the order completes
immediately (Market and Limit order
type)
 Cancelled – the order is open until
explicitly cancelled (Limit Order type)

allowUnmatched No false Specifies whether the order must be

matched in full (false) or can be partially
true matched (true). Must be specified if
goodUntil is specified.

Response

Element Description

status The status of the request, eg. OK (successful) , WARN ( Unsuccessful),

ERROR(System error occurred)
instructionId The unique identifier of the instruction for the order placed.

19
Place Market Sell Order request example

<req>
<body>
<order>
<instrumentId>4003</instrumentId>
<quantity>-1</quantity>
<goodUntil>Immediate</goodUntil>
<allowUnmatched>true</allowUnmatched>
</order>
</body>
</req>

Place Market Order response example

<res>
<header>
<status>OK</status>
</header>
<body>
<instructionId>330055</instructionId>
</body>
</res>

2.4.1.1. Supported Order Types

• Market Order
• Limit order

> Until Cancelled

> Fill or Kill
> Immediate or Cancel

Order Type Good Allow Description

Until Unmatched
Until Cancelled Cancelled True The order is good until cancelled. This is the
default if good until and allow unmatched are
not specified.
Fill or Kill Immediate False If the order is not filled completely then the
order is rejected with a reason code of
INSUFFICIENT_LIQUIDITY
Immediate or Cancel Immediate True If the order is not filled immediately the
remaining unmatched portion is cancelled.

Good Until Cancelled Limit Buy Order Request Example

<req>
<body>
<order>
<instrumentId>4008</instrumentId>
20
 <price>1.0</price>
<quantity>100</quantity>
<stopLossOffset>0.1</stopLossOffset>
<stopProfitOffset>0.1</stopProfitOffset>
<goodUntil>Cancelled</quantity>
<allowUnmatched>true</allowUnmatched>
</order>
</body>
</req>

Good Until Cancelled Limit Order Response Example

<res>
<header>
<status>OK</status>
</header>
<body>
<instructionId>260048</instructionId>
</body>
</res>

2.4.2. Cancel Order

This request allows the unmatched portion of one or more previously placed orders to be cancelled
either individually, by instrument or across all positions for the account.

Fully cancelled orders (i.e. orders cancelled before any matches occurred) are NOT returned by the
cancel request.

Cancelling an order will cause a position change, indicated by an event of type position following the
structure of the position message and may cause a change to available balance, indicated by an
event of type accountState following the structure of the accountState message

Also, orderBook event update will be generated if the cancelation of the order resulted in any
changes to the order book.

URL: secure/trade/cancel

Request

Element Required Description

instrumentId No The id of the LMAX instrument for which to cancel

orders.

originalInstructionId No The id of the original order to be cancelled.

Note: If instrumentId, originalInstructionId are not specified ALL unmatched order

quantities for the account will be cancelled.

Request Example

21
<req>
<body>
<instrumentId>4008</instrumentId>
<originalInstructionId>260048</originalInstructionId>
</body>
</req>

Request Example all orders

<req>
<body/>
</req>

Response

Element Description

status The status of the request, eg. OK (successful) , WARN ( Unsuccessful),

ERROR(System error occurred)
instructionId The ID of the cancelled order

Response Example

<res>
<header>
<status>OK</status>
</header>
<body>
<instructionID>260048</instructionID>
</body>
</res>

2.5. MARKET DATA MANAGEMENT

In order to actively monitor market events user can subscribe to the state and/or price changes for any
instrument meeting their criteria.

Please see the Subscription Management and Push Events chapters for the details of different
subscription options and corresponding events.

2.6. SUBSCRIPTION MANAGEMENT

The Subscribe message allows the client to subscribe to a variety of events. Each request contains
one or more subscription elements. Subscriptions are NOT hierarchical, so subscriptions to an
underlying category are to changes to that category node only, not to the addition, removal or
amendments of its children.

You can subscribe to the following events:

• Account State Changes

• Position Changes

22
• Order Executions
• Exchange Rates
• Order Book events (e.g. price updates)
• Order Book Status (e.g. New, Closed, Suspended)

2.6.1. Subscribe request

The generic subscription request is described below. In order to subscribe for a particular update the
user must include the corresponding elements or specify the type of the subscription.

URI: secure/subscribe

Request

Element Required Supported Values Description

longPollKey Yes- if minLength = 1 Long Poll Key

using
maxLength = 20
longPoll

No – if
using
Streaming

subscription Yes One or more subscriptions.

orderBook No Positive non-zero long type Subscribe to the price changes

unique identifier of the for the instrument(s) specified.
instrument whose price
events are required.

orderBookStatus No Positive non-zero long type Subscribe to order book status

unique identifier of the changes
instrument whose price
events are required.

exchangeRate No The “From” and “To” Subscribe for the Exchange

currencies. "pattern">[A-Z]{3} Rates for particular “From” and
“To” currency.

type No account Subscribe to all events of the

specified type across all
instruments: account state, order
state, positions.

Note: one and only one of each presented above elements must be specified per subscription
element.

Request OrderBook Example

23
<req>
<body>
<subscription>
<orderBook>4001</orderBook>
</subscription>
<subscription>
<orderBook>4008</orderBook>
</subscription>
</body>
</req>

Request Account Changes Example

<req>
<body>
<subscription>
<type>account</type>
</subscription>
</body>
</req>

Request Exchange Rates Example

<req>
<body>
<subscription>
<exchangeRate>
<from>USD</from>
<to>GBP</to>
</exchangeRate>
</subscription>
</body>
</req>

Response

Element Description

status The status of the request, eg. OK (successful) , WARN ( Unsuccessful),

ERROR(System error occurred)

Response Example

<res>
<header>
<status>OK</status>
</header>
<body/>
</res>

2.6.2. Unsubscribe Request

The unsubscribe request is the inverse of a subscribe request. Once received LMAX Trader will stop
24
sending events for the subscription topic. Request and response messages are identical to the
subscribe request.

URL: secure/unsubscribe

2.7. PUSH EVENTS

Subscription Event Type Description

type = account accountState Asynchronous This event occurs when there is a

change to the trading partner’s
Snapshot + account current balances and
Updates exposure. It will generate an
update on the current state of the
account state.

orderBook orderBook Asynchronous It will generate a snapshot of the

current prices available on a
Snapshot specified instrument This event
upon signals the change in the current
request+ prices available on a specified
Updates instrument.

exchangeRate exchangeRate Asynchronous This event signals the change to

Snapshot + the exchange rate for a particular
Updates currency. It will generate the buy
and sell exchange rate update for
the selected currencies.

type = account position Asynchronous Occurs every time any of the

Snapshot positions details change for a
upon specified instrument, for example
request+ in response to a trading partner
Updates placing orders or matching with
counter orders in the LMAX
Trader.

orderBookStatus orderBookStatus Asynchronous An event signalling a change in an

Snapshot + instrument's status. Eg. New,
Updates Close, suspended

type = account instructionRejected Asynchronous An event signalling that an order

Updates has been rejected.

type = account heartbeat Asynchronous Heartbeat event for streaming

Updates

type = account orderState Asynchronous An event signalling any order

Snapshot + changes resulting from order
placement, order matching or order

25
 Updates cancelation.

2.7.1. exchangeRate event

An initial snapshot message exchangeRate with current exchange rates will be submitted after the
subscription request was made, followed by an event of type exchangeRate will be emitted every
time exchange rate updated. The same message structure applies to the body of the event.

Message

Element Description

exchangeRate Name of the event

from The currency to convert from
to The currency to convert to
buy Buy rate
sell Sell rate

Message Example

<exchangeRate>
<from>EUR</from>
<to>GBP</to>
<buy>1.24</buy>
<sell>1.23</sell>
</exchangeRate>

2.7.2. Account events

2.7.2.1. accountState event

This message will contain the trading partner’s current balances and exposure.

If an account has open or working orders then the message with the initial snapshot of the account
state will be published followed by an event of type accountState every time any of the balance
details change.

The same message structure applies to the body of the event.

Message

Element Description

accountState The name of the event.

accountID The unique identifier of the account.
balance The current balance of the account
availableFunds The funds in the account available for trading

26
 availableToWithdraw The funds in the account available to withdraw
wallets Zero or more wallets

wallet

currency The currency of the wallet

balance Current balance in the wallet

Message Example

<accountState>
<accountId>10000</accountId>
<balance>1000.00000</balance>
<availableFunds>950.00000</availableFunds>
<availableToWithdraw>950.00000</availableToWithdraw>
<wallets>
<wallet>
<currency>USD</currency>
<balance>1842080.1</balance>
</wallet>
<wallet>
<currency>JPY</currency>
<balance>1042080.0</balance>
</wallet>
<wallet>
<currency>GBP</currency>
<balance>142080.5</balance>
</wallet>
</wallets>
</accountState>

2.7.2.2. orderState event

orderState message is sent in the result of orderState event generated by any order changes
resulting from order placement, order matching or order cancelation.

Element Description

order An order
page Orders State page
order 0 or more orders
instructionId Auto generated Instruction ID or 0.
orderId Order ID
accountId The id of the account.
instrumentId The unique LMAX id for the instrument associated with this
execution report

27
 quantity Quantity of the order; positive for Buy order, negative for Sell
order
price Price of the order
matchedQuantity The portion of the order matched
cancelledQuantity The portion of the order cancelled
timestamp The time of the instruction
orderType MARKET, PRICE_LIMIT,
STOP_COMPOUND_PRICE_LIMIT
openQuantity signed opened quantity + signed close quantity
openingOrderId Opening Order ID
openCost Cumulative cost + signed profit accrued as a result of this
trade. Negative values indicate a loss.
cumulativeCost Signed opened cost + signed closed cost
commission commission
stopReferencePrice Stop reference type
stopLossOffset Stop loss offset
stopProfitOffset Stop profit offset
executions Execution report for all matches if any occurred
executionId An id for this execution, unique for the instrument, 0 or more
executions.

execution A record for each execution

price The price at which the match was executed.

quantity The quantity matched.

realisedProfit The profit that this execution realised for the overall position
on the instrument.

orderCancelled A cancelled quantity at a price point

quantity

hasMoreresults Indicates whether there is another page to come (true or fault)

correlationId Correlation id for the position update event.

28
Message Example

<order>
<accountId>100000</accountId>
<cancelledQuantity>0</cancelledQuantity>
<commission>1</commission>
<executions>
<executionId>12200642</executionId>
<execution>
<price>1205.5</price>
<quantity>-1</quantity>
</execution>
</executions>
<instructionId>330043</instructionId>
<instrumentId>1002</instrumentId>
<matchedQuantity>-1</matchedQuantity>
<openCost>-12055</openedCost>
<openQuantity>-1</openedQuantity>
<cumulativeCost>"-12055</cumulativeCost>
<orderId>AAAPowAAAAAAXT38</orderId>
<orderType>STOP_COMPOUND_MARKET</orderType>
<quantity>-1</quantity>
<stopLossOffset/>
<stopProfitOffset/>
<stopReferencePrice>1205.5</stopReferencePrice>
<timestamp>2010-11-01T09:57:07</timestamp>
</order>

2.7.2.2.1. Order Execution Update

Each execution represents one or more matches on the LMAX MTF that is related to an order placed
by the account holder. All matches of the same order at the same time and price are summarised in a
single execution and sent as part of the Order Update Message.

Message Example

<executions>
<executionId>12200642</executionId>
<execution>
<price>1.099</price>
<quantity>-5</quantity>
</execution>
</executions>

2.7.2.2.2. Order Cancellation Update

Each orderCancelled represents a cancelation of an order placed by the account holder.

Order Cancelled event example

<executions>
<executionId>3</executionId>
<orderCancelled>
29
 <quantity>4</quantity>
</orderCancelled>
</executions>

2.7.2.3. position event

This message will contain the details of an account holder’s current position in a specified instrument.
In order to get the snapshot of the initial snapshot of the positions the user must explicitly request it
after the subscription request is made.
The subsequent events of type accountPosition will be emitted every time any of the positions
details change, for example in response to a trading partner placing orders or matching with counter
orders in the exchange. The same message structure applies to the body of the event.
Message

Element Description

position
page Positions page
position The position for a specific instrument.
accountId The account holding this position.
instrumentId The id of the Instrument for which this is a report of position.
The current total valuation on this instrument (matched and
valuation
unmatched).
shortUnfilledCost The short unfilled cost
longUnfilledCost The long unfilled cost
openQuantity Open Quantity = Long Quantity - Short Quantity
cumulativeCost Cumulative Cost = Long Cost - Short Cost
openCost Open Cost = Cumulative Cost - Realised Profit
hasMoreResults Indicates whether there will be more updates to come
correlationId Correlation ID for the update

Message Example

<position>
<page>
<position>
<accountId>100000</accountId>
<instrumentId>4008</instrumentId>
<valuation>-30366480</valuation>
<shortUnfilledCost>0</shortUnfilledCost>
<longUnfilledCost>0</longUnfilledCost>
<openQuantity>-603</openQuantity>
<cumulativeCost>-340039750</cumulativeCost>
<openCost>-465101250</openCost>
</position>
<position>

30
 <accountId>100000</accountId>
<instrumentId>4001</instrumentId>
<valuation>-228558</valuation>
<shortUnfilledCost>0</shortUnfilledCost>
<longUnfilledCost>0</longUnfilledCost>
<openQuantity>-105</openQuantity>
<cumulativeCost>-1259650</cumulativeCost>
<openCost>-1259650</openCost>
</position>
</page>
<hasMoreResults>false</hasMoreResults>
<correlationId>0-0</correlationId>
</position>

2.7.2.4. instructionRejected event

Response

Element Description

instructionRejected The status of the request, eg. OK (successful) , WARN ( Unsuccessful),

ERROR(System error occurred)
instructionId The unique instruction id of the order.
accountId The unique identifier of the account that placed the order.
instrumentId The unique identifier of the instrument upon which the order was
placed.
reason The reason code for the rejection.

Example

<instructionRejected>
<accountId>10000</accountId>
<instrumentId>4008</instrumentId>
<instructionId>260048</instructionId>
<reason>TEMPORARY_SUSPENSION</reason>
</instructionRejected>

2.7.2.5. heartbeat event

Response

Element Description

accountId The unique identifier of the account that placed the order.
token

31
Example

<heartbeat>
<accountId>10000</accountId>
<token>4008</token>
</heartbeat>

2.8. MARKET DATA EVENTS

2.8.1. orderbookStatus event

On initial subscription to an Order Books status you will be pushed the current status of the Order
Book, followed by the order book status updates as they occur.
Message

Element Description

orderBookStatus Name of the event

id The unique identifier for the instrument the prices relate to

status Instrument status (New, Closed, Suspended, Opened)

Example

<orderBookStatus>
<id>4008</id>
<status>Opened</status>
</orderBookStatus>

2.8.2. orderBook event

On subscription the price updates of Order Book prices will be pushed. In order to receive the initial
snapshot of the orders, user must explicitly request it after the subscription request is made.
Please see the orderBook event message and examples below.

Message

Element Description

32
orderBook Name of the event

instrumentId The unique identifier for the instrument the prices relate to

bids Zero or more bids. The bid prices, in descending order of best to
worst.

pricePoint Price and quantity of the instrument.

price Price of the instrument.

quantity Quantity of the instrument.

offers Zero or more offers. The offer prices, in descending order of best to
worst.

pricePoint Price and quantity of the instrument.

price Price of the instrument.

quantity Quantity of the instrument.

lastMarketClosePrices Last market close prices

price Last Market close price

timestamp timestamp

dailyHighestTradedPrice Highest traded price for the trading day

dailyLowestTradedPrice Lowest traded price for the trading day

valuationBidPrice Valuation bid price

valuationAskPrice Valuation ask price

lastTradedPrice Last traded price

Example

<orderBook>
<instrumentId>4003</instrumentId>
<bids>
<pricePoint>
<price>1.09900</price>
<quantity>95</quantity>
</pricePoint>
</bids>
<offers>
<pricePoint>
<price>1.10100</price>
<quantity>99</quantity>
</pricePoint>
33
 </offers>
<lastMarketClosePrice>
<price>0.88697</price>
<timestamp>2010-10-29T21:00:00</timestamp>
</lastMarketClosePrice>
<dailyHighestTradedPrice>1.10100</dailyHighestTradedPrice>
<dailyLowestTradedPrice>1.09900</dailyLowestTradedPrice>
<valuationBidPrice>1.09900</valuationBidPrice>
<valuationAskPrice>1.10100</valuationAskPrice>
<lastTradedPrice>1.10100</lastTradedPrice>
</orderBook>

34
3. ERROR CODES

3.1. AUTHORISATION FAILURE REASONS

Code Description

UNAUTHORISED Access unauthorised

UNAUTHENTICATED Unauthenticated user

SESSION_EXPIRED Session expired

3.2. LOGIN FAILURE CODES

Code Description

ACCOUNT_CLOSED Account is closed

ACCOUNT_LOCKED Account is locked

ACCOUNT_SUSPENDED Account is suspended

BAD_CREDENTIALS Bad credentials used

TEMPORARY_SYSTEM_ERROR Temporary system error

SERVICE_UNAVAILABLE Service unavailable

3.3. ORDER REJECTION REASONS

Code Description

INSTRUMENT_DOES_NOT_EXIST The instrument on which the order was placed doesn’t exist.

INSTRUMENT_NOT_OPEN The instrument on which the order was placed is not currently
open for trading.
PRICE_NOT_VALID The price specified on the order was invalid. Typically outside
the range or precision acceptable to the instrument.
DUPLICATE_ORDER Specified instruction id is a duplicate
The quantity specified on the order was invalid. Typically
QUANTITY_NOT_VALID outside the range or number of decimal places acceptable to
the instrument.
EXPOSURE_CHECK_FAILURE The funds available to the account are not sufficient to place
this order.
INTERNAL An internal system error prevented the order being accepted.

UNKNOWN_ORDER The instruction relates to an order that does not exist or has
been closed.
ORDER_TYPE_INVALID The combination of Good Until and Allow Unmatched were
invalid.

35
SERVICE_UNAVAILABLE service is temporarily unavailable
NO_QUANTITY_TO_CANCEL There is no remaining working quantity to cancel
ALREADY_CANCELLED The order has been previously cancelled
ACCESS_DENIED The user is not allowed to submit this instruction

OUTSIDE_ALLOWED_PRICE_RANGE The order price is invalid; too far away from current market
price
STOP_LOSS_OFFSET_INVALID stop loss price offset was invalid
STOP_PROFIT_OFFSET_INVALID profit target price offset was invalid
TEMPORARY_SUSPENSION the market is temporarily suspended

36
4. API SCHEMAS

4.1. userLogin-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-request.rng">
<define name="RequestBody">
<interleave>
<element name="username">
<ref name="UsernameType"/>
</element>
<element name="password">
<ref name="LoginAttemptPasswordType"/>
</element>
<element name="productType">
<ref name="ProductType"/>
</element>
<optional>
<element name="newPassword">
<ref name="PasswordType"/>
</element>
</optional>
</interleave>
</define>
</include>
</grammar>

4.2. userLogin-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-response.rng">
<define name="ResponseBody">
<choice>
<ref name="ValidLoginResponseType"/>
<element name="failureType">
<ref name="LoginFailureEnum"/>
</element>
</choice>
</define>
</include>
</grammar>

4.3. getLongPollKey-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../common/tfx-request.rng"/>
</grammar>

4.4. getLongPollKey-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-response.rng">
<define name="ResponseBody">
<element name="longPollKey">
37
 <ref name="LongPollKeyType"/>
</element>
</define>
</include>
</grammar>

4.5. heartbeat-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../common/tfx-request.rng">
<define name="RequestBody">
<element name="token">
<text/>
</element>
</define>
</include>
</grammar>

4.6. heartbeat-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../common/tfx-response.rng">
<define name="ResponseBody">
<element name="token">
<text/>
</element>
</define>
</include>
</grammar>

4.7. logout-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../common/tfx-request.rng"/>
</grammar>

4.8. logout-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../common/tfx-response.rng"/>
</grammar>

4.9. placeOrder-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<!-- A request to place a single order. -->
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-request.rng">
<define name="RequestBody">
<element name="order">
<interleave>
<element name="instrumentId">
<ref name="InstrumentIdType"/>
</element>
<element name="quantity">
<ref name="QuantityType"/>
</element>

38
 <optional>
<element name="stopLossOffset">
<ref name="StopOffsetType"/>
</element>
</optional>
<optional>
<element name="stopProfitOffset">
<ref name="StopOffsetType"/>
</element>
</optional>
<optional>
<element name="allowUnmatched">
<ref name="BooleanType"/>
</element>
</optional>
<optional>
<element name="price">
<ref name="PriceType"/>
</element>
</optional>
<optional>
<element name="goodUntil">
<ref name="GoodUntilEnum"/>
</element>
</optional>
</interleave>
</element>
</define>
</include>

4.10. placeOrder-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<!-- The response when an order is placed. -->
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-response.rng">
<define name="ResponseBody">
<optional>
<!-- The unique identifier of the instruction for the order placed. -->
<element name="instructionId">
<ref name="InstructionIdType"/>
</element>
</optional>
</define>
</include>
</grammar>

4.11. cancelOrder-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<!-- A request to cancel all orders on an instrument. -->
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-request.rng">
<define name="RequestBody">
<interleave>
<element name="instrumentId">
<ref name="InstrumentIdType"/>
</element>
<element name="originalInstructionId">
<ref name="InstructionIdType"/>
</element>
</interleave>
</define>

39
 </include>
</grammar>

4.12. cancelOrder-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-response.rng">
<define name="ResponseBody">
<optional>
<element name="instructionId">
<ref name="InstructionIdType"/>
</element>
</optional>
</define>
</include>
</grammar>

4.13. subscribe-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-request.rng">
<define name="RequestBody">
<oneOrMore>
<ref name="Subscription"/>
</oneOrMore>
</define>
</include>
</grammar>

4.14. subscribe-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../common/tfx-response.rng"/>
</grammar>

4.15. unsubscribe-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../public/public-datatypes.rng"/>
<include href="../common/tfx-request.rng">
<define name="RequestBody">
<oneOrMore>
<ref name="Subscription"/>
</oneOrMore>
</define>
</include>
</grammar>

4.16. unsubscribe-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="../common/tfx-response.rng"/>
</grammar>

40
 4.17. exchangeRate-event
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="public-datatypes.rng"/>
<start>
<element name="exchangeRate">
<interleave>
<element name="from">
<ref name="CurrencyType"/>
</element>
<element name="to">
<ref name="CurrencyType"/>
</element>
<element name="buy">
<ref name="PriceType"/>
</element>
<element name="sell">
<ref name="PriceType"/>
</element>
</interleave>
</element>
</start>
</grammar>

4.18. accountState-event
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="tfx-datatypes.rng"/>
<start>
<element name="accountState">
<ref name="AccountStateType"/>
</element>
</start>
</grammar>

4.19. orderState-event
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<include href="public-datatypes.rng"/>
<start>
<element name="order">
<choice>
<ref name="OrderStateType"/>
<ref name="OrderStatePageType"/>
</choice>
</element>
</start>

<define name="OrderStatePageType">
<element name="page">
<zeroOrMore>
<element name="order">
<ref name="OrderStateType"/>
</element>
</zeroOrMore>
</element>
<element name="hasMoreResults">
<ref name="BooleanType"/>
</element>
<element name="correlationId">
<ref name="NonEmptyStringType"/>
41
 </element>
</define>

<define name="OrderStateType">
<interleave>
<choice>
<element name="instructionId">
<ref name="InstructionIdType"/>
</element>
<element name="instructionId">
<value>0</value>
</element>
</choice>
<element name="orderId">
<ref name="OrderIdType"/>
</element>
<!--The id of the account.-->
<element name="accountId">
<ref name="AccountIdType"/>
</element>
<!--The id of the instrument.-->
<element name="instrumentId">
<ref name="InstrumentIdType"/>
</element>
<choice>
<group>
<element name="quantity">
<ref name="QuantityType"/>
</element>
</group>
<group>
<element name="price">
<ref name="PriceType"/>
</element>
<element name="quantity">
<ref name="QuantityType"/>
</element>
</group>
</choice>
<!--The portion of the order matched.-->
<element name="matchedQuantity">
<ref name="QuantityType"/>
</element>
<!--The portion of the order cancelled.-->
<element name="cancelledQuantity">
<ref name="QuantityType"/>
</element>
<optional>
<interleave>
<element name="stopReferencePrice">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>
<element name="stopLossOffset">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>
<element name="stopProfitOffset">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>

42
 </interleave>
</optional>
<element name="timestamp">
<ref name="DateTimeType"/>
</element>
<element name="orderType">
<ref name="OrderTypeEnum"/>
</element>
<element name="openQuantity">
<ref name="QuantityType"/>
</element>
<optional>
<element name="openingOrderId">
<ref name="StringType"/>
</element>
</optional>
<element name="openCost">
<ref name="PriceType"/>
</element>
<element name="cumulativeCost">
<ref name="PriceType"/>
</element>
<element name="commission">
<ref name="PriceType"/>
</element>
<optional>
<!-- Represents an execution report -->
<element name="executions">
<!--The identifier of the latest match execution that contributed to the
matched position on this instrument.
Only present if the account has any matches associated with this position.-->
<element name="executionId">
<ref name="ExecutionIdType"/>
</element>
<zeroOrMore>
<choice>
<!-- An execution at a price point -->
<element name="execution">
<ref name="ExecutionType"/>
</element>
<!-- A cancelled quantity at a price point -->
<element name="orderCancelled">
<ref name="OrderCancellationType"/>
</element>
</choice>
</zeroOrMore>
</element>
</optional>
</interleave>
</define>

<define name="ExecutionType">
<!--The price at which the execution occured.-->
<element name="price">
<ref name="PriceType"/>
</element>
<!--The quantity that was executed.-->
<element name="quantity">
<ref name="QuantityType"/>
</element>
<!--The profit that this execution realised for the overall position on the
instrument.-->
<optional>
<element name="realisedProfit">
<ref name="PriceType"/>
</element>
</optional>

43
 </define>

<define name="OrderCancellationType">
<!--The quantity that was cancelled.-->
<element name="quantity">
<ref name="QuantityType"/>
</element>
</define>
</grammar>

4.20. position-event
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<include href="public-datatypes.rng"/>
<start>
<element name="position">
<choice>
<ref name="PositionType"/>
<ref name="PositionPageType"/>
</choice>
</element>
</start>

<define name="PositionPageType">
<element name="page">
<zeroOrMore>
<element name="position">
<ref name="PositionType"/>
</element>
</zeroOrMore>
</element>
<element name="hasMoreResults">
<ref name="BooleanType"/>
</element>
<element name="correlationId">
<ref name="NonEmptyStringType"/>
</element>
</define>

<!--A statement of an account's position on an identified instrument

...for accountController.getOpenPositions(offset) and for push position events.-->
<define name="PositionType">
<interleave>
<!--The unique identifier of the account the position relates to.-->
<element name="accountId">
<ref name="AccountIdType"/>
</element>
<!--The unique identifier of the instrument the position relates to.-->
<element name="instrumentId">
<ref name="InstrumentIdType"/>
</element>
<!-- Cumulative Cost = Long Cost - Short Cost -->
<element name="cumulativeCost">
<ref name="PriceType"/>
</element>
<!-- Open Cost = Cumulative Cost - Realised Profit -->
<element name="openCost">
<ref name="PriceType"/>
</element>
<!-- Open Quantity = Long Quantity - Short Quantity -->
<element name="openQuantity">
<ref name="QuantityType"/>
</element>
<!-- The short unfilled cost -->
<element name="shortUnfilledCost">
44
 <ref name="PriceType"/>
</element>
<!-- The long unfilled cost -->
<element name="longUnfilledCost">
<ref name="PriceType"/>
</element>
<!--The current total valuation on this instrument (matched and unmatched).-->
<element name="valuation">
<ref name="PriceType"/>
</element>
</interleave>
</define>
</grammar>

4.21. instructionRejected-event
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="public-datatypes.rng"/>
<start>
<element name="instructionRejected">
<ref name="InstructionRejectedType"/>
</element>
</start>

<!--An event signalling that an order has been rejected.-->

<define name="InstructionRejectedType">
<interleave>
<element name="instructionId">
<ref name="InstructionIdType"/>
</element>
<element name="accountId">
<ref name="AccountIdType"/>
</element>
<optional>
<element name="instrumentId">
<ref name="InstrumentIdType"/>
</element>
</optional>
<element name="reason">
<ref name="InstructionRejectionEnum"/>
</element>
</interleave>
</define>

<define name="InstructionRejectionEnum">
<choice>
<value>INTERNAL</value>
<value>INSTRUMENT_DOES_NOT_EXIST</value>
<value>INSTRUMENT_NOT_OPEN</value>
<value>PRICE_NOT_VALID</value>
<value>QUANTITY_NOT_VALID</value>
<value>NO_QUANTITY_TO_CANCEL</value>
<value>EXPOSURE_CHECK_FAILURE</value>
<value>DUPLICATE_ORDER</value>
<value>UNKNOWN_ORDER</value>
<value>ORDER_TYPE_INVALID</value>
<value>SERVICE_UNAVAILABLE</value>
<value>STOP_PROFIT_OFFSET_INVALID</value>
<value>STOP_LOSS_OFFSET_INVALID</value>
<value>STOP_WOULD_BE_TRIGGERED_IMMEDIATELY</value>
<value>ALREADY_CANCELLED</value>
<value>INVALID_ORDER_INSTRUCTION</value>
<value>UNAUTHORISED</value>
<value>INSTRUMENT_SUSPENDED</value>
<value>TEMPORARY_SUSPENSION</value>

45
 <value>OUTSIDE_VOLATILITY_BAND</value>
<value>OUTSIDE_ALLOWED_PRICE_RANGE</value>
<value>STOP_PROFIT_WORSE_THAN_MARKET_PRICE</value>
<value>MAXIMUM_POSITION_EXCEEDED</value>
<value>ACCESS_DENIED</value>
<value>DUPLICATE_PRICE</value>
</choice>
</define>
</grammar>

4.22. heartbeat-event
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<include href="tfx-datatypes.rng"/>
<start>
<element name="heartbeat">
<ref name="HeartBeatType"/>
</element>
</start>

<define name="HeartBeatType">
<element name="accountId">
<ref name="AccountIdType"/>
</element>
<element name="token">
<text/>
</element>
</define>
</grammar>

4.23. orderBookStatus-event
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<include href="tfx-datatypes.rng"/>
<start>
<element name="orderBookStatus">
<ref name="OrderBookStatusType"/>
</element>
</start>

<define name="OrderBookStatusType">
<interleave>
<element name="id">
<ref name="InstrumentIdType"/>
</element>
<element name="status">
<ref name="InstrumentStatusEnum"/>
</element>
<optional>
<element name="phoneTradingAvailable">
<empty/>
</element>
</optional>
</interleave>
</define>
</grammar>

4.24. orderBook Event

<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

46
<include href="public-datatypes.rng"/>
<start>
<element name="orderBook">
<ref name="OrderBookType"/>
</element>
</start>

<!--The prices available on an instrument.-->

<define name="OrderBookType">
<interleave>
<!--The unique identifier for the instrument the prices relate to.-->
<element name="instrumentId">
<ref name="InstrumentIdType"/>
</element>
<!--The bid prices, in descending order of best to worst.-->
<element name="bids">
<zeroOrMore>
<!--A price on the instrument.-->
<element name="pricePoint">
<ref name="PricePointType"/>
</element>
</zeroOrMore>
</element>
<!--The offer prices, in descending order of best to worst.-->
<element name="offers">
<zeroOrMore>
<!--A price on the instrument.-->
<element name="pricePoint">
<ref name="PricePointType"/>
</element>
</zeroOrMore>
</element>
<element name="lastMarketClosePrice">
<ref name="MarketClosePriceType"/>
</element>
<element name="dailyHighestTradedPrice">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>
<element name="dailyLowestTradedPrice">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>
<element name="valuationBidPrice">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>
<element name="valuationAskPrice">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>
<element name="lastTradedPrice">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>
</interleave>
</define>

47
</grammar>

4.25. public-datatypes
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<include href="../common/tfx-datatypes.rng"/>
<include href="public-enumerations.rng"/>

<define name="ValidLoginResponseType">
<!-- logged in user's username. -->
<element name="username">
<ref name="UsernameType"/>
</element>
<!-- user's currency -->
<element name="currency">
<ref name="CurrencyType"/>
</element>
<!-- logged in user's account id. -->
<element name="accountId">
<ref name="AccountIdType"/>
</element>
<element name="accountType">
<ref name="AccountTypeType"/>
</element>
<element name="productType">
<ref name="ProductType"/>
</element>
<element name="fundingDisallowed">
<ref name="BooleanType"/>
</element>
</define>

<define name="Subscription">
<element name="subscription">
<choice>
<!-- The unique identifier of the instrument whose events are required. -->
<element name="instrument">
<ref name="InstrumentIdType"/>
</element>
<!-- The unique identifier of the instrument whose price and status events
are required. -->
<element name="orderBook">
<ref name="InstrumentIdType"/>
</element>
<!-- The unique identifier of the instrument whose status events are
required. -->
<element name="orderBookStatus">
<ref name="InstrumentIdType"/>
</element>
<!-- The from and to currencies. -->
<element name="exchangeRate">
<ref name="ExchangeRateReferenceType"/>
</element>
<!-- A type for a generic subscription (not id specific) -->
<element name="type">
<ref name="SubscriptionType"/>
</element>
</choice>
</element>
<optional>
<element name="longPollKey">
<ref name="LongPollKeyType"/>
</element>
</optional>
</define>
48
 <define name="LongPollKeyType">
<ref name="StringType1to20"/>
</define>

</grammar>

4.26. tfx-datatypes
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<include href="enumerations.rng"/>
<include href="primitives.rng"/>

<!--Definition of a password. A password can be any valid string.-->

<define name="PasswordType">
<data type="string" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<param name="pattern">[-0-9a-zA-
Z!@#$%\^&#x00A3;&amp;*()_+|~=\\`{}\[\]:";'&lt;&gt;?,./]{6,20}</param>
</data>
</define>

<define name="LoginAttemptPasswordType">
<data type="string" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<param name="pattern">.{1,20}</param>
</data>
</define>

<define name="UsernameType">
<data type="string" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<param name="pattern">[0-9a-zA-Z\-_]{1,20}</param>
</data>
</define>

<define name="CurrencyType">
<data type="string" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<param name="pattern">[A-Z]{3}</param>
</data>
</define>

<define name="QuantityType">
<data type="decimal" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<param name="totalDigits">19</param>
<param name="fractionDigits">2</param>
</data>
</define>

<define name="StopOffsetType">
<data type="decimal" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<param name="minInclusive">0</param>
<param name="fractionDigits">5</param>
</data>
</define>

<define name="ExchangeRateReferenceType">
<interleave>
<element name="from">
<ref name="CurrencyType"/>
</element>
<element name="to">
<ref name="CurrencyType"/>
</element>
</interleave>
</define>

<define name="AccountIdType">
49
 <ref name="PositiveNonZeroLongType"/>
</define>

<define name="PriceType">
<ref name="DecimalType"/>
</define>

<!--Definition of an instrument identifier.-->

<define name="InstrumentIdType">
<ref name="PositiveNonZeroLongType"/>
</define>

<!--A representation of a price and quantity.-->

<define name="PricePointType">
<!--The price portion.-->
<element name="price">
<ref name="PriceType"/>
</element>
<!--The quantity portion.-->
<element name="quantity">
<ref name="QuantityType"/>
</element>
</define>

<define name="ExecutionIdType">
<ref name="PositiveNonZeroLongType"/>
</define>

<define name="OrderIdType">
<ref name="StringType1to16"/>
</define>

<define name="AccountStateType">
<interleave>
<!--The unique identifier of the account.-->
<element name="accountId">
<ref name="AccountIdType"/>
</element>
<!--The amount of money credited to the account.-->
<element name="balance">
<ref name="PriceType"/>
</element>
<!--The amount of money available for trading.-->
<element name="availableFunds">
<ref name="PriceType"/>
</element>
<!--The amount of money available for withdraw.-->
<element name="availableToWithdraw">
<ref name="PriceType"/>
</element>
<optional>
<element name="onMarginCallExpiryTimestamp">
<ref name="DateTimeType"/>
</element>
</optional>
<element name="wallets">
<zeroOrMore>
<element name="wallet">
<element name="currency">
<ref name="CurrencyType"/>
</element>
<element name="balance">
<ref name="PriceType"/>
</element>
</element>
</zeroOrMore>
</element>

50
 <!-- The position of this state in the life span of the account. -->
<element name="active">
<ref name="BooleanType"/>
</element>
</interleave>
</define>

<define name="InstructionIdType">
<ref name="PositiveNonZeroLongType"/>
</define>

<define name="MarketClosePriceType">
<element name="price">
<choice>
<ref name="PriceType"/>
<empty/>
</choice>
</element>
<element name="timestamp">
<choice>
<ref name="DateTimeType"/>
<empty/>
</choice>
</element>
</define>

</grammar>

4.27. tfx-request
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<start>
<!-- A request -->
<element name="req">
<!-- request id -->
<text/>
<!-- request body -->
<element name="body">
<ref name="RequestBody"/>
</element>
</element>
</start>

<!--Base definition of a request message body.-->

<define name="RequestBody">
<empty/>
</define>

</grammar>

4.28. tfx-response
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<start>
<!-- A response -->
<element name="res">
<choice>
<group>
<element name="header">
<element name="status">
<!--The request was successful.-->

51
 <value>OK</value>
</element>
</element>
<element name="body">
<ref name="ResponseBody"/>
</element>
</group>
<group>
<element name="header">
<element name="status">
<choice>
<!--The request was unsuccessful.-->
<value>WARN</value>
<!--There was a system problem that caused an error.-->
<value>ERROR</value>
</choice>
</element>
<!--Optional list of warnings encountered during processing of the
request.-->
<optional>
<element name="warnings">
<ref name="WarningsType"/>
</element>
</optional>
</element>
<element name="body">
<optional>
<ref name="ResponseBody"/>
</optional>
</element>
<optional>
<!-- Authorization status -->
<element name="auth">
<ref name="AuthorisationEnum"/>
</element>
</optional>
</group>
</choice>
</element>
</start>

<!--Base definition of a request message body.-->

<define name="ResponseBody">
<empty/>
</define>

<!--Definition of a warning messages that can be provided in a response that has the
status WARN.-->
<define name="WarningsType">
<zeroOrMore>
<!--There may be many individual warnings associated with a response.-->
<element name="warning">
<!--Identifies the field name in the request that this warning is associated
with if applicable.-->
<element name="fieldName">
<choice>
<text/>
<empty/>
</choice>
</element>
<!--The warning message.-->
<element name="message">
<text/>
</element>
</element>
</zeroOrMore>
</define>

52
 <!--Enumeration of authorisation failure reasons.-->
<define name="AuthorisationEnum">
<choice>
<!--The user was unauthorised to perform that operation.-->
<value>UNAUTHORISED</value>
<!--The user was not authenticated. This maybe because they have not successfully
logged in or because their session has expired.-->
<value>UNAUTHENTICATED</value>
<!--The user's session has expired, or they have been logged off for security
reasons.-->
<value>SESSION_EXPIRED</value>
</choice>
</define>

</grammar>

4.29. enumerations
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<!--Definition of the domain of instrument statuses.-->

<define name="InstrumentStatusEnum">
<choice>
<!--The instrument has been newly created.-->
<value>New</value>
<!--The is closed and waiting to be opened.-->
<value>Closed</value>
<!--The instrument is temporarily not accepting orders.-->
<value>Suspended</value>
<!--The instrument is no longer trading.-->
<value>Withdrawn</value>
<!--The instrument and all orders upon it have been made void.-->
<value>Settled</value>
<!--The instrument is accepting orders.-->
<value>Opened</value>
</choice>
</define>

</grammar>

4.30. public-enumerations
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<!--Definition of the lifespan of an order.-->

<define name="GoodUntilEnum">
<choice>
<value>Immediate</value>
<value>Cancelled</value>
</choice>
</define>

<define name="AccountTypeType">
<choice>
<value>STANDARD_TRADER</value>
</choice>
</define>

<!--Enumeration of login failure codes.-->

<define name="LoginFailureEnum">
<choice>
<!--The account was closed and therefore the user could not log in.-->

53
 <value>ACCOUNT_CLOSED</value>
<!--The account is locked or the user has messages waiting for them on the web
site.-->
<value>ACCOUNT_LOCKED</value>
<!--The account is suspended.-->
<value>ACCOUNT_SUSPENDED</value>
<!--The user name or password were not valid.-->
<value>BAD_CREDENTIALS</value>
<!--A temporary system error prevented the log in being processed. The log in
can be retried later.-->
<value>TEMPORARY_SYSTEM_ERROR</value>
<!-- The service is not currently available for use. -->
<value>SERVICE_UNAVAILABLE</value>
<!-- The temporary password has expired, and can no longer be used -->
<value>PASSWORD_EXPIRED</value>
</choice>
</define>

<define name="OrderTypeEnum">
<choice>
<value>MARKET</value>
<value>PRICE_LIMIT</value>
<value>STOP_COMPOUND_PRICE_LIMIT</value>
<value>STOP_COMPOUND_MARKET</value>
<value>CLOSE_OUT_ORDER</value>
<value>STOP_LOSS_ORDER</value>
<value>STOP_PROFIT_ORDER</value>
</choice>
</define>

<!-- Currently duplicated in admin-enumerations.rng -->

<define name="ProductType">
<choice>
<value>CFD_DEMO</value>
<value>CFD_LIVE</value>
</choice>
</define>

<!-- Currently duplicated in admin-enumerations.rng -->

<define name="SubscriptionType">
<choice>
<value>account</value>
</choice>
</define>

</grammar>

4.31. primitives
<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">

<define name="NonEmptyStringType">
<data type="string" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<param name="minLength">1</param>
<param name="whiteSpace">collapse</param>
</data>
</define>

<define name="StringType">
<data type="string" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
</define>

<define name="DecimalType">
<data type="decimal" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
</define>

54
 <define name="BooleanType">
<data type="boolean" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
</define>

<define name="DateTimeType">
<data type="dateTime" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
</define>

<define name="PositiveNonZeroLongType">
<data type="long" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<param name="minInclusive">1</param>
</data>
</define>
</grammar>

Website: www.LMAXtrader.com

Email address: [email protected]

Telephone: 0333 700 1000 (+44 203 192 2555)

LMAX Trader is a trading name of LMAX Limited. LMAX Limited is authorised and regulated by the Financial Services
Authority in the United Kingdom (Register Number 509778). LMAX Limited is registered in England and Wales (Number
06505809) and our registered address is LMAX Limited, Yellow Building, 1A Nicholas Road, London W11 4AN.
55