Instruments use cases
The Investment API provides access to available instruments along with their individual trading status. Additionally, it indicates whether fractional trading is permitted for a specific instrument on the Upvest Platform.
Retrieving instruments base data
Clients retrieve the available instruments data along with their individual trading status and whether fractional trading is allowed for a particular instrument on the Upvest platform. The following diagram shows the process flows:
Possible applications
Clients can use the instrument base data to implement these functions:
General system configuration: Activation/deactivation of instruments for trading.
Instrument search: The end user searches for an asset.
Instrument details: The end user selects different assets and compares them or explores an asset.
Instrument orders: The end user selects the asset and triggers an order.
Portfolio view: The end user has access to their portfolio with all holdings.
View of the instrument (purchased): The users want to see the characteristics of the instruments they own.
Retrieving instrument prices
The Investment API gives you access to price data per instrument and venue. You can fetch either the latest prices or OHLC prices.
Upvest works with Infront as a data provider for real-time data. Clients who wish to access the price data require a separate contract with Infront. Tenants who do not have this contract do not receive real-time prices.
The following diagram shows the process flow for retrieving instrument OHLC prices:
Price data
The price history service supports two types of price data, which can be accessed via corresponding API parameters.
| Price data | Description |
|---|---|
| Raw price data | 'Point in time' data, i.e. the raw prices as they were traded on a specific date. |
| Backward corrected price data | Retroactively adjusted price data reflecting corporate actions such as stock splits to avoid large structural breaks in the displayed price trends. Most frequently, (backwards) corrected price data is used for display in the front end of the end user's application. |
Amazon's 2022 stock split, where Amazon shares were trading at around EUR 2,281.50 before the split (on 2022/06/03) and at around EUR 114.08 after the split (on 2022/06/06).
In this example, the raw price data series would show a sharp price decline, while the corrected price data series would show a smooth price time series, as the 20:1 stock split (ratio 20:1) has been fully incorporated into the data.
Possible applications
You can use the price data at the end of the day to display performance calculations or show past price developments (e.g. for creating charts in the user's frontend).
Onboarding new instruments
Clients must contact Upvest if they wish to start trading a new instrument that has not been previously agreed with us.
Once the updates for instruments have been implemented, you will receive update events for all newly added instruments.
Delisting of instruments
In case an instrument is delisted on a specific trading venue, Upvest can no longer accept orders for that instrument at that venue.
If an instrument is delisted on all supported exchanges, Upvest will block the trading of securities by setting their trading status to INACTIVE. After all positions in this instrument have been sold, Upvest will remove this instrument from trading.
Upvest will inform you in advance of the delisting of the instruments on your accounts.
Regulatory trading bans/ halts
In the event of a regulatory trading ban/block, the restrictions generally apply to all supported markets. Therefore, Upvest blocks trading in securities by setting their trading status to INACTIVE. The instrument will still be displayed on the end users' accounts but cannot be traded as long as the trading ban is in place.
When an instrument is delisted by a particular exchange due to legal requirements or a new policy, the exchanges usually give the investment firms time to transfer or liquidate the positions.
In such cases, we restrict users from contnuing to build positions and allow SELL_ONLY for liquidation.
For example, the imminent delisting of Chinese companies from the NYSE was announced in advance and US-based investors were only allowed to sell instruments. Thus each user has the option of transferring their positions to a custodian in the Chinese market or selling them in the market where someone from China or a user who has an account with a Chinese custodian will buy them.