ESP Trade Messages
| This documentation is for FX Professional 2.18 and earlier. From version 2.19 (2 Jun 2019), FX Professional requires back end adapters to implement the FX Integration API 3. For documentation on FX Integration API 3 messages, see FX Integration API. |
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.
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.
| 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. |
|
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 |
| 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.
| 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 |
SpotRate |
[optional] 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 |
|---|---|---|
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 |
L1_AllInRate |
[optional] 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]
Error Message [s]
ClientClose Message [c]
ClientCloseAck Message [s]
See also: