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.

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

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.

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

• Authentication scopes — instruments:read

  For more information, refer to Authentication scopes.

• Webhook handler ready — Set up a webhook endpoint to receive instrument status change notifications.

  • Subscribe to INSTRUMENT.* events.

  For more information, refer to Implementing webhooks.

• Setup caching to support price data - Prepare a cache for price data responses on a per-instrument basis. You can provide faster response times and reduce potential latency by implementing a caching solution for the /latest and /ohlc price data endpoints. This approach also helps preserve a historical views for charting.

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"
    }
  ]
}

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"
}

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"
      ]
    }
  ]
}

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

• latest prices or
• OHLC (Open-High-Low-Close) data.

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 /instruments/{instrument_id}/venues/{venue_id}/prices/ohlc

Price data requests are limited to 5,000 data points per each request. We recommend using multiple requests when calling the Open/High/Low/Close (OHLC) endpoint with a request that may exceed this limit.

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

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
  }
}

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

Subscribe to INSTRUMENT.* events to receive real-time updates when instruments are onboarded, change trading status, or have their data updated. This removes the need to poll the API for instrument state changes.

For a full reference of instrument webhook events, refer to Instrument webhook events.