cashsettle

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

Since R2022a

Syntax

outCS = cashsettle(InstrumentObject,SpotPrice,DiscountCurve)

Description

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

Examples

Compute Cash Settlement for BondFuture Instrument

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
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    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: [1×1 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: [1×1 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: [1×4 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     

Compute Cash Settlement for Multiple FXFuture Instruments

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 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: [1×1 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 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

InstrumentObject — Instrument object

BondFuture object | CommodityFuture object | EquityIndexFuture object | FXFuture object

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

DiscountCurve — ratecurve object for discounting cash flows

ratecurve object

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

Data Types: object

SpotPrice — Quoted spot price for underlying asset to be delivered

numeric

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

outCS — Cash settlement

timetable

Cash settlement, returned as a timetable.

Version History

Introduced in R2022a