fxRangeAccrualOptionPricer

fxRangeAccrualOptionPricer(instrument, pricingDate, spot, domesticCurve, foreignCurve, volSurf, [setting])

Prices a foreign exchange (FX) range accrual option.

instrument is an INSTRUMENT scalar or vector that specifies the FX range accrual option to price. For field requirements, see the product field description.

pricingDate is a DATE scalar or vector that specifies the pricing date.

spot is a numeric scalar or vector that specifies the spot exchange rate.

domesticCurve is an MKTDATA scalar or vector that specifies the domestic currency discount curve (IrYieldCurve).

foreignCurve is an MKTDATA scalar or vector that specifies the foreign currency discount curve (IrYieldCurve).

volSurf is an MKTDATA scalar or vector that specifies the FX volatility surface (FxVolatilitySurface).

setting is an optional Dictionary parameter that specifies whether to calculate option price sensitivities (Greeks).

• If the setting parameter is not specified, the function returns a DOUBLE scalar that indicates the option's net present value (NPV), which is the theoretical price of the option.
• If the setting parameter is specified, the function returns a Dictionary that contains the option's NPV and option price sensitivities (Greeks). For descriptions of the sensitivity measures, see the setting parameter description.

Example 1: Use fxRangeAccrualOptionPricer to price a EURUSD FX range accrual option. This example first constructs the option contract and prepares the market data required for pricing, including the spot exchange rate, domestic and foreign risk-free yield curves, and the FX volatility surface. It then uses the setting parameter to specify the risk measures (Greeks) to calculate, and finally calls fxRangeAccrualOptionPricer to return the option price and the corresponding risk measures.

// ==========================================
// 1. Set up the base environment and global variables
// ==========================================
pricingDate = 2025.12.16 // Pricing date (the reference date for valuation)
ccyPair = "EURUSD"          // Trading currency pair: EUR/USD

// ==========================================
// 2. Define the structure of the FX range accrual option
// ==========================================
option = {
    "productType": "Option",
   "optionType": "RangeAccrualOption", // Option type: Range accrual option
    "assetType": "FxRangeAccrualOption", // Asset type: FX range accrual option
    "instrumentId": "0001",              // Underlying asset code/contract ID
    "notionalAmount": 1000000.0,         // Notional principal: 1,000,000
    "notionalCurrency": "USD",           // Notional currency: USD
   "start": 2025.12.17, // Accrual observation start date
   "maturity": 2026.03.16, // Option expiry date
    "underlying": "EURUSD",              // Underlying asset: EURUSD exchange rate
    "direction": "Sell",                 // Trade direction: sell (short position)
    "dayCountConvention": "Actual365",   // Day count convention: Actual/365
    "lowerBarrier": 1.1160,              // Lower bound of the accrual range; interest does not accrue if the exchange rate is below this level
    "upperBarrier": 1.2335,              // Upper bound of the accrual range; interest does not accrue if the exchange rate is above this level
    "reportCurrency": "USD",             // Functional currency for financial reporting/output: USD
    "payoffType": "Call"                 // Payoff type: call
}

spot = 1.1748                            // EURUSD spot rate on the pricing date
instrument = parseInstrument(option)     // Parse the option structure and convert it to an internal object recognized by the DolphinDB pricing engine

// ==========================================
// 3. Build market data: domestic and foreign interest rate yield curves
// ==========================================
// Key tenor dates corresponding to the subsequent volatility and interest rate tenors
curveDates = [2026.02.24, 2026.05.20]    

// 3.1 Domestic currency (domestic / quote currency) interest rate curve: USD in this example
domesticCurveInfo = {
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",         // Market data type: interest rate yield curve
    "referenceDate": pricingDate,        // Curve reference date
    "currency": "USD",                   // Currency: USD
    "dayCountConvention": "Actual360",   // Day count convention: Actual/360
    "compounding": "Simple",             // Compounding method: Simple
   "interpMethod": "Linear", // Interpolation method: linear interpolation
    "extrapMethod": "Flat",              // Extrapolation method: Flat
   "frequency": "Annual", // Interest rate frequency: annual
    "dates": curveDates,                 // Tenor nodes
    "values":[0.03703, 0.03703] // Corresponding USD interest rate (annualized 3.703%)
}

// 3.2 Foreign/base currency interest rate curve: EUR in this example
foreignCurveInfo = {
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",
    "referenceDate": pricingDate,
    "currency": "EUR",                   // Currency: Euro
    "dayCountConvention": "Actual360",
    "compounding": "Simple",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "frequency": "Annual",
    "dates": curveDates,
    "values":[0.01925, 0.01925]          // Corresponding EUR interest rate value (annualized 1.925%)
}

// Parse and generate the internal interest rate curve object
domesticCurve = parseMktData(domesticCurveInfo)
foreignCurve = parseMktData(foreignCurveInfo)

// ==========================================
// 4. Build market data: FX volatility surface
// ==========================================
surfInfo = {
	"surfaceName": "EURUSD",
	"mktDataType": "Surface",
	"surfaceType": "FxVolatilitySurface", // Market data type: FX volatility surface
	"referenceDate": pricingDate,         // Surface reference date
	"smileMethod": "Linear", // Volatility smile interpolation method: linear
	"termDates": curveDates,              // Tenor nodes
    // Define implied volatilities for different maturities and strikes (simplified here as a constant volatility of 5.736%)
	"volSmiles":[
 {"strikes": [1.1, 1.2, 1.3], "vols": [0.05736, 0.05736, 0.05736]}, // Volatility of node 1
 {"strikes": [1.1, 1.2, 1.3], "vols": [0.05736, 0.05736, 0.05736]} // Volatility of node 2
    ],
	"currencyPair": "EURUSD"              // Currency pair
}
surf = parseMktData(surfInfo)             // Parse and generate the internal volatility surface object

// ==========================================
// 5. Configure calculation parameters (select the Greeks to output)
// ==========================================
setting = dict(STRING, ANY)
setting["calcDelta"] = true // Calculate Delta (sensitivity to the underlying asset price)
setting["calcGamma"] = true          // Calculate Gamma (sensitivity of Delta to the underlying asset price)
setting["calcVega"] = true           // Calculate Vega (sensitivity to volatility)
setting["calcTheta"] = true          // Calculate Theta (sensitivity to the passage of time)
setting["calcRhoDomestic"] = true    // Calculate Rho for the domestic interest rate (sensitivity to the USD interest rate)
setting["calcRhoForeign"] = true     // Calculate Rho for the foreign interest rate (sensitivity to the EUR interest rate)
setting["calcVolga"] = true          // Calculate Volga (second-order sensitivity of Vega to volatility)
setting["calcVanna"] = true          // Calculate Vanna (cross-sensitivity of Delta to volatility)

// ==========================================
// 6. Call the pricing engine and output the results
// ==========================================
res = fxRangeAccrualOptionPricer(instrument, pricingDate, spot, domesticCurve, foreignCurve, surf, setting) 
res

/*==========================================
Output Explanation
==========================================
npv: 568,710.38          -> Option net present value (NPV), the theoretical value of the current contract.
delta: -12,700,391.97    -> Delta, the change in option value for a 1-unit change in the spot exchange rate (the negative value reflects the short position).
gamma: 1,317,948.28      -> Gamma, the rate of change in Delta caused by changes in the spot exchange rate.
vega: 14,960.41          -> Vega, the change in option value for a 1% (or 1-unit) change in implied volatility.
theta: -1,144.35         -> Theta, the rate at which the option value decays for each day that passes.
rhoDomestic: -36,601.48  -> Domestic Rho.
rhoForeign: 38,016.45    -> Foreign Rho.
volga: 4,702.96          -> Volga, second-order volatility risk (volatility of volatility).
vanna: 3,237,277.66      -> Vanna, cross-risk between the exchange rate and volatility.
*/

Example 2: Price a USDJPY FX range accrual option using fxRangeAccrualOptionPricer.

// ==========================================
// 1. Set up the base environment and global variables
// ==========================================
pricingDate = 2025.12.16    // Pricing date (the reference date for valuation)
ccyPair = "USDJPY"          // Currency pair for the trade (US dollar against Japanese yen)

// ==========================================
// 2. Define the structure of the FX range accrual option
// ==========================================
option = {
    "productType": "Option",
    "optionType": "RangeAccrualOption", // Option type: Range accrual option
    "assetType": "FxRangeAccrualOption", // Asset type: FX range accrual option
    "instrumentId": "0001", // Underlying asset code/contract ID
    "notionalAmount": 1000000.0,         // Notional principal: 1,000,000
    "notionalCurrency": "USD",           // Notional currency: USD
    "start": 2025.12.17,                 // Accrual observation start date
    "maturity": 2026.03.16,              // Option expiry date
    "underlying": "USDJPY",              // Underlying asset: USDJPY exchange rate
     "direction": "Sell", // Trade direction: sell (short position)
    "dayCountConvention": "Actual360",   // Day count convention for the option: Actual/360
    "lowerBarrier": 147.1692,            // Lower accrual barrier (no interest accrues for the day if the exchange rate is below 147.1692)
    "upperBarrier": 162.6608,            // Upper accrual barrier (no interest accrues for the day if the exchange rate is above 162.6608)
     "reportCurrency": "USD", // Functional currency for financial reporting/output: USD
     "payoffType": "Call" // Payoff type: call
}

spot = 154.92                            // USDJPY spot rate on the pricing date
instrument = parseInstrument(option) // Parse the option structure and convert it to an internal object recognized by the DolphinDB pricing engine

// ==========================================
// 3. Build market data: domestic and foreign interest rate yield curves
// ==========================================
// Key tenor dates corresponding to the subsequent volatility and interest rate tenors
curveDates = [2026.02.24, 2026.05.20]    

// 3.1 Domestic (quote currency) interest rate curve: for USDJPY, the domestic currency is JPY
domesticCurveInfo = {
    "mktDataType": "Curve",
     "curveType": "IrYieldCurve", // Market data type: interest rate yield curve
    "referenceDate": pricingDate,        // Curve reference date
    "currency": "JPY",                   // Currency: Japanese yen
    "dayCountConvention": "Actual360",   // JPY market day count convention: Actual/360
    "compounding": "Simple",             // Compounding method: Simple
    "interpMethod": "Linear",            // Interpolation method: linear interpolation
    "extrapMethod": "Flat",              // Extrapolation method: flat extrapolation
 "frequency": "Annual", // Interest rate frequency: annual
    "dates": curveDates,                 // Tenor nodes
    "values":[0.00434, 0.00434]          // Corresponding JPY interest rate value (annualized 0.434%)
}

// 3.2 Foreign/base currency interest rate curve: for USDJPY, the foreign currency is USD
foreignCurveInfo = {
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",
    "referenceDate": pricingDate,
    "currency": "USD",                   // Currency: USD
    "dayCountConvention": "Actual365",   // USD market day count convention: Actual/365
    "compounding": "Simple",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "frequency": "Annual",
    "dates": curveDates,
    "values":[0.03703, 0.03703]          // Corresponding USD interest rate (annualized 3.703%)
}

// Parse and generate the internal interest rate curve object
domesticCurve = parseMktData(domesticCurveInfo)
foreignCurve = parseMktData(foreignCurveInfo)

// ==========================================
// 4. Build market data: FX volatility surface
// ==========================================
surfInfo = {
	"surfaceName": "USDJPY",
	"mktDataType": "Surface",
	"surfaceType": "FxVolatilitySurface", // Market data type: FX volatility surface
	"referenceDate": pricingDate,         // Surface reference date
	"smileMethod": "Linear",              // Volatility smile interpolation method: linear
	"termDates": curveDates,              // Tenor nodes
    // Define implied volatilities for different maturities and common USDJPY strikes (constant volatility set to 8.815%)
	"volSmiles":[
        {"strikes": [140.0, 150.0, 160.0], "vols": [0.08815, 0.08815, 0.08815]}, // Volatility of node 1
        {"strikes": [140.0, 150.0, 160.0], "vols": [0.08815, 0.08815, 0.08815]}  // Volatility of node 2
    ],
	"currencyPair": "USDJPY"              // Currency pair
}
surf = parseMktData(surfInfo)             // Parse and generate the internal volatility surface object

// ==========================================
// 5. Configure calculation parameters (select the Greeks to output)
// ==========================================
setting = dict(STRING, ANY)
setting["calcDelta"] = true          // Calculate Delta (sensitivity to the underlying exchange rate)
setting["calcGamma"] = true          // Calculate Gamma (sensitivity of Delta to the underlying exchange rate)
setting["calcVega"] = true           // Calculate Vega (sensitivity to volatility)
setting["calcTheta"] = true          // Calculate Theta (sensitivity to the passage of time)
setting["calcRhoDomestic"] = true    // Calculate domestic interest rate Rho (sensitivity to JPY interest rates)
setting["calcRhoForeign"] = true     // Calculate foreign interest rate Rho (sensitivity to USD interest rates)
setting["calcVolga"] = true          // Calculate Volga (second-order sensitivity of Vega to volatility)
setting["calcVanna"] = true          // Calculate Vanna (cross-sensitivity of Delta to volatility)

// ==========================================
// 6. Call the pricing engine and output the results
// ==========================================
res = fxRangeAccrualOptionPricer(instrument, pricingDate, spot, domesticCurve, foreignCurve, surf, setting)
res

/*==========================================
Output Explanation
==========================================
npv: 455,601.07          -> Option net present value (Net Present Value), the current theoretical value of selling this option contract.
delta: -6,488,682.37     -> Delta, the change in option value for each 1-unit change in the USDJPY spot exchange rate (the negative value reflects the sell direction).
gamma: 1,299,231.79      -> Gamma, the rate of change in Delta caused by changes in the spot exchange rate.
vega: 15,632.86          -> Vega, the change in option value for each 1% (or 1 unit) change in implied volatility.
theta: -1,591.54         -> Theta, the rate at which the option value decays for each day that passes (commonly negative time value for option sellers).
rhoDomestic: -17,887.72  -> Domestic Rho.
rhoForeign: 19,000.95    -> Foreign Rho.
volga: 1,104.27          -> Volga, second-order volatility risk (the rate of change in Vega as volatility changes).
vanna: 9,279.49          -> Vanna, cross risk between the exchange rate and volatility (the rate of change in Vega as the exchange rate changes).
*/

Related functions: parseInstrument and parseMktData