IPA Volatility Surfaces - Getting Started

Welcome to Refinitiv’s Volatility Surfaces API.

The Volatility Surfaces API provides you with an easy way to:

Compute the volatility level for a specific expiry and strike.
Derive volatility slices based on specific strikes or expiries.
Analyze the volatility surface of an asset.

To compute a volatility surface, all you need to do is define the underlying instrument. For more advanced usage, you can easily apply different calculation parameters or adjust the surface layout to match your needs.

Getting started with the Volatility Surfaces API

Authentication: getting a valid token

When making any request to our Volatility Surfaces API, you will need to include a valid token that can be retrieved from the oauth2 API.

Please refer to the quick start guide for details on how to get the authorization token.

Volatility Surfaces API: request

Method: POST

Protocol: https

Endpoint: api.refinitiv.com/data/quantitative-analytics-curves-and-surfaces/v1/surfaces

The request is structured as follows:

    	
            {
  "universe": [
    {
      "surfaceTag": "mySurface",
      "underlyingType": "<underlying-type>",
      "underlyingDefinition": <underlying-definition>,
      "surfaceParameters": {
        "xAxis": "Date",
        "yAxis": "Strike"
      },
      "surfaceLayout": {
        "format": "Matrix"
      }
    }
  ]
}

Here is a description of the properties that compose the API request:

Parameter	Description
surfaceTag	This is a user-defined string that is used to identify the output of the calculation
underlyingType	The value provided describes the type of volatility surface being generated. The possible values are: Eti: for exchange-traded instruments like equities, equity indices, and futures. Fx: for Fx instruments. Cap: for interest rates (caplets stripping model). Swaption: for interest rates (volatility cube, SABR calibration).
underlyingDefinition	In this section, you will find the description of the underlying instruments used for the generation of the volatility surface. The list of the properties depends on the type of instrument and is controlled by the value set to the instrumentType property. A detailed description of the Eti underlying definition can be found here. A detailed description of the Fx underlying definition can be found here. A detailed description of the IR underlying definition can be found here.
surfaceParameters	This object property 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 volatility surfaces contracts, while others are specific to a particular type of volatility. A detailed description of the Eti underlying definition can be found here. A detailed description of the Fx underlying definition can be found here. A detailed description of the IR underlying definition can be found here.
surface Layout	This object property contains the properties that may be used to control how the surface is displayed. Format: the general format of the surface returned. The possible values are: Matrix List NDimensionalArray (used only if underlyingType = 'Swaption'). xValues: Here you can specify your own values for the x-axis. yValues: Here you can specify your own values for the y-axis. xPointCount: The number of points on the x-axis. yPointCount: The number of points on the y-axis. dataPoint: Here you can specify the list of specific data points to be returned. Used only if format = 'List'. Please see the response structure description for more details on the surface layout definition.

Volatility Surfaces API: response structure

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

    	
            {
  "data": [
    {
      "surfaceTag": "mySurface",
      "surface": [
        [
          null,
          "34.088",
          "36.2185",
          "38.349",
          "40.4795"
        ],
        [
          "2019-04-18",
          0.5433581255439179,
          0.48003249444850066,
          0.4131854250680365,
          0.34279427928780754
        ],
        [
          "2019-09-20",
          0.40053081800213886,
          0.3855299957095886,
          0.37502560388285044,
          0.37611620462184264
        ],
        [
          "2019-12-20",
          0.3700413864441955,
          0.35877058687095253,
          0.3515030450704461,
          0.35094606876956363
        ]
      ]
    }
  ]
}

The Surface Layout illustrated:

The table below explains the different types of layout you can specify when requesting a volatility surface.

	Matrix layout format	List layout format
Description	xValues and yValues arrays define values on x and y axis. In the example below, xAxis is Tenor and yAxis is Strike.	Points to return are defined by dataPoints array of (x, y) pairs. In the example below, xAxis is Tenor and yAxis is Strike.
Request example	"surfaceLayout": { "format": "Matrix", "xValues": [ "1M", "3M" ], "yValues":[ 3800, 4200] }	"surfaceLayout": { "format": "List", "dataPoints":[{"x": "1M", "y":3800}, {"x": "3M", "y":4200} ] }
Response	"surface": [ [ null, "3800", "4200" ], [ "1M", 22.280937986749098, 14.902041118838 ], [ "3M", 12.935225550274199, 8.652717035855979 ] ]	"surface": [ [ "1M", "3800", 22.280937986749098 ], [ "3M", "4200", 8.652717035855979 ] ]