cmFutAmericanOptionPricer

cmFutAmericanOptionPricer(instrument, pricingDate, futPrice, discountCurve, volSurf, [setting], [model], [method])

Prices American commodity futures options.

instrument: An INSTRUMENT scalar or vector specifying the American commodity futures options to be priced. For field requirements, see the Instrument Field Description.

pricingDate: A DATE scalar or vector specifying the pricing date.

futPrice: A DOUBLE scalar or vector specifying the current price of the underlying futures contract.

domesticCurve: A MKTDATA scalar or vector specifying the domestic discount curve.

volSurf : A MKTDATA scalar or vector specifying the volatility surface.

setting (optional): A dictionary used to configure pricing outputs. It supports the following keys:

• calcDelta: Set a boolean value to specify whether to calculate delta.

• calcGamma: Set a boolean value to specify whether to calculate gamma.

• calcVega: Set a boolean value to specify whether to calculate vega.

• calcTheta: Set a boolean value to specify whether to calculate theta.

• calcRho: Set a boolean value to specify whether to calculate rho.

model (optional): A STRING scalar specifying the pricing model to use. Valid values:

• "Black76": Black 76 formula

• "BAW" (default): Barone-Adesi-Whaley formula

• "AmericanBinomialTree": American-style binomial tree pricing model

method (optional): A STRING scalar specifying the calculation method. Valid values:

• "Analytic" (default): Analytic method

• "Tree": Tree method, supports the model AmericanBinomialTree

• If setting is not specified, returns a DOUBLE scalar indicating the net present value (NPV) of the option.

• If setting is specified, returns a dictionary containing the NPV and the Greeks as specified in setting .

// ================================================================
// AUTO-GENERATED DolphinDB Script
// Function   : cmFutAmericanOptionPricer  Commodity futures American option pricing example
// Underlying : Shanghai Futures Exchange copper futures options (cu)
// PricingDate: 2026-02-13
//
// Data sources:
//   Futures settlement price : akshare get_futures_daily(market='SHFE')
//   Options settlement price : akshare option_hist_shfe('copper options', '20260213')
//   Interest rate curve      : ChinaMoney FX implied rate curve (CNY, USD.CNY/Shibor/swap points)
//                              https://www.chinamoney.com.cn/chinese/bkcurvuiruuh/
//                              API: POST /ags/ms/cm-u-bk-fx/IuirCurvHis  2026-02-13
//
// Pricing instrument : CU2605 copper futures American call option
//                      strike=102000  opt_expiry=2026-04-24
//                      fut_price=101230
// ================================================================

pricingDate   = 2026.02.13
referenceDate = pricingDate

// ------------------------------------------------------------------
// 1. Discount curve (CNY_FR_007) ── ChinaMoney FX implied rate curve
//    Data source: https://www.chinamoney.com.cn/chinese/bkcurvuiruuh/
//    USD.CNY / Shibor / spot quote average / swap points  →  rmbRateStr field
// ------------------------------------------------------------------
discountCurveDict = {
    "mktDataType"       : "Curve",
    "curveType"         : "IrYieldCurve",
    "referenceDate"     : referenceDate,
    "currency"          : "CNY",
    "dayCountConvention": "Actual365",
    "compounding"       : "Continuous",
    "interpMethod"      : "Linear",
    "extrapMethod"      : "Flat",
    "frequency"         : "Annual",
    "dates"             : [referenceDate + 1, referenceDate + 7, referenceDate + 14, referenceDate + 21, referenceDate + 30, referenceDate + 61, referenceDate + 91, referenceDate + 182, referenceDate + 273, referenceDate + 365, referenceDate + 547, referenceDate + 730, referenceDate + 1095],
    "values"            : [0.016134, 0.016107, 0.016102, 0.016102, 0.016102, 0.016103, 0.016029, 0.015832, 0.015889, 0.015898, 0.015561, 0.015583, 0.015892],
    "name"              : "CNY_FR_007"
}
discountCurve = parseMktData(discountCurveDict)

// ------------------------------------------------------------------
// 2. Futures price curve (AssetPriceCurve)
//    Settlement prices of copper futures across maturities
// ------------------------------------------------------------------
futPriceCurveDict = {
    "mktDataType" : "Curve",
    "curveType"   : "AssetPriceCurve",
    "referenceDate": referenceDate,
    "currency"    : "CNY",
    "asset"       : "CU",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "dates"       : [2026.04.15, 2026.05.15, 2026.06.15, 2026.07.15, 2026.08.17, 2026.09.15],
    "values"      : [100980.0, 101230.0, 101240.0, 101100.0, 101230.0, 101250.0]
}
futPriceCurve = parseMktData(futPriceCurveDict)

// ------------------------------------------------------------------
// 3. Option market data ── build volatility surface
//    Number of expiries: 6
//    Use OTM options: K < F → Put, K >= F → Call
// ------------------------------------------------------------------
optionExpiries = [2026.03.25, 2026.04.24, 2026.05.25, 2026.06.24, 2026.07.27, 2026.08.25]
futMaturities  = [2026.04.15, 2026.05.15, 2026.06.15, 2026.07.15, 2026.08.17, 2026.09.15]

// ------------------------------------------------------------------
// 4. Build volatility surface ── BAW formula + SVI model
//    Use BAW formula to compute implied volatility of American options
// ------------------------------------------------------------------
volSurf = cmFutVolatilitySurfaceBuilder(
    referenceDate, futMaturities, optionExpiries,
    strikes, optionPrices, payoffTypes,
    discountCurve, futPriceCurve,
    formula="BAW", model="SVI",
    surfaceName="cu_vol_surface_20260213"
)
print(volSurf)

// ------------------------------------------------------------------
// 5. Define pricing instrument ── copper futures American call option
//    Underlying: CU2605  Strike: 102000  Expiry: 2026-04-24
// ------------------------------------------------------------------
cmFutAmericanOption = {
    "productType"       : "Option",
    "optionType"        : "AmericanOption",
    "assetType"         : "CmFutAmericanOption",
    "instrumentId"      : "CU2605C102000",
    "notionalAmount"    : 5.0,
    "notionalCurrency"  : "CNY",
    "strike"            : 102000.0,
    "maturity"          : 2026.04.24,
    "payoffType"        : "Call",
    "dayCountConvention": "Actual365",
    "underlying"        : "CU2605",
    "domesticCurve"     : "CNY_FR_007"
}
instrument = parseInstrument(cmFutAmericanOption)

// ------------------------------------------------------------------
// 6. Pricing ── single instrument NPV (BAW model)
// ------------------------------------------------------------------
spot = 101230.0
npv = cmFutAmericanOptionPricer(instrument, pricingDate, spot, discountCurve, volSurf, model="BAW")
print("NPV = " + string(npv))

// ------------------------------------------------------------------
// 7. Pricing ── with Greeks
// ------------------------------------------------------------------
setting = {
    "calcDelta" : true,
    "calcGamma" : true,
    "calcVega"  : true,
    "calcTheta" : true,
    "calcRho"   : true
}
result = cmFutAmericanOptionPricer(instrument, pricingDate, spot, discountCurve, volSurf, setting, model="BAW")
print(result)

// ------------------------------------------------------------------
// 8. Batch pricing ── price multiple Call options with different strikes for CU2605 maturity
// ------------------------------------------------------------------
allStrikes = [82000, 84000, 86000, 88000, 90000, 92000, 94000, 96000, 98000, 100000, 102000, 104000, 106000, 108000, 110000, 112000, 114000, 116000, 118000, 120000]
results = array(DOUBLE, 0)
for (k in allStrikes) {
    iDict = {
        "productType"       : "Option",
        "optionType"        : "AmericanOption",
        "assetType"         : "CmFutAmericanOption",
        "instrumentId"      : "CU2605C" + string(int(k)),
        "notionalAmount"    : 5.0,
        "notionalCurrency"  : "CNY",
        "strike"            : k,
        "maturity"          : 2026.04.24,
        "payoffType"        : "Call",
        "dayCountConvention": "Actual365",
        "underlying"        : "CU2605",
        "domesticCurve"     : "CNY_FR_007"
    }
    iOpt = parseInstrument(iDict)
    results.append!(cmFutAmericanOptionPricer(iOpt, pricingDate, spot, discountCurve, volSurf, model="BAW"))
}
t = table(allStrikes as strike, results as npv)
print(t)

Related Functions: parseInstrument, parseMktData, cmFutVolatilitySurfaceBuilder