Overview

The Financial Contracts API provides you with an easy way to compute quantitative analytics that you can easily integrate into a multitude of contexts and workflows. For example, the Financial Contracts API can be used to:

• compute quantitative analytics like premiums and risk measures for a wide range of market instruments.
• compute and analyze cash flows for a list of instruments.
• run what-if scenarios for a specific instrument.
• get analytics to dynamically manage your portfolio.
• get Intraday and/or historical portfolio valuation.
• compute spreads to curves or to other benchmark instruments.

Using Financial Contracts API you can retrieve the data for different market instruments.

The analytics calculated for a market instrument will be based on a set of defaults and assumptions described in this document.

For more advanced usage, the API allows you to easily apply different pricing and market data parameters based on your own market assumptions.

You can also can send financial contract requests in an asynchronous mode (when they contain thousands of instruments and/or take long time to be executed). For more details, plese refer here: IPA Financial Contracts: Asynchronous Mode.

Financial Instruments Supported

The API currently supports the following financial contracts:

• Fixed-income Instruments
  • Bonds
    
  • Convertible Bonds
  • Bond Futures
• FX and Money Market Instruments
  • FX Cross (FX Spots, FX Forwards, FX Swaps)
  • Repos
    
  • Loan
  • Term Deposits
• Options
  • Equity Options
  • Fx Options
    
• Interest Rate Derivatives
  • Cap Floors
  • Interest Rate Swaps
  • Swaptions
  • Forward Rate Agreements (FRA)
• Credit Derivatives
  • Credit Default Swaps (CDS)
  • Credit Valuation Adjustment (CVA)
• Structured Products

Keep in mind that this list is constantly updating since new supported financial instruments are added.

Besides, you can submit a request for a new financial instrument.

For many of the instruments in the list the Cash Flows analysis is available. For multi-currency portfolios the Cash Flow Currency Conversion Service can be useful.

There is also a list of API parameters and Market Conventions (e.g., calendars, currencies, index names, day count conventions, frequencies, tenors etc.) that can be used across different financial contracts (if such convention applies to a financial contract, a corresponding link is added in the contract's documentation).

For more details on the calculation of the fields, please refer to IPA Financial Contracts: Fields Calculation.

Before You Begin

To start using the Financial Contracts API, you need to provide a valid token. It can be retrieved from the oauth2 API. Please refer to the quick start guide for details on how to get the authorization token. 

Performing a Request

To retrieve quantitative analytics for a financial contract, you need to send the POST request to the endpoint as listed below:

POST - https://api.refinitiv.com/data/quantitative-analytics/v1/financial-contracts

The request is structured as follows:

Below is the description of the properties that can be used in the API request:

• "fields" (array): optional. It contains the list of Analytics that the quantitative analytic service will compute. The list of Analytics depends on the instrument type sent in the request. Some fields that were previously used and updated for some reason are listed on a special Deprecated fields page. They can still be used in relevant contracts along with new fields corresponding to them, both of which are listed on this page.

• "universe" (array of objects): mandatory. It contains the list of financial contracts you want to price. Each object of the list will contain the following properties:
  • "instrumentType" (string): mandatory. It defines the financial contract described in the 'instrumentDefinition' object. The possible values are provided here.
  • "instrumentDefinition" (object): mandatory. It contains the properties you may use to define a financial contract. The list of the properties depends on the type of instrument defined for the instrumentType property. In some contracts additional definitions or object properties should be requested in the 'instrumentDefinition' object to define a financial contract: 
    
    • "legs" (array of objects): contains the properties that can be used to define the instrument’s legs (paid or recieved). Applicable to Swaps and FxCross contracts.
    • "underlyingDefinition" (object): contains the properties that can be used to define the underlying asset of a financial contract (if only one underlying asset applies, for example, Options, Swaption),
    • "underlyingInstruments" (array of objects): contains the properties that can be used to define different underlying assets of a financial contract (for example, Bond Futures, Repo),
    • another specific definitions used to define a financial contract (for example, definitions of exotic options).   
  • "pricingParameters" (object): optional. It contains the properties that may be used to control the calculation. It mainly covers dates, market data assumptions (e.g. interpolation), and pricing model preferences. Some Parameters are common to all financial contracts, others are specific to a particular contract. By default, override does not apply. For 'Date-time' parameters, ‘time’ is ignored. An information may be requested in a ‘Date’ format ('YYYY-MM-DD ').
• "dataLayout" (object): optional. It controls how the resulting data array is structured, for example for multi-leg instruments to be displayed as a single or as multiple instruments. 
• "outputs" (array): optional. It contains the sections that will be returned by the API. The possible values are:
  • "Data": If specified, the response will contain the data tabular object. This object will contain rows for each instrument object defined in the universe array and columns for each calculation field defined in the fields array of the request. This is the main output, which contains the requested calculations, and is mandatory.
  • "Headers":  If specified, the response will contain the headers object.. This object will contain the list of requested fields and their types.
  • "Statuses": If specified, the response will contain the statuses tabular object. This object will contain rows for each object defined in the universe array and columns for each calculation field defined in the fields array of the request. The following status may be returned:
    • 0 - Not Applicable. There is no applicable status for this field.
    • 1 - User Override. This data item was provided in the request.
    • 2 - From Market Data. This data has been derived from market data (e.g. interpolated).
    • 3 - Computed output. This field has been computed.
    • 4 - Error. The calculation has returned an error.  If you need more details about the returned error, specify the "ErrorCode" and/or "ErrorMessage" properties in the fields array and  send the request again.
  • "MarketData":  If specified, the response will contain the curves and volatility surfaces used for computations.

Getting a Response

The API response contains the different sections defined in the output property of the request. 

The headers property will contain the same number of objects as the fields specified in the request.