bondPricer

First introduced in version: 3.00.4

Syntax

bondPricer(instrument, pricingDate, discountCurve, [spreadCurve], [setting], [forwardCurve])

Details

Prices the bond instrument(s), supporting output of multiple risk measures, including (NPV (Net Present Value), Delta (first-order sensitivity), Gamma (second-order sensitivity), and Key Rate Duration (sensitivity to interest rate shifts at specified key maturities).

Supports floating-rate bonds (bondType="FloatingRateBond"). The first unpaid coupon uses lastFixing. For subsequent periods, the reference rate is derived from forwardCurve, and spread is added to obtain the coupon rate.

Parameters

Note:

Scalar inputs will be automatically expanded to match the length of other vector inputs. All vector inputs must be of equal length.

instrument is an INSTRUMENT scalar/vector object representing the bond(s) to be priced. The required key fields vary depending on the type of bond product; see Bond Product Field Specifications for details.

pricingDate is a DATE scalar/vector specifying the pricing date(s).

discountCurve is a MKTDATA scalar/vector of type IrYieldCurve representing the discount curve(s). See Curve Field Specifications for details.

spreadCurve (optional) is a MKTDATA scalar/vector of type IrYieldCurve representing the credit spread curve(s). If not specified, defaults to a flat curve with 0% spread. See Curve Field Specifications for details.

setting (optional)is a Dictionary<STRING, ANY> with the following key-value pairs：


Key	Value Type	Description
"calcDiscountCurveDelta"	BOOL	Whether to compute the bond’s first-order sensitivity (delta) to the discount curve.
"calcDiscountCurveGamma"	BOOL	Whether to compute the bond’s second-order sensitivity (gamma) to the discount curve.
"calcDiscountCurveKeyRateDuration"	BOOL	Whether to compute the bond’s key rate durations.
"discountCurveShift"	DOUBLE scalar	The parallel shift applied to the discount curve. For example, a bp(0.0001).
"discountCurveKeyTerms"	DOUBLE scalar/vector	The specific maturity point(s) to calculate the key rate duration. For example, [1.0, 3.0, 5.0].
"discountCurveKeyShifts"	DOUBLE scalar/vector	The shift amounts corresponding to each maturity point. It has the same length with discountCurveKeyTerms. For example, [0.0001, 0.0002, 0.0015].
"useExerciseCashflow"	BOOL	(Optional) Whether to calculate NPV using cash flows from the nearest future exercise date. Defaults to false, indicating not to use exercise cash flow for calculation. If the pricing date is after the last exercise date, this setting is invalid and still calculates using original cash flows.

forwardCurve (optional) is a MKTDATA scalar/vector of type IrYieldCurve used to derive floating coupon rates. It is required when instrument is a floating-rate bond and ignored for other bond types. The curve's referenceDate must match pricingDate.

Returns

For scalar input:

If setting is not specified, returns the NPV (a DOUBLE scalar).
If setting is specified, returns a Dictionary<STRING, ANY> with the following key-value pairs:
- "npv": A DOUBLE scalar
- "discountCurveDelta": A DOUBLE scalar
- "discountCurveGamma": A DOUBLE scalar
- "discountCurveKeyRateDuration": A DOUBLE vector

For vector input, it returns a DOUBLE vector (if setting is not specified) or a tuple of dictionaries (if setting is specified).

Examples

Price fixed rate bonds.

bond = {
  "productType": "Cash",
  "assetType": "Bond",
  "bondType": "FixedRateBond",
  "version": 0, 
  "instrumentId": "240025.IB",
  "start": 2024.12.25,
  "maturity": 2031.12.25,
  "issuePrice": 100.0,
  "coupon": 0.0149,
  "frequency": "Annual",
  "dayCountConvention": "ActualActualISDA"
}

pricingDate = 2025.08.18

curve = {
  "mktDataType": "Curve",
  "curveType": "IrYieldCurve",
  "referenceDate": pricingDate,
  "currency": "CNY",
  "curveName": "CNY_TREASURY_BOND",
  "dayCountConvention": "ActualActualISDA",
  "compounding": "Compounded",
  "interpMethod": "Linear",
  "extrapMethod": "Flat",
  "frequency": "Annual",
  "dates":[2025.09.18, 2025.11.18, 2026.02.18, 2026.08.18, 2027.08.18, 2028.08.18, 2030.08.18,
      2032.08.18, 2035.08.18, 2040.08.18, 2045.08.18, 2055.08.18,2065.08.18, 2075.08.18],
  "values":[1.3000, 1.3700, 1.3898, 1.3865, 1.4299, 1.4471, 1.6401,
       1.7654, 1.7966, 1.9930, 2.1834, 2.1397, 2.1987, 2.2225] / 100.0
}

instrument = parseInstrument(bond)
discountCurve = parseMktData(curve)

setting = dict(STRING, ANY)
setting["calcDiscountCurveDelta"] = true
setting["calcDiscountCurveGamma"] = true
setting["calcDiscountCurveKeyRateDuration"] = true
setting["discountCurveShift"] = 0.0001
setting["discountCurveKeyTerms"] = [1.0, 3.0, 5.0]
setting["discountCurveKeyShifts"] = [0.0002, 0.0003, 0.0001]

bondPricer(instrument, pricingDate, discountCurve, setting=setting)

bondPricer([instrument, instrument], pricingDate, discountCurve, setting=setting)
bondPricer(instrument, pricingDate, [discountCurve, discountCurve], setting=setting)
bondPricer(instrument, [pricingDate], discountCurve, setting=setting)
bondPricer(instrument, [pricingDate, pricingDate], discountCurve, setting=setting)

Price a three-year floating-rate bond with semiannual coupon payments:

floatingBond = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FloatingRateBond",
    "instrumentId": "240025.IB",
    "start": 2017.09.11,
    "maturity": 2020.09.11,
    "frequency": "Semiannual",
    "dayCountConvention": "Actual365",
    "iborIndex": "LPR_1Y",
    "spread": 0.02,
    "lastFixing": 0.08
}
instrument = parseInstrument(floatingBond)
pricingDate = 2017.09.11

discountCurve = parseMktData({
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",
    "referenceDate": pricingDate,
    "currency": "CNY",
    "curveName": "CNY_TREASURY_BOND",
    "dayCountConvention": "Actual365",
    "compounding": "Continuous",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "frequency": "Semiannual",
    "dates": [2018.03.11, 2018.09.11, 2019.03.11, 2019.09.11, 2020.03.11, 2020.09.11],
    "values": [0.05, 0.06, 0.07, 0.08, 0.09, 0.10]
})

forwardCurve = parseMktData({
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",
    "referenceDate": pricingDate,
    "currency": "CNY",
    "curveName": "CNY_FORWARD",
    "dayCountConvention": "Actual365",
    "compounding": "Continuous",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "frequency": "Semiannual",
    "dates": [2018.03.11, 2018.09.11, 2019.03.11, 2019.09.11, 2020.03.11, 2020.09.11],
    "values": [0.05, 0.06, 0.07, 0.08, 0.09, 0.10]
})

round(bondPricer(
    instrument=instrument,
    pricingDate=pricingDate,
    discountCurve=discountCurve,
    forwardCurve=forwardCurve
), 4)
// output: 106.6335

Price an option bond.

bond = {
  "productType": "Cash",
  "assetType": "Bond",
  "bondType": "OptionBond",
  "version": 0, 
  "instrumentId": "240025.IB",
  "start": 2024.12.25,
  "maturity": 2031.12.25,
  "issuePrice": 100.0,
  "coupon": 0.0149,
  "frequency": "Annual",
  "exerciseDates": [2028.12.25],
   "hasCallOption": true,
   "hasPutOption": true,
   "hasCouponAdjust": true,
   "dayCountConvention": "ActualActualISMA"
}

pricingDate = 2025.08.18

curve = {
  "mktDataType": "Curve",
  "curveType": "IrYieldCurve",
  "referenceDate": pricingDate,
  "currency": "CNY",
  "curveName": "CNY_TREASURY_BOND",
  "dayCountConvention": "ActualActualISDA",
  "compounding": "Compounded",
  "interpMethod": "Linear",
  "extrapMethod": "Flat",
  "frequency": "Annual",
  "dates":[2025.09.18, 2025.11.18, 2026.02.18, 2026.08.18, 2027.08.18, 2028.08.18, 2030.08.18,
      2032.08.18, 2035.08.18, 2040.08.18, 2045.08.18, 2055.08.18,2065.08.18, 2075.08.18],
  "values":[1.3000, 1.3700, 1.3898, 1.3865, 1.4299, 1.4471, 1.6401,
       1.7654, 1.7966, 1.9930, 2.1834, 2.1397, 2.1987, 2.2225] / 100.0
}

instrument = parseInstrument(bond)
discountCurve = parseMktData(curve)

// useExerciseCashflow=false, do not use exercise cash flow for calculation (default)
setting = dict(STRING, ANY)
setting["calcDiscountCurveDelta"] = true
setting["calcDiscountCurveGamma"] = true
setting["calcDiscountCurveKeyRateDuration"] = true
setting["discountCurveShift"] = 0.0001
setting["discountCurveKeyTerms"] = [1.0, 3.0, 5.0]
setting["discountCurveKeyShifts"] = [0.0002, 0.0003, 0.0001]
setting["useExerciseCashflow"] = false

useExeFalse = bondPricer(instrument, pricingDate, discountCurve, setting=setting)

// useExerciseCashflow=true, use exercise cash flow for calculation (based on nearest exercise date execution)
setting = dict(STRING, ANY)
setting["calcDiscountCurveDelta"] = true
setting["calcDiscountCurveGamma"] = true
setting["calcDiscountCurveKeyRateDuration"] = true
setting["discountCurveShift"] = 0.0001
setting["discountCurveKeyTerms"] = [1.0, 3.0, 5.0]
setting["discountCurveKeyShifts"] = [0.0002, 0.0003, 0.0001]
setting["useExerciseCashflow"] = true

useExeTrue = bondPricer(instrument, pricingDate, discountCurve, setting=setting)

Related functions: parseInstrument, parseMktData

Bond Product Field Specifications

Discount Bond


Field Name	Data Type	Description	Required
productType	STRING	Must be "Cash"	Yes
assetType	STRING	Must be "Bond"	Yes
bondType	STRING	Must be "DiscountBond"	Yes
nominal	DOUBLE	Nominal amount, defalut 100	No
instrumentId	STRING	Bond code, e.g., "259926.IB"	No
start	DATE	Value date	Yes
maturity	DATE	Maturity date	Yes
dayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	Yes
issuePrice	DOUBLE	Issue price	Yes
currency	STRING	Currency, defaults to "CNY"	No
discountCurve	STRING	The discount curve, e.g., "CNY_TRASURY_BOND"	No
spreadCurve	STRING	The credit spread curve	No
subType	STRING	Subtypes. China's bonds include: "TREASURY_BOND": Treasury Bonds "CENTRAL_BANK_BILL": Central Bank Bills "CDB_BOND": Policy Bank Financial Bonds (China Development Bank) "EIBC_BOND": Policy Bank Financial Bonds (Export-Import Bank of China) "ADBC_BOND": Policy Bank Financial Bonds (Agricultural Development Bank of China) "MTN": Medium-term Notes "CORP_BOND": Corporate Bonds "UNSECURED_CORP_BOND": Unsecured Corporate Bonds "SHORT_FIN_BOND": Short-term Financing Bills "NCD": Negotiable Certificates of Deposit "LOC_GOV_BOND": Local Government Bonds "COMM_BANK_FIN_BOND": Commercial Bank Financial Bonds "BANK_SUB_CAP_BOND": Bank Subordinated Capital Bonds "ABS": Asset-backed Securities "PPN": Privately Offered Bonds	No
creditRating	STRING	Credit rating. It can be: "B", "BB", "BBB", "BBB+", "A-", "A", "A+", "AA-", "AA", "AA+", "AAA-", "AAA", "AAA+"	No

Zero Coupon Bond


Field Name	Data Type	Description	Required
productType	STRING	Must be "Cash"	Yes
assetType	STRING	Must be "Bond"	Yes
bondType	STRING	Must be "ZeroCouponBond"	Yes
nominal	DOUBLE	Nominal amount, defalut 100	No
instrumentId	STRING	Bond code, e.g., "259926.IB"	No
start	DATE	Value date	Yes
maturity	DATE	Maturity date	Yes
coupon	DOUBLE	Coupon rate, e.g., 0.03 means 3%	Yes
frequency	STRING	Frequency of interest payment	No
dayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	Yes
currency	STRING	Currency, defaults to "CNY"	No
discountCurve	STRING	The discount curve, e.g., "CNY_TRASURY_BOND"	No
spreadCurve	STRING	The credit spread curve	No
subType	STRING	Subtypes. China's bonds include: "TREASURY_BOND": Treasury Bonds "CENTRAL_BANK_BILL": Central Bank Bills "CDB_BOND": Policy Bank Financial Bonds (China Development Bank) "EIBC_BOND": Policy Bank Financial Bonds (Export-Import Bank of China) "ADBC_BOND": Policy Bank Financial Bonds (Agricultural Development Bank of China) "MTN": Medium-term Notes "CORP_BOND": Corporate Bonds "UNSECURED_CORP_BOND": Unsecured Corporate Bonds "SHORT_FIN_BOND": Short-term Financing Bills "NCD": Negotiable Certificates of Deposit "LOC_GOV_BOND": Local Government Bonds "COMM_BANK_FIN_BOND": Commercial Bank Financial Bonds "BANK_SUB_CAP_BOND": Bank Subordinated Capital Bonds "ABS": Asset-backed Securities "PPN": Privately Offered Bonds	No
creditRating	STRING	Credit rating. It can be: "B", "BB", "BBB", "BBB+", "A-", "A", "A+", "AA-", "AA", "AA+", "AAA-", "AAA", "AAA+"	No

Fixed Rate Bond


Field Name	Data Type	Description	Required
productType	STRING	Must be "Cash"	Yes
assetType	STRING	Must be "Bond"	Yes
bondType	STRING	Must be "FixedRateBond"	Yes
nominal	DOUBLE	Nominal amount, defalut 100	No
instrumentId	STRING	Bond code, e.g., "259926.IB"	No
start	DATE	Value date	Yes
maturity	DATE	Maturity date	Yes
coupon	DOUBLE	Coupon rate, e.g., 0.03 means 3%	Yes
frequency	STRING	Frequency of interest payment	Yes
dayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	Yes
currency	STRING	Currency, defaults to "CNY"	No
discountCurve	STRING	The discount curve, e.g., "CNY_TRASURY_BOND"	No
spreadCurve	STRING	The credit spread curve	No
subType	STRING	Subtypes. China's bonds include: "TREASURY_BOND": Treasury Bonds "CENTRAL_BANK_BILL": Central Bank Bills "CDB_BOND": Policy Bank Financial Bonds (China Development Bank) "EIBC_BOND": Policy Bank Financial Bonds (Export-Import Bank of China) "ADBC_BOND": Policy Bank Financial Bonds (Agricultural Development Bank of China) "MTN": Medium-term Notes "CORP_BOND": Corporate Bonds "UNSECURED_CORP_BOND": Unsecured Corporate Bonds "SHORT_FIN_BOND": Short-term Financing Bills "NCD": Negotiable Certificates of Deposit "LOC_GOV_BOND": Local Government Bonds "COMM_BANK_FIN_BOND": Commercial Bank Financial Bonds "BANK_SUB_CAP_BOND": Bank Subordinated Capital Bonds "ABS": Asset-backed Securities "PPN": Privately Offered Bonds	No
creditRating	STRING	Credit rating. It can be: "B", "BB", "BBB", "BBB+", "A-", "A", "A+", "AA-", "AA", "AA+", "AAA-", "AAA", "AAA+"	No

Floating Rate Bond


Field Name	Data Type	Description	Required
productType	STRING	Must be "Cash"	Yes
assetType	STRING	Must be "Bond"	Yes
bondType	STRING	Must be "FloatingRateBond"	Yes
nominal	DOUBLE	Nominal amount. The default value is 100.	No
instrumentId	STRING	Bond code, e.g., "1680437.IB"	No
start	DATE	Value date	Yes
maturity	DATE	Maturity date	Yes
iborIndex	STRING	Reference rate, e.g., "LPR_1Y"	Yes
lastFixing	DOUBLE	Reference-rate fixing from the previous fixing date	Yes
spread	DOUBLE	Spread. The default value is 0.0.	No
frequency	STRING	Coupon payment frequency	Yes
dayCountConvention	STRING	Day count convention: "ActualActualISDA", "ActualActualISMA", "Actual365", or "Actual360"	Yes
fixingOffsetDays	INT	Number of days between the next accrual start date and the fixing date. The default value is 1.	No
currency	STRING	Currency. The default value is "CNY".	No
discountCurve	STRING	Name of the discount curve used for pricing, e.g., "CNY_TREASURY_BOND"	No
spreadCurve	STRING	Name of the credit spread curve used for pricing	No
forwardCurve	STRING	Name of the forward curve used for pricing	No
subType	STRING	Bond subtype. Supported Chinese bond subtypes are: "TREASURY_BOND": Treasury bond "CENTRAL_BANK_BILL": Central bank bill "CDB_BOND": Policy bank bond issued by China Development Bank "EIBC_BOND": Policy bank bond issued by the Export-Import Bank of China "ADBC_BOND": Policy bank bond issued by the Agricultural Development Bank of China "MTN": Medium-term note "CORP_BOND": Corporate bond "UNSECURED_CORP_BOND": Unsecured corporate bond "SHORT_FIN_BOND": Short-term financing bill "NCD": Negotiable certificate of deposit "LOC_GOV_BOND": Local government bond "COMM_BANK_FIN_BOND": Commercial bank financial bond "BANK_SUB_CAP_BOND": Bank subordinated capital bond "ABS": Asset-backed security "PPN": Privately placed note	No
creditRating	STRING	Credit rating: "B", "BB", "BBB", "BBB+", "A-", "A", "A+", "AA-", "AA", "AA+", "AAA-", "AAA", or "AAA+"	No

Curve Field Specifications


Field Name	Data Type	Description	Required
mktDataType	STRING	Must be "Curve"	√
referenceDate	DATE	Reference Date	√
curveType	STRING	Must be "IrYieldCurve"	√
dayCountConvention	STRING	The day count convention to use. It can be: "Actual360": actual/360 "Actual365": actual/365 "ActualActualISMA": actual/actual according to ISMA (International Securities Market Association) convention "ActualActualISDA": actual/actual according to ISDA (International Swaps and Derivatives Association) convention.	√
interpMethod	STRING	Interpolation method. It can be: "Linear": linear interpolation "CubicSpline": cubic spline interpolation "CubicHermiteSpline": cubic Hermite interpolation	√
extrapMethod	STRING	Extrapolation method. It can be Flat: flat extrapolation Linear: linear extrapolation	√
dates	DATE vector	Date of each data point	√
values	DOUBLE vector	Value of each data point, corresponding to the elements in dates.	√
curveName	STRING	Curve name	×
currency	STRING	Currency. It can be CNY", "USD", "EUR", "GBP", "JPY", "HKD"	√
compounding	STRING	The compounding interest. It can be: "Compounded": discrete compounding "Simple": simple interest (no compounding). "Continuous": continuous compounding.	√
settlement	DATE	Settlement date. If specified, all subsequent tenor intervals are computed starting from "settlement" rather than from "referenceDate".	×
frequency	INTEGRAL/STRING	The interest payment frequency. Supported values: -1 or "NoFrequency": No payment frequency 0 or "Once": Single lump-sum payment of principal and interest at maturity. 1 or "Annual": Annually 2 or "Semiannual": Semiannually 3 or "EveryFourthMonth": Every four months 4 or "Quarterly": Quarterly 6 or "BiMonthly": Every two months 12 or "Monthly": Monthly 13 or "EveryFourthWeek": Every four weeks 26 or "BiWeekly": Every two weeks 52 or "Weekly": Weekly 365 or "Daily": Daily 999 or "Other": Other frequencies	×
curveModel	STRING	Curve construction model; It can be "Bootstrap" (default), "NS", "NSS". When the value is "NSS" or "NS", the fields interpMethod, extrapMethod, dates, and values are not required.	×
curveParams	DICT	Model parameters. It is required when curveModel is "NSS" or "NS": If curveModel = "NS": must include keys 'beta0', 'beta1', 'beta2', 'lambda'. If curveModel = "NSS": must include keys 'beta0', ‘beta1', 'beta2', 'beta3', 'lambda0', 'lambda1'.	×