OpenAPI provides three different resources for getting prices. The resources are called Prices, InfoPrices and OptionChain. A price is a large collection of values and attributes and if possible it's recommended that only those needed are requested. Prices are provided based on instruments which are defined by a combination of a Uic and an AssetType parameter (read more about instruments here). If the purpose is just to get a price, InfoPrices offers a request/response interface for a single price as well as a list of prices for a single AssetType. The Prices are intended for trading and works through setting up a subscription and getting values back on the streaming channel.
Anatomy of a price
A price consists of data in groups according to different uses. They can be requested through the use of the FieldGroup parameter on the request for a price. Data in the price is grouped as follows:
|Commissions||Costs associated with buy and sell. Dependent on client setup and account/amount|
|DisplayAndFormat||Basic reference data about how to correctly display a price. It is convenience data intended for very simple applications and it is generally recommended that an app does not use this, but instead look the full instrument up via the Reference Data|
|Greeks||Contains price sensitivity data relevant for option trading. Will be empty for all other asset types|
|HistoricalChanges||Contains percent change values for a select set of periods of longer duration like 3 months to 5 years. This is to supplement the daily percent change can be found in PriceInfo.|
HistoricalChanges are only supported for StockIndices
|InstrumentPriceDetails||Additional values which are specific to the underlying asset type|
|MarketDepth||Contains the order book for the instrument and is restricted based on feed rights|
|PriceInfo||Basic and probably common secondary price values (high, low, netchange, percentchange)|
|PriceInfoDetails||Basic and probably less common secondary price values|
|Quote||The core data about a price: delay, bid/mid/ask & price type.|
It is recommended to only ask for the field groups needed.
Values returned as part of a price is controlled by your price feed rights. Price feeds control whether prices are delayed or real time and whether there is access to market depth data. Price feeds can usually be subscribed to, to get more data. In the below example for instance the price is delayed 15 minutes.
In order to ask for a price, some parameters must be provided in order for OpenAPI to return a price. This is an overview of what is required:
|StockIndexOption||Exchange Traded Options have an explicit strike/expiry so they do not need to be provided|
|StockOption||Exchange Traded Options have an explicit strike/expiry so they do not need to be provided|
|FuturesOption||Exchange Traded Options have an explicit strike/expiry so they do not need to be provided|
Other Important Parameters
On top of the required parameters there are a few parameters that requires special attention. Obvious ones are amount and accountkey. On top of that pay special attention to:
RequireTradableQuote: If not provided, the value is assumed to be false. It controls whether the price is usable for a spot trading and not just order placement. If set, the prices returned will contain a QuoteId value, which serves as the reference to the specific offer. A position can be created through a trade by referring to the specific quote (this is subject to limitations. One being that the offer is only available for a limited time span) (See article about spot trading Fx options).
ToClosePositionId: Is not supported for InfoPrices and is only relevant for clients on End-of-Day netting mode. It is used to indicate that the intend of getting the price is to close an existing position.
Special Rules of Convenience
FieldGroups: If no list of field groups are provided in the price request, the following defaults are used:
|Every other asset type|
And the Quote field group cannot be deselected by explicitly providing something else in the request.
Amount: Pricing depends on the amount and if the amount is not provided a default will be chosen and returned in the Quote field group.
AccountKey: Identifies what account the price is for. If not provided, the client default account is assumed.
ForwardDate: For an FxSpot, the value date is always today plus two bank days. A forward date is the intended value date for the resulting spot position and must be a) more than two bank days in the future (or it would just be a spot) as well as b) within the FxForwardMinForwardDate and FxForwardMaxForwardDate range as specified on the instrument data. Note that if the forward date is a bank holiday, the provided will be for the following bank day. The date of the corrected date can be found as the value date of the price response in the InstrumentPriceDetails field group.
ExpiryDate: This parameter for Fx options behaves like the ForwardDate for forwards. If an expiry date is a bank holiday, the API will use the next following bank day as expiry date and return the corrected date in the InstrumentPriceDetails field group's ExpiryDate field.
Strike: It is highly recommended to provide a strike parameter for a FxVanillaOption price-request, but if it isn't a default strike is used. The strike price chosen for pricing is returned as the StrikePrice value in the InstrumentPriceDetails field group.
LowerBarrier + UpperBarrier: For FxOneTouch and FxNoTouch option, only one of these fields can be set. If none is provided, the API automatically picks a LowerBarrier value. The chosen LowerBarrier value is returned as LowerBarrier in the InstrumentPriceDetails field group.
What is in a Quote
Most of the field groups returned on a price are supporting information. The Quote field group however, contains the core values used for placing orders an trading. The values here must be understood together:
- Bid/Mid/Ask are the core prices - self explanatory
- DelayedByMinutes indicates whether the price is real time or delayed and if so by how much. 0 indicates real time prices
ErrorCode: Is usually None, but can indicate whether an order for that amount will be to large or to small.
PriceTypeBid/PriceTypeAsk:The values are usually the same, but there are situations where this is not the case. Usually around price subscriptions to close a position. Price types can be:
For Fx options this means that if, you are on TradeLevel FullTradingAndChat and you also have a QuoteId, then you can place a spot trade on the price (See article about spot trading Fx options)
In most cases this price is as relevant as a Tradable price. The exception is, that it cannot be used for spot trading on Fx options
There are currently no prices in the market, so what the price you see here is usually that last traded from when the market was open. Typically happens for exchange traded products when the market is closed or Fx over the weekend
- You are not setup for a price feed or the instrument. No price will be provided. If you beleive this is an error, please contact Saxo to be set up for prices on this instrument
There are currently no prices Trying again may yield a different result
There is no price right now, but if asking again it will likely be there. On subscriptions an update is likely to contain a valid price soon (common for StockIndexOptions, StockOptions and FuturesOptions)
QuoteID: A reference to the price used for spot trading on Fx Options.
Examples and Errors
When asking for a price a response will be provided if the instrument exists and the required parameters checks out. If not the case, the endpoints for setting up subscriptions and getting single prices can be expected to return a 400 Bad Request.
While there is a lot one can do by simply requesting an info price, a full trading application usually requires continuous access to the latest price. For that a streaming connection must be established and a subscription on a price must be set up:
InfoPrices and Lists
InfoPrices allows two things that the regular price interface does not. First of all it allows a request/response interface to getting a price which can be convenient in situations where you don't need a stream of prices, but just a single one. It also supports getting prices for a list of instruments with some limitations. Those limitations are as follows:
- It only works with a single AssetType
- It is not possible to provide individual parameters to each instrument. I.e. asking for a price for 10,000 EURUSD and at the same time ask for prices for 10 ounces of XAUUSD is not possible. For this reason is is usually recommended to leave the optional fields blank and let OpenAPI use some sensible defaults
- A uic should not be provided more than once. Only one price per instrument
- Getting commissions is not supported on infoprices
- Error handling is different for lists. Asking for prices with invalid parameters will lead to an (partially) empty list, rather than an error in the request
In the below example we show the list interface behaves when asking for prices for the three FxSpot instruments 21 (EURUSD), 42 (USDJPY) & 10000 (Does not exist):
As can be seen, the semantics for lists are a little unusual in that it allows for semi illegal input and reacts by only returning the data for the valid combinations.