# cashsettle

Compute cash settlement for BondFuture, CommodityFuture, EquityIndexFuture, or FXFuture instrument

Since R2022a

## Description

example

outCS = cashsettle(InstrumentObject,SpotPrice,DiscountCurve) computes the cash settlement for a BondFuture, CommodityFuture, FXFuture, or EquityIndexFuture instrument object.

## Examples

collapse all

This example shows the workflow to price a BondFuture instrument and then use cashsettle to compute the cash settlement amount for the BondFuture instrument.

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2022,3,1);
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;
ZeroCurve = ratecurve("zero",Settle,ZeroDates,ZeroRates,Compounding=2);

Create Underlying FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

FixB = fininstrument("FixedBond",Maturity=datetime(2032,9,1),CouponRate=0.05,Name="fixed_bond_instrument")
FixB =
FixedBond with properties:

CouponRate: 0.0500
Period: 2
Basis: 0
EndMonthRule: 1
Principal: 100
Holidays: NaT
IssueDate: NaT
FirstCouponDate: NaT
LastCouponDate: NaT
StartDate: NaT
Maturity: 01-Sep-2032
Name: "fixed_bond_instrument"

Create BondFuture Instrument Object

Use fininstrument to create a BondFuture instrument object.

BondFut = fininstrument("BondFuture",Maturity=datetime(2022,9,1),QuotedPrice=86,Bond=FixB,ConversionFactor=1.43,Name="bondfuture_instrument")
BondFut =
BondFuture with properties:

Maturity: 01-Sep-2022
QuotedPrice: 86
Bond: [1x1 fininstrument.FixedBond]
ConversionFactor: 1.4300
Notional: 100000
Name: "bondfuture_instrument"

Create Future Pricer Object

Use finpricer to create a Future pricer object and use the ratecurve object with the DiscountCurve name-value argument.

outPricer = finpricer("Future",DiscountCurve=ZeroCurve,SpotPrice=125)
outPricer =
Future with properties:

DiscountCurve: [1x1 ratecurve]
SpotPrice: 125

Price BondFuture Instrument

Use price to compute the price and price result for the BondFuture instrument.

[Price,outPR] = price(outPricer,BondFut)
Price = -151.9270
outPR =
priceresult with properties:

Results: [1x4 table]
PricerData: []

outPR.Results
ans=1×4 table
Price     FairDeliveryPrice    FairFuturePrice    AccruedInterest
_______    _________________    _______________    _______________

-151.93       1.2283e+05            85.893                0

Compute Cash Settlement Amount

Use cashsettle with the BondFuture instrument to compute the cash settlement.

SpotPrice = 125; % Clean spot price for \$100 face value of underlying bond.
outCS = cashsettle(BondFut,SpotPrice,ZeroCurve)
outCS= 1×1timetable
Time        CashSettleAmount
___________    ________________

01-Sep-2022        -152.33

This example shows the workflow to price multiple FXFuture instruments and then use cashsettle to compute the cash settlement amount for the FXFuture instruments.

Create ratecurve Objects

Create ratecurve objects using ratecurve for the foreign and domestic zero curves.

% Define Foreign Zero Curve
Settle = datetime(2022, 3, 1);
ForeignZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
ForeignZeroRates = [0.0031 0.0035 0.0047 0.0058 0.0062 0.0093 0.0128 0.0182 0.0223 0.0285]';
ForeignZeroDates = Settle + ForeignZeroTimes;
ForeignRC = ratecurve('zero', Settle, ForeignZeroDates, ForeignZeroRates);

% Define Domestic Zero Curve
DomesticZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]';
DomesticZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]';
DomesticZeroDates = Settle + DomesticZeroTimes;
DomesticRC = ratecurve('zero', Settle, DomesticZeroDates, DomesticZeroRates);

Create FXFuture Instrument Object

Use fininstrument to create a FXFuture instrument object for three FX Future instruments.

FXFut = fininstrument("FXFuture",Maturity=datetime([2022,9,1 ; 2022,10,1 ; 2022,11,1]),QuotedPrice=[0.78 ; 0.82 ; 0.86],ForeignRateCurve=ForeignRC,Notional=200000,Name=["FXfuture_instrument1";"FXfuture_instrument2";"FXfuture_instrument3"])
FXFut=3×1 object
3x1 FXFuture array with properties:

Maturity
QuotedPrice
ForeignRateCurve
Notional
Name

Create Future Pricer Object

Use finpricer to create a Future pricer object and use the ratecurve object with the DiscountCurve name-value argument.

outPricer = finpricer("Future",DiscountCurve=DomesticRC,SpotPrice=0.79)
outPricer =
Future with properties:

DiscountCurve: [1x1 ratecurve]
SpotPrice: 0.7900

Price FXFuture Instruments

Use price to compute the prices and price results for the FXFuture instrument.

[Price,outPR] = price(outPricer,FXFut)
Price = 3×1
104 ×

0.2162
-0.5789
-1.3732

outPR=1×3 object
1x3 priceresult array with properties:

Results
PricerData

outPR.Results
ans=1×4 table
Price     FairDeliveryPrice    FairFuturePrice    AccruedInterest
______    _________________    _______________    _______________

2161.7       1.5817e+05            0.79084               0

ans=1×4 table
Price    FairDeliveryPrice    FairFuturePrice    AccruedInterest
_____    _________________    _______________    _______________

-5789       1.5819e+05            0.79097               0

ans=1×4 table
Price     FairDeliveryPrice    FairFuturePrice    AccruedInterest
______    _________________    _______________    _______________

-13732       1.5822e+05            0.7911                0

Compute Cash Settlement Amounts

Use cashsettle with the FXFuture instruments to compute the cash settlement.

SpotPrice = 0.79; % Quoted in domestic currency for one unit of foreign currency
outCS = cashsettle(FXFut(1),SpotPrice,DomesticRC)
outCS= 1×1timetable
Time        CashSettleAmount
___________    ________________

01-Sep-2022         2167.4

outCS = cashsettle(FXFut(2),SpotPrice,DomesticRC)
outCS= 1×1timetable
Time        CashSettleAmount
___________    ________________

01-Oct-2022        -5806.9

outCS = cashsettle(FXFut(3),SpotPrice,DomesticRC)
outCS= 1×1timetable
Time        CashSettleAmount
___________    ________________

01-Nov-2022         -13781

## Input Arguments

collapse all

Instrument object, specified using a previously created instrument object for one of the following: BondFuture, CommodityFuture, FXFuture, or EquityIndexFuture.

Note

If InstrumentObject is a vector of instruments, you must use cashsettle separately with each instrument.

Data Types: object

ratecurve object for discounting cash flows, specified using the name of a previously created ratecurve object.

Data Types: object

Quoted spot price for underlying asset to be delivered, specified using a numeric value that depends on the type of future instrument being priced:

• BondFuture instrument — Clean spot price quoted for \$100 face value of underlying bond

• CommodityFuture instrument — Spot price for underlying commodity quantity specified in contract

• EquityIndexFuture instrument — Spot equity index value

• FXFuture instrument — Spot price quoted in domestic currency for one unit of foreign currency

Data Types: double

## Output Arguments

collapse all

Cash settlement, returned as a timetable.

## Version History

Introduced in R2022a