The reference data services supports delivering base data on instruments (details and summaries), option roots, option spaces and future spaces. In addition it also provides list of other mostly static data like exchanges, supported languages etc. When looking up data through OpenAPI, only instruments that the user is set up for, will be returned.

Data Model

Instruments

An instrument represents a financial instrument (across different asset classes) in which you can (usually*) have a position. It uniquely identifies what you are trading or holding a position in, and executing a trade on an instrument will result in your net position on that instrument being affected. Most instruments are uniquely identified by the combination of UIC and AssetType. For option instruments additional parameters are introduced. See the section on options for details.

There are two main cases when different instruments will share the same UIC:

1) A Forex currency-pair will have the same UIC for all relevant AssetType variations (FxSpot, FxForwards, FxVanillaOption, FxBinaryOption, FxKnockInOption, FxKnockOutOption, FxOneTouchOption, FxNoTouchOption).

2) If there is a corresponding CfdOnStock for a Stock (which is generally the case), they will share a UIC.

* Stock Indices are a case of an instrument which is non-tradeable. Despite never being tradeable, the ability to treat them as instruments allows better logical grouping and navigation of instrument relations and a convenient way to access chart data.

Option Instruments

Option instruments, in addition to their UIC and AssetType, are also identified by whether the contract is a Put or Call and, depending on the type of option, a Strike or Barrier. Forex options will have a Uic matching the related spot currency-pair, Futures options (and stock and index options) will have a unique Uic for each contract variation.

Underlying Instruments

An underlying instrument refers to the relationship between a future and an option on the future, between a stock and a cfd on that stock, etc. Each side of this bidirectional relationship is found in the RelatedInstruments of the other when retrieving instrument details. As a cfd on a stock and a stock will share UIC, this is mostly relevant when working with options. When using the ContractOptionsSpace endpoint, the underlying for each option is specified directly. Needing the uic of underlying contract for an option (in order to make a price subscription, and determine which strikes are in in the money) is a very common scenario.

Option Roots

It is important to note that Contract Option Roots are not instruments per se (i.e. you cannot trade a or hold a position in them), but they represent a collection of strongly related option instruments. Root IDs are used to identify Contract Option Roots, and these cannot be used interchangeably with UICs.

Instrument search may return a UIC or a Root ID in the Identifier field. Use SummaryType to determine which type of identifier it is. Instrument means it is a UIC, ContractOptionRoot means it is a Root ID. Use /v1/Instruments/contractoptionspaces/ to look up which instrument UICs belong to a Root ID. Further detail on the results can be retrieved via the normal endpoints accepting a UIC. This means that getting the details for all options under a root requires a two-step process of retrieving the contract option space and the enumerating the result and calling the v1/instrument/details/{Uic}{AssetType} end point.

Summary vs Details

Instrument data can be returned in two different formats. Details represent the full set of data regarding an instrument, whereas a Summary has limited data. Summaries are suitable for displaying a list of instruments without any related price, position or order data. Details are needed to properly format prices, to determine what accounts a trade can be made on and/or to create proper validation of an interactive trading application.

Data is a mixture of properties relevant to validating order and trade placement and properties relevant to display and format.

Validation	Display, Format and Defaults	Important Meta Data
IsTradable LotSize LotSizeType MinimumLotSize MinimumOrderValue SupportedOrderTypes TickSize TickSizeScheme TradableAs TradableOn	AmountDecimals DefaultAmount DefaultSlippage DefaultSlippageType Description Exchange Format Decimals OrderDecimals IncrementSize OrderDistances EntryDefaultDistance EntryDefaultDistanceType StopLimitDefaultDistance StopLimitDefaultDistanceType StopLossDefaultDistance StopLossDefaultDistanceType StopLossDefaultEnabled StopLossDefaultOrderType TakeProfitDefaultDistance TakeProfitDefaultDistanceType TakeProfitDefaultEnabled StandardAmounts Symbol TradingUnitsPlural TradingUnitsSingular Uic	CurrencyCode ExpiryDate ExpiryDateTime PriceToContractFactor PrimaryListing RelatedInstruments

ReferenceData Usage Patterns

ReferenceData endpoints can be divided roughly into three categories of usage:

1) You want some static set of data - ie all exchanges, all countries, all languages, etc.

/v1/countries
/v1/cultures
/v1/currencies
/v1/exchanges
/v1/languages
/v1/timezones

2) You want to search for instruments that fulfill a given set of criteria. When using keyword search, the keywords supplied will be checked against a variety of fields, including symbol code, description and an internal list of keywords. These keywords can be commonly used aliases (ie Google for Alphabet) or contextually relevant search words (ie Oil for various oil-related commodity contracts).

/v1/instruments (summaries)
/v1/instruments/details (details)

3) You have a UIC or Root ID provided by a different end point and need to look up the relevant details. This is typically formatting data, but can also be what accounts an instrument is tradeable on, related instruments, or actual reference data.

/v1/exchanges/{ExchangeId}
/v1/instruments/contractoptionspaces/{OptionRootId}
/v1/instruments/details/{Uic}{AssetType}
/v1/instrument/futuresspaces/{ContinousFuturesUic}

Example - Finding KO:xnys

Finding instrument data for stock of The Coca Cola Company on NYSE.

In order to look up that instrument we have to find its unique identifier, so a starting point is to use the /openapi/ref/v1/instruments endpoint to search for instruments summaries matching the data we have. Coca Cola is listed on many exchanges and exist as both a Cfd and a Stock, so those parameters help limit the number of search results. The below example shows how such a query returns 3 results, where the one we are interested in is number 2.

GET https://gateway.saxobank.com/sim/openapi/ref/v1/instruments?ExchangeId=NYSE&Keywords=Coca Cola&AssetTypes=Stock

HTTP/1.1 200 OK
[
	...,
	{
		"AssetType": "Stock",
		"Description": "Coca-Cola Co.",
		"ExchangeId": "NYSE",
		"Identifier": 307,
		"PrimaryListing": 307,
		"SummaryType": "Instrument",
		"Symbol": "KO:xnys",
		"TradableAs": [
			"Stock"
		]
	},
	...
}

In cases where there are more than one result, the right one can usually be derived from the symbol and the description fields. In this case the fact that the primary listing is the same as the search results identifier is also a strong indication that this is what we looked for.

The next step is to look up the actual instrument's base data (result truncated for clarity):

GET https://gateway.saxobank.com/sim/openapi/ref/v1/instruments/details/307/Stock
 
HTTP/1.1 200 OK
{
	"AssetType": "Stock",
	"CurrencyCode": "USD",
	"Description": "Coca-Cola Co.",
	"Exchange": {
		"CountryCode": "US",
		"ExchangeId": "NYSE",
		"Name": "New York Stock Exchange"
	},
	"Format": {
		"Decimals": 2
	},
	"IncrementSize": 1,
	"IsTradable": true,
	"MinimumOrderValue": 50,
	"PrimaryListing": 307,
	"RelatedInstruments": [
	{
		"AssetType": "CfdOnStock",
		"Uic": 307
	}
	],
    "RelatedOptionRoots": [
        485
    ],
	"SupportedOrderTypes": [
		"Limit",
		"Market",
		"StopIfTraded",
		"TrailingStopIfTraded",
		"StopLimit"
	],
	"Symbol": "KO:xnys",
	"TickSizeScheme": {
		"DefaultTickSize": 0.01,
		"Elements": [
		{
			"HighPrice": 0.9999,
			"TickSize": 0.0001
		}
		]
	},
	"TradableAs": ["Stock"],
	"TradableOn": ["339070INET"],
	"Uic": 307
}

From the returned data we can see that prices on the instrument should be formatted with two decimals and that order prices are either rounded to 0.01 or 0.0001 depending on whether the price is equal to or above 1. It can also be traded as a cfd and that the calling client can trade it on account 339070INET. The instrument can be traded with 5 different order types, although not all of them are supported for an entry order.

Futures and Option Space

For futures and options OpenAPI supports dedicated endpoints for navigating series of instruments.

Option Spaces

The entire universe of options under an option root can be quite large. In their most basic form, they can be retrieved by their option root id. In the example above the Coca-Cola company has a related option root id of 485. The specific options on that stock can then be found by the following request:

GET https://gateway.saxobank.com/sim/openapi/ref/v1/instruments/contractoptionspaces/485
 
{
  "AmountDecimals": 0,
  "AssetType": "StockOption",
  "ContractSize": 1000,
  "CurrencyCode": "GBP",
  "DefaultAmount": 1,
  "DefaultExpiry": "2017-03-17T00:00:00Z",
  "DefaultOption": {
    "PutCall": "Call",
    "StrikePrice": 215,
    "Uic": 4061136,
    "UnderlyingUic": 860
  },
  "Description": "Legal & General Group Plc.",
  "Exchange": {
    "CountryCode": "GB",
    "ExchangeId": "ICE_LIF",
    "Name": "ICE Futures Europe – Financials"
  },
  "ExerciseStyle": "American",
  "Format": {
    "Decimals": 2,
    "OrderDecimals": 2,
    "StrikeDecimals": 2
  },
  "IncrementSize": 1,
  "IsTradable": true,
  "LotSize": 1,
  "LotSizeType": "OddLotsNotAllowed",
  "OptionRootId": 385,
  "OptionSpace": [
    {
      "DisplayDaysToExpiry": 215,
      "DisplayExpiry": "2017-10-01",
      "Expiry": "2017-10-20",
      "SpecificOptions": [
        {
          "PutCall": "Put",
          "StrikePrice": 190,
          "Uic": 5289662,
          "UnderlyingUic": 860
        },
        {
          "PutCall": "Put",
          "StrikePrice": 230,
          "Uic": 5289663,
          "UnderlyingUic": 860
        },
...

From the result we can see that 5289662 is the Uic for the first specific Coca-Cola StockOtption, but also that the resulting data set is huge. Due to the result's size, it is common to want to limit the data returned. This is controlled by the OptionSpaceSegment parameter.

OptionSpaceSegment	Example	Comment
AllDates	GET /sim/openapi/ref/v1/instruments/contractoptionspaces/10?OptionSpaceSegment=AllDates	Default. The entire option space
DefaultDates	GET /sim/openapi/ref/v1/instruments/contractoptionspaces/10?OptionSpaceSegment=DefaultDates	Will return the option space, but only the specific options for the first expiry date
None	GET /sim/openapi/ref/v1/instruments/contractoptionspaces/10?OptionSpaceSegment=None	Used to lookup the optionspace common data with no specific options
SpecificDates	GET /sim/openapi/ref/v1/instruments/contractoptionspaces/10?OptionSpaceSegment=SpecificDates&ExpiryDates=2017-04-21	Used to lookup the option space, but only the specific options that matches the provided expiry date
UnderlyingUic	GET /sim/openapi/ref/v1/instruments/contractoptionspaces/10?OptionSpaceSegment=UnderlyingUic&UnderlyingUic=2456771	Used to lookup a specific option in a space by the Uic of a specific option

Future Spaces

A future space are ContractFutures in the same series with different expiry dates. They can be found through their non-tradable parent future. A common scenario is to have a non-tradable ContractFutures instrument (with DisplayHint "Continouous") and then use that to, navigate´to tradable instances of that instrument

GET https://gateway.saxobank.com/sim/openapi/ref/v1/instruments/details?AssetTypes=ContractFutures&Uics=4034
{
  "Data": [
    {
      "AmountDecimals": 0,
      "AssetType": "ContractFutures",
      "ContractSize": 1000,
      "CurrencyCode": "USD",
      "DefaultAmount": 0,
      "DefaultSlippage": 0,
      "DefaultSlippageType": "Ticks",
      "Description": "Light Sweet Crude Oil (WTI) - continuous",
      "DisplayHint": "Continuous",
	  ...
	}]
}
 
GET https://gateway.saxobank.com/sim/openapi/ref/v1/instruments/futuresspaces/4034

HTTP/1.1 200 OK
{
  "BaseIdentifier": "CL",
  "Elements": [
    {
      "DaysToExpiry": 21,
      "ExpiryDate": "2017-03-21",
      "Symbol": "CLJ7",
      "Uic": 3124672
    },
    {
      "DaysToExpiry": 51,
      "ExpiryDate": "2017-04-20",
      "Symbol": "CLK7",
      "Uic": 3346801
    },
	...
  ]
}

How to Interpret Not Found (404)

When calling /v1/instruments/details/{Uic}{AssetType} you may experience a 404. This can generally mean one of three things:

1) Your combination of client and accounts does not have access to detailed information for this instrument

2) The instrument has been temporarily or permanently delisted.

3) The instrument never existed

Depending on this reason for the 404 you may still be able to get a summary for the instrument by calling /v1/instruments/ (use IncludeNonTradable as relevant).

Account and Client-Specific Reference Data

Many endpoints take an optional AccountKey, Note that instrument availability and details may change between accounts, and if an application locally caches the result of requests, these should not be considered interchangeable for different values of AccountKey.

Looking up Several Instrument Details

When looking up multiple instruments it is preferable to use batching as there is optimized processing in place for this. Specifically calls to: /v1/instruments/details/{Uic}{AssetType} should be batched, as detailed in Batching.

TickSize and TickSizeSchemes

Tick sizes denotes how to round prices when placing an order. Order prices not conforming to the instrument's tick size rules will be rejected.

This HighPrice is the highest price to still use the tick size for rounding. This means that a HighPrice+TickSize (from the same band) is a valid price.

Example:

"TickSizeScheme": {
   "DefaultTickSize": 0.01,
   "Elements": [ { "HighPrice": 0.199,
       "TickSize": 0.001
     },
     {
       "HighPrice": 1.995,
       "TickSize": 0.005
     }
   ]
 }

Transformed into a series of intervals we get this.

From	To	Tick Size
0.001	0.2	0.001
0.2	2	0.05
2	x	0.01

Meaning that a price of 0.028 is in the ]0.001; 0.2] interval and should be rounded to 0.001.

How can an Instrument be Traded

There are fields that determines if, how and where an instrument can be traded. Pricing may be limited to accounts where the instrument can be traded.

IsTradable

On some instruments like StockIndex and ContinuousFutures you may be able to get a price, but you can't trade. This flag determine whether the specific instrument can be traded.

TradableOn

Shows what accounts the specific instrument can be traded on. In the portfolio services for clients and account values broadly indicate what asset types can be traded on what accounts, but there may be an even more specific configuration in place, so the authoritative answer to what accounts an instrument can be traded on is found directly on the instrument.

See also the live sample on the reference endpoints (with source).