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

Client

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.

Server

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

 

Trade Leg Fields

Field Name Value Example
L1_Amount The amount to trade, specified in the dealt currency. 1000000
L1_BuySell

The trade direction of the base currency, from the perspective of the user. Valid values: "BUY", "SELL".

BUY
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

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

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

 

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

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: