Loan

This page lists what you need to book and value a loan: the loan and callable_loan calls and their arguments, fixed and floating interest, amortisation, the borrower's credit, and the par quotes. A loan draws a principal on its start date, pays interest each period and repays the principal, at the end or in instalments.

Quick example

The example reads its quotes from the desk sheets; load them once and it runs as shown.

This lends ten million for five years at 5.00% on the USD close, reads the par rate and books the same loan from the borrower's side. Then it lends at SOFR plus 150bp and reads the par margin.

Rust

use chrono::NaiveDate;
use helixio_docs_sheets::{SOFR_CLOSE_DATE, USD_SOFR_CLOSE};
use helixrs::{AnyInstrument, CollateralSpec, Currency, DayCountFraction, Loan, MarketContext, QuoteSheet, Schedule};

type Outcome<T> = Result<T, Box<dyn std::error::Error>>;

const NOTIONAL: f64 = 10_000_000.0;

fn date((year, month, day): (i32, u32, u32)) -> NaiveDate {
    NaiveDate::from_ymd_opt(year, month, day).expect("a real calendar date")
}

/// A five-year fixed loan at `rate` on ACT/360, from the lender's side unless `borrower`.
fn fixed(schedule: &Schedule, usd: Currency, rate: f64, borrower: bool) -> AnyInstrument {
    AnyInstrument::Loan(Box::new(Loan::new(schedule, usd, NOTIONAL, rate, DayCountFraction::Act360, borrower)))
}

/// The lender's side of a five-year SOFR loan at `margin` over.
fn floating(schedule: &Schedule, usd: Currency, margin: f64) -> Outcome<AnyInstrument> {
    Ok(AnyInstrument::Loan(Box::new(Loan::floating(
        schedule,
        usd,
        NOTIONAL,
        "USD-SOFR",
        margin,
        DayCountFraction::Act360,
        false,
    )?)))
}

fn main() -> Outcome<()> {
    let usd: Currency = "USD".parse()?;
    let market = MarketContext::as_of(date(SOFR_CLOSE_DATE)).with_recipe_quotes(
        &CollateralSpec::Currency(usd),
        &QuoteSheet::from_rows(USD_SOFR_CLOSE.iter().copied())?,
    )?;
    // Five annual periods from spot.
    let schedule = Schedule::from_dates((0..6).map(|i| date((2026 + i, 10, 5))).collect())?;

    // Lend ten million for five years at 5.00%, read the rate that is fair, and
    // book the same loan from the borrower's side.
    let loan = fixed(&schedule, usd, 0.05, false);
    let par = loan.par_rate(&market)?;
    let at_par = fixed(&schedule, usd, par, false).npv(&market)?;
    let borrowed = fixed(&schedule, usd, 0.05, true);
    println!("npv         {:.2}", loan.npv(&market)?);
    println!("par rate    {par:.8}");
    println!("at par      {:.6}", at_par.abs());
    println!("borrower    {:.2}", borrowed.npv(&market)?);

    // A SOFR loan at 150bp over, and the par margin: the spread that makes it worth
    // nothing.
    let floater = floating(&schedule, usd, 0.015)?;
    let margin = floater.par_spread(&market)?;
    let at_margin = floating(&schedule, usd, margin)?.npv(&market)?;
    println!("npv         {:.2}", floater.npv(&market)?);
    println!("par margin  {margin:.8}");
    println!("at margin   {:.6}", at_margin.abs());

    Ok(())
}

Python

import datetime as dt

import helixio as hlx
from desk_sheets import SOFR_CLOSE_DATE, USD_SOFR_CLOSE

NOTIONAL = 10_000_000.0
market = hlx.MarketContext(SOFR_CLOSE_DATE).with_recipe_quotes("USD", USD_SOFR_CLOSE)
# Five annual periods from spot.
schedule = hlx.dates.Schedule.from_dates([dt.date(2026 + i, 10, 5) for i in range(6)])

def fixed(rate, borrower=False):
    """A five-year fixed loan at `rate` on ACT/360, from the lender's side by default."""
    return hlx.products.loan(
        schedule, "USD", notional=NOTIONAL, fixed_rate=rate, day_count="ACT/360", borrower=borrower
    )

def floating(margin):
    """The lender's side of a five-year SOFR loan at `margin` over."""
    return hlx.products.loan(
        schedule, "USD", notional=NOTIONAL, index="USD-SOFR", margin=margin, day_count="ACT/360", borrower=False
    )

# Lend ten million for five years at 5.00%, read the rate that is fair, and
# book the same loan from the borrower's side.
loan = fixed(0.05)
par = loan.par_rate(market)
at_par = fixed(par).npv(market)
borrowed = fixed(0.05, borrower=True)
print(f"npv         {loan.npv(market):.2f}")
print(f"par rate    {par:.8f}")
print(f"at par      {abs(at_par):.6f}")
print(f"borrower    {borrowed.npv(market):.2f}")

# A SOFR loan at 150bp over, and the par margin: the spread that makes it worth
# nothing.
floater = floating(0.015)
margin = floater.par_spread(market)
at_margin = floating(margin).npv(market)
print(f"npv         {floater.npv(market):.2f}")
print(f"par margin  {margin:.8f}")
print(f"at margin   {abs(at_margin):.6f}")

npv         128303.01
par rate    0.04709919
at par      0.000000
borrower    -128303.01
npv         663435.22
par margin  0.00000034
at margin   0.000000

5.00% is above the par rate, so the loan is worth something to the lender and exactly the opposite to the borrower. On a curve that both projects SOFR and discounts it, the index leg reprices to par, so the par margin is close to zero and the 150bp margin is the lender's value.

How it's priced

A loan of notional $N$ over periods $i = 1, \dots, n$ with accrual fractions $\tau_i$ and fixed rate $K$ is worth to the lender

V = -N\,P(t_0) + \sum_{i=1}^{n} N_{i-1} K \tau_i\,P(t_i) + \sum_{i=1}^{n} (N_{i-1} - N_i)\,P(t_i),

where $N_i$ is the principal outstanding after period $i$ , with $N_0 = N$ and $N_n = 0$ . A bullet loan has $N_i = N$ until maturity, and straight-line amortisation has $N_i = N(1 - i/n)$ . The borrower holds $-V$ . The par rate $K^\ast$ makes $V = 0$ ; on a floating loan, the par margin $m^\ast$ does.

Tagged to a borrower with survival $Q(t)$ and recovery $R$ , each servicing flow is weighted by $Q(t_i)$ , and a default between $t_{i-1}$ and $t_i$ recovers $R\,N_{i-1}$ . The drawdown stays risk-free. Why credit is what a lender is paid for is covered in how financing works.

API

products.loan(schedule, currency, *, notional, day_count, ...):

Argument	Type	Default	Meaning
`schedule`	`Schedule`	required	the period dates: drawn on the first, repaid by the last
`currency`	`str`	required	the loan's currency
`notional`	`float`	required	the principal drawn
`day_count`	`str` or `DayCountFraction`	required	how each period's interest accrues
`fixed_rate`	`float`	none	the fixed rate; give this or `index`
`index`	`str`	none	a term or overnight index code, such as `"USD-SOFR"`, to float the interest on
`margin`	`float`	`0.0`	the spread over `index`
`borrower`	`bool`	`True`	books the borrower's side; `False` books the lender's
`amortisation`	`str`	none: a bullet	`"Straight-Line"` repays `notional / n` at each period end
`issuer`	`str`	none	the borrower's credit curve key, such as `"ACME/SeniorUnSec/XR14/USD"`

products.callable_loan(loan, schedule, issuer=None, *, exercise="bermudan") adds rights to a loan:

Argument	Type	Default	Meaning
`loan`	`Instrument`	required	the loan the rights sit on
`schedule`	`list[tuple]`	required	`(date, price, "call" \| "put")`, with an optional fourth element, the price basis (`"clean"`, the default, or `"dirty"`): the borrower may prepay on a call, the lender demand repayment on a put, at `price` per 100 of the principal outstanding, plus accrued on a clean basis
`issuer`	`str`	none	the borrower's credit
`exercise`	`str`	`"bermudan"`	how the dates are exercised, as for a callable bond

In Rust a fixed loan is Loan::new(schedule, currency, notional, rate, day_count, borrower), a floating one Loan::floating(schedule, currency, notional, index, margin, day_count, borrower), then .amortising_straight_line() and .issued_by(key). The rights are CallableLoan::new(loan, rights) with Callability::call(date, price) and Callability::put.

Symbol	Meaning	Rust	Python
$N$ , $K$ , $\tau_i$	a fixed loan	`Loan::new`	`products.loan(.., fixed_rate=)`
$m$	a floating loan's margin	`Loan::floating`	`products.loan(.., index=, margin=)`
$N_i$	the straight-line outstanding	`Loan::amortising_straight_line`	`amortisation="Straight-Line"`
$Q$ , $R$	the borrower's credit	`Loan::issued_by` with `MarketContext::with_credit_curve`	`issuer=` with `MarketContext.with_credit_curve`
$K^\ast$	the par rate	`AnyInstrument::par_rate`	`Instrument.par_rate`
$m^\ast$	the par margin	`AnyInstrument::par_spread`	`Instrument.par_spread`
$V$	its value	`AnyInstrument::npv`	`Instrument.npv`

Defaults and limits

Side: a loan is the borrower's unless you pass borrower=False, because the borrower books a loan most often. The two sides hold opposite values.
Rate: give exactly one of fixed_rate and index.
Par quotes: par_rate belongs to a fixed loan and par_spread to a floating one; asking a loan for the other one is refused.
Credit: only the servicing is weighted by survival. The drawdown, which the lender pays, stays risk-free. The market needs the borrower's credit curve and a recovery rate under the issuer key, with_credit_curve(key, curve, recovery).
Rights: a callable loan is valued on the currency's Hull-White lattice, so the market needs with_hull_white(currency, mean_reversion, vol). A floating loan exercises on its interest dates only.
A deposit: booked from the lender's side, a loan is a term deposit, and with a put it's a puttable deposit.

More examples

The rows of the loan's cashflow table checked by hand, straight-line amortisation, the borrower's credit, and the borrower's and lender's rights. The rows and their present values add up to the loan's value; amortising lowers the value at an above-par rate; tagging the loan to its borrower lowers its value and raises its par rate; and the prepayment right costs the lender while a put adds to its value.