OpenAPI

The auto trading service group provides capabilities to interact with Saxo Bank's SaxoSelect offering. This contains of a set of endpoints to explore various trade leaders in which investments can be made along with capabilities to add/maintain investments in them.

What is SaxoSelect?

SaxoSelect is an automated investment service that enables clients to conveniently invest in a wide variety of investment portfolios, leveraging the expertise of selected third parties such as Morningstar and BlackRock. In SaxoSelect a strategy manager (called trade leader in OpenAPI) buys and sells assets on a Saxo Bank trading account. An investor (called a trade follower in OpenAPI)  may choose to "invest" in the trade leader. By doing so, the trade follower instructs Saxo Banks system to create a proportional replica of the positions held by the trade leader onto an account held by the trade follower.

Whenever a strategy/model portfolio is re-balanced by the trade leader, the Select engine will send a block order to the market and once the order is filled do a post allocation to all underlying investor accounts that are tracking the strategy. 

The flow is indicated below.

SaxoTraderGO Screen shot of SaxoSelect:

On the LEFT you see the portfolios available to the client. On the right you see detailed information on a specific chosen portfolio.


AutoTrading Overview

The endpoints are grouped into resources, divided as follows:

ResourcesUse for...Supports Subscriptions
Trade Leaders

Trade leaders resource provides information on trade leaders. This includes:

  • Get details for all the available leaders.
  • Get details about a specific leader.
  • Get logo information for a leader.

An application can use this information to present available trade leaders and their performance. Clients - or trade followers - who many use this information as the basis for making an investment.


Trade Follower

A trade follower represents a client, who may be interested in making investments in one or more trade leaders. The trade follower endpoints allow the application to set and retrieve information about a trade followers suitability as it applies to investing in different trade leaders.

Typically it will be a separate part of the application which sets the suitability level. Suitability is determined on the basis of a set of questionnaires. OpenAPI supports setting the suitability level, but it does not determine which questions must be asked or how answers should be scored. This is up to the application owner.


Investments

The Investment resource provides access to possible and active investments, along with the support to start and maintain a particular investment. This includes: 

  • Get all the possible investments that a client can enter into.
  • Retrieve information on all the active investments.
  • Start a new investment which is equivalent to start following a particular trade leader.
  • Update a specific investment.
 (tick)

Typical usage :

The most common usage of this service group can be summarized in the below use case:

  • Store the suitability level of the trade follower, based on completing a suitability test.
  • Store if the trade follower has accepted terms and conditions.
  • Retrieve all trade leader portfolios available for a client. Availability is based on the clients suitability level, which instruments the client can trade, and which trade leaders have been configured for the partner the client belongs to.
    Portfolio information can be litimted or can be detailed to include a description of the portfolio, criteria such as minimum investment amount and risk level and performance data.
  • Retrieve trade follower investments as well as the trade followers suitability level, their legal instruments and if terms and conditions are accepted. 
  • Start and stop investments and check their state using the "Investments" endpoint. 
  • Perform funding and withdrawals.

Suitability

A clients suitability is determined by a suitability test and results in four levels:

  • Very High
  • High
  • Medium
  • Low

Partners must supply a suitability test, or be configured to use Saxo Bank's suitability test. A suitability test developed by the partner, must determine a clients suitability in relation to SaxoSelect, and the result must be mapped to one of the Saxo Bank suitability levels.

Trade leaders are equally configured with a required suitability level.  To follow a a trade leader requiring suitability level "High", the trade follower must have either suitability level "High" or "Very High".

Relating OpenAPI functionality to how it is being used by SaxoTraderGO

The following describes how SaxoTraderGO uses OpenAPI to create an intuitive user journey. 

Trade Leader Information

In SaxoTrader, the information found in the "TradeLeaders" resource is displayed as shown below.

At the top level each trade leader is presented in terms of key information, such as name, minimum Investment, risk level, return and top holdings

'See more' reveals further details about the portfolio/Leader:

E.g performance over various periods, risk level, fees,, Monthly return... a drawdown report, etc.

All of this can be retrieved from the "AccountPerformance" sub section of the trade leader resource.

The entries in the list of trade leaders will depend on the client's legal instruments, country of residence and what leaders are made available for the partner. Investment ability is dependend on the suitability level set for the client, as explained above.

Making an Investment

In SaxoTraderGO, to make an investment the client will select a portfolio from the overview and click "Invest". The client will be shown a summary of the investment opportunity (all available from the TradeLeaders endpoint) and can select the amount to invest.

If the client has not taken the Suitability test, then the 'Review Investment' button would say 'Take Test' and route him to the Suitability test. SaxoTraderGo makes this decision by inspecting the tradefollowers/me ressource and checking if SuitabilityLevel is greater than or equal to the suitability level requirement of the trade leader. If the suitability test has not been taken it is up to your application to ask the appropirate questions and set the suitability level. If the client is not suitiable for an investment, the call to OpenAPI to initiate an investment will fail. 

In the below example the test is already taken, and the client has been found to be suitable for the investment. 

The client just has to tick the 'I confirm..' and 'Confirm' the amount to get started.

Starting an investment is done by posting to the /at/v3/investments endpoint, specifying the following:

 

 Shortly after the POST to the /investments endpoint a new entry will appear in the  /investments collection.

The status will change as the request is processed, the new investment account is created and finally funded.

the Status will keep changing:

Until it the investment reaches an "Active" , "Error"  or "Stopped" state (look at InvestmentProcessState in the investments resource).

Investment life cycle (InvestmentProcessState)

An investment can go through several stages as outlined below:

The cycle is broken into four main stages:

  • Starting - the investment has been initiated and its creation is being processed. This includes creating an account, funding it, setting fee profile and synchronizing it with the trade leader portfolio.
  • Active - the investment has been successfully created and synchronized, and is now following the trade leader portfolio.
  • Stopping - the investment is in the process of being stopped. This includes closing positions (if selected to do so), settling pending fees and changing fee profile.
  • Stopped - the investment has succefully stopped and the funds can be returned to the funding account.

These are supplemented by three stages that detail the processing of starting or stopping an investment and if something went wrong during this process:

  • Processing - the initial stages of starting an investment, where the account is created and configured or the stopping stage of an investment where the positions are closed and fee profiles changed.
  • Retry - Something went wrong starting an investment, for instance the funding has failed. The system uses a retry schedule based on a retry interval.
  • Error  - Something went wrong starting or stopping the investment, and the process is blocked. 


Investment States

Saxo Select uses various levels of abstraction to signal the state of an investment.

The main status in the investment life cycle is available in the InvestmentProcessState field. Each high level process state is further divided into minor individual states as outlined below. These can be tracked through the InvestmentStateId field. Further, the StateName field includes a textual description of this substate. It is generally recommended that a client application does not perform special logic based on the value of InvestmentStateId, but simply displays the value of the StateName to the end user. Further remember that the list of sub states may change and be extended over time.


InvestmentProcessStateInvestment States
Processing
InvestmentStateIdStateName
1New
2Account creation in progress
3Account creation succeeded
5Funding in progress
6Funding succeeded
10Resurrected
11Funding pre-check in progress
12Funding pre-check succeeded
16Funding skipped
17Account creation entry
18Funding entry
19Funding post-check in progress
20Funding post-check succeeded
22Funding pre-check entry
24Funding post-check entry
100FeeProfile assign entry
101FeeProfile assign in progress
102FeeProfile assign succeeded
105FeeProfile assign skipped
106FeeProfile assign pending
200FeeProfile unassign entry
201FeeProfile unassign in progress
206FeeProfile unassign pending
Retry
InvestmentStateIdStateName
7Funding failed
13Funding pre-check failed
21Funding post-check failed
103FeeProfile assign failed
203FeeProfile unassign failed
Error
InvestmentStateIdStateName
4Account creation failed
14Funding exception
15Account creation exception
23Funding pre-check exception
25Funding post-check exception
104FeeProfile assign exception
204FeeProfile unassign exception
Starting
InvestmentStateIdStateName
31Starting
Active
InvestmentStateIdStateName
8Ready
Stopping
InvestmentStateIdStateName
26Stopout margin limit
27Stopout protection limit
28Stopout non-specific
29Revoked terms and conditions
30Revoked suitability test
32Stopping
Stopped
InvestmentStateIdStateName
9Disabled
202FeeProfile unassign succeeded
205FeeProfile unassign skipped


Errors and Error States 

Errors can occur at various states in the Investment cycle.  For investmentProcessState = Retry, Error, Stopping and Stopped, you can inspect InvestmentStateId and StateName for further information about the problem. 

Propose to Add InvestmentProcessState here.InvestmentStateIdStateName DescriptionSteps to resolve
Error4Account creation failedAn error occurred during account creationContact Saxo Bank
Retry7Funding failedInitial attempt at Funding has failed, but retry initiated.Verify that the client has sufficient funds on the funding account
Retry13 Funding pre-check failedThe pre-check executed for funding failedContact Saxo Bank
Error14 Funding exceptionAn exception occurred during fundingContact Saxo Bank
Error15 Account creation exception An exception occurred during account creationContact Saxo Bank
Retry21Funding post-check failedFunding post-check failedContact Saxo Bank
Error23 Funding pre-check exceptionAn exception occurred during funding pre-checkContact Saxo Bank
Error25 Funding post-check exceptionAn exception occurred during funding post-checkContact Saxo Bank
Stopping26Stopout Margin LimitThe account value has exceeded the margin limit and has been stopped out.The account value has exceeded the margin limit and has been stopped out.
Decide if investment should be restarted.
Stopping27Stopout protection limitThe account has hit the investment shield and has been stopped out.

The account has hit the investment shield and has been stopped out.
Decide if investment should be restarted.

Stopping28Stopout non-specificThe account has been stopped out. Contact Saxo Bank for details.The account has been stopped out. Contact Saxo Bank for details.
Stopping29Revoked terms and conditionsAcceptance of terms and conditions has been revokedThe client must accept terms and conditions
Stopping30Revoked suitability testSuitability level for client has been revokedThe client must take the suitability test
Retry103FeeProfile assign failedThe SaxoSelect fee profile could not be assignedContact Saxo Bank
Error104FeeProfile assign exceptionAn error occurred during assignment of SaxoSelect fee profileContact Saxo Bank
Retry203 FeeProfile unassign failedThe SaxoSelect fee profile could not be unassignedContact Saxo Bank
Error204 FeeProfile unassign exception An error occurred during unassignment of SaxoSelect fee profileContact Saxo Bank


A special case is when an Investment is active, but some external condition has changed, which should really be attended to. This is being signalled by:

  • InvestmentProcessState = "Active" , and
  • ErrorCode= <errorcode>

Note that the Investment continues in the active state, but the error should be dealt with, typcially by the client calling the broker.

If the steps to resolve don't apply to the situation, please contact Saxo Bank for assistance.

ErrorCodeSteps to resolve
NotSuitable

The client or account is not suitable for the investment:

  1. Risk e.g.trade leader requires "Very High" and client suitability test resulted in "High" - client must retake suitability test
  2. Legal instruments e.g. the trade leader requires shares and the client is not allowed to trade in shares - contact Saxo Bank
JointInactiveLeader account, follower account og follower is no longer active - contact Saxo Bank


Other important properties

In addition to the ErrorCode, an investment contains several properties which can be used to check the status and availability of a portfolio investment.

Trade follower specific information can be used to determine why an investment cannot proceed or be initiated.

PropertyDescriptionSteps to resolve
IsAuthorizedToFollowIs the trade follower authorized to follow the leader?If false: If the follower is not authorized, this is due to an insufficient suitability level.
Check if the follower macthes the leader suitability requirement.
IsOpenForFollowersDoes the trade leader have room for more followers i.e.
has the follower amount exceeded the limit
If false: Await other followers stopping or contact Saxo Bank to increase maximum investment amount for the trade leader.


Managing Investments

Trade Followers/Investors can see their portfolios listed with their Status (status of the Investment), account value etc. by calling the GET /investments endpoint or subscribing to investment updates.

The mange button allows the client to change the Account Shield, Invest more/deposit, withdraw etc.. subject to the Status of the Portfolio (e.g. if

'Stopped' the client will not be able to Deposit etc)

Updating the Investment using PATCH ... investments/{investmentid}

You may you may use the PATCH command to change some properties of a current investment. When using the PATCH command you only need to specify the values, which you want to change.

  • To stop an active investment, simply set "IsActive" to false, and use the value of PositionsCloseOnActivation to specify what should happen with the invested positions.
  • To change the InvestmentShieldAmount, simply specify a new InvestmentShieldAmount.
  • To add additional funds to an existing investment, specify that extra amount in the "PendingFunding" field, and use the value of FundingAccountKey to specify from which account this extra money should be taken from. Note you cannot specify additional funding before a previous request to fund the investment has been completed.  When pending funding is set to 0 (zero), the funding is completed.  

Withdrawing money from an investment

You may first call the /investments/{investmentid}/maxwithdrawal endpoint to get the maximum amount, which can be withdrawn from the investment. You can use this to inform the user, so they can make an informed decision about the actual amount to withdraw.

You can then call the PUT .... /investments/{investmentid}/withdraw endpoint to effectuate the withdrawal, specifying the parameters listed below: