ESP Trade Messages

The following trade model and set of messages describe the fields and values required to successfully execute an ESP Trade using the FX Professional Motif. For each of the messages below, [c] denotes that the message is sent by the client, [s] denotes that the message is sent by the server, and [c/s] both client or server.

Contents:

Architecture
Trade Model State Diagram
Submit Message [c]
SubmitAck Message [s]
PickUp Message [s]
TradeConfirmation Message [s]
Reject Message [s]
Error Message [s]
ClientClose Message [c]
ClientCloseAck Message [s]

Architecture

For the front-end client the trademodel library handles the processing of these messages. Streamlink is used to send messages to the back end. The messages are sent using a Contrib. For ESP Trades there is only one message sent to the back end - the submission of the trade. The remaining messages are from the server denoting the transitions of the trade as they are processed by the back-end adapters and the back-end trading system.

For the back-end adapters, the FXIntegrationAPI consumes the client message to execute an ESP trade. The trade is usually handled by an Adapter that instantiates the FXTrade object and registers an ESPTradeListener (see the FX Integration API documentation for more information on Adapters). The FX Integration API uses the ESPTrade object to interact with the trade model and send messages back to the client. This object contains the Responders and Events required to transition to the next stage of the trade model.

Trade Model State Diagram

Blue arrows denote a message sent by the client, green arrows denote messages sent by the server.

States that allow the server to send messages, can also send the Error and Reject message. These two transitions are therefore not shown on the diagram above.

Submit Message [c]

This is the message the client sends in order to submit an ESP Quote for trading. It can be used for Spot and Forward one/two click trades.

Trade Fields:

Field Name Value Example

Field Name	Value	Example
MsgType	The transition that the client wants to make in the state model.	Submit
CurrencyPair	The currency pair for the trade. This is sent in preference to BaseCurrency and TermCurrency because CurrencyPair is what we permission on. It would be a security hole for the back end to read BaseCurrency and TermCurrency fields, because a malicious client could send a valid currency pair in the CurrencyPair field in order to pass the permission check, but send two different currencies in the BaseCurrency and TermCurrency fields in order to execute a trade on a non-permissioned currency pair.	GBPUSD
DealtCurrency	The dealt currency for the trade (what the amount is expressed in). Must be either the base or term currency.	USD
QuoteID	The unique ID of the quote the client wants to trade on. This is generated by the OMS. For SPOT trades it will be the Quote ID for the SPOT quote, for Forward trades it will be the Quote ID of the forward points quote.	EQ:1366899484.1:230
SpotRate	This is the spot rate that the client wants to trade on. The value of this field must equal the value of either the SpotBidRate or SpotAskRate field on the rate update that the client is executing.	1.2345
AssetClass	The asset class for the trade; used by permissioning and licensing.	FX
TradingAssetClass	The trading asset class for the trade; used by permissioning and licensing.	FX
TradingProtocol	The trade protocol, e.g, ESP or RFS. The Trading DataSource library needs this so that it knows which state model to use for the trade. Also used for permissioning.	ESP
TradingType	This could be SPOT, FWD or SWAP but there is no such thing as an ESP (one-click) swap trade so in this case it can only be SPOT or FWD.	SPOT or FWD
Account	The settlement account to use.	-
TOBOUser	The user the trade is on behalf of. For example, if `dealer1@novobank.co.za` does a trade on behalf of `bob_treasurer@anglo.co.za` then the value of this field will be `bob_treasurer@anglo.co.za`. If this is not a TOBO trade then this field is not sent.	bob_treasurer@anglo.co.za
ControlAddLeg	This is a control field that the front end trading library adds automatically. The user code doesn’t need to do anything with this.	1

MsgType

The transition that the client wants to make in the state model.

Submit

CurrencyPair

The currency pair for the trade. This is sent in preference to BaseCurrency and TermCurrency because CurrencyPair is what we permission on. It would be a security hole for the back end to read BaseCurrency and TermCurrency fields, because a malicious client could send a valid currency pair in the CurrencyPair field in order to pass the permission check, but send two different currencies in the BaseCurrency and TermCurrency fields in order to execute a trade on a non-permissioned currency pair.

GBPUSD

DealtCurrency

The dealt currency for the trade (what the amount is expressed in). Must be either the base or term currency.

USD

QuoteID

The unique ID of the quote the client wants to trade on. This is generated by the OMS. For SPOT trades it will be the Quote ID for the SPOT quote, for Forward trades it will be the Quote ID of the forward points quote.

EQ:1366899484.1:230

SpotRate

This is the spot rate that the client wants to trade on. The value of this field must equal the value of either the SpotBidRate or SpotAskRate field on the rate update that the client is executing.

1.2345

AssetClass

The asset class for the trade; used by permissioning and licensing.

TradingAssetClass

The trading asset class for the trade; used by permissioning and licensing.

TradingProtocol

The trade protocol, e.g, ESP or RFS. The Trading DataSource library needs this so that it knows which state model to use for the trade. Also used for permissioning.

ESP

TradingType

This could be SPOT, FWD or SWAP but there is no such thing as an ESP (one-click) swap trade so in this case it can only be SPOT or FWD.

SPOT or FWD

Account

The settlement account to use.

TOBOUser

The user the trade is on behalf of. For example, if dealer1@novobank.co.za does a trade on behalf of bob_treasurer@anglo.co.za then the value of this field will be bob_treasurer@anglo.co.za. If this is not a TOBO trade then this field is not sent.

bob_treasurer@anglo.co.za

ControlAddLeg

This is a control field that the front end trading library adds automatically. The user code doesn’t need to do anything with this.

Trade Leg Fields

Field Name	Value	Example
L1_Amount	The amount to trade, specified in the dealt currency.	1000000
L1_BuySell	Whether the client wants to buy or sell the base currency, NOT the dealt currency. For example if the currency pair is EURGBP and this value is EUR then this field always tells you if the client wants to buy or sell EUR, even if the dealt currency is GBP. The dealt currency simply tells you which currency the client has specified the amount in.	Either "BUY" or "SELL"
L1_SettlementDate	The settlement date for the trade, in ISO format (only support standard settlement dates)	20131212
L1_Tenor	The tenor at which to settle (only support standard settlement dates, so cannot be broken)	12M
L1_Price	This is the all-in rate that the client wants to trade on. The value of this field must equal the value of either the L1_AllInBidRate or L1_AllInAskRate field on the rate update that the client is executing. The front end typically populates this field by reading the currently rendered price on the buy or sell button at the time the user clicks.	1.2345
L1_FwdPips	For forward trades this is the forward pips that the client wants to trade on. The value of this field must equal the value of either the BidPips or AskPips field on the rate update that the client is executing. The front end typically populates this field by reading the currently rendered forward points on the buy or sell button at the time the user clicks. For SPOT trades this field should be not sent.	4.5
L1_FwdPoints	For forward trades this is the forward points that the client wants to trade on. The value of this field must equal the value of either the BidPoints or AskPoints field on the rate update that the client is executing. For SPOT trades this field should be not sent. If the trade is a forward but the back end did not send the BidPoints and AskPoints fields (because they are optional) then this field should be not sent.	0.00045

Field Name

Value

Example

L1_Amount

The amount to trade, specified in the dealt currency.

1000000

L1_BuySell

Whether the client wants to buy or sell the base currency, NOT the dealt currency. For example if the currency pair is EURGBP and this value is EUR then this field always tells you if the client wants to buy or sell EUR, even if the dealt currency is GBP. The dealt currency simply tells you which currency the client has specified the amount in.

Either "BUY" or "SELL"

L1_SettlementDate

The settlement date for the trade, in ISO format (only support standard settlement dates)

20131212

L1_Tenor

The tenor at which to settle (only support standard settlement dates, so cannot be broken)

12M

L1_Price

This is the all-in rate that the client wants to trade on. The value of this field must equal the value of either the L1_AllInBidRate or L1_AllInAskRate field on the rate update that the client is executing. The front end typically populates this field by reading the currently rendered price on the buy or sell button at the time the user clicks.

1.2345

L1_FwdPips

For forward trades this is the forward pips that the client wants to trade on. The value of this field must equal the value of either the BidPips or AskPips field on the rate update that the client is executing. The front end typically populates this field by reading the currently rendered forward points on the buy or sell button at the time the user clicks. For SPOT trades this field should be not sent.

4.5

L1_FwdPoints

For forward trades this is the forward points that the client wants to trade on. The value of this field must equal the value of either the BidPoints or AskPoints field on the rate update that the client is executing. For SPOT trades this field should be not sent. If the trade is a forward but the back end did not send the BidPoints and AskPoints fields (because they are optional) then this field should be not sent.

0.00045

SubmitAck Message [s]

This is the message that is sent back by the server (normally a trading adapter) in order to acknowledge that the trade has been received by the back-end adapters.

Field Name	Value	Example
RequestID	The client generated ID that is unique for this user and trade. The client-side trading library generates this.	112314243333
MsgType	The transition that the server wants to make in the state model	SubmitAck
SubmissionDate	The date on the server that the trade was submitted to the OMS (ISO format)	20130425
SubmissionTime	The time on the server that the trade was submitted to the OMS (HH:MM:SS)	20130425

Field Name

Value

Example

RequestID

The client generated ID that is unique for this user and trade. The client-side trading library generates this.

112314243333

MsgType

The transition that the server wants to make in the state model

SubmitAck

SubmissionDate

The date on the server that the trade was submitted to the OMS (ISO format)

20130425

SubmissionTime

The time on the server that the trade was submitted to the OMS (HH:MM:SS)

20130425

PickUp Message [s]

This is the message that is sent by the sever (normally a trading adapter) in order to notify the client that the trade is now being processed by the back-end trading system.

Field Name	Value	Example
RequestID	The client generated id that is unique for this user and trade. The client-side trading library generates this.	112314243333
MsgType	The transition that the server wants to make in the state model	PickUp

Field Name

Value

Example

RequestID

The client generated id that is unique for this user and trade. The client-side trading library generates this.

112314243333

MsgType

The transition that the server wants to make in the state model

PickUp

TradeConfirmation Message [s]

This is the message that is sent by the server (a trading adapter) to confirm to the client that the trade has been successfully executed in the back-end trading system. This message contains the details of the trade that the client wants to see in order to verify the correctness of the trade.

Trade Fields:

Field Name	Value	Example
RequestID	The client generated id that is unique for this user and trade. The client-side trading library generates this.	112314243333
MsgType	The transition that the server wants to make in the state model	TradeConfirmation
TradeID	The ID for the trade as generated by the OMS	EQ:1366900842.9:245
ExecutionDateTime	The timestamp in UTC that the trade was executed. The front end should convert this to the users’s local time.	20121212150000
Optional Fields
SpotRate	The SPOT rate that the client traded on. This should be either the L1_AllInBidRate or L1_AllInAskRate, depending on whether the client wanted to do a buy or a sell.	1.2345

Field Name

Value

Example

RequestID

The client generated id that is unique for this user and trade. The client-side trading library generates this.

112314243333

MsgType

The transition that the server wants to make in the state model

TradeConfirmation

TradeID

The ID for the trade as generated by the OMS

EQ:1366900842.9:245

ExecutionDateTime

The timestamp in UTC that the trade was executed. The front end should convert this to the users’s local time.

20121212150000

Optional Fields

SpotRate

The SPOT rate that the client traded on. This should be either the L1_AllInBidRate or L1_AllInAskRate, depending on whether the client wanted to do a buy or a sell.

1.2345

Trade Leg Fields:

Field Name	Value	Example
L1_ContraAmount	The amount that the client traded specified in the non-dealt currency. This should be the amount multiplied by the rate.	894.57
Optional Fields
L1_AllInRate	The rate that the client traded on. This should be either the L1_AllInBidRate or L1_AllInAskRate sent on the Open message, depending on whether the client wanted to do a buy or a sell.	1.23456

Field Name

Value

Example

L1_ContraAmount

The amount that the client traded specified in the non-dealt currency. This should be the amount multiplied by the rate.

894.57

Optional Fields

L1_AllInRate

The rate that the client traded on. This should be either the L1_AllInBidRate or L1_AllInAskRate sent on the Open message, depending on whether the client wanted to do a buy or a sell.

1.23456

Reject Message [s]

See Common Messages Specifications

Error Message [s]

See Common Messages Specifications

ClientClose Message [c]

See Common Messages Specifications

ClientCloseAck Message [s]

See Common Messages Specifications

See also: