OpenAPI
Open API Learn Tutorial Reference Docs Explorer Apps Updates Get 24 Hour Token Sign in
Other Products FIX Trading API Client Management Systems API End-of-Day File Transfers Trade Event Notification System OpenAPI for Excel

Session Capabilities

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 which level of market data your application is able to receive.

If trade level is OrderOnly, your application is only able to receive delayed market data.

If trade level is FullTradingAndChat, your application is also able to receive real-time market data, depending on your subscriptions. 


If you set trade level to FullTradingAndChat, you will degrade the trade level for other sessions for the same user. This might log off other Saxo trading applications including SaxoTraderGO, or downgrades the sessions to delayed prices.

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.

See the JavaScript sample for a demo (source).

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. 

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.


For example, to upgrade your session in order to leverage real-time market data subscriptions, send the below PATCH request in order to set the TradeLevel to FullTradingAndChat:

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

{
  "TradeLevel": "FullTradingAndChat"
}


202 No Body


To confirm the session's extended capabilities, see the below section.

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. The current state of the session is also available in a GET call.

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.


Monitor continuously: Session Event Subscription

Create a subscription to get changes to the session as quick as possible.

POST https://developer.saxobank.com/sim/openapi/root/v1/sessions/events/subscriptions/active HTTP/1.1
authorization: BEARER token
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 to the session 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"
      }
    ]
  }
]


Monitor intermittently: Get Session Capabilities

Make a single GET request to get the current state of the session

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


With the response showing the sesssion's current capabilities:

{
  "AuthenticationLevel": "Authenticated",
  "DataLevel": "Premium",
  "TradeLevel": "FullTradingAndChat"
}

An example response containing extended capabilities