Price Interest-Rate Instruments

Create interest-rate instrument object, associate the object with a model, and specify pricing method

An interest-rate instrument is a derivative with a value that is linked to the movement of interest rates. This toolbox provides functionality to price, compute sensitivity, and perform hedging analysis for many interest-rate securities. You can price bonds, floating-rate notes, vanilla swaps, futures, bond options, amortizing bonds, CMS, caps, and floors with pricing models that include lattice models, Monte Carlo simulations, and multiple closed-form solutions.

The object-based framework supports a workflow for creating instruments, models, and pricer objects to price financial instruments. Using these objects, you can price interest-rate, inflation, equity, commodity, FX, or credit derivative instruments. The object-based workflow is an alternative to pricing financial instruments using functions. Working with modular objects for instruments, models, and pricers, you can easily reuse these objects to compare instrument prices for different models and pricing engines. You can use the object-based workflow to price a single instrument or to price a collection of instruments in a portfolio. For more information on the workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

Create an interest-rate instrument with or without optionality.

To create an interest-rate instrument object without optionality, use fininstrument, associate a ratecurve object using ratecurve, and then specify a pricing method using finpricer.
To create an interest-rate instrument object with optionality, use fininstrument, associate a ratecurve object using ratecurve and a model object using finmodel, and then specify a pricing method using finpricer.

Functions

expand all

Create Instrument, Model, and Pricer

`fininstrument`	Create specified instrument object type (Since R2020a)
`finmodel`	Create specified model object type (Since R2020a)
`finpricer`	Create pricing method (Since R2020a)

Exercise Policy for `FixedBondOption`, `FloatBondOption`, `OptionEmbeddedFixedBond`, `OptionEmbeddedFloatBond`, or `ConvertibleBond` Instruments

`setExercisePolicy`	Set exercise policy for `FixedBondOption`, `FloatBondOption`, or `Vanilla` instrument (Since R2020b)
`setPutExercisePolicy`	Set put exercise policy for `OptionEmbeddedFixedBond`, `OptionEmbeddedFloatBond`, or `ConvertibleBond` instrument (Since R2020b)
`setCallExercisePolicy`	Set call exercise policy for `OptionEmbeddedFixedBond`, `OptionEmbeddedFloatBond`, or `ConvertibleBond` instrument (Since R2020b)

Cash Management for FixedBond, FloatBond, Swap, Deposit, FRA, STIRFuture, OISFuture, OvernightIndexedSwap, or BondFuture Instruments

`cashflows`	Compute cash flow for `FixedBond`, `FloatBond`, `Swap`, `FRA`, `STIRFuture`, `OISFuture`, `OvernightIndexedSwap`, or `Deposit` instrument (Since R2020a)
`fairdelivery`	Compute fair delivery price of underlying asset for `BondFuture`, `CommodityFuture`, `EquityIndexFuture`, or `FXFuture` instrument (Since R2022a)
`cashsettle`	Compute cash settlement for `BondFuture`, `CommodityFuture`, `EquityIndexFuture`, or `FXFuture` instrument (Since R2022a)

Par Swap Rate for `Swap` and `OvernightIndexedSwap` Instruments

parswaprate Compute par swap rate for Swap and OvernightIndexedSwap instrument (Since R2020b)

Cash flows for `CMS` or `CMSNote` Instrument

cmsCashflows Compute cash flows for CMS or CMSNote instrument (Since R2023a)

Implied Volatility Using `SABR` Pricer

volatilities Compute implied volatilities when using SABR pricer (Since R2020b)

Option Adjusted Spread (OAS) Using `IRTree` Pricer

oas Compute option adjusted spread for OptionEmbeddedFixedBond instrument using interest-rate tree (Since R2023a)

Price Functions for Interest-Rate Instruments

`price`	Compute price for interest-rate, equity, or credit derivative instrument with `Analytic` pricer (Since R2020a)
`price`	Compute price for interest-rate instrument with `Discount` pricer (Since R2020a)
`price`	Compute price for interest-rate instrument with `IRTree` pricer (Since R2020a)
`price`	Compute price for interest-rate instrument with `IRMonteCarlo` pricer (Since R2021b)
`price`	Compute price for interest-rate instrument with `Future` pricer (Since R2022a)

Objects

expand all

Underlying Interest-Rate Curve

ratecurve Create ratecurve object for interest-rate curve from dates and data (Since R2020a)

Interest-Rate Instruments

`CMS`	`CMS` instrument object (Since R2023a)
`CMSNote`	`CMSNote` instrument object (Since R2023a)
`Deposit`	`Deposit` instrument object (Since R2020a)
`FixedBond`	`FixedBond` instrument object (Since R2020a)
`FixedBondOption`	`FixedBondOption` instrument object (Since R2020a)
`FloatBond`	`FloatBond` instrument object (Since R2020a)
`FloatBondOption`	`FloatBondOption` instrument object (Since R2020a)
`OptionEmbeddedFixedBond`	`OptionEmbeddedFixedBond` instrument object (Since R2020a)
`OptionEmbeddedFloatBond`	`OptionEmbeddedFloatBond` instrument object (Since R2020a)
`ConvertibleBond`	`ConvertibleBond` instrument object (Since R2021a)
`Cap`	`Cap` instrument object (Since R2020a)
`Floor`	`Floor` instrument object (Since R2020a)
`Swap`	`Swap` instrument object (Since R2020a)
`Swaption`	`Swaption` instrument object (Since R2020a)
`FRA`	`FRA` instrument object (Since R2020a)
`OvernightIndexedSwap`	`OvernightIndexedSwap` instrument object (Since R2021b)
`STIRFuture`	`STIRFuture` instrument object (Since R2021b)
`OISFuture`	`OISFuture` instrument object (Since R2021b)
`BondFuture`	`BondFuture` instrument object (Since R2022a)

Models for Interest-Rate Instruments

`HullWhite`	Create `HullWhite` model object for `Cap`, `Floor`, `Swaption`, `Swap`, `FixedBond`, `FloatBond`, `FloatBondOption`, `FixedBondOption`, `OptionEmbeddedFixedBond`, or `OptionEmbeddedFloatBond` instrument (Since R2020a)
`CoxIngersollRoss`	Create `CoxIngersollRoss` model object for `Cap`, `Floor`, `Swaption`, `Swap`, `FixedBond`, `FloatBond`, `FloatBondOption`, `FixedBondOption`, `OptionEmbeddedFixedBond`, or `OptionEmbeddedFloatBond` instrument (Since R2023b)
`CMSConvexityHull`	Create `CMSConvexityHull` model object for `CMS` or `CMSNote` instrument (Since R2023a)
`BlackKarasinski`	Create `BlackKarasinski` model object for a `Cap`, `FloorSwaption`, `Swap`, `FloatBond`, `FixedBond`, `FixedBondOption`, `FloatBondOption`, `OptionEmbeddedFixedBond`, or `OptionEmbeddedFloatBond` instrument (Since R2020a)
`BlackDermanToy`	Create `BlackDermanToy` model object for a `Cap`, `Floor`, `Swaption`, `Swap`, `FloatBond`, `FixedBond`, `FixedBondOption`, `FloatBondOption`, `OptionEmbeddedFixedBond`, or `OptionEmbeddedFloatBond` instrument (Since R2022b)
`Black`	Create `Black` model object for `Cap`, `Floor`, or `Swaption` instrument (Since R2020a)
`Normal`	Create `Normal` model object for `Cap`, `Floor`, or `Swaption` instrument (Since R2020a)
`SABR`	Create `SABR` model object for `Swaption` instrument (Since R2020a)
`SABRBraceGatarekMusiela`	Create `SABRBraceGatarekMusiela` model object for `Cap`, `Floor`, `FixedBond`, `FloatBond`, `FloatBondOption`, `FixedBondOption`, `OptionEmbeddedFixedBond`, or `OptionEmbeddedFloatBond` instrument (Since R2021b)
`BraceGatarekMusiela`	Create `BraceGatarekMusiela` model object for `Cap`, `Floor`, `FixedBond`, `FloatBond`, `FloatBondOption`, `FixedBondOption`, `OptionEmbeddedFixedBond`, or `OptionEmbeddedFloatBond` instrument (Since R2021b)
`LinearGaussian2F`	Create `LinearGaussian2F` model object for `Cap`, `Floor`, `Swaption`, `Swap`, `FixedBond`, `FloatBond`, `FloatBondOption`, `FixedBondOption`, `OptionEmbeddedFixedBond`, or `OptionEmbeddedFloatBond` instrument (Since R2021b)

Pricers for Interest-Rate Instruments

`Discount`	Create `Discount` pricer object for `Deposit`, `FRA`, `Swap`, `FixedBond`, `FloatBond`, `OISFuture`, `STIRFuture`, and `OvernightIndexedSwap` using `ratecurve` object (Since R2020a)
`CMSConvexityHull`	Create `CMSConvexityHull` pricer object for `CMS` or `CMSNote` instrument using `CMSConvexityHull` model (Since R2023a)
`IRTree`	Create `IRTree` pricer object for `Cap`, `Floor`, `Swap`, `Swaption`, `FloatBond`, `FixedBond`, `FixedBondOption`, `FloatBondOption`, `OptionEmbeddedFixedBond`, or `OptionEmbeddedFloatBond` instrument (Since R2020a)
`IRMonteCarlo`	Create `IRMonteCarlo` pricer object for interest-rate instruments using `HullWhite`, `BraceGatarekMusiela`, `BlackKarasinski`, or `LinearGaussian2F` model (Since R2021b)
`Normal`	Create `Normal` pricer object for `Cap`, `Floor`, or `Swaption` instrument using `Normal` model (Since R2020a)
`SABR`	Create `SABR` pricer object for `Swaption` instrument using `SABR` model (Since R2020a)
`Black`	Create `Black` pricer object for `Cap`, `Floor`, or `Swaption` instrument using `Black` model (Since R2020a)
`HullWhite`	Create `HullWhite` pricer object for `Cap`, `Floor`, or `Swaption` instrument using `HullWhite` model (Since R2020a)
`Future`	Create `Future` pricer object for `BondFuture`, `CommodityFuture`, `EquityIndexFuture`, and `FXFuture` using `ratecurve` object (Since R2022a)

Topics

Calibrate Shifted SABR Model Parameters for Swaption Instrument
Calibrate model parameters for a Swaption instrument when you use a SABR pricing method.
Calibrate SABR Model Using Normal (Bachelier) Volatilities with Analytic Pricer
This example shows how to use two different methods to calibrate the SABR stochastic volatility model from market implied Normal (Bachelier) volatilities with negative strikes.
Calibrate SABR Model Using Analytic Pricer
This example shows how to use two different methods to calibrate a SABR stochastic volatility model from market implied Black volatilities.
Price a Swaption Using SABR Model and Analytic Pricer
This example shows how to price a swaption using the SABR model.
Historical Value-at-Risk Estimation with US Treasury Bonds
This example shows how to estimate the value at risk (VaR) for a portfolio of US Treasury bonds by using both the historical and filtered historical VaR methods.
Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments
Use objects to model and price financial instruments.
Choose Instruments, Models, and Pricers
Select instruments, associated models, and associated pricers.
Work with Negative Interest Rates Using Objects
Financial Instruments Toolbox™ computes prices for caps, floors, swaptions when modeling for negative interest-rates using the object framework.
Mapping Financial Instruments Toolbox Functions to Object-Based Framework for Instruments, Models, and Pricers
Mapping functions to a workflow using objects for instruments, models, and pricers.
Supported Exercise Styles
The following table lists the interest-rate instrument objects with their associated models and pricers and supported Exercise styles.

Related Information

Object-Based Framework for Pricing Financial Instruments (2 min 42 sec)

Featured Examples

Calibrate SABR Model Using Normal (Bachelier) Volatilities with Analytic Pricer

Use two different methods to calibrate the SABR stochastic volatility model from market implied Normal (Bachelier) volatilities with negative strikes. Both approaches use the SABR analytic pricer. When the Beta parameter of the SABR model is set to zero, the model is a Normal SABR model, which allows computing the implied Normal volatilities for negative strikes.

Open Live Script

Calibrate SABR Model Using Analytic Pricer

Use two different methods to calibrate a SABR stochastic volatility model from market implied Black volatilities. Both approaches use the SABR analytic pricer.

Open Live Script

Price a Swaption Using SABR Model and Analytic Pricer

Price a swaption using the SABR model. First, you construct a swaption volatility surface from market volatilities by calibrating the SABR model parameters separately for each swaption maturity using the SABR analytic pricer. You then compute the swaption price by using the implied Black volatility on the surface with the SABR analytic pricer.

Open Live Script

Calibrate Shifted SABR Model Parameters for Swaption Instrument

Calibrate model parameters for a Swaption instrument when you use a SABR pricing method.

Open Live Script

Compute LIBOR Fallback

Compute a USD LIBOR fallback. Regulators and industry groups have recommended that firms transition away from the London inter-bank offered rate (LIBOR) and prepare to replace them with overnight Alternative Reference Rates (ARRs). What happens to contracts with a notional value of trillions of dollars if they refer to a benchmark that no longer exists? If the LIBOR benchmark is no longer published, references to that benchmark rate must change and benchmark rates “fall back” to a new benchmark in contracts. For example, if a 30-year floating-rate instrument with a three-month coupon based on the LIBOR rate is created in 2008 and expires in 2038, then the rate will need to change in 2023 because in 2023, the publication of a LIBOR rate permanently ceases. To calculate three-month coupon payments after 2023, you must use a LIBOR fallback. This example is based on the ISDA® 2020 IBOR Fallbacks Protocol.

Open Live Script

Create and Price Portfolio of Instruments

Use finportfolio and pricePorfolio to create and price a portfolio of interest-rate and equity instruments. The portfolio contains a vanilla FixedBond, an OptionEmbeddedFixedBond, a Vanilla European call option, a Vanilla American call option, and an Asian call option.

Open Live Script

Bond Portfolio Optimization Using Portfolio Object

Use a Portfolio object to construct an optimal portfolio of 10, 20, and 30 year treasuries that will be held for a period of one month. The workflow for the overall asset allocation process is:

Select Cheapest-to-Deliver Bond Using BondFuture Instrument

Select the cheapest-to-deliver (CTD) bond for Treasury bond future contracts using a BondFuture instrument. It demonstrates two workflows for selecting the CTD bond:

Open Live Script

Historical Value-at-Risk Estimation with US Treasury Bonds

Estimate the value at risk (VaR) for a portfolio of US Treasury bonds by using both the historical and filtered historical VaR methods. While this example uses treasury bonds as a typical asset type, you can apply this workflow to any fixed-rate bond with similar par yield data.

Open Live Script