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:
| Resources | Use for... | Supports Subscriptions |
|---|---|---|
| Trade Leaders | Trade leaders resource provides information on trade leaders. This includes:
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:
|  |
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.
| InvestmentProcessState | Investment States | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Processing |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Retry |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Error |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Starting |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Active |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Stopping |
| ||||||||||||||||||||||||||||||||||||||||||||||||
| Stopped |
|
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. | InvestmentStateId | StateName | Description | Steps to resolve |
|---|---|---|---|---|
| Error | 4 | Account creation failed | An error occurred during account creation | Contact Saxo Bank |
| Retry | 7 | Funding failed | Initial attempt at Funding has failed, but retry initiated. | Verify that the client has sufficient funds on the funding account |
| Retry | 13 | Funding pre-check failed | The pre-check executed for funding failed | Contact Saxo Bank |
| Error | 14 | Funding exception | An exception occurred during funding | Contact Saxo Bank |
| Error | 15 | Account creation exception | An exception occurred during account creation | Contact Saxo Bank |
| Retry | 21 | Funding post-check failed | Funding post-check failed | Contact Saxo Bank |
| Error | 23 | Funding pre-check exception | An exception occurred during funding pre-check | Contact Saxo Bank |
| Error | 25 | Funding post-check exception | An exception occurred during funding post-check | Contact Saxo Bank |
| Stopping | 26 | Stopout Margin Limit | The 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. |
| Stopping | 27 | Stopout protection limit | The account has hit the investment shield and has been stopped out. | The account has hit the investment shield and has been stopped out. |
| Stopping | 28 | Stopout non-specific | The account has been stopped out. Contact Saxo Bank for details. | The account has been stopped out. Contact Saxo Bank for details. |
| Stopping | 29 | Revoked terms and conditions | Acceptance of terms and conditions has been revoked | The client must accept terms and conditions |
| Stopping | 30 | Revoked suitability test | Suitability level for client has been revoked | The client must take the suitability test |
| Retry | 103 | FeeProfile assign failed | The SaxoSelect fee profile could not be assigned | Contact Saxo Bank |
| Error | 104 | FeeProfile assign exception | An error occurred during assignment of SaxoSelect fee profile | Contact Saxo Bank |
| Retry | 203 | FeeProfile unassign failed | The SaxoSelect fee profile could not be unassigned | Contact Saxo Bank |
| Error | 204 | FeeProfile unassign exception | An error occurred during unassignment of SaxoSelect fee profile | Contact 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.
| ErrorCode | Steps to resolve |
|---|---|
| NotSuitable | The client or account is not suitable for the investment:
|
| JointInactive | Leader 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.
| Property | Description | Steps to resolve |
|---|---|---|
| IsAuthorizedToFollow | Is 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. |
| IsOpenForFollowers | Does 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:
