parseInstrument

Syntax

parseInstrument(obj)

Arguments

obj is a dictionary or a tuple of dictionaries indicating the instrument description to be parsed.

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.

Return value: An INSTRUMENT object.

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 instrument types illustrated as leaf nodes in the classification tree below are supported:

Discount Bond (DiscountBond)


Field Name	Data Type	Description	Required
productType	STRING	Must be "Cash"	√
assetType	STRING	Must be "Bond"	√
bondType	STRING	Must be "DiscountBond"	√
version	INT	Version, default 0	×
nominal	DOUBLE	Nominal amount, defalut 100	×
instrumentId	STRING	Bond code, e.g., "259926.IB"	×
start	DATE	Value date	√
maturity	DATE	Maturity date	√
dayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	√
issuePrice	DOUBLE	Issue price	√
currency	STRING	Currency, defaults to "CNY"	×
cashFlow	TABLE	Cash flow table	×
discountCurve	STRING	The discount curve, e.g., "CNY_TRASURY_BOND"	×
spreadCurve	STRING	The credit spread curve	×
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	×
creditRating	STRING	Credit rating. It can be: "B", "BB", "BBB", "BBB+", "A-", "A", "A+", "AA-", "AA", "AA+", "AAA-", "AAA", "AAA+"	×

Define an INSTRUMENT object of DiscountBond type.

bond = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "DiscountBond",
    "version": 0, 
    "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"	√
assetType	STRING	Must be "Bond"	√
bondType	STRING	Must be "ZeroCouponBond"	√
version	INT	Version, default 0	×
nominal	DOUBLE	Nominal amount, defalut 100	×
instrumentId	STRING	Bond code, e.g., "259926.IB"	×
start	DATE	Value date	√
maturity	DATE	Maturity date	√
coupon	DOUBLE	Coupon rate, e.g., 0.03 means 3%	√
frequency	STRING	Frequency of interest payment	√
dayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	√
currency	STRING	Currency, defaults to "CNY"	×
cashFlow	TABLE	Cash flow table	×
discountCurve	STRING	The discount curve, e.g., "CNY_TRASURY_BOND"	×
spreadCurve	STRING	The credit spread curve	×
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	×
creditRating	STRING	Credit rating. It can be: "B", "BB", "BBB", "BBB+", "A-", "A", "A+", "AA-", "AA", "AA+", "AAA-", "AAA", "AAA+"	×

Define an INSTRUMENT object of ZeroCouponBond type.

dict = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "ZeroCouponBond",
    "version": 0, 
    "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"	√
assetType	STRING	Must be "Bond"	√
bondType	STRING	Must be "FixedRateBond"	√
version	INT	Version, default 0	×
nominal	DOUBLE	Nominal amount, defalut 100	×
instrumentId	STRING	Bond code, e.g., "259926.IB"	×
start	DATE	Value date	√
maturity	DATE	Maturity date	√
coupon	DOUBLE	Coupon rate, e.g., 0.03 means 3%	√
frequency	STRING	Frequency of interest payment	√
dayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	√
currency	STRING	Currency, defaults to "CNY"	×
cashFlow	TABLE	Cash flow table	×
discountCurve	STRING	The discount curve, e.g., "CNY_TRASURY_BOND"	×
spreadCurve	STRING	The credit spread curve	×
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	×
creditRating	STRING	Credit rating. It can be: "B", "BB", "BBB", "BBB+", "A-", "A", "A+", "AA-", "AA", "AA+", "AAA-", "AAA", "AAA+"	×

Define an INSTRUMENT object of FixedRateBond type.

bond = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FixedRateBond",
    "version": 0, 
    "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)

Bond Futures (BondFutures)


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

Define an INSTRUMENT object of BondFutures type.

bond ={
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FixedRateBond",
    "version": 0, 
    "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",
    "version": 0,
    "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)

Deposit (Deposit)


Field Name	Data Type	Description	Required
productType	STRING	Must be "Cash"	√
assetType	STRING	Must be "Deposit"	√
version	INT	Version, default 0	√
notional	ANY vector	Notional principal amount, e.g., ["USD", 1.0]	√
instrumentId	STRING	Deposit reference rate index, e.g., "SHIBOR_3M"	×
start	DATE	Value date	√
maturity	DATE	Maturity date	√
rate	DOUBLE	Deposit interest rate	√
dayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	√
payReceive	STRING	Pay/Receive indicator: "Pay" indicates paying; "Receive" indicates receiving.	√
domesticCurve	STRING	The domestic discount curve. The default is "CNY_FR_007" for CNY.	×
calendar	STRING	Trading calendar	×

Define an INSTRUMENT object of Deposit type.

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

IR Fixed-Floating Swap (IrFixedFloatingSwap)


Field Name	Data Type	Description	Required
productType	STRING	Must be "Swap"	√
swapType	STRING	Must be "IrSwap"	√
irSwapType	STRING	Must be "IrFixedFloatingSwap"	√
version	INT	Version, default 0	×
notional	ANY vector	Notional principal amount, e.g., ["USD", 1.0]	√
instrumentId	STRING	IR fixed-floating swap name. It can be "CNY_FR_007 or "CNY_SHIBOR_3M".	×
start	DATE	Value date	√
maturity	DATE	Maturity date	√
fixedRate	DOUBLE	Fixed-rate	√
calender	STRING	Trading calendar	√
fixedDayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	√
floatingDayCountConvetion	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	√
spread	DOUBLE	Interest rate spread	√
iborIndex	STRING	Floating reference rate. It can be "FR_007" or "SHIBOR_3M".	√
frequency	STRING	Frequency of interest payment	√
payReceive	STRING	Pay/Receive indicator "Pay": pay fixed interest rate/ receive floating interest rate "Receive": receive fixed interest rate/ pay floating interest rate	√
domesticCurve	STRING	The domestic discount curve name	×
foreignCurve	STRING	The foreign discount curve name	×

Define an INSTRUMENT object of IrFixedFloatingSwap type.

swap =  {
    "productType": "Swap",
    "swapType": "IrSwap",
    "irSwapType": "IrFixedFloatingSwap",
    "version": 0, 
    "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,
    "notional":["CNY", 1E8]
}
instrument = parseInstrument(swap)
print(instrument)

Foreign Exchange Forward (FxForward)


Field Name	Data Type	Description	Required
productType	STRING	Product name. It must be "Forward".	√
forwardType	STRING	Foreign exchange forward type. It must be "FxForward".	√
version	INT	Version, default 0	×
notional	ANY vector	Notional principal amount, e.g., ["USD", 1.0]	√
instrumentId	STRING	InstrumentId ID	×
expiry	DATE	Value date	√
delivery	DATE	Settlement date	√
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	√
direction	STRING	Trading direction, can be "Buy" or "Sell"	√
strike	DOUBLE	Strike price	√
domesticCurve	STRING	The domestic discount curve name	×
foreignCurve	STRING	The foreign discount curve name	×

Define an INSTRUMENT object of FxForward type.

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

Foreign Exchange Swap (FxSwap)


Field Name	Data Type	Description	Required
productType	STRING	Product name. It must be "Swap".	√
swapType	STRING	Foreign exchange swap type. It must be "FxSwap".	√
version	INT	Version, default 0	×
notional	ANY vector	Notional principal amount, e.g., ["USD", 1.0]	√
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	√
nearExpiry	DATE	Maturity date for the near leg	√
nearDelivery	DATE	Settlement date for the near leg	√
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.	√
nearStrike	DOUBLE	Strike price for the near leg	√
farExpiry	DATE	Maturity date for the far leg	√
farDelivery	DATE	Settlement date for the far leg	√
farStrike	DOUBLE	Strike price for the far leg	√
domesticCurve	STRING	The domestic discount curve name	×
foreignCurve	STRING	The foreign discount curve name	×

Define an INSTRUMENT object of FxSwap type.

swap = {
    "productType": "Swap",
    "swapType": "FxSwap",
    "version": 0,
    "currencyPair": "EURUSD",
    "direction": "Buy",
    "notional": ["EUR", 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)

Fx European Style Option (FxEuropeanOption)


Field Name	Data Type	Description	Required
productType	STRING	Must be "Option"	√
optionType	STRING	Must be "EuropeanOpiton"	√
assetType	STRING	Must be "FxEuropeanOpiton"	√
version	INT	Version, default 0	×
notional	ANY vector	Notional principal amount, e.g., ["USD", 1.0]	√
instrumentId	STRING	InstrumentId ID	×
maturity	DATE	Maturity date	√
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	√
direction	STRING	Trading direction, can be "Buy" or "Sell"	√
strike	DOUBLE	Strike price	√
dayCountConvention	STRING	The day count convention. It can be: "ActualActualISDA", "ActualActualISMA"," Actual365", "Actual360"	√
payoffType	STRING	Payoff type. It can be "Call" or "Put".	√
domesticCurve	STRING	The domestic discount curve name	×
foreignCurve	STRING	The foreign discount curve name	×

Define an INSTRUMENT object of FxEuropeanOption type.

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

Related functions: bondPricer (Bond Pricing), irDepositPricer (Deposit Pricing), bondFuturesPricer (Treasury Futures Pricing), fxForwardPricer (FX Forward Pricing), fxSwapPricer (FX Swap Pricing), irFixedFloatingSwapPricer (IR Fixed-Floating Swap Pricing), fxEuropeanOptionPricer (FX European Option Pricing)