Block 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 Block Trades 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
- Trade Model State Diagram
- Open Message [c]
- OpenAck [s]
- PickUp Message [s]
- PriceUpdate Message [s]
- Submit Message [c]
- SubmitAck Message [s]
- TradeConfirmation Message [s]
- Expire Message [c]
- Withdraw Message [c]
- Reject Message [s]
- Error Message [s]
- Hold 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. For Block Trades, two messages must be sent by the client:
-
the first is to initiate the Block Trade, known as the open message. In response to this message, if successful a trade channel is created and the back end begins to process the request.
-
the second is the submission message which occurs when the client wants to trade on a Block Trade Quote.
For the back-end adapters, the FXIntegrationAPI consumes the client messages. The requests for Block Trades are handled by an Adapter that instantiates the FXTradeAdapter object and registers an BlockTradeListener (see the FX Integration API documentation for more information on Adapters). The Block Trade is handled by the FX Integration API using the BlockTrade object. The object contains the Responders and Events required to send block trade quote updates, as well as transition to the next stage of the trade model.
Trade Model State Diagram
The trade model for block quote is the same as for RFS:
Blue arrows denote a message sent by the client, green arrows denote messages sent by the server.
Open Message [c]
This is the message that the client sends in order to open a Block Trade ticket and receive quotes.
Trade fields and trade-leg fields are identical to the ESP Open message apart from the following differences:
| Field Name | Value | Example |
|---|---|---|
QuoteID |
This should be not sent because we haven’t received a quote yet. We are asking for a stream of quotes, we are not trying to trade on a quote we already received. |
N/A |
TradingProtocol |
The value must be BLOCK, not ESP or RFS |
BLOCK |
| Field Name | Value | Example |
|---|---|---|
Ln_Account |
The settlement account to use |
- |
Ln_Tenor |
Unlike ESP you can do Block Trades on broken dates, so this value can be "broken", in which case the settlement date should be used. |
12M |
Ln_DATE |
This should be not sent because we haven’t received a quote yet. We are asking for a stream of quotes, we are not trying to trade on a quote we already received. |
- |
Ln_SpotBidRate |
This should be not sent for the same reason as above. |
- |
Ln_SpotAskRate |
This should be not sent for the same reason as above. |
- |
Ln_TradingType |
This should be not sent for the same reason as above. |
SPOT, FWD or SWAP |
Ln_SettlementDate |
The settlement date of the trade; use this if the tenor is "broken" |
20121212 |
Also note that unlike ESP you can do a two-legged BlockTrade trade - this means that all of the L1 fields are also valid as L2 fields if the trade is a swap.
OpenAck [s]
This is the message the server will send in order to acknowledge that the request to initiate a Block Trade (the Open Message above) has been received by the back-end adapters. These fields should be identical to the ESP OpenAck message apart from the following differences:
| Field Name | Value | Example |
|---|---|---|
SubmissionDate |
This should be not sent because the user hasn’t submitted a trade yet |
N/A |
SubmissionTime |
This should be not sent for the same reason as above |
N/A |
PickUp Message [s]
This is the message the server should send in order to notify the client that the Block Trade request is being processed by the back-end trading system. These fields should be identical to the ESP PickUp message.
PriceUpdate Message [s]
This is the message the server (a trading adapter) will send to the client when it receives a price update from the back-end trading system. The initial price update should contain the overall timeout, which is the duration for which prices will be streamed; subsequent quotes in the stream should not set the overall timeout otherwise they will reset the overall timeout for the stream to a new value.
Trade fields and trade-leg fields are identical to the Streaming price update message apart from the following differences:
| 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 client wants to make in the state model |
PriceUpdate |
OverallTimeOut |
This is not present on standard price updates. It is the number of seconds remaining before this stream (not this individual quote) is timed out. |
60 |
| Field Name | Value | Example |
|---|---|---|
Ln_Amount |
Unlike streaming prices which are based on volume bands Block quotes are based on the exact amount the user specified, so we could send this field if we want to. However the client already knows it, so it’s probably unnecessary. |
50000 |
Ln_ContraAmount |
The amount that the client traded specified in the non-dealt currency. This should be the amount multiplied by the rate. |
894.57 |
Also note that unlike streaming prices you can have a two-legged Block trade, so all of the L1 fields are also valid as L2 fields if the trade is a swap.
Submit Message [c]
This is the message the client will send in order to execute a trade on a quote received on the stream. The fields on this message are similar to, but subtly different from the ESP Open message.
| 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 client wants to make in the state model |
Submit |
CurrencyPair |
We already sent this on the Open message but we have to include it again or the Permissioning system will block the message |
GBPUSD |
AssetClass |
We already sent this on the Open message but we have to include it again or the Permissioning system will block the message |
FX |
TradingAssetClass |
We already sent this on the Open message but we have to include it again or the Permissioning system will block the message |
FX |
TradingProtocol |
We already sent this on the Open message but we have to include it again or the Permissioning system will block the message |
BLOCK |
TradingType |
We already sent this on the Open message but we have to include it again or the Permissioning system will block the message |
SPOT or FWD |
QuoteID |
We already sent this on the Open message but we have to include it again or the Permissioning system will block the message |
1 |
Trade leg fields
| Field Name | Value | Example |
|---|---|---|
Ln_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 just tells you which currency the client has specified the amount in. |
Either "BUY" or "SELL" |
Ln_Spot |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message. |
1.2345 |
Ln_Points |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message. |
5.00 |
Ln_AllIn |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message. |
1.2543 |
Ln_ContraAmount |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message. |
845.96 |
Ln_ContraCcy |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message. |
USD |
| Field Name | Value | Example |
|---|---|---|
Ln_Account |
The settlement account to use - if defined then is should be the same as on the Open message |
- |
If the trade is a swap, then we want L2_ fields for each of the L1_ fields above, representing the second leg of the swap.
SubmitAck Message [s]
This is the message sent by the server (a trading adapter) to acknowledge that the clients submission to trade on the Block Quote 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 client 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 |
TradeConfirmation Message [s]
This is the message sent by the server to confirm to the client that the Block Trade has been successfully executed in the back-end trading system. The 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 client wants to make in the state model |
TradeConfirmation |
TradeID |
The ID for the trade as generated by the OMS |
EQ:1366900842.9:245 |
FillID |
A unique identifier for the execution. This is generated by the OMS, and is different to the Trade ID. For example, in the OMS there might be a trade with ID 1 and an execution for that trade with ID 2. |
1366844776:228_1 |
SpotRate |
The SPOT rate that the client traded on |
1.2345 |
TradeDate |
The business day that the trade is executed, e.g. if I trade on a Saturday, this would be Monday, in the format YYYYMMDD |
20121212 |
| Field Name | Value | Example |
|---|---|---|
Ln_Spot |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message |
1.2345 |
Ln_Points |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message |
5.00 |
Ln_AllIn |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message |
1.2543 |
Ln_ContraAmount |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message |
845.96 |
Ln_ContraCcy |
This field is included on the rate update that the client wants to trade on, and should be sent back unchanged on the Submit message |
USD |
If the trade is a swap, then we want L2_ fields for each of the L1_ fields above, representing the second leg of the swap.
Expire Message [c]
At various states (see the trade model above) the server may send an Expire message. A state will be made to transition to the Expired state in certain instances, for example if the stream was kept open for the total amount of time without a quote being traded on it.
| 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 client wants to make in the state model |
Expire |
Withdraw Message [c]
At various states (see the trade model above) the server may send a Withdraw message. The state will be made to transition to the either the PickedUp state or the Error state depending on what state the transition is made from. The Withdraw message is sent to notify the client that the back-end trading system has withdrawn the current quote stream and that we are awaiting a new set of price updates.
| 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 client wants to make in the state model |
Withdraw |
Reject Message [s]
Error Message [s]
Hold Message [s]
ClientClose Message [c]
ClientCloseAck Message [s]
See also: