IPA Volatility Surfaces : ETI

This document describes the properties that can be used to construct Volatility Surfaces for Exchange-Traded Instruments (ETIs), which include equities, indices, and futures.

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: 

  • DiscountCurve: the list of the zero-coupon discount curve attributes used to construct the volatility surface,
  • Dividends: the list of dividend yield curve attributes used to construct the volatility surface,
  • UnderlyingSpot: the list of properties of the underlying’s spot and/or the futures used to construct the volatility surface,
  • MoneynessStrike: the strike values corresponding to moneyness levels defined. It is returned in response only if one of the axis is set to Moneyness. 
 Optional 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:

  • Eti.
 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.
shiftScenarios Array of objects

The list of attributes applied to the shift scenarios. Mandatory for shifting.

For a detailed breakdown, please refer here.

 Optional No default value applies.

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. The value is expressed in the following formats:

  • RIC for equities and indices (e.g., 'VOD.L', '.SPX'),
  • xx@RICROOT for futures (e.g., 'CL@RICROOT').
 Mandatory No default value applies.
exchange String Specifies the exchange to be used to retrieve the underlying data. Optional By default, it is the main exchange where the underlying equity is quoted.

Surface Parameters

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

Note: Either xAxis or yAxis properties should be set to 'Date' or 'Tenor', 'Date' and 'Tenor' values cannot be set at a time for xAxis and yAxis properties, 'Strike' and 'Moneyness' values cannot be set at a time for xAxis and yAxis properties.

Input Name Type Description Importance Default value
xAxis String (enumeration)

The unit for the 'x' axis. The possible values are:

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

The unit for the 'y' axis. The possible values are:

  • Date,
  • Strike,
  • Delta,
  • Tenor,
  • Moneyness.
 Optional The default value is 'Strike'.
calculationDate 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 can not be a future date. Optional The default value is today's date.
volatilityModel String (enumeration) The model used to build the surface. The possible values are:
  • SVI: separate parametrization for each expiry option date can be set (smile by smile approach). By default, with SVI the extrapolation is flat in moneyness space.
  • SSVI (sometimes called wholesurface): the parametrization is global across all the maturities. The extrapolation is not flat in moneyness space.
 Optional The default value is 'SVI'.
inputVolatilityType String (enumeration) The type of volatility used to construct the surface. The possible values are:
  • Implied,
  • Quoted.
 Optional The default value is 'Implied'.
priceSide String (enumeration) The quoted price side of options used to construct the surface. The possible values are:
  • Bid,
  • Ask,
  • Mid,
  • Last.
 Optional The default value is 'Mid'.
timeStamp String (enumeration)

The mode of selecting the timestamp of options used to construct the surface. The possible values are:

  • Default: the latest snapshot is used when calculationDate is today, and the close price is used when calculationDate is in the past,
  • Open: the opening price of calculationDate,
  • Close: the closing price of calculationDate, or if it is not available, the close price of the previous day is used,
  • Settle: settlement values will be used.
If priceSide is 'Bid' or 'Ask', timeStamp cannot be 'Close'. 

Note: For most cases, only the 'Default' value may be available when pricing a historical surface.

 Optional The default value is 'Default'.
moneynessType String (enumeration) The enumerate that specifies how moneyness is computed for the calibration. The possible values are:
  • Spot: moneyness is computed using current price,
  • Fwd: moneyness is computed using future price,
  • Sigma: standardized moneyness is used.
 Optional The default value is 'Spot'.
sviAlphaExtrapolation Boolean The indicator that determines if svi extrapolation should be used to construct the surface. The possible values are:
  • True: svi extrapolation is used;
  •  False: svi extrapolation is not used.
 Optional The default value is 'True'.
smileBySmileArbitrageCheck Boolean The indicator of whether smile by smile arbitrage check is applied when constructing the volatility surface. The possible values are:
  • True: the arbitrage check is applied,
  • False: the arbitrage check is not applied.
 Optional The default value is 'True'.
filters Object

The parameters of options that should be used to construct the volatility surface.

For a detailed breakdown, please refer here.

 Optional If not provided, default values of parameters are used.
weights Array of objects

The list of calibration weights that should be applied to different moneyness ranges.

For a detailed breakdown, please refer here.

 Optional If not provided, default values of parameters are used.
 
Weights
The table below lists the properties of surfaceParameters → weights object.
 
 
Input Name Type Description Importance Default value
minMoneyness Double The lower bound of the moneyness range of options to which the specified weight should be applied for surface construction. The value is expressed in  percentages (call option moneyness = UnderlyingPrice / Strike * 100; put option moneyness = Strike / UnderlyingPrice * 100). The value of 100 corresponds to at-the-money option. Optional No default value applies.
maxMoneyness Double The upper bound of the moneyness range of options to which the specified weight should be applied for surface construction. The value is expressed in percentages (call option moneyness = UnderlyingPrice / Strike * 100; put option moneyness = Strike / UnderlyingPrice * 100). The value of 100 corresponds to at-the-money option. Optional No default value applies.
weight Double

The weight which should be applied to the options in the specified range of the moneyness. The value is expressed in absolute numbers. The contribution of a specific option is computed by the dividing the weight of the option by the sum of weights of all constituent options.

Mandatory if the weights array of objects is used.

 Optional The default value is '1.0' for all constituent options.

Filters

The table below lists the properties of surfaceParameters → filters object.

Input Name Type Description Importance Default value
atmToleranceIntervalPercent Double The width of the at-the-money interval. The value is expressed in percentages. For example, when it's set to 1 (the default value), call options with moneyness <99% and put options with moneyness>101% will be excluded.
In-the-money options are excluded from the list of input options. 		 Optional The default value is '1.0'.
ensurePricesMonotonicity Boolean The indicator of whether the filter on the monotonicity of price options is used  to construct the surface. The possible values are:
  • True: monotonicity of option prices is used,
  • False: monotonicity of option prices is not used. 
 Optional The default value is 'True'.
useWeeklyOptions Boolean The indicator of whether the filter on the weekly options is used to construct the surface. The possible values are:
  • True: use weekly options,
  • False: do not use weekly options.
Note: It has impact only on underlyings that have liquid weekly options.		 Optional The default value is 'False'.
useOnlyCalls Boolean The indicator of whether only call options should be used to construct the surface. The possible values are:
  • True: only call options are used,
  • False: not only call options are used.
 Optional The default value is 'False'.
useOnlyPuts Boolean The indicator of whether only put options should be used to construct the surface. The possible values are:
  • True: only put options are used,
  • False: not only put options are used.
 Optional The default value is 'False'.

exerciseStyle

String (enumeration)

A filter on the exercise of options to be used for the surface calculation. The possible values are :

  • EURO : use European options only
  • AMER : use American options only.

Optional

The default value is 'AMER' if constituents contain an American option else it is 'EURO'.
maxStalenessDays Integer The value specifies the maximum staleness past days to use to construct the surface. Optional The default value is '5.0'.
maxOfMedianBidAskSpread Double The value specifies the spread multiplier used to filter the options with the same expiry but high bid-ask spread. Upper bound of the spread is computed as maxOfMedianBidAskSpread multiplied by median spread. Optional The default value is '4.0'.
strikeRange Object The range allows to exclude strike levels that have implied volatilities which exceed upper bound or below lower bound. For a detailed breakdown, please refer here. Optional If not provided, default values of parameters are used.
maturityFilterRange Object The object allows to specify the range of expiry periods of options that are used to construct the surface. For a detailed breakdown, please refer here. Optional If not provided, default values of parameters are used.

Strike Range

The table below lists the properties of surfaceParameters → filters → strikeRange object.

Input Name Type Description Importance Default value
minOfMedianImpliedVolPercent Double The value can be used to exclude strikes with implied volatilities less than lower bound. The lower bound is computed as MinOfMedianImpliedVolPercent multiplied by median implied volatility and divided by 100. The value is expressed in percentages. Optional The default value is '30.0'.
maxOfMedianImpliedVolPercent Double

The value can be used to exclude strikes with implied volatilities larger than upper bound. The upper bound is computed as MaxOfMedianImpliedVolPercent multiplied by median implied volatility and divided by 100. The value is expressed in percentages.

Mandatory if strikeRange object is used.

 Optional The default value is '500.0'.

Maturity Filter Range

The table below lists the properties of  surfaceParameters → filters → maturityFilterRange object.

Input Name Type Description Importance Default value
minOfMedianNbOfStrikesPercent Double The value is used to set the minimum number of strikes that should be available for maturities that are used to construct the surface. The minimum threshold is computed as MinOfMedianNbOfStrikesPercent multiplied by the median number of Strikes and divided by 100. The value is expressed in percentages. Optional The default value is '20.0'.
minMaturity String The period code used to set the minimal maturity of options used to construct the surface (e.g., '1M', '1Y'). Optional The default value is '7D'.
maxMaturity String The period code used to set the maximal maturity of options used to construct the surface (e.g., '1M', '1Y'). Optional No default value applies.

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'.		 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'.		 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'.

Mandatory 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.
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'.
surface Array of arrays The values of the properties that apply to the constructed volatility surface. 
discountCurve Object

The list of the zero-coupon discount curve attributes used to construct the volatility surface.

For a detailed breakdown, please refer here.
dividends Object The description of dividend yield of the underlying equity instrument. For a detailed breakdown, please refer here.
underlyingSpot Array of objects

The list of properties of the underlying’s spot and/or the futures values used to construct the volatility surface.

For a detailed breakdown, please refer here.
moneynessStrike Array of objects

The strike values corresponding to moneyness levels defined. It is returned in response only if one of the axis is set to Moneyness.

For a detailed breakdown, please refer here.
shiftedSurfaces Array of objects

The list of attributes applied to the shifted volatility surface. It is returned in response only if shiftScenarios is requested.

For a detailed breakdown, please refer here.

Discount Curve

The table below lists the discountCurve object properties.

Output Name Type Description
marketDataId String The identifier of the curve that is used to reference the market data item (e.g. 'IRCurve_EUR-DepoIRSvs6MEuribor_2022-06-17T00:00:00').
curveDefinition Object The definition of attributes for the curve. For the detailed breakdown please refer here.
curveParameters Object The list of parameters used to construct the curve. For the detailed breakdown please refer here.
points Array of objects The description of curve points. For the detailed breakdown please refer here.
currency String The currency code of the curve (e.g., 'EUR'). The possible values are listed here.

Curve Definition

The table below lists the properties of discountCurve → curveDefinition object. 

Output Name Type Description
chainRic String The chain RIC including the instruments to build the curve (e.g., '0#EURZ=R').
indexTenor String The code indicating the tenor applied to the curve (e.g., '6M', '1Y').
currency String The currency code of the curve (e.g., 'EUR'). The possible values are listed here.
name String The name of the curve (e.g., 'EUR - Depo IRS vs 6M Euribor').

Curve Parameters

The table below lists the properties of discountCurve → curveParameters object. 

Output Name Type Description
dayCountBasis String The day count basis method used to calculate the interest payments when constructing the curve. The possible values are listed here.
parallelShiftBp Double The amount by which every curve point is shifted. The value is expressed in basis points. At this moment it is equal to 0. 
compoundingType String The yield type of the curve (e.g., 'Compounded').
interpolationMode String The interpolation method used in the curve bootstrapping (e.g., 'CubicSpline').
extrapolationMode String The extrapolation method used in the curve bootstrapping (e.g., 'Constant').
marketDataDate Date-time The date at which the market data is retrieved. The value is expressed in ISO 8601 format: YYYY-MM-DDT[hh]:[mm]:[ss]Z (e.g., '2021-01-01T00:00:00Z').

Points

The table below lists the properties of discountCurve → points array of objects. 

Output Name Type Description
startDate Date The start date of the curve point tenor. The value is expressed in ISO 8601 format: YYYY-MM-DD (e.g., '2021-01-01').
endDate Date The end date of the curve point tenor. The value is expressed in ISO 8601 format: YYYY-MM-DD (e.g., '2021-01-01').
ratePercent Double The rate percent of the curve computed for the given curve point.
instruments Array of objects
The list of instruments used for the curve points computation.
Output Name Type Description
instrumentCode String The code used to define the instrument which is used for the curve point computation.
tenor String The code indicating the period between startDate and endDate of the curve points (e.g., '1M', '6M', '4Y').
instrument String The code used to define the instrument which is used for the curve point computation (e.g., 'EUR6MZ=R').
discountFactor Double The ratio used to calculate the present value of future cash flows at valuationDate. It is derived from ratePercent which corresponds to the curve point tenor.

Dividends

The table below lists the dividends object properties.

Output Name Type Description
curveDefinition Object

The description of the dividend yield curve. For a detailed breakdown, please refer here.
curveParameters Object

The description of dividend yield curve structure. For a detailed breakdown, please refer here.
points Array of objects

The description of points on the dividend yield curve. For a detailed breakdown, please refer here.

Curve Definition

The table below lists the properties of dividends -> curveDefinition object.

Output Name Type Description
instrumentCode String The code (a RIC) used to define the underlying asset.
type String

The type of the dividend yield. The possible values are:

  • None: the underlying doesn't distribute dividends.
  • HistoricalYield: historical dividends. Available both for stocks and indices.
  • ForecastTable: forecasted dividends, the calculation is based on dividend history and estimates. Available both for stocks and indices.
  • ImpliedYield: forecasted dividends, implied from option prices. Available for indices only.

For more details, please refer here.
ric String

The code used to define the underlying asset's dividend cash flows.

Dividend Logic

Depending on the underlying type (stock, ETF, index) and the availability of the data, dividends can be of the following types.

Note: The logic around the default dividend type for a particular Ric or underlying type might have changed since the calculation date.

Dividend Type

Calculation Mode

Dividend Values for Stocks

Dividend Values for Indices

Comment

HistoricalYield

Calculated for:

  • historical requests with one or more custom parameters.

Dividends are expressed in percentages.

Dividends are expressed in percentages.

Historical requests with default parameters use pre-calculated SVI calibration parameters in order to improve performance.

ForecastTable

 Calculated for:
  • historical requests with default parameters,
  • real-time requests.

Dividends are expressed in cash amount.

Dividends are expressed in percentages and index points.

 Coverage:
  •  stocks in <IMPLIEDVOL4>,
  • indices in <INDEX/DIVCF>.

ImpliedYield

 Calculated for:
  • historical requests with default parameters,
  • real-time requests.

n/a

Dividends are expressed in percentages.

Coverage: indices in <INDEX/DIVCF>.

Curve Parameters

The table below lists the properties of dividends -> curveParameters object.

Output Name

Type

Description

structure

String

The description of the internal structure of the dividend yield curve.

Points

The table below lists the properties of dividends -> points object.

Output Name Type Description
exDate Date-time The date from which the stock starts trading without the value of its dividend payment. The value is expressed in ISO 8601 format: YYYY-MM-DDT[hh]:[mm]:[ss]Z (e.g., '2021-01-01T00:00:00Z').
dividendYieldPercent Double The ratio of annualized dividends to the underlying asset's price. The value is expressed in percentages.
dividendCashAmount Double

The cash amount of dividends. The value is expressed in the instrument's currency.

Underlying Spot

The table below lists the underlyingSpot array of objects properties. 

Output Name Type Description
instrumentCode String The code used to define the underlying (e.g., 'BNPP.PA').
timeStamp String

 The timestamp of the underlying’s price. The possible values are:

  • Default: the latest snapshot is used when calculationDate is today, and the close price is used when calculationDate is in the past,
  • Open: the opening price of calculationDate,
  • Close: the closing price of calculationDate, or if it is not available, the close price of the previous day is used,
  • Settle: settlement values are used.
priceSide String

The price side of the underlying instrument. The possible values are:

  • Bid,
  • Ask,
  • Mid,
  • Last.
price Double

The price of the underlying instrument.

Moneyness Strike

The table below lists the moneynessStrike array of objects properties. 

Output Name Type Description
Moneyness Double The moneyness value is either requested from the surface layout or computed by default. 
Strike Double

The strike price associated with the moneyness level of the constructed volatility surface.

Error Messages

Error Code Error Message Description
8002. VolSurf.10006 Invalid input: Instrument code must end with @RIC, @RICROOT or @TICKER instrumentCode missing @RIC.
8003. VolSurf.10004 Invalid input: SurfaceDefinition is empty. Please fill it! UnderlyingDefinition is null.
8004 Invalid input: SurfaceParameters is empty. Please fill it! SurfaceParameters is null.
8005 Invalid input: SurfaceLayout is empty. Please fill it! SurfaceLayout is null.
VolSurf.10005 Invalid input: InstrumentCode is empty. Please fill it! InstrumentCode is null.
  Invalid input: Instrument code is not recognized. 'xxx@RIC' is not valid underlying. Wrong instrument code.
No error returned Invalid input: The service only supports today as a calculation date. Historical volatility will be available soon. Calculation date is in the past.
VolSurf.10200 Market data: The service failed to retrieve the necessary data to build the volatility surface. Global DPS error.
VolSurf.10102 Market data: The service failed to gather enough options to build the volatility surface. Static filter returned no option.
VolSurf.10201 Market data: The options available for xxx can't be used to build an accurate volatility surface. The Prepare returns no filtered RICs (dynamic filter).
VolSurf.10300 The service failed to build the volatility surface. Global VolSurf error.
8006 Market data: No rate curve available to build an accurate volatility surface. The Prepare returns no rate curve.
8007 Pricer: The service failed to build the volatility surface. Global Pricer error.
8007 Pricer: The service failed to build the volatility surface. Adfin error when calibrating the surface. Adfin error message: "Calibration failed" "SVI automatic guess failed".
8007 Pricer: The service failed to build the volatility surface with the specified calibration parameters. Adfin error due to invalid surface parameters. Adfin error message:Invalid calibrated params.
8007 Pricer: The service failed to build the volatility surface. Adfin error due to invalid options. Adfin error message:Invalid options input.
8008 Invalid input: Same value has been entered in XAxis and YAxis! The same value has been set in xAxis nad yAxis.
8009 Invalid input: Either XAxis or YAxis should contain either 'Date' or 'Tenor'. At least one axis should contain 'Date' or 'Tenor'.
8010 Invalid input: Both XAxis and YAxis should not contain 'Date' and 'Tenor'. Both axis contains 'Date' and 'Tenor'.
8011 Market data: No Dividend curve available to build an accurate volatility surface. Impossible to rebuild a surface because no dividend curve has been saved.
8012 Market data: No Discount curve available to build an accurate volatility surface. Impossible to rebuild a surface because no discount curve has been saved.
8013 Market data: No Forward curve available to build an accurate volatility surface. Impossible to rebuild a surface because no forward curve has been saved.
8014 Market data: No Calibration Parameter available to build an accurate volatility surface. Impossible to rebuild a surface because no calibration parameter has been saved.
8018 Invalid inputVolatilityType: neither surface nor ATM volatility market data has this inputVolatilityType. Impossible to identify volatility of this type with available Vol market data.
VolSurf.10102 The volatility surface cannot be calculated at the requested date. Surface requested at a historical date on which we don't have any calibration parameters.
VolSurf.10008 Unknown instrument. Instrument is unknown.