Swap

Swap instrument object

Description

Create and price a Swap instrument object using this workflow:

1. Use fininstrument to create a Swap instrument object.

2. Use ratecurve to specify a curve model for the Swap instrument or use finmodel to specify a HullWhite or BlackKarasinski model.

3. Use finpricer to specify a Discount pricing method when using a ratecurve object or an IRTree pricing method when using a HullWhite or BlackKarasinski model for the Swap instrument.

For more information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.

For more information on the available models and pricing methods for a Swap instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

SwapInstrument = fininstrument(InstrumentType,'Maturity',maturity_date,'LegRate',leg_rate)

SwapInstrument = fininstrument(___,Name,Value)

Description

SwapInstrument = fininstrument(InstrumentType,'Maturity',maturity_date,'LegRate',leg_rate) creates a Swap object by specifying InstrumentType and sets the properties for the required name-value pair arguments Maturity and LegRate.

The Swap instrument supports vanilla swaps, amortizing swaps and forward swaps. You can use the Swap instrument for a single currency swap but not a cross-currency swap. For more information on a Swap instrument, see More About.

SwapInstrument = fininstrument(___,Name,Value) sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For example, SwapInstrument = fininstrument("Swap",'Maturity',datetime(2019,1,30),'LegRate',[0.06 0.12],'LegType',["fixed","fixed"],'Basis',1,'Notional',100,'StartDate',datetime(2016,1,30),'DaycountAdjustedCashFlow',true,'BusinessDayConvention',"follow",'ProjectionCurve',ratecurve,'Name',"swap_instrument") creates a Swap option with a maturity of January 30, 2019. You can specify multiple name-value pair arguments.

Input Arguments

InstrumentType — Instrument type

string with value "Swap" | character vector with value 'Swap'

Instrument type, specified as a string with the value of "Swap" or a character vector with the value of 'Swap'.

Data Types: char | string

Swap Name-Value Pair Arguments

Specify required and optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: SwapInstrument = fininstrument("Swap",'Maturity',datetime(2019,1,30),'LegRate',[0.06 0.12],'LegType',["fixed","fixed"],'Basis',1,'Notional',100,'StartDate',datetime(2016,1,30),'DaycountAdjustedCashFlow',true,'BusinessDayConvention',"follow",'ProjectionCurve',ratecurve,'Name',"swap_instrument")

Required Swap Name-Value Pair Arguments

'Maturity' — Swap maturity date

datetime | serial date number | date character vector | date string

Swap maturity date, specified as the comma-separated pair consisting of 'Maturity' and a scalar datetime, serial date number, date character vector, or date string.

If you use a date character vector or date string, the format must be recognizable by datetime because the Maturity property is stored as a datetime.

Data Types: char | double | string | datetime

'LegRate' — Leg rate in decimal values

matrix

Leg rate in decimal values, specified as the comma-separated pair consisting of 'LegRate' and a NINST-by-2 matrix. Each row can be defined as one of the following:

• [CouponRate Spread] (fixed-float)

• [Spread CouponRate] (float-fixed)

• [CouponRate CouponRate] (fixed-fixed)

• [Spread Spread] (float-float)

CouponRate is the decimal annual rate. Spread is the number of basis points in decimals over the reference rate. The first column represents the receiving leg, while the second column represents the paying leg.

Data Types: double

Optional Swap Name-Value Pair Arguments

'LegType' — Leg type

["fixed","float"] for each instrument (default) | cell array of character vectors with values {'fixed','fixed'}, {'fixed','float'}, {'float','fixed'}, or {'float','float'} | string array with values ["fixed","fixed"], ["fixed","float"], ["float","fixed"], or ["float","float"]

Leg type, specified as the comma-separated pair consisting of 'LegType' and a cell array of character vectors or a string array with the supported values. The LegType defines the interpretation of the values entered in LegRate.

Note

When you specify a Swap instrument as the underlying asset for a Swaption instrument while using a Normal, SABR, Black, or HullWhite pricer, the Swap LegType must be ["fixed","float"] or ["float","fixed"]. You must also set the ExerciseStyle name-value pair argument of the associated Swaption instrument to 'European'.

Data Types: cell | string

'ProjectionCurve' — Rate curve for projecting floating cash flows

ratecurve.empty (default) | ratecurve object

Rate curve for projecting floating cash flows, specified as the comma-separated pair consisting of 'ProjectionCurve' and a ratecurve object. You must create this object using ratecurve. Use this optional input if the forward curve is different from the discount curve.

Data Types: object

'Reset' — Frequency of payments per year

[2 2] (default) | numeric value of 0, 1, 2, 3, 4, 6, or 12 | vector

Frequency of payments per year, specified as the comma-separated pair consisting of 'Reset' and scalar or NINST-by-2 if Reset is different for each leg) with one of the following values: 0, 1, 2, 3, 4, 6, or 12.

Data Types: double

'Basis' — Day-count basis representing the basis for each leg

[0 0] (actual/actual) (default) | integer from 0 to 13

Day-count basis representing the basis for each leg, specified as the comma-separated pair consisting of 'Basis' and a NINST-by-1 array (or NINST-by-2 if Basis is different for each leg).

• 0 — actual/actual

• 1 — 30/360 (SIA)

• 2 — actual/360

• 3 — actual/365

• 4 — 30/360 (PSA)

• 5 — 30/360 (ISDA)

• 6 — 30/360 (European)

• 7 — actual/365 (Japanese)

• 8 — actual/actual (ICMA)

• 9 — actual/360 (ICMA)

• 10 — actual/365 (ICMA)

• 11 — 30/360E (ICMA)

• 12 — actual/365 (ISDA)

• 13 — BUS/252

For more information, see Basis.

Data Types: double

'Notional' — Notional principal amount or principal value schedule

100 (default) | scalar numeric | timetable

Notional principal amount or principal value schedule, specified as the comma-separated pair consisting of 'Notional' and a scalar numeric or timetable. Use a scalar for a vanilla Swap instrument and a timetable for an amortizing Swap instrument.

Notional accepts a scalar for a principal amount (or a NINST-by-2 matrix if Notional is different for each leg) or a timetable for principal value schedules. For schedules, the first column of the timetable is dates and the second column is the associated notional principal value. The date indicates the last day that the principal value is valid.

Data Types: timetable | double

'LatestFloatingRate' — Latest floating rate for float legs

if not specified, then ratecurve must contain this information (default) | scalar numeric | vector

Latest floating rate for float legs, specified as the comma-separated pair consisting of 'LatestFloatingRate' and a scalar numeric value.

LatestFloatingRate is a NINST-by-1 matrix (or NINST-by-2 matrix if LatestFloatingRate is different for each leg).

Data Types: double

'ResetOffset' — Lag in rate setting

[0 0] (default) | vector

Lag in rate setting, specified as the comma-separated pair consisting of 'ResetOffset' and a NINST-by-2 vector.

Data Types: double

'DaycountAdjustedCashFlow' — Flag to adjust cash flows based on actual period day count

false (default) | value of true or false

Flag to adjust cash flows based on actual period day count, specified as the comma-separated pair consisting of 'DaycountAdjustedCashFlow' and a NINST-by-1 (or NINST-by-2 if AdjustCashFlowsBasis is different for each leg) of logicals with values of true or false.

Data Types: logical

'BusinessDayConvention' — Business day conventions

"actual" (default) | string | string array | character vector | cell array of character vectors

Business day conventions, specified as the comma-separated pair consisting of 'BusinessDayConvention' and string (or string array if BusinessDayConvention is different for each leg) or a character vector (or NINST-by-2 cell array of character vectors if BusinessDayConvention is different for each leg). The selection for business day convention determines how nonbusiness days are treated. Nonbusiness days are defined as weekends plus any other date that businesses are not open (for example, statutory holidays). Values are:

• "actual" — Nonbusiness days are effectively ignored. Cash flows that fall on non-business days are assumed to be distributed on the actual date.

• "follow" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day.

• "modifiedfollow" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day. However if the following business day is in a different month, the previous business day is adopted instead.

• "previous" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day.

• "modifiedprevious" — Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day. However if the previous business day is in a different month, the following business day is adopted instead.

Data Types: char | cell | string

'Holidays' — Holidays used in computing business days

NaT (default) | datetime | cell array of date character vectors | date string array | serial date numbers

Holidays used in computing business days, specified as the comma-separated pair consisting of 'Holidays' and dates using datetimes, serial date numbers, cell array of date character vectors, or date string array. For example:

H = holidays(datetime('today'),datetime(2025,12,15));
Swap = fininstrument("Swap",'Maturity',datetime(2025,12,15),'LegRate',[0.06 20],'Holidays',H)

Data Types: double | cell | datetime | string

'EndMonthRule' — End-of-month rule flag for generating dates when Maturity is end-of-month date for month with 30 or fewer days

[true true] (in effect) (default) | logical with value of true or false

End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month with 30 or fewer days, specified as the comma-separated pair consisting of 'EndMonthRule' and a logical value of true or false using a NINST-by-1 (or NINST-by-2 if EndMonthRule is different for each leg).

• If you set EndMonthRule to false, the software ignores the rule, meaning that a payment date is always the same numerical day of the month.

• If you set EndMonthRule to true, the software sets the rule on, meaning that a payment date is always the last actual day of the month.

Data Types: logical

'StartDate' — Date swap starts

Settle date (default) | datetime | serial date number | date character vector | date string

Date swap starts, specified as the comma-separated pair consisting of 'StartDate' and a scalar datetime, serial date number, date character vector, or date string.

Use StartDate to price a forward swap, that is, a swap that starts at a future date.

If you use a date character vector or date string, the format must be recognizable by datetime because the StartDate property is stored as a datetime.

Data Types: char | double | string | datetime

'Name' — User-defined name for instrument

" " (default) | string | character vector

User-defined name for the instrument, specified as the comma-separated pair consisting of 'Name' and a scalar string or character vector.

Data Types: char | string

Properties

Maturity — Maturity date

datetime

Maturity date, returned as a datetime.

Data Types: datetime

LegRate — Leg rate

matrix

Leg rate, returned as a NINST-by-2 matrix of decimal values, with each row defined as one of the following:

• [CouponRate Spread] (fixed-float)

• [Spread CouponRate] (float-fixed)

• [CouponRate CouponRate] (fixed-fixed)

• [Spread Spread] (float-float)

Data Types: double

LegType — Leg type

["fixed","float"] for each instrument (default) | string array with values ["fixed","fixed"], ["fixed","float"], ["float","fixed"], or ["float","float"]

Leg type, returned as a string array with the values ["fixed","fixed"], ["fixed","float"], ["float","fixed"], or ["float","float"].

Data Types: string

ProjectionCurve — Rate curve used in generating future cash flows

ratecurve.empty (default) | ratecurve object

Rate curve used in projecting the future cash flows, returned as a ratecurve object.

Data Types: object

Reset — Reset frequency per year for each swap

[2 2] (default) | vector

Reset frequency per year for each swap, returned as an NINST-by-2 vector.

Data Types: double

Basis — Day count basis

[0 0] (actual/actual) (default) | integer from 0 to 13

Day count basis, returned as an NINST-by-2 vector.

Data Types: double

ResetOffset — Lag in rate setting

[0 0] (default) | vector

Lag in rate setting, returned as an NINST-by-2 vector.

Data Types: double

Notional — Notional principal amount or principal value schedules

100 (default) | scalar numeric | timetable

Notional principal amount, returned as a scalar numeric or timetable.

Data Types: cell | double

LatestFloatingRate — Rate for the next floating payment

if not specified, then ratecurve must contain this information (default) | scalar numeric

Rate for the next floating payment, set at the last reset date, returned as a scalar numeric value.

Data Types: double

DaycountAdjustedCashFlow — Flag to adjust cash flows based on actual period day count

false (default) | value of true or false

Flag to adjust cash flows based on actual period day count, returned as an NINST-by-1 matrix (or an NINST-by-2 matrix if AdjustCashFlowsBasis is different for each leg) of logicals with values of true or false.

Data Types: logical

BusinessDayConvention — Business day conventions

"actual" (default) | string | string array

Business day conventions, returned as a string or a NINST-by-2 string array if BusinessDayConvention is different for each leg.

Data Types: char | cell | string

Holidays — Holidays used in computing business days

NaT (default) | datetime

Holidays used in computing business days, returned as datetimes.

Data Types: datetime

EndMonthRule — End-of-month rule flag for generating dates when Maturity is end-of-month date for month with 30 or fewer days

[true true] (in effect) (default) | logical with value of true or false

End-of-month rule flag for generating dates when Maturity is an end-of-month date for a month with 30 or fewer days, returned as a scalar logical.

Data Types: logical

StartDate — Date swap starts

Settle date (default) | datetime

Date swap starts, returned as a datetime.

Data Types: datetime

Name — User-defined name for instrument

" " (default) | string

User-defined name for the instrument, returned as a string.

Data Types: string

Object Functions

cashflows	Computes cash flow for FixedBond, FloatBond, Swap, FRA, or Deposit instrument
parswaprate	Compute par swap rate for Swap instrument

Examples

Price Vanilla Swap Instrument Using ratecurve and Discount Pricer

This example shows the workflow to price a vanilla Swap instrument when you use a ratecurve and a Discount pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve for the underlying interest-rate curve for the Swap instrument.

Settle = datetime(2019,9,15);
Type = 'zero';
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 15-Sep-2019
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create a vanilla Swap instrument object.

Swap = fininstrument("Swap",'Maturity',datetime(2024,9,15),'LegRate',[0.022 0.019 ],'LegType',["float","fixed"],'ProjectionCurve',myRC,'Name',"swap_instrument")

Swap = 
  Swap with properties:

                     LegRate: [0.0220 0.0190]
                     LegType: ["float"    "fixed"]
                       Reset: [2 2]
                       Basis: [0 0]
                    Notional: 100
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [1x2 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: NaT
                    Maturity: 15-Sep-2024
                        Name: "swap_instrument"

Create Discount Pricer Object

Use finpricer to create a Discount pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

outPricer = finpricer("Discount", 'DiscountCurve',myRC)

outPricer = 
  Discount with properties:

    DiscountCurve: [1x1 ratecurve]

Price Swap Instrument

Use price to compute the price and sensitivities for the vanilla Swap instrument.

[Price, outPR] = price(outPricer, Swap,["all"])

Price = 7.2279

outPR = 
  priceresult with properties:

       Results: [1x2 table]
    PricerData: []

outPR.Results

ans=1×2 table
    Price       DV01  
    ______    ________

    7.2279    -0.02212

Price Amortizing Swap Instrument Using ratecurve and Discount Pricer

This example shows the workflow to price an amortizing Swap instrument when you use a ratecurve and a Discount pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve for the underlying interest-rate curve for the Swap instrument.

Settle = datetime(2019,1,1);
Type = 'zero';
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 01-Jan-2019
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create an amortizing Swap instrument object.

Maturity = datetime(2024,1,1);
ADates = datetime([2020,1,1 ; 2024,1,1]);
APrincipal = [100; 85];
Notional = timetable(ADates,APrincipal);
Swap = fininstrument("Swap",'Maturity',Maturity,'LegRate',[0.035,0.01],'Reset',[1 1],'Notional',Notional,'Name',"swap_instrument")

Swap = 
  Swap with properties:

                     LegRate: [0.0350 0.0100]
                     LegType: ["fixed"    "float"]
                       Reset: [1 1]
                       Basis: [0 0]
                    Notional: [2x1 timetable]
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [0x0 ratecurve]
       BusinessDayConvention: ["actual"    "actual"]
                    Holidays: NaT
                EndMonthRule: [1 1]
                   StartDate: NaT
                    Maturity: 01-Jan-2024
                        Name: "swap_instrument"

Create Discount Pricer Object

Use finpricer to create a Discount pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

outPricer = finpricer("Discount", 'DiscountCurve',myRC)

outPricer = 
  Discount with properties:

    DiscountCurve: [1x1 ratecurve]

Price Swap Instrument

Use price to compute the price and sensitivities for the amortizing Swap instrument.

[Price, outPR] = price(outPricer, Swap,["all"])

Price = 5.7183

outPR = 
  priceresult with properties:

       Results: [1x2 table]
    PricerData: []

outPR.Results

ans=1×2 table
    Price       DV01  
    ______    ________

    5.7183    0.022979

Price Vanilla Swap Instrument Using Hull-White Model and IRTree Pricer

This example shows the workflow to price a vanilla Swap instrument when you use a HullWhite model and an IRTree pricing method.

Create ratecurve Object

Create a ratecurve object using ratecurve for the underlying interest-rate curve for the Swap instrument.

Settle = datetime(2020,1,15);
Type = 'zero';
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 15-Jan-2020
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Swap Instrument Object

Use fininstrument to create a vanilla Swap instrument object.

LegType = ["float","fixed"]

LegType = 1x2 string
    "float"    "fixed"

Swap = fininstrument("Swap",'Maturity',datetime(2030,9,15),'LegRate',[0.022 0.019],'LegType',LegType,'ProjectionCurve',myRC,'Name',"swap_instrument");

Create HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",'Alpha',0.032,'Sigma',0.04)

HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0320
    Sigma: 0.0400

Compute Swap Instrument Cash Flow Dates

Use cfdates to compute the cash flows.

CFdates = cfdates(Settle, Swap.Maturity, Swap.Reset(1), Swap.Basis(1))

CFdates = 1x22 datetime
Columns 1 through 5

   15-Mar-2020   15-Sep-2020   15-Mar-2021   15-Sep-2021   15-Mar-2022

Columns 6 through 10

   15-Sep-2022   15-Mar-2023   15-Sep-2023   15-Mar-2024   15-Sep-2024

Columns 11 through 15

   15-Mar-2025   15-Sep-2025   15-Mar-2026   15-Sep-2026   15-Mar-2027

Columns 16 through 20

   15-Sep-2027   15-Mar-2028   15-Sep-2028   15-Mar-2029   15-Sep-2029

Columns 21 through 22

   15-Mar-2030   15-Sep-2030

Create IRTree Pricer Object

Use finpricer to create an IRTree pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

HWTreePricer = finpricer("IRTree",'Model',HullWhiteModel,'DiscountCurve',myRC,'TreeDates',CFdates')

HWTreePricer = 
  HWBKTree with properties:

             Tree: [1x1 struct]
        TreeDates: [22x1 datetime]
            Model: [1x1 finmodel.HullWhite]
    DiscountCurve: [1x1 ratecurve]

Price Swap Instrument

Use price to compute the price and sensitivities for the vanilla Swap instrument.

[Price, outPR] = price(HWTreePricer, Swap,"all")

Price = 24.3727

outPR = 
  priceresult with properties:

       Results: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results

ans=1×4 table
    Price        Vega        Gamma     Delta 
    ______    __________    _______    ______

    24.373    8.5265e-10    -8790.5    820.67

More About

Swap

A swap is contract between two parties obligating the parties to exchange future cash flows.

A vanilla swap is composed of a floating-rate leg and a fixed-rate leg.

Swap with Amortization

A swap with an amortization schedule repays part of the principal (face value) along with the coupon payments.

A swap with an amortization schedule is used to manage interest-rate risk and serve as a cash flow management tool. For this particular type of swap, the notional amount decreases over time. This means that interest payments decrease not only on the floating leg but also on the fixed leg. Use the Notional name-value pair argument to support an amortization schedule.

Forward Swap

In a forward interest-rate swap, a fixed interest-rate loan is exchanged for a floating interest-rate loan at a future specified date.

The StartDate name-value pair argument supports the future date for the forward swap.