IPA Volatility Surfaces : FX

This document describes the properties that can be used to construct FX Volatility Surface.

For the general guidelines on how to structure a request to construct a volatility surface please refer to the Volatility Surfaces Getting Started page.

This page explains how to build the underlying definition section, define your own surface parameters and layout preferences, and what fields can be returned for ETI Volatility Surface.

Inputs

The table below lists the root object properties that should be defined in the request body.

Input Name Type Description Importance Default Value
outputs Array of strings

The list of requested output analytics. The possible values are: 

  • Data: the list of properties that apply to the constructed volatility surface, 
  • CrossCurrencyCurves: the list of the cross-currency curve attributes used to construct the volatility surface.
 Optional The default values are based on the value of surface layout format. By default, surfaceTag and properties that apply to the constructed volatility surface are returned.
universe Array of objects

The array of objects that describe the volatility surface and the surface preferences.

For a detailed breakdown, please refer here.

 Mandatory No default value applies.

Universe

The table below lists the properties that can be requested in the universe object.

Input Name Type Description Importance Default Value

underlyingType

 String (enumeration)

The type of underlying used to generate the volatility surface. The possible value is:

  • Fx.
 Mandatory No default value applies.
surfaceTag String A user-defined string to identify the volatility surface. It can be used to link output results to the requested definition. Limited to 40 characters. Only alphabetic, numeric and '- _.#=@' characters are supported. Optional No default value applies.
underlyingDefinition Object The definition of the volatility surface. For a detailed breakdown, please refer here. Mandatory No default value applies.
surfaceParameters Object The pricing parameters to be applied to the volatility surface. For a detailed breakdown, please refer here. Optional If not provided, default values of parameters are used.
surfaceLayout Object The list of properties used to modify the layout of the volatility surface in outputs. For a detailed breakdown, please refer here.  Optional If not provided, default values of parameters are used.

Underlying Definition

The table below lists the properties that can be requested in the underlyingDefinition object.

Input Name Type Description Importance Default Value
instrumentCode String

The code used to define the underlying asset, expressed in ISO 4217 alphabetical format (e.g., 'EURCHF').

 Mandatory No default value applies.

Surface Parameters

The table below lists the properties that can be requested in the surfaceParameters object.

Note:

  • At least one parameter out of xAxis or yAxis must be set to 'Date' or 'Tenor'.
  • For format = 'Matrix', if 'Date' and 'Tenor' values are set for xAxis and yAxis at a time, the default values of yAxis is used.
Input Name Type Description Importance Default value
xAxis String (enumeration)

The list of properties that can be set for the 'x' axis. The possible values are:

  • Date,
  • Strike,
  • Delta,
  • Tenor,
  • Moneyness.
 Optional The default value is 'Date'.
yAxis String (enumeration)

The list of properties that can be set for the 'y' axis. The possible values are:

  • Date,
  • Strike,
  • Delta,
  • Tenor,
  • Moneyness.
 Optional The default value is 'Delta'.
valuationDate DateTime The date at which the volatility surface is constructed. The value is expressed in ISO 8601 format: YYYY-MM-DDT[hh]:[mm]:[ssZ (e.g., '2021-01-01T00:00:00Z'). It should be less or equal to today's date. Optional The default value is today's date.
volatilityModel String (enumeration)

The model used to build the surface. The possible values are:

  • SVI,
  • SABR,
  • CubicSpline,
  • TwinLognormal,
  • VannaVolga10D,
  • VannaVolga25D.
 Optional The default value is 'SVI'.
fxSwapCalculationMethod String (enumeration) The method used to calculate an outright price or deposit rates. The possible values are:
  • FxSwapImpliedFromDeposit: implied FX swap points are computed from deposit rates,
  • DepositCcy1ImpliedFromFxSwap: the currency 1 deposit rates are computed using swap points,
  • DepositCcy2ImpliedFromFxSwap: the currency 2 deposit rates are computed using swap points.
 Optional The default value is 'DepositCcy2ImpliedFromFxSwap'.
priceSide String (enumeration) The quoted price side of the volatility constituents used to construct the surface. The possible values are:
  • Bid,
  • Ask,
  • Mid.
 Optional The default value is 'Mid'.
deltaConvention String (enumeration) The convention of how delta is defined (the ratio of change in FX option value to the change in exchange rate of the underlying currency pair) when constructing the volatility surface. The possible values are:
  • Spot: spot rate is used,
  • Fwd: forward rate is used.

Note: It can be used if xAxis or yAxis is set to 'Delta' or 'Moneyness'.

 Optional The default value is 'Spot'.
deltaPremiumConvention String (enumeration)

The convention used to compute delta. Possible values are:

  • PA: adjusted premium (excluding hedging costs),
  • Regular: non-adjusted premium.
 Optional The default value is 'PA'.
returnAtm Boolean

An indicator of whether the ATM volatility is returned in the surface constructed. The possible values are:

  • true: the ATM volatility is returned,
  • false: the ATM volatility is not returned.

Note: It can be used if xAxis or yAxis is set to 'Delta' or 'Moneyness'.

 Optional The default value is 'true'.

Surface Layout

The table below lists the properties that can be requested in the surfaceLayout object.

Input Name Type Description Importance Default value
format String (enumeration) The format of the returned volatility surface. The possible values are:
  • Matrix,
  • List.
 Optional The default value is 'Matrix'.
xValues Array of strings The list of values of discrete data points on the x-axis. The possible values are determined by value of xAxis.
It is used only if format = 'Matrix'.		 Optional No default value applies.
yValues Array of strings The list of values of discrete data points on the y-axis. The possible values are determined by the value of yAxis. 
It is used only if format = 'Matrix'.		 Optional No default value applies.
xPointCount Integer The number of data points that will be generated along the x-axis. These values will be distributed depending on the available input data and the type of volatility.
It is used only if format = 'Matrix'. This parameter is ignored if xValues parameter is used.		 Optional No default value applies.
yPointCount Integer The number of data points that will be generated along the y-axis. These values will distributed depending on the available input data and the type of volatility.
It is used only if format = 'Matrix'. This parameter is ignored if yValues parameter is used.		 Optional No default value applies.
dataPoints Array of objects

The list of specific data points to be returned.
It is used only if format = 'List'.

For a detailed breakdown, please refer here.

 Optional No default value applies.
  • Data Points

The table below lists the properties of  surfaceLayout → dataPoints object.

Input Name Type Description Importance Default value
x String A value of a point to be returned on x-axis. Optional No default value applies.
y String A value of a point to be returned on y-axis. Optional No default value applies.

Outputs

The table below lists properties returned in the response, including properties requested in the outputs object.

Output Name Type Description
surfaceTag String A user-defined string to identify the volatility surface.
surface Array of arrays The values of the properties that apply to the constructed volatility surface. 
headers Array of strings The names of the properties that apply to the constructed volatility surface. It is returned if the surface layout's format is set to 'List'.
crossCurrencyCurves Array of objects The parameters of curves used to construct the volatility surface. For a detailed breakdown, please refer here.

Error Messages

Error Code Error Message Description
QPS-DPS.Error_InvalidInput_UnbindableJsonPayload Invalid input: Unbindable json Error converting value \"expiry\" to type 'TR.Qps.Models.Messages.VolSurfApi.VolatilitySurfaceAxis'. Path 'surfaceParameters.YAxis', line 1, position 164 Wrong y-axis.
VolSurf.10200 Market data: The service failed to retrieve the necessary data to build the volatility surface. Global DPS error.
VolSurf.10300 The service failed to build the volatility surface. Global VolSurf error.
8007 Pricer: The service failed to build the volatility surface. Pricer error.

Deprecated properties

The table below lists the deprecated properties.

Data Model Type Deprecated Name New Name
underlyingDefinition fxCrossCode instrumentCode