QS.INSTRUMENT.LOAN

Creates a fixed or floating loan contract; rate is an annual decimal coupon or spread; defaults to French monthly repayment and Actual365; value with QS.EVALUATE

Category: QuantSupport - Instruments.

QS.INSTRUMENT.LOAN(name: text, context: text, start_date: text, maturity_date: text, currency: text, notional: number, rate: number, market_index: text or blank, repayment: text or blank, payment_frequency: text or blank, day_counter: text or blank, settings: text or blank, coupon_periods: cell or range, coupon_rates: cell or range, coupon_indices: cell or range, prepayment_dates: cell or range, prepayment_cprs: cell or range, start_tenor: text or blank, tenor: text or blank) → text handle
Parameters:

  • name (text) – Workbook-unique object name; unchanged recalculation reuses its current handle

  • context (text) – Required prepared context handle used to build concrete dates and initial contractual terms; construction waits for committed market inputs

  • start_date (text) – Contractual advance/accrual start as YYYY-MM-DD text, e.g. 2026-02-24; required; distinct from the position’s trade date

  • maturity_date (text) – Final contractual accrual date as YYYY-MM-DD text; required and after start_date; payment date may be adjusted by Loan Settings

  • currency (text) – Three-letter ISO currency code, for example USD or EUR

  • notional (number) – Positive original principal in currency units, e.g. 10000 = EUR 10,000 for EUR; contractual principal, not a price or percentage

  • rate (number) – Annual decimal fixed coupon when market_index is blank; otherwise the floating spread, e.g. 0.01 for 100 bp

  • market_index (text or blank) – Optional floating projection index such as EURIBOR12m; omitted or blank creates a fixed-rate loan

  • repayment (text or blank) – Optional French = level initial instalments (blank default); Bullet = all principal at maturity; Balloon = amortization plus final residual, requiring balloon_fraction in QS.LOAN.SETTINGS

  • payment_frequency (text or blank) – Optional contractual payment frequency; omitted or blank defaults to Monthly; floating resets independently use index metadata unless settings override it

  • day_counter (text or blank) – Optional coupon accrual day count, also used for amortization; blank uses the index convention for floating coupons or Actual365 for fixed coupons

  • settings (text or blank) – Optional handle returned by QS.LOAN.SETTINGS, not a range or JSON; blank = no credit/prepayment/bounds, 40% recovery, zero fixing lag, NullCalendar and Unadjusted payments

  • coupon_periods (cell or range) – Optional payment counts per coupon segment, e.g. 12 for 12 monthly payments; align with coupon_rates; only the final count may be blank to fill maturity; counts must cover the whole loan

  • coupon_rates (cell or range) – Optional successive annual decimal coupons/spreads, e.g. 0.05 = 5% fixed or 0.01 = 100 bp spread; overrides scalar rate and market_index; align with coupon_periods and coupon_indices; blank uses scalar terms

  • coupon_indices (cell or range) – Optional projection index per coupon segment, e.g. EURIBOR12m; blank entry = fixed coupon, otherwise coupon_rates is a spread; omitted array makes ALL segments fixed, regardless of scalar market_index

  • prepayment_dates (cell or range) – Optional YYYY-MM-DD observation dates for dated annual CPRs; align with prepayment_cprs; do not combine with constant annual_cpr or refinancing settings

  • prepayment_cprs (cell or range) – Optional dated annual prepayment fractions in [0,1], e.g. 0.10 = 10% CPR per year, not per payment; align with prepayment_dates; no prepayment model when all prepayment inputs are blank

  • start_tenor (text or blank) – Optional start offset from the evaluation date, e.g. 0D or 1Y; leave start_date blank; built from the explicit construction context

  • tenor (text or blank) – Optional maturity/accrual tenor from resolved start, e.g. 5Y; for swaptions from expiry; leave the corresponding end/maturity date blank

Returns:

Concrete Loan contract handle with its principal schedule fixed at construction. #N/A means construction is pending. QS.EVALUATE prices lender receipts at the context date by default; QS.TRADE.CREATE sets side/date explicitly. Value excludes the original advance; FairRate(index) selects a zero-based coupon/spread segment.

Return Type:

text handle

Errors:

#VALUE! for invalid dates/principal, missing Balloon fraction, incomplete coupon segments, conflicting settings/prepayment models or invalid reset grids.

Formula

=QS.INSTRUMENT.LOAN(name, context, start_date, maturity_date, currency, notional, rate, market_index, repayment, payment_frequency, day_counter, settings, coupon_periods, coupon_rates, coupon_indices, prepayment_dates, prepayment_cprs, start_tenor, tenor)

Calculation

Runs on Excel’s main calculation thread.

Native Declaration

fn qs_instrument_loan (name : & str , context : & str , start_date : & str , maturity_date : & str , currency : & str , notional : f64 , rate : f64 , market_index : Option < String > , repayment : Option < String > , payment_frequency : Option < String > , day_counter : Option < String > , settings : Option < String > , coupon_periods : * const XLOPER12 , coupon_rates : * const XLOPER12 , coupon_indices : * const XLOPER12 , prepayment_dates : * const XLOPER12 , prepayment_cprs : * const XLOPER12 , start_tenor : Option < String > , tenor : Option < String > ,) -> Result < String , XllError >

Rust source