OpenAPI

RELEASED CHANGES

Planned December 2023 - BREAKING

Permanent change to use Extended AssetTypes

After introducing Extended AssetTypes more than two years ago, we're ready to deprecate the old AssetTypes and this means everybody will start receiving the new set of Extended AssetTypes starting from December 2023.

This will affect a lot of applications, so please make sure to carefully check whether or not your application will be impacted by this.

To read more about the change and find instructions on how to check the impact, see our guide here: Extended AssetTypes.

Please notice: All applications in our Simulation environment (SIM) have already automatically been switched to Extended AssetTypes from October 2023.

Removal of DeltaHedgeType, ExpiryCut, and DeltaHedgeData  fields (trade/v1/prices/multileg)

Due to the deprecation the Trade on Quote trading flow from OpenAPI, we will be deprecating the DeltaHedgeType, ExpiryCut, and DeltaHedgeData fields from the trade/v1/prices/multileg and trade/v1/prices/multileg/subscriptions endpoints.

The instruments impacted will be FxOptions, as all other AssetTypes are traded via our order based trading flow. As these fields are specific to FxOptions Asset Types, they will be removed.

Planned October 2023 - BREAKING - Released November 2023

Removal of Trade on Quote functionality (trade/v1/positions)

Due to high complexity and low usage we will be deprecating the Trade on Quote trading flow from OpenAPI, we will remove the POST trade/v1/positions endpoint.

The only instruments impacted will be FxOptions as all other AssetTypes are traded via our order based trading flow.

Planned November 2022 - POTENTIALLY BREAKING - Released January 2023

Change to functionality in PUT ca/v2/elections (On or after November 2022)

While changing and withdrawing previous elections are allowed for most of the voluntary events, some events have special terms that once submitting the elections, investors are not be allowed to change or withdraw these elections. Today it is possible to submit changes or withdrawal via OpenAPI and such elections are handled in later stages.

After this change,

  • the PUT ca/v2/elections endpoint will reject an election base on the AllowedAction settings of the options. Error codes ChangeInElectionNotAllowed and WithdrawalOfElectionNotAllowed will be responded together with their messages respectively;
  • the GET /ca/v2/events will respond the additional AllowedAction in each options to indicate which actions are allowed on this option. For most of the voluntary events, the AllowedActions will be ["Change", "Withdrawal"];
  • these election rules will also take place in the PUT ca/v2/elections/bulk endpoint.

As an example, assume that an event has 2 options, option 1 allows change and withdrawal while option 2 disallows change and withdrawal, it's response of GET /ca/v2/events will be:

GET /ca/v2/events
{
    "EventId": "9652429",
    "Electable": "Electable",
    "ElectionStatus": "NotElected",
    ....
    "Options": [
        {
            "AllowedActions": ["Change", "Withdrawal"],
            "OptionId": "1"
            ...
        },
        {
            "AllowedActions": [],
            "OptionId": "2"
            ...
    ]
}

After making the initial election, further changes on Option 1 will still be available. But changes or withdrawals on Option 2 will be rejected.

PUT ca/v2/elections
{
  "AccountKey": "2y0tX0m9ZH7MH8HK38qM9g==",
  "EventId": "9652429",
  "Options": [
    {
      "Amount": 200,
      "OptionId": "2",
      "Remarks": "I want to change the amount to 200 on option 2."
    }
  ]
}


400 - Bad Request
{
  "Message": "Option 2 has already been elected once. Election cannot be updated further on this option.",
  "ErrorCode": "ChangeInElectionNotAllowed"
}
PUT ca/v2/elections
{
  "AccountKey": "2y0tX0m9ZH7MH8HK38qM9g==",
  "EventId": "9652429",
  "Options": [
    {
      "Amount": 0,
      "OptionId": "2",
      "Remarks": "I want to withdraw my election on option 2."
    }
  ]
}


400 - Bad Request
{
  "Message": "Option 2 has already been elected once. Withdrawal is not allowed from this option now.",
  "ErrorCode": "WithdrawalOfElectionNotAllowed"
}


Planned November 2022 - BREAKING - Released December 2022

Removal of a number of fields in the trade/v2/orders, trade/v2/orders/multileg , trade/v2/orders/precheck and trade/v2/orders/multileg/precheck resources:

The following fields are planned for removal (On or after November 2022)

Field Comment
OrderDuration.ExpirationDatePlease use ExpirationDateTime instead.
OrderDuration.ExpiryTimeOnExchangePlease use ExpirationDateTime instead.

Planned October 2022 - BREAKING - Released December 2022

Removal of a number of fields in the trade/v1/allocationkeys resource:

The following fields are planned for removal (On or after October 2022)

Field Comment
PredefinedQuantityPlease use TotalUnitValues instead.

Planned November 2022 - BREAKING - Released November 2022

Deprecation of /details resources under port/v1/orders, positions, netpositions, and closedpositions

These resources will be removed from OpenAPI on or after November 2022.

All fields that are currently available in the Details FieldGroups have been moved to root model under each respective entity (all fields under /orders/{ID}/details are now in the /orders/{ID} route, etc). A new FieldGroup has been added for "Costs", which covers the cost data that was previously available in the /details resource.

Moving these fields to the base route instead of a designated /details resource comes with the added benefit that all values can now be streamed, which allows for creating a more interactive front-end experience. Consumers currently using /details should instead use /positions/{PositionId} and add all available FieldGroups. This will allow for a seamless transition away from the /details resource.

For detailed information, see this in-depth explanation/guide: https://www.developer.saxo/openapi/learn/deprecation-of-details-resources-in-portfolio-service-group

Removal of a number of fields in the port/v1/positions resource:

The following fields are planned for removal (On or after November 2022)

Field Comment
PositionBase.RelatedOpenOrders.Duration.ExpirationDatePlease use ExpirationDateTime instead.

Removal of a number of fields in the port/v1/orders resource:

The following fields are planned for removal (On or after November 2022)

Field Comment
Duration.ExpirationDatePlease use ExpirationDateTime instead.

Removal of "SinglePosition" FieldGroups in port/v1/netpositions (On or after November 2022)

The below three FieldGroups will be removed from the NetPositions resource (the static endpoints and streaming service). Instead of these FieldGroups, the port/v1/positions endpoints can be used to retrieve single instances of positions. The netposition response includes a field indicating the number of single positions that make up the netposition: NetPositionView.PositionCount (this field remains unchanged).

The following operations/resources will be affected by this change:

  • GET port/v1/netpositions
  • GET port/v1/netpositions/{NetPositionId}
  • GET port/v1/netpositions/me
  • POST port/v1/netpositions/subscriptions
FieldGroupResponse FieldComment
SinglePositionSinglePosition.PositionIdAlternative: port/v1/positions → PositionId
SinglePositionBaseSinglePosition.PositionBaseAlternative: port/v1/positions → PositionBase
SinglePositionViewSinglePosition.PositionViewAlternative: port/v1/positions → PositionView


Planned October 2022 - BREAKING - Released November 2022

Removal of a number of fields in the port/v1/orders resource:

The following fields are planned for removal (On or after October 2022)

Field Comment
TradeAllocationKeyPlease use AllocationKeyId instead.

Planned October 2022 - BREAKING - Released October 2022

Change to functionality in PUT ca/v2/elections (On or after October 2022)

It will not longer be possible to make a corporate action election with the sum of elected amounts being zero (0).

Today it is possible make an election in which the sum of elected amounts is 0.

As an example, assume that the total eligible amount for a given even is 100. 

Today this will be accepted:

PUT ca/v2/elections
{
  "AccountKey": "2y0tX0m9ZH7MH8HK38qM9g==",
  "EventId": "9652429",
  "Options": [
    {
      "Amount": 0.0,
      "OptionId": "1",
      "Remarks": "Electing on 0 holdings for option 1."
    },
    {
      "Amount": 0.0,
      "OptionId": "2",
      "Remarks": "Electing on 0 holdings for option 2."
    }
  ]
}

This will not be possible after this change!

Also, assume the client has already made an election for the amount of 50 for option 1 but 0 for option 2.  Today the client can actually make a subsequent election of 0 for option 1 to indicate that he is still undecided.

After the change this will no longer be possible as this would again bring the total elected amount back to 0.

Removal of the cs/v1/audit/activities resource:

This endpoint will be removed from OpenAPI (on or after October 2022).

Removal of a number of fields in the cs/v1/tradingconditions/instrument resource:

The following fields are planned for removal (On or after October 2022)

Field 

Comment

InternalCosts.TrailingCommissionPctPlease use RetrocessionPct  instead.
CurrencyCutSpreadRatePlease use CurrencyConversion instead.

Removal of a number of fields in the cs/v1/tradingconditions/contractoptionspaces:

The following fields are planned for removal (On or after October 2022)

Field 

Comment

CurrencyCutSpreadRatePlease use CurrencyConversion instead.

Removal of a number of fields in the cs/v1/tradingconditions/costs resource:

The following fields are planned for removal (On or after October 2022)

Field 

Comment

Cost.Long.HoldingCost.TomNextPlease use SwapPoints instead.
Cost.Short.HoldingCost.TomNextPlease use SwapPoints instead.

Removal of a number of fields in the cs/v1/cashmanagement/wiretransfers/instructions resource:

The following fields are planned for removal (On or after October 2022)

Field 

Comment

RemitterInfo.AttainKeyPlease use AccountId   instead.


Removal of a number of fields in the port/v1/balances resource:

The following fields are planned for removal (On or after October 2022)

Field 

Comment

ShareSpendingPower Please use SpendingPowerDetail.Maximum instead
SpendingPower Please use the SpendingPowerDetail.Current instead
SrdSpendingPower Please use the SpendingPowerDetail.Current instead
FirstFundingDateNOTE: There is no replacement for this field. The field was only applicable for a very limited set of account types and never in use.



Planned - June 2022 - BREAKING - Released July 2022:

Removal of a number of fields in the cs/v1/tradingconditions/instrument resource:

The following fields are planned for removal (On or after June 2022)

Field Comment
ExchangeFeePlease use ExchangeFeeRules instead
FinanceInterestMarkUpPlease use the FinancingInterest section instead
InterestRateMarginRequirementPlease use the InterestRateInstrumentMarginRequirement section instead
LoanInterestChargePlease use the LoanInterest section instead
MarginRequirementsPlease use InstrumentMarginRequirements instead
MaxOrderAutoPlaceAmountPlease use FxSpotMaxOrderAutoPlaceAmount  or FxForwardMaxOrderAutoPlaceAmount instead
MaxStreamingAmountPlease use FxSpotMaxStreamingAmount  or FxForwardMaxStreamingAmount instead
SwapInterestMarkUpPlease use the SwapPoints section instead

Planned - May 2022 - Potentially BREAKING - Released May 2022

Changing value returned in NetPositionId (Potentially BREAKING)

On, or shortly after May 1st. 2022 we will be changing the value returned in the NetPositionId field, which can be found on the /port/v1/positions, /port/v1/netpositions  and /port/v1/closedpositions resources.

The intended purpose of the NetPositionId field is to represent a summation/grouping of positions, which should be related based on a scope, such as Client, AccountGroup or Account. No other meaning should be inferred from the NetPositionId!

Since the NetPositionId is a temporary construct it is synthesized from a combination of several factors. Currently you may see a NetPositionId of "APPL:XNAS__Stock". After the change being introduced on or after May 1st 2022, the NetPositionId may instead be "9834780_xyz", or "OTgzNDc4MF94eXoK".

The intended purpose of NetPositionId serving as a temporary group of related positions will continue to hold.

What to check?

Please review you usage of NetPositionId. If you only use it for the purpose of identifying a group of related positions, you do not need to do anything.

If on the other hand you somehow parse the value returned in NetPositionId and use this to infer something about the instrument on which the grouping is made, then you must change your code!

This usage was never intended and going forward this will no longer be possible. Instead you may  look at the values of AssetType found directly on the  entity and Symbol found in the nested object "DisplayAndFormat".



Planned - January 2022 - BREAKING - Released May 2022

All resources related to CashManagement - Cash Withdrawal in the Client Service service group will be removed (On or after January  1st 2022)

We will be removing external access to all endpoints under the /cs/v2/cashmanagement/withdrawals/* route.

If you are using any of these endpoints, you should be switching to the equivalent endpoints in the AssetTransfers service group:

  • atr/v1/cashmanagement/beneficiaryinstructions - to get a list of a clients registered beneficiary instructions
  • atr/v1/cashmanagement/withdrawallimits - to retrieve the maximal amount which can be withdrawn
  • atr/v1/cashmanagement/withdrawals - to submit a cash withdrawal request.


Planned - April 2022 - Potentially BREAKING - Released April 2022

Introduction of HTTP/2 and Akamai acceleration for Saxo Bank OpenAPI (Potentially BREAKING)

On or shortly after April 1st. 2022 we will be introducing HTTP/2 and Akamai acceleration for Saxo Bank OpenAPI.

This is to optimize performance. We expect this to be non-breaking for almost all of our client applications, but we still encourage you to read this article and perform the suggested tests.

Planned - March 2021 - BREAKING - Released December 2021

Correction of naming in AutoTrading ServiceGroup (On or after March 1st 2021) 

We will be correcting two field names within the at/v3/tradeleaders resource:

  • MaxInvestAmt and MaxInvestAmtDescription will be removed during March 2021
  • MaxInvestmentAmount and MaxInvestmentAmountDescription will be added during December 2020 to replace them.

Planned - November 2021 - Released November 2021:

Introduction of Extended AssetTypes

To facilitate a better separation of instruments with different properties, Saxo Bank has decided to redefine the AssetType enumeration. In the following we will refer to this refined definition as "Extended AssetTypes".

If we were to enforce this, it would be a breaking change, so currently we will only introduce the new definition for new applications, created after Nov 1st 2021. At that time we will also switch the developer portal to work with this new definition.

Please read this description on Extended AssetTypes for further information.

Planned - March 2021 - BREAKING - Released September/October 2021:

Removal of ISINCode field from endpoints in ClientServices (On or after March 1st 2021)

We will be removing the ISINCode field from the following endpoints under the ClientServices service group:

  • cs/v1/reports/closedpositions
  • cs/v1/reports/trades

Removal of CashAvailableForWithDrawal field in Portfolio (On or after March 1st 2021)

We will be removing the CashAvailableForWithdrawal field from:

  •   port/v1/balances

The value returned was not always accurate, and improving this would be computationally very expensive, especially for an endpoint which is used heavily. Applications which require this number - for the purpose of letting a client determine how much money to actually withdraw - can explicitly call the atr/v1/cashmanagement/withdrawallimits endpoint.

Planned September 2020 - Released October:

Id Upscaling and correction of types for a few Id's - Potentially BREAKING (On/after Sept. 1st 2020)

With Saxo Banks rapid growth, we are soon approaching the point where several identifiers including PositionIds, OrderIds, and TradeIds reach the number of '2.147.483.647'.

We expect this to happen between October 2020 and December 2020.

We are informing you about this for two reasons.

If you are storing such Id's in an integer your code may break!

In many programming languages 2.147.483.647 is the maximum positive number, which can be stored in an integer. If your code is written to interpret or store such Ids as integers, there is a risk that your code will break when our ids pass that barrier.

Almost everywhere in our API have we defined such ids as strings, and if you have also used a string representation in your code, you should not experience any problems.

If on the other hand - for whatever reason - you have converted these strings to integers in your code, you must now start to consider the impact of the Id's passing the magic 2.147.483.647 number!

We must actually update the type of a few in-frequently used fields in our API from 'int' to 'string' - BREAKING! (On or after September 1 2020)

When reviewing this issue, we unfortunately found two API endpoints, which did not represent these ids as strings.

Since the fields are used very infrequently we have decided to make minor BREAKING changes as outlined below.

Service Group

Release notes

Client Services

GET /cs/v1/reports/closedPositions/{ClientKey}/{fromDate}/{toDate}

BREAKING The field 'OpenPositionId' in the response will be changed from integer to string.

BREAKING The field 'ClosePositionId' in the response will be changed from integer to string.

Trade

POST /trade/v1/prices/subscriptions

BREAKING The field 'ToClosePositionId' in the PriceRequest will be changed from integer to string.

Planned May 2020 - Released May 2020:

Trade Allocation Keys are no longer allowed to include a broker account - Breaking! (On or after May 1st)

While not recommended, it is currently possible to specify an allocation key in which one of the participating accounts is the brokers block trading account.

It is not allowed for a broker account to participate in a block trade allocation. This restriction has been enforced in our UI's for the past two years. With the release on or after May 1st. the restriction will also be enforced in OpenAPI.

Background

In case the traded amount doesn't match the total number of units in the key, there can be one or several remainders when allocation, typically through partial fills. Therefore an allocation key must always include at least one account designated to receive the remainder.

Until now it has been possible - through OpenAPI - to specify an allocation key, where:

  • All of the client accounts have been specified an AcceptRemainderAmount property set to false, 
  • The broker account is also included, but with the AcceptRemainderAmount property set to true and a UnitValue property of 0

As a result any remainder would be placed on the brokers account.

After the upcoming release on or after May 1st, this will no longer be possible.

At that time::

  • An allocation key can only include client accounts.
  • One of these accounts must have the AcceptRemainder property to true.

Trying to create a key which violates these rules will be rejected.

Trying to place an order, with a previously defined key which violates these rules, will also be rejected.



Planned December 2019 - Released January 2020:

Correction of Error on hist/v3/perf and at/v3/tradeLeaders endpoint - Potentially Breaking. (on or after Dec 1st)

Around Dec. 1st we will correct an error in two end points returning time weighted portfolio performance. The two end points are:

In the Account History service group:

hist/v3/perf/{ClientKey}/?AccountGroupKey={AccountGroupKey}&AccountKey={AccountKey}&FromDate={FromDate}&ToDate={ToDate}&StandardPeriod={StandardPeriod}&MockDataId={MockDataId}&FieldGroups={FieldGroups}


In the AutoTrading service group:

at/v3/tradeLeaders/?StandardPeriod={StandardPeriod} and openapi/at/v3/tradeLeaders/{TradeLeaderId}/?StandardPeriod={StandardPeriod}.

When investigating the sections:

  • AccoumulatedTimeWeightedTimeSeries and 
  • BenchMarkPerformance

you will find that both endpoints return data for a date one day out of the requested range.


For example if the caller specifies a FromDate=2019-01-01, the response will also include an entry for 2018-12-31, with a value of 0. Once our change is released, we will no longer return data outside the specified range.

As an example. Currently we will return this:


After the change has been released we will instead return:


Removal of SingleAndClosedPositions array in NetPositions endpoint - Breaking (On or after Dec 1st).

Please beware that during November we will no longer support the SingleAndClosedPositions struction in the NetPositions resource. This as been marked obsolete/do not use since June.

Your application should not specify the field values "SingleAndClosedPositionsBase" and "SingleAndClosedPositionsView" as FieldGroup values when requesting data. Further, we will no longer return the SingleAndClosedPositions array in the response. Analysing how a few apps used this array, we found that they were all only fetching this data to get a count of the underlying positions included in the net position. This value is now found in the NetPositionView.PositionCount.

Note: We are only releasing this with short notice as we have no known apps using this data structure.



Planned October 2019 - Released December 2019: 

Removal of TradeSessions field group enum value in Instrument Details - Breaking

By October 2019 we will remove the enum value "TradeSessions"  used when calling /ref/v1/instruments details.

This enum will be replaced with the value "TradingSessions".

Providing the "TradingSessions" enum value will have the same functionality as currently providing the "TradeSessions" value. The renaming ensures consistency between the enum value, and the name of the field group actually selected (which is in fact called TradingSessions).

There is no change to the response contract.

Removal of UtilzationPct field in LineStatus structure in Balances endpoint - Breaking

By October 2019 we will remove the field named "UtilzationPct" from the LineStatus structure. This structure is returned by several properties within the response from the port/v1/balances endpoint.

The field will be replaced with a field called "UtilizationPct" with exactly the same meaning. Please use this instead.

Removal of trade/v1/orders endpoint

By October 2019 we will finally remove support for trade/v1/orders. Please use the trade/v2/orders endpoint instead.


Planned September 2019 - Released December 2019:

Removal of AskSwap and BidSwap from trade/v1/InstrumentPriceDetails structure in InfoPrices and Prices endpoint - Breaking

By September 2019 we will remove the AskSwap and BidSwap fields from the InstrumentPriceDetails structure. This structure is currently returned from the trade/v1/infoprices and trade/v1/prices endpoints.

The fields will be replaced with the new fields SwapAsk and SwapBid with exactly the same value and meaning, please use these instead.

Removal of DisplayName from trade/v1/ messages endpoint - Breaking

Removed as the contents of this field was always just an empty string "".

Planned November 2019  - Released November 2019 in most regions.

Removal of support for TLS 1.0 and 1.1 - Potentially Breaking

Please beware that by November 1st we will no longer support connections using TLS 1.0 or 1.1. We are making this move in order to ensure a higher level of transport security and due to the fact that TLS 1.0 and 1.1 are planned to be deprecated during 2020.

You must make sure that your connection software supports TLS 1.2.

Planned February 2019 - June 2019 - Released July 2019:

OrderId remains the same for partially filled orders held overnight - Potentially Breaking

In January we will introduce a change whereby an order will retain the same order id, even if the order is filled over several exchange sessions. This change will make it easier to keep track of an order and the position or positions created as the result of the order being filled.

The details of this change and how it may impact you is described in the enclosed article: RELEASED: OrderId remains the same for partially filled orders held overnight.

Planned April 2019- June 2019 - Released June 2019:

Removal of Commissions precheck response - Breaking

By April 2019 we will remove the Commissions:CommissionsDetailed field from the /trade/v2/orders/precheck endpoint.

Specifically: 

  • Commissions will no longer be a valid value for PreCheckOrderSpec.
  • The Commissions field group will no longer be returned.

Instead please use the Cost fieldgroup instead, which also includes a commissions component.

Planned for January 2019 - May 2019 - Final stage completed June 2019: 

New Order Types for FX instruments - Potentially Breaking

In an effort to simplify order placement for FX instruments, we will be transitioning from one set of stop orders to another set of stop orders. The details of this change and how it may impact you is described in the enclosed article: RELEASED: New Order Types for FX Instruments.

In order to make the transition as smooth as possible the change will be rolled out over the period of January 2019- May 2019.

Planned for February 2019 - Released February 09:

Removal of MaxExposure from Trading Conditions response 

In February we will no longer provide a value for the MaxExposure field returned from the /cs/v1/tradingconditions/instrument endpoint. The field is already nullable.

Planned for January 2019 - Released February 09:

Removal of MarginImpactDetailed from precheck response - Breaking

By early January 2019 we will remove the MarginImpactDetailed field group from the /trade/v2/orders/precheck endpoint.

Specifically: 

  • MarginImpactDetailed will no longer be a valid value for PreCheckOrderSpec.
  • The MarginImpactDetailed field group will no longer be returned.

Instead please use the MarginImpactBuySell fieldgroup instead.


Planned for August 2018 - Released Nov 24.

New Tick Sizes when Placing FX Orders

Until now, FX instruments have only had one tick size which was defined by the field 'TickSize' under instrument details.

As of today we will operate with three separate tick sizes when placing orders:

  • TickSize: to be used for IOC and FOK orders.
  • TickSizeLimitOrder: to be used for Limit orders
  • TickSizeStopOrder: to be used for Stop orders.


GET https://gateway.saxobank.com/sim/openapi/ref/v1/instruments/details/21/FxSpot/
{
  "AmountDecimals": 6,
  "AssetType": "FxSpot",
  [...],
  "Symbol": "EURUSD",
  "TickSize": 0.00005,
  "TickSizeLimitOrder": 0.0001,
  "TickSizeStopOrder": 0.00005,
  [...],
  "Uic": 21
}


Until August 15th we will not enforce these new tick sizes when placing orders and instead continue to accept the standard tick size for all orders. After August 15th any order not using the correct tick size for its order type will be rejected.

This will not affect any non-FX instruments.