OpenAPI

Messages are core events signalling trade, order activity as well as warnings about exposure, etc. In some commercial setups it is actually a requirement that a third party application displays these messages to the user, and registers that the user has seen/acknowledged them. 

The messages can be retrieved by requesting a list of pending messages, but since many of them (such as order confirmations) are time critical to the end user, the resource also supports subscription. Most messages will stay for an indeterminate period until confirmed. It is an applications responsibility to let the user acknowledge that messages have been received.

The messages are primarily intended for communicating important information to the user. Therefore all messages have a core set of properties, such as MessageHeader and MessageBody, which the third party application can simply display to the user, without the application understanding the precise meaning of the message. A third party application should not rely on parsing the contents of the MessageBody to extract values from it, as texts are translated and their formatting may change without notice.

Recently we have started to introduce structured information in message specific fields, but this is an ongoing effort.

Properties of a Message

All messages have a few shared properties:

Of particular interest is:

  • MessageHeader and MessageBody are used for display to the user. They are translated into the language defined by the users language setting.
  • MessageId identifies the unique message and is also used for acknowledging that it has been seen by the end user.
  • MessageType determines the meaning of the message. You may also use this to determine which extra fields (if any) are provided in addition to those in the base message.


Message Types

Currently the following types are available: 

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


Appendix: Meaning and contents of individual message types

Account Depreciation

Message to indicate that an account has depreciated beyond a limit as specified by MIFID II regulations. Only sent for configured client segments.

Additional Fields

FieldFieldTypeDescription
DepreciationPctDecimalHow much has the account depreciated since ReportingPeriodStart (100%=100).
ReportingPeriodStartDateDate of reporting period start.

Sample Message

An example of an account depreciation message:

Account Depreciation
{
    "AccountId": "ATSEACCOUNT",
    "DateTime": "2017-09-11T15:59:21.000000Z",
    "DepreciationPct": 21.5,
    "DisplayName": "",
    "MessageBody": "",
    "MessageHeader": "Account depreciation",
    "MessageId": "875192084_0",
    "MessageType": "AccountDepreciation",
    "ReportingPeriodStart": "2017-07-03T09:23:10.000000Z"
} 

Note, at this point in time we do NOT provide a MessageBody for this message. Please construct a suitable text based on MessageType, AccountId, DepreciationPct and ReportingPeriodStart.


Margin Call

Message to indicate that some margin utilization threshold has been breached. Margin calls can either come in the form of a warning or as a margin stop out indicating that the account is now being stopped out.

Additional Fields

None.

Sample Message

An example of a margin call provided as the users account breaches a configured limit for receiving a margin utilization warning (in this case 80%).


{
    "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"
}


Mifid

Message to indicate that the clients Mifid status has changed.

Additional Fields

None.

Sample Message

An example of a Mifid message:

Mifid
{
    "DateTime": "2018-02-12T00:00:00.000000Z",
    "DisplayName": "",
    "MessageBody": "Client classification changed for Product Area Mutual Funds from Professional to Retail",
    "MessageHeader": "Product Area Classification Change",
    "MessageId": "875236381_0",
    "MessageType": "Mifid"
} 

Notification

Message sent from broker to client, typically about important trading related event.

Additional Fields

None.

Sample Message

An example of a Mifid message:

Mifid
{
    "DateTime": "2018-02-16T00:00:00.000000Z",
    "DisplayName": "",
	"DisplayType": "Popup",
    "MessageBody": "As a result of today's UK decision to leave EU, we will continue to hold margins at current levels for the time being.
    "MessageHeader": "Dealer Broadcast",
    "MessageId": "875236381_4",
    "MessageType": "Notification"
} 


Position Depreciation

Message to indicate that a position has depreciated beyond a limit as specified by MIFID II regulations. Only sent for configured client segments.

Additional Fields

FieldFieldTypeDescription
AccountIdStringAccount to which this message relates.
AssetTypeAssetTypeAssetType of instrument affected.
DepreciationPctDecimalHow much has the account depreciated since ReportingPeriodStart (100%=100).
DisplayAndFormatInstrumentDisplayAndFormatThe standard data structure providing information about how to display the instrument.
ExecutionTimeOpenDateTimeDate and Time of position open.
ReportingPeriodStartDateDate of reporting period start.
OpenPriceDecimalOpen price of the position.
UicIntInstrument Uic.

Sample Message

An example of a position depreciation message:

Account Depreciation
{
    "AccountId": "ATSEACCOUNT",
    "AssetType": "Stock",
    "DateTime": "2017-08-16T16:30:21.000000Z",
    "DepreciationPct": 19.5,
    "DisplayAndFormat": {
      "BarrierFormat": "Normal",
      "Currency": "DKK",
      "Decimals": 2,
      "Description": "Vestas Wind Systems A/S",
      "Format": "Normal",
      "OrderDecimals": 2,
      "StrikeFormat": "Normal",
      "Symbol": "VWS:xcse"
    },
    "DisplayName": "",
    "ExecutionTimeOpen": "2017-07-03T09:23:10.000000Z",
    "MessageBody": "",
    "MessageHeader": "Position depreciation",
    "MessageId": "875135463_0",
    "MessageType": "PositionDepreciation",
    "OpenPrice": 615.75,
    "Uic": 15611
}

Note, at this point in time we do NOT provide a MessageBody for this message. Please construct a suitable text based on the other properties in the message.

Price Alert

Message to indicate that a price alert has been triggered.

Additional Fields

FieldFieldTypeDescription
AssetTypeAssetTypeAssetType of instrument affected.
CommentStringComment entered by the user, when the price alert was defined.
DisplayAndFormatInstrumentDisplayAndFormatThe standard data structure providing information about how to display the instrument.
OperationStringSome indication of the state typically "trg" for triggered..
OperatorStringOne of ">=" or "<=".
PriceAlertDataStructureObject containing details of the price alerte (mostly redundant).
PriceAlertIdStringUnique identifier for the price alert.
PriceVariablePriceVariableThe aspect of the price, which is being monitored. One of: "AskTick", "BidTick", "PercentChange" or "Traded".
TriggerPriceDecimalThe price which the observed value is compared to.
UicIntInstrument Uic.

Sample Message

An example of a position depreciation message:

Account Depreciation
{
    "AssetType": "Stock",
    "Comment": "",
    "DateTime": "2018-01-24T14:25:58.000000Z",
    "DisplayAndFormat": {
      "BarrierFormat": "Normal",
      "Currency": "GBP",
      "Decimals": 2,
      "Description": "Great Portland Estates Plc",
      "Format": "Normal",
      "OrderDecimals": 2,
      "StrikeFormat": "Normal",
      "Symbol": "GPOR:xlon"
    },
    "DisplayName": "",
    "MessageBody": "Price alert was triggered",
    "MessageHeader": "PriceAlert",
    "MessageId": "875236289_0",
    "MessageType": "PriceAlert",
    "Operation": "trg",
    "Operator": ">=",
    "PriceAlertData": {
      "AssetType": "Stock",
      "Comment": "",
      "Operation": "trg",
      "Operator": ">=",
      "PriceAlertId": "77637",
      "PriceVariable": "Traded",
      "TriggerPrice": 650,
      "Uic": 4198
    },
    "PriceAlertId": "77637",
    "PriceVariable": "Traded",
    "TriggerPrice": 650,
    "Uic": 4198
}


Trade Confirmation

Message to indicate changes to orders or positions.

Additional Fields

FieldFieldTypeDescription
AccountIdStringAccount to which this message relates.
OrderIdStringId of the order being created, updated, changed.
PositionIdStringId of the position to which this message relates.
SourceOrderIdStringSourceOrderId of the position being created.

Sample Message

An example of a trade confirmation message provided when placing a limit order.

Account Depreciation
{
    "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",
	"OrderId": "52323005"
}


See also the live sample on Trade messages (with source).