parseInstrument

First introduced in version: 3.00.4

Syntax

parseInstrument(obj)

Details

Parse the instrument description obj into an INSTRUMENT object for modeling and pricing. See Supported Instruments and Fields for details.

Note: parseInstrument preserves non-standard scalar or vector fields (i.e., fields not defined as attributes of the financial instrument) during serialization or deserialization.

Parameters

obj is a dictionary, a tuple of dictionaries, an in-memory table, or a STRING scalar/vector, indicating the financial instrument description to be parsed.

Note: If obj is specified as a table, it must store instruments of a single type.

Returns

An INSTRUMENT object.

Examples

Store the description of a coupon bond in a dictionary and use parseInstrument to parse it into an INSTRUMENT object.

bond = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FixedRateBond",
    "instrumentId": "230205.IB",
    "start": 2023.03.06,
    "maturity": 2033.03.06,
    "issuePrice": 100.0,
    "coupon": 0.0302,
    "calendar": "CFET",
    "frequency": "Annual",
    "dayCountConvention": "ActualActualISDA",
    "subType": "CDB_BOND",
    "issuer": "CDB"
}
parseInstrument(bond)

Parse a tuple of dictionaries and obtain INSTRUMENT objects for three bonds.

bond1 = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "DiscountBond",
    "instrumentId": "259924.IB",
    "start": 2025.04.17,
    "maturity": 2025.07.17,
    "issuePrice": 99.664,
    "dayCountConvention": "ActualActualISDA",
    "subType": "TREASURY_BOND",
    "issuer": "MOF"
}

bond2 = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "ZeroCouponBond",
    "instrumentId": "250401.IB",
    "start": 2025.01.09,
    "maturity": 2026.02.05,
    "coupon": 0.0119,
    "dayCountConvention": "ActualActualISDA",
    "subType": "CDB_BOND",
    "issuer": "ADBC"
}

parseInstrument([bond,bond1,bond2])

Store instrument descriptions in a table, with each column representing a field. Use parseInstrument to parse it and obtain an INSTRUMENT object.

Note: If a product is missing a field required by the table columns, set that field to NULL when inserting the product into the table.

create table t (
    productType STRING,
    assetType STRING,
    bondType STRING,
    version INT,
    instrumentId STRING,
    start DATE,
    maturity DATE,
    issuePrice DOUBLE,
    coupon DOUBLE,
    calendar STRING,
    frequency STRING,
    dayCountConvention STRING,
    subType STRING,
    issuer STRING
)
go

insert into t values( "Cash", "Bond", "FixedRateBond", 0, "230205.IB", 2023.03.06, 2033.03.06, 100.0, 0.0302, "CFET", "Annual", "ActualActualISDA", "CDB_BOND", "CDB")
insert into t values( "Cash", "Bond", "DiscountBond", 0, "259924.IB", 2025.04.17, 2025.07.17, 99.664, NULL, NULL, NULL, "ActualActualISDA", "TREASURY_BOND", "MOF")
insert into t values( "Cash", "Bond", "ZeroCouponBond", 0, "250401.IB", 2025.01.09, 2026.02.05, NULL, 0.0119, NULL, NULL, "ActualActualISDA", "CDB_BOND", "ADBC")

parseInstrument(t)

When obj is a STRING scalar:

bond1 = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FixedRateBond",
    "coupon": 0.0302,
    "frequency": "Annual",
    "version": 0,
    "instrumentId": "230205.IB",
    "nominal": 100,
    "start": 2023.03.06,
    "maturity": 2033.03.06,
    "dayCountConvention": "ActualActualISDA",
    "calendar": "CFET",
    "currency": "CNY",
    "discountCurve": "",
    "spreadCurve": "",
    "subType": "CDB_BOND",
    "issuePrice": 100,
    "issuer": "CDB"
}
bond1Str = toStdJson(bond1)

parseInstrument(obj=bond1Str)

When obj is a STRING vector, parse it and obtain multiple INSTRUMENT objects:

bond2 = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "DiscountBond",
    "issuePrice": 99.664000000000001,
    "version": 0,
    "instrumentId": "259924.IB",
    "nominal": 100,
    "start": 2025.04.17,
    "maturity": 2025.07.17,
    "dayCountConvention": "ActualActualISDA",
    "calendar": "",
    "currency": "CNY",
    "discountCurve": "",
    "spreadCurve": "",
    "subType": "TREASURY_BOND",
    "issuer": "MOF"
}

bond3 = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "ZeroCouponBond",
    "coupon": 0.0119,
    "version": 0,
    "instrumentId": "250401.IB",
    "nominal": 100,
    "start": 2025.01.09,
    "maturity": 2026.02.05,
    "dayCountConvention": "ActualActualISDA",
    "calendar": "",
    "currency": "CNY",
    "discountCurve": "",
    "spreadCurve": "",
    "subType": "CDB_BOND",
    "issuer": "CDB"
}

bond2Str = toStdJson(bond2)
bond3Str = toStdJson(bond3)

parseInstrument(obj=[bond1Str,bond2Str,bond3Str])

Supported Instruments and Fields

The INSTRUMENT type is newly introduced in DolphinDB version 3.00.4, designed to store financial instruments and provide a foundation for pricing and risk measurement of financial products.

The parseInstrument function generates corresponding instrument objects based on the fields of the instrument description. Currently, only the following instrument types are supported:

Discount Bond (DiscountBond)

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

Define an INSTRUMENT object of DiscountBond type.

bond = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "DiscountBond",
    "instrumentId": "259924.IB",
    "start": 2025.04.17,
    "maturity": 2025.07.17,
    "issuePrice": 99.664,
    "dayCountConvention": "ActualActualISDA"
}
instrument = parseInstrument(bond)
print(instrument)

Zero Coupon Bond (ZeroCouponBond)

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

Define an INSTRUMENT object of ZeroCouponBond type.

dict = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "ZeroCouponBond",
    "instrumentId": "250401.IB",
    "start": 2025.01.09,
    "maturity": 2026.02.05,
    "coupon": 0.0119,
    "dayCountConvention": "ActualActualISDA"
}

Fixed Rate Bond (FixedRateBond)

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

Define an INSTRUMENT object of FixedRateBond type.

bond = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FixedRateBond",
    "instrumentId": "240021.IB",
    "start": 2024.10.25,
    "maturity": 2025.10.25,
    "issuePrice": 100,
    "coupon": 0.0133,
    "frequency": "Annual",
    "dayCountConvention": "ActualActualISDA"
}
instrument = parseInstrument(bond)
print(instrument)

Floating Rate Bond (FloatingRateBond)

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

Define and parse a floating-rate bond:

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
}
typestr(parseInstrument(floatingBond))
// output: INSTRUMENT

Bond Futures (BondFutures)

Field Name Data Type Description Required
productType STRING Must be "Futures" Yes
futuresType STRING Must be "BondFutures" Yes
nominal DOUBLE Nominal amount, defalut 100 No
instrumentId STRING Bond future code, e.g., "T2509" No
maturity DATE Maturity date Yes
settlement DATE Settlement date Yes
underlying Dictionary Fixed-rate bond structure, indicating the underlying deliverable bonds. Yes
nominalCouponRate DOUBLE Nominal coupon rate Yes

Define an INSTRUMENT object of BondFutures type.

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

futures =  {
    "productType": "Futures",
    "futuresType": "BondFutures",
    "instrumentId": "T2509",  //Future code
    "nominal": 100.0,
    "maturity": 2022.09.09,
    "settlement": 2022.09.11,
    "underlying": bond,
    "nominalCouponRate": 0.03  //Nominal coupon rate corresponding to the bond futures. You can get it from the China Financial Futures Exchange (CFFEX).
}
instrument = parseInstrument(futures)
print(instrument)

Bond Outright Repo (BondOutrightRepo)

Field Name Type Description Required
productType STRING Must be "Cash". Yes
assetType STRING Must be "Repo". Yes
repoType STRING Must be "BondOutrightRepo". Yes
notionalAmount DOUBLE Notional amount Yes
notionalCurrency STRING Notional currency, defaults to "CNY" No
instrumentId STRING User-defined unique identifier, such as "repo000002" No
start DATE Interest start date Yes
maturity DATE Maturity date Yes
rate DOUBLE Repo rate Yes
payReceive STRING Payment/receipt indicator; "Pay" indicates the repo side, and "Receive" indicates the reverse repo side Yes
underlying DICT/INSTRUMENT Basic information about the pledged bonds Yes
dayCountConvention STRING Day count convention. Valid values are "ActualActualISDA", "ActualActualISMA", "Actual365", and "Actual360". Yes
discountCurve STRING Name of the discount curve used as a pricing reference; for CNY deposits, the default is "CNY_FR_007". No

Bond Pledged Repo (BondPledgedRepo)

Field Type Description Required
productType STRING Must be "Cash". Yes
assetType STRING Must be "Repo". Yes
repoType STRING Must be "BondPledgedRepo". Yes
notionalAmount DOUBLE The notional amount. Yes
notionalCurrency STRING The notional currency. The default value is "CNY". No
instrumentId STRING A user-defined unique identifier, such as "repo000001". No
start DATE The start date. Yes
maturity DATE The maturity date. Yes
rate DOUBLE The repo rate. Yes
payReceive STRING The pay/receive indicator. "Pay" indicates the repo party, and "Receive" indicates the reverse repo party. Yes
dayCountConvention STRING The day count convention. Valid values are "ActualActualISDA", "ActualActualISMA", "Actual365", and "Actual360". Yes
discountCurve STRING The name of the discount curve used for pricing. For CNY scenarios, the default value is "CNY_FR_007". No

Deposit (Deposit)

Field Name Data Type Description Required
productType STRING Must be "Cash". Yes
assetType STRING Must be "Deposit". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional principal Yes
instrumentId STRING Deposit reference rate index, e.g., "SHIBOR_3M" No
start DATE Value date Yes
maturity DATE Maturity date Yes
rate DOUBLE Deposit interest rate Yes
dayCountConvention STRING The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360" Yes
payReceive STRING Pay/Receive indicator: "Pay" indicates paying; "Receive" indicates receiving. Yes
discountCurve STRING The domestic discount curve. The default is "CNY_FR_007" for CNY. No
calendar STRING Trading calendar No

Define an INSTRUMENT object of Deposit type.

deposit =  {
    "productType": "Cash",
    "assetType": "Deposit",
    "start": 2025.05.15,
    "maturity": 2025.08.15,
    "rate": 0.02,
    "dayCountConvention": "Actual360",
    "notionalCurrency": "CNY",
    "notionalAmount": 1E6,
    "payReceive": "Receive"
}
instrument = parseInstrument(deposit)
print(instrument)

IR Fixed-Floating Swap (IrFixedFloatingSwap)

Field Name Data Type Description Required
productType STRING Must be "Swap". Yes
swapType STRING Must be "IrSwap". Yes
irSwapType STRING Must be "IrFixedFloatingSwap". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional principal Yes
instrumentId STRING IR fixed-floating swap name. It can be "CNY_FR_007 or "CNY_SHIBOR_3M". No
start DATE Value date Yes
maturity DATE Maturity date Yes
fixedRate DOUBLE Fixed-rate Yes
calendar STRING Trading calendar Yes
fixedDayCountConvention STRING The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360" Yes
floatingDayCountConvetion STRING The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360" Yes
spread DOUBLE Interest rate spread Yes
iborIndex STRING Floating reference rate. It can be "FR_007" or "SHIBOR_3M". Yes
frequency STRING Frequency of interest payment Yes
payReceive STRING

Pay/Receive indicator

  • "Pay": pay fixed interest rate/ receive floating interest rate

  • "Receive": receive fixed interest rate/ pay floating interest rate

 Yes
discountCurve STRING The discount curve name No
forwardCurve STRING Name of the forward curve used to project future floating rates No

Define an INSTRUMENT object of IrFixedFloatingSwap type.

swap =  {
    "productType": "Swap",
    "swapType": "IrSwap",
    "irSwapType": "IrFixedFloatingSwap",
    "start": 2021.05.15,
    "maturity": 2023.05.15,
    "frequency": "Quarterly",
    "fixedRate": 0.02,
    "calendar": "CFET", 
    "fixedDayCountConvention": "Actual365",
    "floatingDayCountConvention": "Actual360",
    "payReceive": "Pay",
    "iborIndex": "SHIBOR_3M",
    "spread": 0.0005,
    "notionalCurrency": "CNY",
    "notionalAmount": 1E8
}
instrument = parseInstrument(swap)
print(instrument)

Credit Default Swap (CreditDefaultSwap)

Field Name Data Type Description Required
productType STRING Must be "Swap". Yes
swapType STRING Must be "CreditDefaultSwap". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional principal, defaults to "CNY" No
instrumentId STRING Instrument ID No
start DATE Effective date Yes
maturity DATE Maturity date Yes
payReceive STRING Pay/Receive indicator: "Pay" indicates paying; "Receive" indicates receiving. Yes
frequency STRING Frequency of interest payment, defaults to "Quarterly" No
protectionLegRefPrice DOUBLE Protection leg reference price Yes
protectionLegLeverage DOUBLE Protection leg leverage ratio Yes
protectionLegRecoveryRate DOUBLE Protection leg recovery rate Yes
creditProtectionType STRING

Credit protection type. It can be:

  • "PayProtectionAtDefault": pay protection at default

  • "PayProtectionAtMaturity": pay protection at contract maturity

 Yes
creditPremiumType STRING

Credit premium type. It can be:

  • "PayPremiumAtDefault": pay premium at default

  • "PayPremiumUptoCurrentPeriod": pay premium up to current period

  • "PayPremiumUptoMaturity": pay premium up to maturity

  • "PayNothingAfterDefault": pay nothing after default

 Yes
premiumRate DOUBLE Premium rate Yes
calendar STRING Trading calendar Yes
dayCountConvention STRING The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360" Yes
businessDayConvention STRING

The business day convention. It can be:

  • "Following": following

  • "ModifiedFollowing": modified following

  • "Preceding": preceding

  • "ModifiedPreceding": modified preceding

  • "Unadjusted": unadjusted
upfrontRate DOUBLE Upfront rate Yes
rebateAccrual BOOL Whether to calculate rebate accruals Yes

Define an INSTRUMENT object of CreditDefaultSwap type.

instrumentDict = {
    "productType": "Swap",
    "swapType": "CreditDefaultSwap",
    "instrumentId": "CFETS_SHCH_GTJA",
    "notionalAmount": 1.0e7,
    "notionalCurrency": "CNY",
    "start": 2019.06.20,
    "maturity": 2024.06.20,
    "payReceive": "Pay",
    "protectionLegRefPrice": 0.0,
    "protectionLegLeverage": 1.0,
    "protectionLegRecoveryRate": 0.4,
    "creditProtectionType": "PayProtectionAtMaturity",
    "creditPremiumType": "PayPremiumUptoCurrentPeriod",
    "premiumRate": 0.01,
    "dayCountConvention": "Actual360",
    "frequency": "Quarterly",
    "businessDayConvention": "ModifiedFollowing",
    "calendar": "XNYS",
    "upfrontRate": 0.01,
    "rebateAccrual": false
}
instrument = parseInstrument(instrumentDict)

Foreign Exchange Forward (FxForward)

Field Name Data Type Description Required
productType STRING Must be "Forward". Yes
forwardType STRING Must be "FxForward". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional principal Yes
instrumentId STRING InstrumentId ID No
expiry DATE Value date Yes
delivery DATE Settlement date Yes
currencyPair STRING

The currency pair, in the format "EURUSD", "EUR.USD", or "EUR/USD". Supported currency pairs include:

  • "EURUSD": Euro to US Dollar

  • "USDCNY": US Dollar to Chinese Yuan

  • "EURCNY": Euro to Chinese Yuan

  • "GBPCNY": British Pound to Chinese Yuan

  • "JPYCNY": Japanese Yen to Chinese Yuan

  • "HKDCNY": Hong Kong Dollar to Chinese Yuan

 Yes
direction STRING Trading direction, can be "Buy" or "Sell" Yes
strike DOUBLE Strike price Yes
domesticCurve STRING The domestic discount curve name No
foreignCurve STRING The foreign discount curve name No

Define an INSTRUMENT object of FxForward type.

forward =  {
   "productType": "Forward",
    "forwardType": "FxForward",
    "expiry": 2025.09.24,
    "delivery": 2025.09.26,
    "currencyPair": "USDCNY",
    "direction": "Buy",
    "notionalCurrency": "USD",
    "notionalAmount": 1E8,
    "strike": 7.2
}
instrument = parseInstrument(forward)
print(instrument)

Standard Bond Forward (stdBondForward)

Field Type Description Required
productType STRING Must be "Forward". Yes
forwardType STRING Must be "StdBondForward". Yes
nominal DOUBLE The notional amount. The default value is 100. No
instrumentId STRING The standard bond forward identifier, e.g., "CDB3". No
yearLength INT The tenor of the notional bond, typically 3-year, 5-year, or 10-year. Yes
maturity DATE The maturity date (T-1, adjusted to a trading day). Yes
settlement DATE The settlement date (T), the third Wednesday of the contract month. Yes
underlying DICTIONARY/TUPLE of INSTRUMENT objects The basket of deliverable fixed-rate bonds underlying the contract(s). Can be generated by parsing bond dictionaries via parseInstrument. Yes
settlementType STRING

The settlement type. Supported values are:

  • "PhysicalSettlement": physical delivery
  • "CashSettlement": cash settlement
 Yes
nominalCouponRate DOUBLE The notional coupon rate of the notional bond. The default value is 0.03, i.e., 3%. No

Forward Rate Agreement (IrForwardRateAgreement)

Field Name Data Type Description Required
productType STRING Must be "Forward". Yes
forwardType STRING Must be "IrForwardRateAgreement". Yes
notionalAmount DOUBLE Notional principal amount, e.g., 1E8 Yes
notionalCurrency STRING Notional principal currency, defaults to "CNY" No
instrumentId STRING FRA tenor identifier, represented in the format of "forward tenor x (forward tenor + contract tenor)". For example, "3Mx6M" indicates that the FRA starts in 3 months and matures in 6 months. No
start DATE Value date Yes
maturity DATE Maturity date Yes
fixedRate DOUBLE Fixed-rate Yes
calendar STRING Trading calendar Yes
dayCountConvention STRING The day count convention. It can be: "ActualActualISDA", "ActualActualISMA", "Actual365", "Actual360" Yes
iborIndex STRING Floating reference rate. It can be "FR_007" or "SHIBOR_3M" Yes
payReceive STRING

Pay/Receive indicator:

  • "Pay": pay fixed interest rate / receive floating interest rate

  • "Receive": receive fixed interest rate / pay floating interest rate

 Yes
discountCurve STRING Name of the discount curve used for pricing. No
forwardCurve STRING Name of the forward curve used for pricing. No

Define an INSTRUMENT object of IrForwardRateAgreement type.

irFRA = {
    "productType": "Forward",
    "forwardType": "IrForwardRateAgreement",
    "notionalAmount": 1.0,
    "instrumentId": "3Mx6M",
    "start": 2019.10.10,
    "maturity": 2020.01.10,
    "fixedRate": 0.03,
    "calendar": "CFET",
    "dayCountConvention": "Actual360",
    "iborIndex": "SHIBOR_3M",
    "payReceive": "Pay"
}
instrument = parseInstrument(irFRA)
print(instrument)

Foreign Exchange Swap (FxSwap)

Field Name Data Type Description Required
productType STRING Must be "Swap". Yes
swapType STRING Must be "FxSwap". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional principal Yes
currencyPair STRING

The currency pair, in the format "EURUSD", "EUR.USD", or "EUR/USD". Supported currency pairs include:

  • "EURUSD": Euro to US Dollar

  • "USDCNY": US Dollar to Chinese Yuan

  • "EURCNY": Euro to Chinese Yuan

  • "GBPCNY": British Pound to Chinese Yuan

  • "JPYCNY": Japanese Yen to Chinese Yuan

  • "HKDCNY": Hong Kong Dollar to Chinese Yuan

 Yes
nearExpiry DATE Maturity date for the near leg Yes
nearDelivery DATE Settlement date for the near leg Yes
direction STRING

Trading direction, can be

  • "Buy": Buy the foreign currency on the near leg and sell it on the far leg.

  • "Sell": Sell the foreign currency on the near leg and buy it back on the far leg.

 Yes
nearStrike DOUBLE Strike price for the near leg Yes
farExpiry DATE Maturity date for the far leg Yes
farDelivery DATE Settlement date for the far leg Yes
farStrike DOUBLE Strike price for the far leg Yes
domesticCurve STRING The domestic discount curve name No
foreignCurve STRING The foreign discount curve name No

Define an INSTRUMENT object of FxSwap type.

swap = {
    "productType": "Swap",
    "swapType": "FxSwap",
    "currencyPair": "EURUSD",
    "direction": "Buy",
    "notionalCurrency": "EUR",
    "notionalAmount": 1E6,
    "nearStrike": 1.1,
    "nearExpiry": 2025.12.08,
    "nearDelivery": 2025.12.10,
    "farStrike": 1.2,
    "farExpiry": 2026.06.08,
    "farDelivery": 2026.06.10
}
instrument = parseInstrument(swap)
print(instrument)

Foreign Exchange European Style Option (FxEuropeanOption)

Field Name Data Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "EuropeanOption". Yes
assetType STRING Must be "FxEuropeanOption". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional principal Yes
instrumentId STRING InstrumentId ID No
maturity DATE Maturity date Yes
underlying STRING

The currency pair, in the format "EURUSD", "EUR.USD", or "EUR/USD". Supported currency pairs include:

  • "EURUSD": Euro to US Dollar

  • "USDCNY": US Dollar to Chinese Yuan

  • "EURCNY": Euro to Chinese Yuan

  • "GBPCNY": British Pound to Chinese Yuan

  • "JPYCNY": Japanese Yen to Chinese Yuan

  • "HKDCNY": Hong Kong Dollar to Chinese Yuan

 Yes
direction STRING Trading direction, can be "Buy" or "Sell" Yes
strike DOUBLE Strike price Yes
dayCountConvention STRING The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360" Yes
payoffType STRING Payoff type. It can be "Call" or "Put". Yes
domesticCurve STRING The domestic discount curve name No
foreignCurve STRING The foreign discount curve name No
delivery DATE The delivery date No
Note:

The delivery field is supported starting from version 2.

When upgrading data from versions earlier than version 2 to version 2 or later, missing delivery fields in existing records will be automatically populated with maturity + 2.

Define an INSTRUMENT object of FxEuropeanOption type.

option =  {
    "productType": "Option",
    "optionType": "EuropeanOption",
    "assetType": "FxEuropeanOption",
    "notionalCurrency": "EUR",
    "notionalAmount": 1000000.0,
    "strike": 1.2,
    "maturity": 2025.10.08,
    "payoffType": "Call",
    "dayCountConvention": "Actual365",
    "underlying": "EURUSD"
}
instrument = parseInstrument(option)
print(instrument)

Foreign Exchange Non-deliverable Forward (fxNonDeliverableForwardPricer)

Field Name Type Description Required
productType STRING Must be "Forward". Yes
forwardType STRING Must be "FxNonDeliverableForward". Yes
notionalAmount DOUBLE Notional amount, for example, 1E7. Yes
notionalCurrency STRING Notional currency, for example, "USD". Yes
instrumentId STRING Instrument ID No
expiry DATE Expiry date Yes
delivery DATE Delivery date Yes
currencyPair STRING Currency pair, in a format such as "EURUSD", "EUR.USD", or "EUR/USD". The following currency pairs are supported:

  • EURUSD: Euro/US dollar

  • USDCNY: US dollar/Chinese yuan
  • EURCNY: Euro/Chinese yuan
  • GBPCNY: British pound/Chinese yuan
  • JPYCNY: Japanese yen/Chinese yuan
  • HKDCNY: Hong Kong dollar/Chinese yuan
 Yes
direction STRING Trade direction. Valid values: "Buy", "Sell" Yes
strike DOUBLE Strike price Yes
settlementCurrency STRING Settlement currency Yes
domesticCurve STRING Name of the domestic discount curve referenced for pricing No
foreignCurve STRING Name of the foreign discount curve referenced for pricing No

Foreign Exchange Range Accrual Option (fxRangeAccrualOptionPricer)

Field Name Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "RangeAccrualOption". Yes
assetType STRING Must be "FxRangeAccrualOption". Yes
notionalAmount DOUBLE Notional amount, for example, 1E7 Yes
notionalCurrency STRING Notional currency, for example, "USD" Yes
instrumentId STRING Instrument ID No
start DATE Value date. Yes
maturity DATE Maturity date Yes
underlying STRING Currency pair, in a format such as "EURUSD", "EUR.USD", or "EUR/USD". The following currency pairs are supported:

  • "EURUSD": Euro against US dollar

  • "USDJPY": US dollar against Japanese yen
  • "USDCNY": US dollar against Chinese yuan
  • "EURCNY": Euro against Chinese yuan
  • "GBPCNY": British pound against Chinese yuan
  • "JPYCNY": Japanese yen against Chinese yuan
  • "HKDCNY": Hong Kong dollar against Chinese yuan
 Yes
direction STRING Trade direction. Valid values are "Buy" and "Sell". No
dayCountConvention STRING Day count convention. Valid values are "ActualActualISDA", "ActualActualISMA", "Actual365", and "Actual360". Yes
lowerBarrier DOUBLE Lower barrier Yes
upperBarrier DOUBLE Upper barrier Yes
payoffType STRING Payoff type. Valid values are "Call" and "Put". Yes
reportCurrency STRING Reporting currency Yes

American Commodity Futures Options (cmFutAmericanOption)

Field Name Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "AmericanOption". Yes
assetType STRING Must be "CmFutAmericanOption". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional currency. Default value: "CNY" No
instrumentId STRING Contract code, standard format: Underlying futures contract code + Contract expiry month + Option type code + Strike price, e.g., Sugar option SR2509P6300 = SR+2509+P+6300 No
direction STRING Trading direction. Valid values: “Buy” (default), “Sell”. No
maturity DATE Maturity date Yes
strike DOUBLE Strike price Yes
payoffType STRING Payoff type. Valid values: “Call”, “Put” Yes
underlying STRING Underlying futures contract code, e.g., SR2509 Yes
dayCountConvention STRING Day count convention. Valid values: "ActualActualISDA", "ActualActualISMA", "Actual365", "Actual360" Yes
discountCurve STRING Discount curve name for pricing reference. The default value for RMB deposits is "CNY_FR_007". No

European Commodity Futures Options (CmFutEuropeanOption)

Field Name Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "EuropeanOption". Yes
assetType STRING Must be "CmFutEuropeanOption". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional currency. Default value: "CNY" No
instrumentId STRING Contract code, standard format: Underlying futures contract code + Contract expiry month + Option type code + Strike price, e.g., Sugar option SR2509P6300 = SR+2509+P+6300 No
direction STRING Trading direction. Valid values: "Buy" (default), "Sell". No
maturity DATE Maturity date Yes
strike DOUBLE Strike price Yes
payoffType STRING Payoff type. Valid values: "Call", "Put" Yes
underlying STRING Underlying futures contract code, e.g., SR2509 Yes
dayCountConvention STRING Day count convention. Valid values: "ActualActualISDA", "ActualActualISMA", "Actual365", "Actual360" Yes
discountCurve STRING Discount curve name for pricing reference. The default value for RMB deposits is "CNY_FR_007". No

American Equity Options (eqAmericanOption)

Field Name Data Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "AmericanOption". Yes
assetType STRING Must be "EqAmericanOption". Yes
notionalAmount DOUBLE Notional amount. Yes
notionalCurrency STRING Notional currency. Default value: "CNY". No
instrumentId STRING Instrument identifier. For example, TCH250328C0040000 is interpreted as follows: TCH = underlying (Tencent Holdings); 250328 = maturity date (March 28, 2025); C = Call option; 0040000 = strike price 400.00 HKD. No
direction STRING Trade direction: "Buy" (default) or "Sell". No
maturity DATE Maturity date Yes
strike DOUBLE Strike price. Yes
payoffType STRING Payoff type: "Call" or "Put". Yes
underlying STRING Underlying futures contract code, e.g., "TCH". Yes
dayCountConvention STRING Day count convention. Valid values: "ActualActualISDA", "ActualActualISMA", "Actual365", "Actual360" Yes
discountCurve STRING Discount curve name for pricing reference. The default value for RMB deposits is "CNY_FR_007". No
dividendCurve STRING Dividend curve name used for pricing. No

European Equity Options (eqEuropeanOption)

Field Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "EuropeanOption". Yes
assetType STRING Must be "EqEuropeanOption". Yes
notionalAmount DOUBLE Notional amount Yes
notionalCurrency STRING Notional currency. Default value: "CNY". No
instrumentId STRING

Contract identifier, e.g. CSI 500 ETF option

510500C2512M04800

 No
direction STRING Trade direction: "Buy" (default) or "Sell". No
maturity DATE Maturity date Yes
strike DOUBLE Strike price Yes
payoffType STRING Payoff type: "Call" or "Put". Yes
underlying STRING Underlying contract code, e.g. 510050. Yes
dayCountConvention STRING Day count convention. Valid values: "ActualActualISDA", "ActualActualISMA", "Actual365", "Actual360" Yes
discountCurve STRING Discount curve name for pricing reference. The default value for RMB deposits is "CNY_FR_007". No
dividendCurve STRING Name of the dividend curve used for pricing. No

Equity Range Accrual Options (EqRangeAccrualOption)

parseInstrument supports equity range accrual options. The instrument description must contain the following fields:

Field Name Data Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "RangeAccrualOption". Yes
assetType STRING Must be "EqRangeAccrualOption". Yes
instrumentId STRING The instrument ID, which can be customized for OTC options. No
maturity DATE The maturity date. Yes
delivery DATE The delivery date. The default value is maturity. No
coupon DOUBLE The coupon rate. Yes
lowerBarrier DOUBLE The lower boundary of the accrual range. Yes
upperBarrier DOUBLE The upper boundary of the accrual range. Yes
fixingDates DATE vector The fixing date sequence. It must be in ascending order. Yes
direction STRING The buy/sell direction. It can be "Buy" or "Sell". The default value is "Buy". No
dayCountConvention STRING The day count convention. It can be "ActualActualISDA", "ActualActualISMA", "Actual365", or "Actual360". Yes
underlying STRING The underlying name, such as "50ETF". Yes
notionalAmount DOUBLE The notional amount. Yes
notionalCurrency STRING The notional currency. The default value is "CNY". No
discountCurve STRING The name of the discount curve used for pricing. The default value is an empty string. No
dividendCurve STRING The name of the dividend curve used for pricing. The default value is an empty string. No

The following example describes an equity range accrual option with a dictionary and calls parseInstrument to generate an INSTRUMENT object.

option = {
    "productType": "Option",
    "optionType": "RangeAccrualOption",
    "assetType": "EqRangeAccrualOption",
    "instrumentId": "0001",
    "notionalAmount": 1000000.0,
    "notionalCurrency": "CNY",
    "maturity": 2026.06.01,
    "delivery": 2026.06.01,
    "underlying": "50ETF",
    "direction": "Buy",
    "dayCountConvention": "Actual365",
    "lowerBarrier": 2.95,
    "upperBarrier": 3.25,
    "coupon": 0.1,
    "fixingDates": [2026.04.01, 2026.05.01],
    "discountCurve": "CNY_FR_007",
    "dividendCurve": "510050"
}
instrument = parseInstrument(option)
print(instrument)

Equity Digital Options (EqDigitalOption)

parseInstrument supports equity digital options. The instrument description must contain the following fields:

Field Name Data Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "DigitalOption". Yes
assetType STRING Must be "EqDigitalOption". Yes
instrumentId STRING Contract code. For OTC options, it can be customized. No
maturity DATE Maturity date. Yes
strike DOUBLE Strike price. Yes
dayCountConvention STRING Day count convention. It can be "ActualActualISDA", "ActualActualISMA", "Actual365", or "Actual360". Yes
direction STRING Buy/sell direction. It can be "Buy" or "Sell". The default value is "Buy". No
payoffType STRING Payoff type. It can be "Call" or "Put". Yes
underlying STRING Underlying code, for example "510050". Yes
notionalAmount DOUBLE Notional amount. Yes
notionalCurrency STRING Notional currency. The default value is "CNY". No
discountCurve STRING Name of the discount curve used for pricing. The default value is an empty string. No
dividendCurve STRING Name of the dividend curve used for pricing. The default value is an empty string. No

European Interest Rate Swaption

Field Name Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "EuropeanOption". Yes
assetType STRING Must be "IrEuropeanSwaption". Yes
instrumentId STRING Contract code, in the following standard format:"SWPT_reference rate_option expiry x swap tenor C/P"For example, "SWPT_LPR1Y_1Y5YC" represents a fixed-rate payer swaption with LPR1Y as the reference rate, an option expiry of 1Y, and a swap tenor of 5Y. No
start DATE Value date Yes
maturity DATE Maturity date Yes
strike DOUBLE Strike rate Yes
payoffType STRING Payoff type. Valid values are "Call" and "Put". Yes
underlying DICT/INSTRUMENT Underlying asset: a dictionary that can be parsed into an IrFixedFloatingSwap object, or an IrFixedFloatingSwap object Yes
dayCountConvention STRING Day count convention. Valid values are "ActualActualISDA", "ActualActualISMA", "Actual365", and "Actual360". Yes
discountCurve STRING Name of the discount curve used for pricing. For CNY deposits, the default is "CNY_FR_007". No
forwardCurve STRING Name of the forward curve used for pricing, for example, "CNY_LPR_1Y". No

Interest Rate Cap and Floor Option (IrCapFloor)

Field Data Type Description Required
productType STRING Must be "Option". Yes
optionType STRING Must be "EuropeanOption". Yes
assetType STRING Must be "IrCapFloor". Yes
notionalAmount DOUBLE Notional principal amount Yes
notionalCurrency STRING Notional currency No
instrumentId STRING Contract code, standard format: Cap/Floor_Reference Rate_Option Term, e.g., "Cap_LPR1Y_6M". No
iborIndex STRING Reference rate. It can be "LPR_1Y" or "LPR_5Y" Yes
lastFixing DOUBLE The latest fixing rate for the reference rate. No
start DATE Value date Yes
maturity DATE Maturity date Yes
strike DOUBLE Strike price Yes
capFloorType STRING

Identifies whether the instrument is a Cap or a Floor. Available options:

  • "Cap": Interest rate cap

  • "Floor": Interest rate floor

 Yes
frequency STRING

Frequency of interest payment. If not specified, the system applies the convention for the reference rate. For "LPR_1Y" and "LPR_5Y", the default is "Quarterly". It can be:

  • "Annual": Annually

  • "Semiannual": Semiannually

  • "EveryFourthMonth": Every four months

  • "Quarterly": Quarterly

  • "BiMonthly": Every two months

  • "Monthly": Monthly

  • "EveryFourthWeek": Every four weeks

  • "BiWeekly": Every two weeks

  • "Weekly": Weekly

  • "Daily": Daily

 No
dayCountConvention STRING The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360" Yes
discountCurve STRING The discount curve name, e.g., "CNY_FR_007". No
forwardCurve STRING The forward curve name, e.g., "CNY_LPR_1Y". No

Define an INSTRUMENT object of IrCapFloor type.

lpr1yFloorDict = {
    "productType": "Option",
    "optionType": "EuropeanOption",
    "assetType": "IrCapFloor",
    "instrumentId": "LPR1Y_FLOOR_SAMPLE_11",
    "notionalAmount": 37000000.0,
    "notionalCurrency": "CNY",
    "start": 2021.03.18,
    "maturity": 2022.03.17,
    "strike": 0.035,
    "lastFixing": 0.0340,
    "frequency": "Quarterly",
    "capFloorType": "Floor",
    "iborIndex": "LPR_1Y",
    "dayCountConvention": "Actual360",
    "discountCurve": "CNY",
    "forwardCurve": "LPR_1Y"
}
lpr1yFloor = parseInstrument(lpr1yFloorDict)

Related functions: bondPricer (Bond Pricing), bondPledgedRepoPricer (Bond Pledged Repo Pricing), irDepositPricer (Deposit Pricing), bondFuturesPricer (Treasury Futures Pricing), fxForwardPricer (FX Forward Pricing), fxSwapPricer (FX Swap Pricing), irCapFloorPricer (Interest Rate Cap and Floor Option Pricing), irFixedFloatingSwapPricer (IR Fixed-Floating Swap Pricing), fxEuropeanOptionPricer (FX European Option Pricing), eqDigitalOptionPricer (Equity Digital Option Pricing), irForwardRateAgreementPricer (Forward Rate Agreement Pricing)