Implementing instruments

The Upvest Investment API offers the endpoints /instruments and instruments/:id through which you can fetch the information about instruments available for trading or fractional trading. But you can also request information about prices of venues, etc.

INFO

All these endpoints are purely informative. There is nothing that a client can change.


This chapter guides you through the necessary steps to get you ready to work with the /instruments endpoint.

Prerequisites

Clients who wish to access the price data require a separate contract with an external data providing service partner, such as Infront. Clients who do not have this contract do not receive real-time prices.

INFO

Please note that our external partners may reserve time slots for their maintenance and minor service interruptions may therefore occur occasionally.


However, this contract is not required to retrieve the instruments or venues information.

1. Listing instruments

To retrieve the list of available instruments, submit this request:

GET /instruments

Example response

{
  "meta": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "total_count": 10,
    "sort": "created_at",
    "order": "ASC"
  },
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2022-08-31T17:28:00.00Z",
      "updated_at": "2022-08-31T17:28:00.00Z",
      "isin": "DE0007664005",
      "wkn": "766400",
      "name": "Volkswagen (VW) St. Aktie.",
      "fractional_trading": true,
      "trading_status": "ACTIVE"
    }
  ]
}
ParameterDescriptionExample
idThe instrument's unique identifier.123e4567-e89b-12d3-a456-426614174000
created_atThe date the instrument was created.2022-08-31T17:28:00.00Z
updated_atThe date the instrument was last updated.2022-08-31T17:28:00.00Z
ìsinThe instrument ISIN.DE0007664005
wknThe instrument Wertpapierkennnummer766400
nameThe instrument name.Volkswagen (VW) St. Aktie
fractional_tradingIs fractional trading is allowed?TRUE
trading_statusPossible values:
* ACTIVE - The instrument can be traded.
* INACTIVE - The instrument cannot be traded.
ACTIVE
COMING SOON

Upvest plans to extend the list of available trading statuses at instrument level to support corporate actions such as rights issues, tender offers and the delisting case described above. The following two additional statuses will be available soon:

  • BUY_ONLY
  • SELL_ONLY

If you want to retrieve a single instrument, you can specify its ID:

GET /instruments/{instrument_id}

Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2022-08-31T17:28:00.00Z",
  "updated_at": "2022-08-31T17:28:00.00Z",
  "isin": "DE0007664005",
  "wkn": "766400",
  "name": "Volkswagen (VW) St. Aktie.",
  "fractional_trading": true,
  "trading_status": "ACTIVE"
}

2. Get instrument venues

As the prices are linked to an exchange, a user must first be able to see at which venues prices are available and in which quality.

To retrieve the trading venues on which the instrument is traded and for which price data is available, proceed as follows:

GET /instruments/{instrument_id}/venues

Example response

{
  "data": [
    {
      "id": "20d6024b-2df4-41ae-8d42-62e4744e455b",
      "name": "Tradegate",
      "price_qualities": [
        "EOD",
        "REALTIME"
      ]
    }
  ]
}

3. Retrieving instruments prices

Once you have opted for a trading venue (how to find venues is described in the 'Get instruments venues' step above), you can either retrieve

INFO

Please note that our external partners may reserve time slots for their maintenance and minor service interruptions may therefore occur occasionally.


Get instrument latest prices

GET /instruments/{instrument_id}/venues/{venue_id}/prices/latest

Example response

{
  "price_quality": "REALTIME",
  "currency": "EUR",
  "bids": [
    {
      "time": "2023-01-09T13:02:15Z",
      "price": "210.01",
      "size": "100"
    }
  ],
  "asks": [
    {
      "time": "2023-01-09T13:02:15Z",
      "price": "212.32",
      "size": "50"
    }
  ],
  "last_trade": {
    "time": "2023-01-09T12:59:04Z",
    "price": "211.32",
    "size": "40"
  }
}

Get instrument OHLC prices

GET /instruments/{instrument_id}/venues/{venue_id}/prices/ohlc

You can use the following query parameters to narrow down the result:

Query parameterDescription
start_dateReturns OHLC prices from and including this date (UTC).
If not specified, OHLC prices are returned from 30 days before the specified end date.
Example: 2020-08-21
end_dateReturns OHLC prices from and including this date (UTC).
If not specified, OHLC prices are returned up to yesterday.
Example: 2020-08-21
adjusted_forIndication of the desired data adjustment. Prices are adjusted for corporate actions such as cash dividends and stock splits.
Possible values:
- NONE
- ALL (default).
intervalSpecification of the maximum length of the interval that each OHLC price tuple covers.
If a price did not change subsequent price tuples are omitted.
Possible values:
- 1d for daily prices (default)
- any positive integer followed by h (for hour) or m (for minute) respectively.
Requests are limited to a maximum of 1000 data points.

Example response

{
  "data": [
    {
      "currency": "EUR",
      "time": "2023-01-09T00:00:00Z",
      "open": "213.32",
      "high": "215.32",
      "low": "210.32",
      "close": "213.22",
      "volume": "277973"
    },
    {
      "currency": "EUR",
      "time": "2023-01-10T00:00:00Z",
      "open": "214.42",
      "high": "214.42",
      "low": "213.22",
      "close": "213.22",
      "volume": "260335"
    }
  ],
  "meta": {
    "count": 2
  }
}

Instruments status

The individual instrument status and configuration is the single source of truth for each instrument, which affects the following cases:

StatusDescription
FRACTIONAL_TRADINGOnly instruments with the attribute fractional_trading=TRUE can be executed as nominal orders.
INACTIVEOrders that include instruments with an INACTIVE status will be rejected.
It is possible to retrieve a list of inactive instruments by using this attribute (by default, only the currently activated instruments are listed when retrieving instruments).

Webhooks

Upvest has introduced event-driven communication via webhook allowing clients to receive instrument updates immediately (e.g. after trading status changes). As usual with Upvest Investment API, the webhook event will contain the same data as the corresponding GET endpoint - in this case for a single instrument.

See Instruments events.

Was this page helpful?