OpenAPI

Trade and data level properties

Every session (see core API concepts) associated with a logged in user is assigned with a capability comprising two properties.

The TradeLevel property can be either:

  • OrdersOnly (default)
  • FullTradingAndChat

The DataLevel property can be either:

  • Standard (default)
  • Premium

Only one session (per user) can have the upgraded trade level of FullTradingAndChat and only one session can have the upgraded data level of Premium. If the trade level or data level is upgraded for one session associated with a user, all other sessions associated with the same user will have their trade or data level demoted to the default level. 

Currently the setting of DataLevel has no impact for 3rd party applications, and you should leave it at the default value of Standard

Trade level usage

Trade level affects how your application is able to trade.

If trade level is OrderOnly, your application is only able to place orders.

If trade level is FullTradingAndChat, your application is also able to trade on quote. 

Setting trade level to FullTradingAndChat has the effect that:

  • A price subscription for FxOptions can return a QuoteId
  • It is subsequently possible to execute a trade by posting this QuoteId to the trade/positions endpoint. (see TODO: Add link)

In practical terms you should only set the trade level to FullTradingAndChat, if your application is trading FxOptions. 

If your application is not trading FxOptions it is recommended that you leave trade level at the value OrdersOnly. Also note, that if you set trade level to FullTradingAndChat, you will degrade the trade level for other sessions for the same user. This will currently log off other Saxo trading applications including SaxoTraderGO.

Monitoring and modifying and the trade level

If your application needs the elevated trade level, it must do two things:

  1. Set up a subscription to listen for changes on the current session (e.g. upgrade or downgrade of the trade level)
  2. Request capabilities = upgrade trade level.

It is also possible to poll for current capabilities, but it is recommended to set up a subscription to get notified as soon as possible. 

Tip

Only requesting the required levels - and not setting up a subscription to listen for changes - is not recommended, since you (the client application) will be unaware when the capabilities are downgraded to the default ones, which typically happens if the same user creates a new (user) session and requests full trading capabilities on that one.

The consequence is that the client application will be working with wrong assumptions and some requests will be rejected or data is (unexpectedly) delayed.

Monitoring Trade and Data levels

A session event subscription will notify the client application (over the streaming channel) when changes to trade and data level occurs.

You may set up a session event subscription as follows:

POST https://developer.saxobank.com/sim/openapi/root/v1/sessions/events/subscriptions/active HTTP/1.1
authorization: BEARER token
content-Length: x
content-type: application/json;

{"RefreshRate":1000,"ContextId":"valid_context_id","ReferenceId":"valid_reference_id"}

The subscription will return the current levels in the response and deliver any additional updates on the streaming channel.

See the endpoint documentation for more details on this.

Also see the streaming documentation for how subscriptions work, which will also explain how context ids are defined (and how they together with sessions define streaming sessions).

Modifications will look like this:

[
  {
    "ReferenceId": "valid_reference_id",
    "Timestamp": "2017-02-06T10:28:10.187036Z",
    "Data": {
      "TradeLevel": "FullTradingAndChat"
    }
  }
]

Since changes like the above might not happen that often (depending on the user pattern), it is very likely to see heartbeat messages on the streaming channel:

[
  {
    "ReferenceId": "_heartbeat",
    "Heartbeats": [
      {
        "OriginatingReferenceId": "valid_reference_id",
        "Reason": "NoNewData"
      }
    ]
  }
]

Modifying Trade Level

When a new (user) session is created it will automatically get the trade level: OrdersOnly.

If the FullTradingAndChat capability is required, it can be requested by using the /openapi/v1/sessions/capabilities endpoint:

PATCH https://developer.saxobank.com/sim/openapi/root/v1/sessions/capabilities HTTP/1.1
authorization: BEARER token
content-Length: x
content-type: application/json;

{"TradeLevel":"FullTradingAndChat"}

Note that the response status code is a 202 Accepted with no content. It means that the upgrade will be done eventually (unless another session (for same user) does the same: that results in a race condition, where last one wins). It also means that there can be a slight delay before the capability is in place.

The trade level can be downgraded in the same manner.