Messages are core events signalling trade, order activity as well as warnings about exposure. Messages are typically text with an message id, a type and a written translated description. The messages can be retrieved by requesting a list of pending messages, but since many messages are critical to the client, the resource is primarily intended for a subscription/event type pattern. Messages with a message id will stay for a indeterminate period until confirmed. It is an applications responsibility to let the user acknowledge that messages have been received.
These messages are intended for display and identifying specific sub types automatically is unreliable since texts and translations can change.
Properties of a Message
A message has a few shared properties:
- AccountId - if relevant, the account related to the message
- DateTime - A timestamp indicating when the message was sent
- MessageHeader - A translated header for the message
- MessageBody - The translated message itself
- MessageId - the Id used to identify the unique message and also used for acknowledging that it has been seen by the end user
- MessageType - Can be either TradeConfirmation, MarginCall or PriceAlert
The two translated fields are translated using the user's preferred language. The MessageType is a reliable indicator for what type of message has been received, but new types can be added so functionality that depends on this value ought to be robust against extensions.
Trade Confirmations
Trade confirmations can be a notification that:
An order has been placed
- An order has expired
- An order has been (partially) filled
- An order was cancelled
- A position was stopped out (due to insufficient margin)
- A position was placed
An example of a trade confirmation message can be for placing a limit order (here in English as that is the preferred language of the user:
{
"AccountId": "339070INET",
"DateTime": "2017-02-17T10:54:04.867000Z",
"DisplayName": "",
"MessageBody": "You placed order to buy 25,000 GBPUSD spot @ 1.24130 limit G.T.C. .\r\nFront office order id: 49066054\r\nAccount: 339070INET",
"MessageHeader": "Order placed",
"MessageId": "873066395_0",
"MessageType": "TradeConfirmation"
}
Margin Calls
A margin call is a message informing the client about loses affecting his ability fullfill the margin requirements of his positions in the market. The messages comes in different flavors depending on the client's setup. Usually the escalation is from a warning about high margin utilization ending up with a message indicating that his positions will be closed.
Example 1:
{
"DateTime": "2017-02-17T11:54:01.883000Z",
"DisplayName": "",
"MessageBody": "\r\n\r\nOn 17 Feb 2017 at 11:54:01 (GMT)\r\n\r\nPlease be advised that you are now utilizing 80.6% of your available margin.\r\n\r\n\r\n",
"MessageHeader": "Margin Usage",
"MessageId": "1238325560_69048872",
"MessageType": "MarginCall"
}
Example 2:
{
"DateTime": "2017-02-17T11:56:57.400000Z",
"DisplayName": "",
"MessageBody": "\r\n\r\nOn 17 Feb 2017 at 11:56:57 (GMT)\r\n\r\nPlease be advised that you are now exceeding your available margin for trading purposes.\r\nYou should not increase your positions further.\r\nPlease note that failure to meet prevailing margin requirements may result in your positions being closed without further notice.\r\n\r\n\r\n",
"MessageHeader": "Full Margin Usage",
"MessageId": "1238325562_69048873",
"MessageType": "MarginCall"
}
Example 3:
{
"DateTime": "2017-02-17T11:59:28.480000Z",
"DisplayName": "",
"MessageBody": "\r\n\r\nOn 17 Feb 2017 at 11:59:28 (GMT)\r\n\r\nYour margin requirement is 64088.75, while your available margin is 49939.50.\r\nPlease immediately reduce your positions accordingly and/or transfer sufficient funds to support your open positions.\r\nPlease note that failure to meet prevailing margin requirements may result in your positions being closed without further notice.\r\n\r\n\r\n",
"MessageHeader": "Margin Call",
"MessageId": "1238325566_69048874",
"MessageType": "MarginCall"
}
Example 4:
{
"DateTime": "2017-02-17T12:02:51.467000Z",
"DisplayName": "",
"MessageBody": "\r\n\r\nOn 17 Feb 2017 at 12:02:51 (GMT)\r\n\r\n Due to insufficient margin collateral funds on your account, we have now commenced the closing down of open margin positions on your account.\r\n\r\n\r\n\r\nPlease note that any exchange based positions will be closed during the operating hours of the related exchange.\r\n\r\n\r\n\r\n",
"MessageHeader": " Stop out ",
"MessageId": "1238325569_69048875",
"MessageType": "MarginCall"
}
Price Alerts and Other Special Messages
On top of the messages related to trade activity, the message response may also contain alerts on prices defined either in SaxoTrader GO or through services in the ValueAdd.
Acknowledging Messages
When a message is received whether that is through a request for a list or as an event due to a subscription, it is recommended to show the message to the end-user and let him acknowledge that he has seen the message. It has the effect of both removing the message and logging the fact that the end-user has seen the message, An acknowledge is done through a put request to the underlying message.
PUT https://developer.saxobank.com/sim/openapi/trade/v1/messages/seen/873066395_0 HTTP/1.1 204 No Content