Recco

Getting started

RECCO is EdgeLab's Risk API for financial assets and portfolios.

Introduction

This API allows to get risk data at the asset, allocation and aggregate level.

  • asset level: at the single asset level, assuming a quantity of 1 of the asset is held;
  • allocation level: at the single asset, with potentially more than 1 unit of the asset held in a portfolio;
  • aggregate level: per group of assets, in particular per entire portfolios.

Different types of risk data can be accessed, with a different set of parameters.

Our FAQ will hopefully help you answer most of questions you may have.

Getting started

RECCO can be accessed from the following endpoint

https://api.edgelab.ch/recco

An API key is necessary for using the API (you don't have an API key? write us at info@edgelab.ch).

In order to get familiar with the different data types that can be obtained through this API, you may want to make a GET request on the endpoint

/types

This will give you access to the list of available data types, together with their respective parameters. These parameters can be obtained through their respective endpoints, e.g. Confidence levels, Time horizons,...

To start with a simple example, we can check how risky a well-known Swiss Bank may be. You may want to make a POST request on the endpoint

/data/allocations/Var

with the following body

{
    "allocations": [
        "CH0244767585"
    ],
    "timeHorizon": "252d",
    "confidenceLevel": "99",
    "scenarioTypes":["Historical"],
    "currency": "CHF"
}

This will give you a response including the following content

{
    "CH0244767585": {
        "quantity": 1,
        "body": [{
            "id": "Var",
            "value": 7.1309,
            "normalizedValue": 0.4301
        }]
    }
}

This basically tells you that if you hold 1 share of this Bank in CHF over 1 year, then you may not lose more than 43.01% of its value (i.e. 7.13 CHF at the time of calculation) with a 99% probability. In more technical terms, it says that, based on historical data, the Value-at-Risk over a 1 year time horizon and with a confidence level of 99%, is of 43.01% of current stock's value in CHF (or of 7.1309 CHF).

FAQ

This FAQ compiles the most frequent technical and functional questions on the use of RECCO.

New questions are more than welcome at info@edgelab.ch

What types of data are available through this API?

This API gives access to a variety of risk data, in particular:

  • Fair values of assets;
  • Interest rate sensitivities (e.g. duration or convexity) for instruments that are exposed to interest rates changes;
  • Option sensitivities (e.g. delta or vega);
  • Risk metrics (e.g. Value-at-Risk or Expected Shortafall);
  • Product-Risk-Classifications and Portfolio-Risk-Classifications (e.g. for MiFID II/FIDLEG/LSFIN regulations).

For each of these data, a specific set of configuration parameters are available. For example, Value-at-Risk can be derived for different time-horizons, confidence levels or even underlying models.

The risk data currently supported and their respective parameters can be obtained via a GET request on the following endpoint

/types?view=full

What is the format for timestamps?

All timestamps are returned in ISO 8601 Zulu format YYYY-MM-DDTHH:MM:SSZ.

I would like to use the API but I do not have an API key?

We would be happy to help you with that, please contact our team at info@edgelab.ch

An instrument that I would like to include in my risk calculations is a contract and hence does not have a public identifier like ISIN?

This is not an issue. The terms and conditions of the contract have to be provided to EdgeLab first through our market data API

https://api.edgelab.ch/cerberus

Once the contract is created, an identifier is generated which can then be used to query risk derivations on it. Note that this approach can also be used to include private placements, hypothetical instruments,... in risk calculations.

Instruments that I have included in my portfolio are not known or their results are not yet ready, what is the implication?

If the instrument is used in standalone instrument risk calculations, the result for this instrument will not be provided and the error will be described in the response. If the instrument is used in the context of a portfolio risk calculations, the positions on this instrument will be ignored in the portfolio. More details are available in the documentation for Aggregates.

Should the cash be part of the portfolio sent to Recco for a risk calculation?

For sure! Especially if the cash accounts are in a currency that is different from the portfolio currency. For adding cash accounts in portfolio, see Cash identifiers.

Instruments that I have included in my portfolio are not known, despite they are common instrument. What shall I do?

Please contact our team at info@edgelab.ch to sort this out as soon as possible.

What is the unit price assumed when a quantity is attached to a position?

A unit price of 1, for all assets classes. In consequence, if a Bond is quoted at 102 (in unit price %) and a quantity of 1'000 is provided to Recco, then the position value will be 1'000 * 1.02 = 1'020.

Is this documentation a comprehensive resource for the quantitative aspects of the derived data?

Definitely not. If this is what you are looking for, then please contact our team at info@edgelab.ch

I would like to obtain more information on the methodology used for deriving the risk data?

We can provide a comprehensive methodology documentation and all the support required for making sure the methodology is clear to our users. Please contact our team at info@edgelab.ch

I wonder whether the Product-Risk-Classification (PRC) available in this API complies with MiFID II and FIDLEG/LSFin requirements?

Yes it does. For more details on regulatory topics, please contact our team at info@edgelab.ch

Could I define my own methodology for deriving the Product-Risk-Classification (PRC)?

A priori, yes. For more details, please contact our team at info@edgelab.ch

Why Recco?

Because as the electronic mountain kit with the same name, the goal of this API is to help you stay safe in case of bad events.

Cash identifiers

Cash accounts can be added in portfolios for risk calculation as well. As any other asset which does not have a public identifier, cash accounts have their own identifiers. We provide below the list of identifiers for risk-free cash assets for main currencies, together with the digits precision.

Currency Asset ID Precision
CHF b1f8c4c5-04ac-4f5d-8d44-e8d7a7f186f0 2
EUR 3f662c06-4a03-4870-9db7-398e14b17911 2
USD 289ed3da-6b7a-402e-9a17-16ab0b739061 2
GBP bd9d44ea-f93c-4e5b-9dd1-4edd832c6965 2
AUD bb2ee075-e639-4ac5-8173-35a7a8296026 2
NOK f999480c-df25-4deb-bfd8-6fae46c19c93 2
SEK 5f4fb81a-5621-4e8e-ad41-76d597438f18 2
CAD 6efb0235-3e53-42f4-8259-90cbf70fc727 2
JPY 772dfc81-48c5-4b72-bf6f-c89bf4de4e64 0
SGD 138ca62f-2339-4f65-84c1-1673ffdd1199 2
CNY be0f0c51-f059-47ce-9dab-ded929a5bc5a 2

For example, for a portfolio containing 28518 units of instrument with ISIN LU1236092984 and 50'000 EUR, the allocations in the body of the query would look like:

 "allocations": [{
        "asset": "LU1236092984",
        "quantity": 28518
    }, {
        "asset": "3f662c06-4a03-4870-9db7-398e14b17911",
        "quantity": 50000
    }
 ]

More generally, cash asset identifiers for a specific currency can be obtained from our market data API.