fuggers_py.rates

Public home for nominal interest-rate products, rate-index conventions, fixing storage, swap and FRA pricing, rates risk, futures delivery helpers, and rates option pricers.

Use one-layer imports from fuggers_py.rates for rates objects:

from fuggers_py.rates import (
    FixedFloatSwap,
    FixedLegSpec,
    FloatingLegSpec,
    IndexFixingStore,
    ScheduleDefinition,
    SwapPricer,
    SwapQuote,
    key_rate_risk,
    swap_dv01,
)

The public export source of truth is fuggers_py.rates.__all__, mirrored in specs/public_api_surface.json.

Core Rules

  • Rates, spreads, basis values, volatilities, and FX forward points are raw decimals. Decimal("0.05") means 5%, and Decimal("0.0001") means one basis point.

  • A basis point is one hundredth of 1%. In decimal form it is 0.0001.

  • Bond future prices and bond clean or dirty prices are percent of par. 112.5 means 112.5% of face value.

  • Notionals and present values are currency amounts.

  • PV means present value: today’s value of future cash flows.

  • A pay leg has a negative sign. A receive leg has a positive sign.

  • swap_dv01() and key_rate_risk() return positive values when the instrument gains PV after rates move down by one basis point.

  • Cross-currency swaps quote spot_fx_rate as receive-currency units per one pay-currency unit.

  • Constructors normalize many labels. For example, "usd" becomes Currency.USD, "quarterly" becomes a quarterly frequency, and "3M" becomes a Tenor.

  • Constructors also validate important contract rules, such as positive notionals and maturity dates after start dates.

Curve Inputs Used By Pricers

Rates pricers take an instrument plus a curve container. The container is not a special rates class. It only needs the fields the resolver reads:

  • discount_curve

  • forward_curve

  • collateral_curve

  • projection_curves

  • multicurve_environment

  • fx_forward_curve

  • optional fields used by other analytics, such as repo_curve and vol_surface

The tiny curve classes below are only for examples. Real code normally uses curves from fuggers_py.curves.

from dataclasses import dataclass, field
from decimal import Decimal
from math import exp

from fuggers_py import Date


@dataclass(frozen=True)
class ExampleCurveSpec:
    day_count: str = "ACT_365_FIXED"


@dataclass(frozen=True)
class FlatCurve:
    reference_date: Date
    rate: Decimal
    spec: ExampleCurveSpec = field(default_factory=ExampleCurveSpec)

    def discount_factor_at(self, tenor_years: float) -> Decimal:
        return Decimal(str(exp(-float(self.rate) * float(tenor_years))))

    def zero_rate_at(self, tenor_years: float) -> Decimal:
        return self.rate

    def rate_at(self, tenor_years: float) -> Decimal:
        return self.rate

    def forward_rate_between(self, start_tenor: float, end_tenor: float) -> Decimal:
        return self.rate


@dataclass(frozen=True)
class ExampleRatesCurves:
    discount_curve: FlatCurve
    forward_curve: FlatCurve
    government_curve: object | None = None
    benchmark_curve: object | None = None
    credit_curve: object | None = None
    repo_curve: object | None = None
    collateral_curve: object | None = None
    fx_forward_curve: object | None = None
    multicurve_environment: object | None = None
    projection_curves: dict[str, object] = field(default_factory=dict)
    inflation_curve: object | None = None
    inflation_curves: dict[str, object] = field(default_factory=dict)
    vol_surface: object | None = None


valuation_date = Date.from_ymd(2026, 1, 15)
curves = ExampleRatesCurves(
    discount_curve=FlatCurve(valuation_date, Decimal("0.035")),
    forward_curve=FlatCurve(valuation_date, Decimal("0.04")),
)

Schedules And Legs

These objects describe coupon periods and swap legs.

Export

What it represents

Behavior and useful methods

AccrualPeriod

One coupon accrual window.

Stores start_date, end_date, adjusted payment_date, and year_fraction. year_fraction is coerced to Decimal.

ScheduleDefinition

Rules used to build a date schedule.

Coerces frequency, calendar, and business-day convention labels. generate(start, end) returns a schedule. accrual_periods(start, end, day_count_convention=...) returns AccrualPeriod records.

FixedLegSpec

Fixed-rate cash-flow leg.

Coerces pay/receive, notional, fixed rate, currency, and day count. Notional must be positive. accrual_periods(start, end) builds fixed-leg periods.

FloatingLegSpec

Floating-rate cash-flow leg.

Coerces pay/receive, notional, spread, index tenor, currency, and day count. Index name is uppercased. Notional must be positive. rate_index() returns the normalized curve lookup key. accrual_periods(start, end) builds floating-leg periods.

 
from decimal import Decimal

from fuggers_py import Currency, Date, PayReceive
from fuggers_py.rates import FixedLegSpec, FloatingLegSpec, ScheduleDefinition

start = Date.from_ymd(2026, 1, 15)
end = Date.from_ymd(2027, 1, 15)

schedule = ScheduleDefinition(frequency="quarterly")
raw_schedule = schedule.generate(start, end)
periods = schedule.accrual_periods(start, end, day_count_convention="ACT_360")

fixed_leg = FixedLegSpec(
    pay_receive=PayReceive.PAY,
    notional=Decimal("1000000"),
    fixed_rate=Decimal("0.04"),
    currency=Currency.USD,
)
floating_leg = FloatingLegSpec(
    pay_receive="receive",
    notional=Decimal("1000000"),
    index_name="sofr",
    index_tenor="3M",
    spread=Decimal("0.0005"),
    currency="USD",
)

rate_index = floating_leg.rate_index()
fixed_period_count = len(fixed_leg.accrual_periods(start, end))
first_year_fraction = periods[0].year_fraction

Swap, FRA, Basis, And Asset-Swap Products

These objects store dated rates trades. They do not fetch curves or market data. They validate contract shape and expose period helpers used by pricers.

Export

What it represents

Behavior and useful methods

FixedFloatSwap

Fixed-rate leg against floating-rate leg in one currency.

Maturity must be after effective date. Legs must share currency and have opposite pay/receive directions. currency(), fixed_periods(), and floating_periods() expose derived data.

InterestRateSwap

Alias for FixedFloatSwap.

It is the same class, not a separate product type.

Ois

Overnight indexed swap.

Subclass of FixedFloatSwap with kind == "rates.swap.ois". It reuses fixed-float validation.

OvernightIndexedSwap

Alias for Ois.

It is the same class, not a separate product type.

Fra

Forward-rate agreement.

Stores start date, end date, notional, fixed rate, pay/receive direction, currency, day count, and optional index metadata. year_fraction() returns the accrual factor. rate_index() returns the normalized index when index_tenor is set.

ForwardRateAgreement

Alias for Fra.

It is the same class, not a separate product type.

BasisSwap

Same-currency floating leg against floating leg.

Legs must share currency. pay_leg must be marked pay, and receive_leg must be marked receive. currency(), pay_periods(), receive_periods(), and quoted_leg_spec() expose derived data.

SameCurrencyBasisSwap

Alias for BasisSwap.

It is the same class, not a separate product type.

CrossCurrencyBasisSwap

Floating leg in one currency against floating leg in another currency.

Legs must use different currencies. spot_fx_rate must be positive and is quoted as receive-currency per pay-currency. currency_pair(), pay_periods(), receive_periods(), and quoted_leg_spec() expose derived data.

AssetSwap

Fixed-rate bond plus floating leg.

Exactly one of market_clean_price or market_dirty_price is required. Prices are percent of par. currency(), maturity_date(), accrued_interest(), dirty_price(), clean_price(), and effective_floating_notional() expose derived values.

Swap Pricing And Risk

SwapPricer discounts the fixed and floating coupons. The fixed leg uses the discount curve. The floating leg uses the projection curve for its index and tenor. The result PV is in the swap currency.

from decimal import Decimal

from fuggers_py import Currency, Date, PayReceive
from fuggers_py.rates import (
    FixedFloatSwap,
    FixedLegSpec,
    FloatingLegSpec,
    SwapPricer,
    key_rate_risk,
    swap_dv01,
)

effective = Date.from_ymd(2026, 1, 15)
maturity = Date.from_ymd(2031, 1, 15)

swap = FixedFloatSwap(
    effective_date=effective,
    maturity_date=maturity,
    fixed_leg=FixedLegSpec(
        pay_receive=PayReceive.PAY,
        notional=Decimal("1000000"),
        fixed_rate=Decimal("0.04"),
        currency=Currency.USD,
    ),
    floating_leg=FloatingLegSpec(
        pay_receive=PayReceive.RECEIVE,
        notional=Decimal("1000000"),
        index_name="SOFR",
        index_tenor="3M",
        currency=Currency.USD,
    ),
)

pricer = SwapPricer()
result = pricer.price(swap, curves)

par_rate = pricer.par_rate(swap, curves)
present_value = pricer.pv(swap, curves)
dv01 = swap_dv01(swap, curves)
key_rates = key_rate_risk(swap, curves, tenor_grid=("2Y", "5Y", "10Y"))

summary = {
    "par_rate": result.par_rate,
    "pv": present_value,
    "fixed_leg_pv": result.fixed_leg_pv,
    "floating_leg_pv": result.floating_leg_pv,
    "dv01": dv01,
    "five_year_key_rate": key_rates["5Y"],
}

FRA Pricing

FraPricer projects the forward rate for the FRA accrual window and discounts the payoff to the FRA start date. The sign follows the FRA holder’s pay/receive direction.

from decimal import Decimal

from fuggers_py import Currency, Date, PayReceive
from fuggers_py.rates import Fra, FraPricer

fra = Fra(
    start_date=Date.from_ymd(2026, 4, 15),
    end_date=Date.from_ymd(2026, 7, 15),
    notional=Decimal("5000000"),
    fixed_rate=Decimal("0.039"),
    pay_receive=PayReceive.RECEIVE,
    currency=Currency.USD,
    index_name="SOFR",
    index_tenor="3M",
)

fra_pricer = FraPricer()
fra_result = fra_pricer.price(fra, curves)

fra_outputs = {
    "index": fra.rate_index(),
    "year_fraction": fra.year_fraction(),
    "forward_rate": fra_result.forward_rate,
    "pv": fra_result.present_value,
}

Basis And Cross-Currency Basis Pricing

BasisSwapPricer solves the spread for the quoted leg. CrossCurrencyBasisSwapPricer does the same, but it also converts cash flows into the selected valuation currency. If no explicit FX forward curve is supplied, it derives forward FX from the two discount curves and the swap spot FX rate.

from decimal import Decimal

from fuggers_py import Currency, Date, PayReceive
from fuggers_py.rates import (
    BasisSwap,
    BasisSwapPricer,
    CrossCurrencyBasisSwap,
    CrossCurrencyBasisSwapPricer,
    FloatingLegSpec,
)

basis = BasisSwap(
    effective_date=Date.from_ymd(2026, 1, 15),
    maturity_date=Date.from_ymd(2029, 1, 15),
    pay_leg=FloatingLegSpec(PayReceive.PAY, Decimal("1000000"), "SOFR", "1M"),
    receive_leg=FloatingLegSpec(PayReceive.RECEIVE, Decimal("1000000"), "SOFR", "3M"),
    quoted_leg=PayReceive.RECEIVE,
)

basis_pricer = BasisSwapPricer()
basis_result = basis_pricer.price(basis, curves)
basis_leg = basis.quoted_leg_spec()

xccy = CrossCurrencyBasisSwap(
    effective_date=Date.from_ymd(2026, 1, 15),
    maturity_date=Date.from_ymd(2029, 1, 15),
    pay_leg=FloatingLegSpec(PayReceive.PAY, Decimal("900000"), "EURIBOR", "3M", currency=Currency.EUR),
    receive_leg=FloatingLegSpec(PayReceive.RECEIVE, Decimal("1000000"), "SOFR", "3M", currency=Currency.USD),
    spot_fx_rate=Decimal("1.10"),
    quoted_leg=PayReceive.RECEIVE,
)

xccy_pricer = CrossCurrencyBasisSwapPricer()
xccy_result = xccy_pricer.price(xccy, curves, valuation_currency=Currency.USD)

basis_outputs = {
    "basis_par_spread": basis_result.par_spread,
    "quoted_leg_index": basis_leg.rate_index(),
    "xccy_pair": xccy.currency_pair(),
    "xccy_pv_usd": xccy_result.present_value,
    "principal_exchange_pv": xccy_result.principal_exchange_pv,
}

Asset-Swap Pricing

AssetSwapPricer uses the bond, the floating leg, the market bond price, and the resolved curves. It returns a par spread, PV, funding component, credit component, and a detailed breakdown. Funding and credit components are spreads, not currency amounts. Breakdown PV fields are currency amounts.

from decimal import Decimal

from fuggers_py import Currency, Date, Frequency, PayReceive
from fuggers_py.bonds import FixedBondBuilder
from fuggers_py.rates import AssetSwap, AssetSwapPricer, FloatingLegSpec

bond = (
    FixedBondBuilder.new()
    .with_issue_date(Date.from_ymd(2021, 1, 15))
    .with_maturity_date(Date.from_ymd(2031, 1, 15))
    .with_coupon_rate(Decimal("0.035"))
    .with_frequency(Frequency.SEMI_ANNUAL)
    .with_currency(Currency.USD)
    .with_notional(Decimal("100"))
    .build()
)

asset_swap = AssetSwap(
    bond=bond,
    settlement_date=Date.from_ymd(2026, 1, 15),
    floating_leg=FloatingLegSpec(PayReceive.RECEIVE, Decimal("1000000"), "SOFR", "3M"),
    quoted_spread=Decimal("0.0010"),
    market_clean_price=Decimal("99.25"),
)

asset_swap_pricer = AssetSwapPricer()
asset_swap_result = asset_swap_pricer.price(asset_swap, curves)

asset_swap_outputs = {
    "clean_price": asset_swap.clean_price(),
    "dirty_price": asset_swap.dirty_price(),
    "effective_floating_notional": asset_swap.effective_floating_notional(),
    "par_spread": asset_swap_result.par_spread,
    "pv": asset_swap_result.present_value,
    "funding_component": asset_swap_result.funding_component,
    "credit_component": asset_swap_result.credit_component,
}

Pricing And Risk Reference

Export

What it represents

Behavior and outputs

SwapPricer

Fixed-float swap pricer.

annuity() returns discounted fixed-leg accrual notional. fixed_leg_pv() and floating_leg_pv() return signed currency PVs. par_rate() returns the raw decimal fixed rate that sets PV to zero. pv() returns total signed PV. price() returns SwapPricingResult.

SwapPricingResult

Full swap pricing output.

Fields: par_rate, present_value, fixed_leg_pv, floating_leg_pv, and annuity. PV fields are currency amounts.

FraPricer

FRA pricer.

forward_rate() projects the FRA rate. pv() returns signed currency PV. price() returns FraPricingResult.

FraPricingResult

FRA pricing output.

Fields: forward_rate, present_value, year_fraction, and discount_factor.

BasisSwapPricer

Same-currency basis-swap pricer.

pay_leg_pv(), receive_leg_pv(), pv(), par_spread(), and price() use the quoted leg to solve the par spread.

BasisSwapPricingResult

Basis-swap pricing output.

Fields: par_spread, present_value, pay_leg_pv, receive_leg_pv, and spread_annuity.

CrossCurrencyBasisSwapPricer

Cross-currency basis-swap pricer.

pay_leg_pv(), receive_leg_pv(), principal_exchange_pv(), pv(), par_spread(), and price() report values in valuation_currency.

CrossCurrencyBasisSwapPricingResult

Cross-currency basis result.

Fields: valuation_currency, par_spread, present_value, leg PVs, principal_exchange_pv, and spread_annuity.

AssetSwapPricer

Asset-swap pricer.

par_spread(), funding_component(), credit_component(), pv(), and price() decompose a bond asset swap.

AssetSwapPricingResult

Asset-swap pricing output.

Fields: par_spread, present_value, funding_component, credit_component, and breakdown.

AssetSwapBreakdown

Detailed asset-swap calculation record.

Fields include clean and dirty price, accrued interest, quoted spread, annuity, spread PV factor, effective floating notional, reference rates, and funding/credit PV pieces.

swap_dv01

One-basis-point risk for fixed-float and OIS swaps.

Bumps relevant curves up and down by default 0.0001. Positive means PV rises when rates fall.

key_rate_risk

Tenor-by-tenor risk map.

Bumps each tenor node separately and returns dict[str, Decimal]. Keys are tenor labels such as "5Y". Positive means PV rises when that tenor is bumped lower.

Quotes, Reference Data, Fixings, And Indices

These objects store market quotes and reference-index fixings. They do not price trades by themselves.

Export

What it represents

Behavior and useful methods

SwapQuote

Swap market quote.

Stores rate, optional bid, ask, and mid. Decimal fields are coerced. Tenor and index labels are normalized. quoted_value(side="mid") returns a side value. for_side(side) returns a copy with rate set to that side, or None.

BasisSwapQuote

Basis-swap market quote.

Same side behavior as SwapQuote, but the main value field is basis.

BondFutureQuote

Government bond future quote.

Same side behavior as SwapQuote, but the main value field is price. Delivery month and CTD id are parsed when supplied.

FxForwardQuote

FX forward quote.

Stores a currency pair, forward rate, spot rate, and points. If forward_rate is missing and both spot_rate and points are present, it sets forward_rate = spot_rate + points. Properties: instrument_id and currency. Methods: quoted_value() and for_side().

SwapReferenceData

Static swap reference metadata.

Parses instrument_id; uppercases tenor, floating index, day count, and calendar labels.

ArrearConvention

Whether a coupon resets in advance or in arrears.

Values: IN_ADVANCE, IN_ARREARS.

ObservationShiftType

How overnight observation dates are shifted.

Values: NONE, LOOKBACK, OBSERVATION_SHIFT.

ShiftType

Alias for ObservationShiftType.

It is the same enum, not a separate type.

LookbackDays

Small record for a business-day lookback count.

int(value) returns the day count.

LockoutDays

Small record for a final-days lockout count.

int(value) returns the day count.

OvernightCompounding

How overnight fixings become one period rate.

Values: COMPOUNDED, SIMPLE, and AVERAGED. compounded_rate(), simple_average_rate(), required_fixing_dates(), and accrual_factor() compute period data.

PublicationTime

When a daily fixing is published.

Values: SAME_DAY, END_OF_DAY, NEXT_BUSINESS_DAY.

IndexConventions

Rules for a floating or overnight index.

Defaults to ACT/360, compounded overnight, same-day publication, and no shift. Properties: observation_shift_type and observation_shift_days.

IndexSource

Where a fixing came from.

Values: MANUAL, PUBLICATION, CURVE, and FALLBACK.

IndexFixing

One fixing for one index and date.

Uppercases index_name; coerces rate to Decimal.

IndexFixingStore

In-memory fixing store.

from_rates(), add_fixing(), add_fixings(), get_fixing(), get_rate(), has_fixing(), history(), get_range(), last_fixing_before(), indices(), count(), has_index(), clear(), and rate_for_period() manage and use fixings.

BondIndex

Reference-rate definition with optional fixing store.

fixing(date) returns a stored rate. rate_for_period(start, end, ...) asks the store for a period rate, using conventions, fallback rates, or a forward curve. str(index) returns the name.

 
from decimal import Decimal

from fuggers_py import Currency, Date
from fuggers_py.rates import (
    BondIndex,
    FxForwardQuote,
    IndexConventions,
    IndexFixingStore,
    OvernightCompounding,
    SwapQuote,
)

swap_quote = SwapQuote(
    instrument_id="USD-SOFR-5Y",
    rate=Decimal("0.0410"),
    bid=Decimal("0.0409"),
    ask=Decimal("0.0411"),
    tenor="5y",
    floating_index="sofr",
    currency=Currency.USD,
)
mid_rate = swap_quote.quoted_value()
bid_quote = swap_quote.for_side("bid")

fx_quote = FxForwardQuote(
    currency_pair="EUR/USD",
    spot_rate=Decimal("1.1000"),
    points=Decimal("0.0025"),
)
forward_rate = fx_quote.forward_rate
quote_currency = fx_quote.currency

store = IndexFixingStore.from_rates(
    "SOFR",
    {
        Date.from_ymd(2026, 1, 15): Decimal("0.0395"),
        Date.from_ymd(2026, 1, 16): Decimal("0.0396"),
    },
)
store.add_fixing("SOFR", Date.from_ymd(2026, 1, 20), Decimal("0.0397"))

conventions = IndexConventions(overnight_compounding=OvernightCompounding.COMPOUNDED)
period_rate = store.rate_for_period(
    "SOFR",
    Date.from_ymd(2026, 1, 15),
    Date.from_ymd(2026, 1, 22),
    conventions=conventions,
    fallback_rate=Decimal("0.0396"),
)
needed_fixings = OvernightCompounding.COMPOUNDED.required_fixing_dates(
    Date.from_ymd(2026, 1, 15),
    Date.from_ymd(2026, 1, 22),
    conventions=conventions,
)

sofr = BondIndex(name="SOFR", conventions=conventions, fixing_store=store)
latest_rate = sofr.fixing(Date.from_ymd(2026, 1, 20))

Government Bond Futures

These exports support deliverable government bond futures. Futures prices are percent of par. Invoice amounts are currency values.

Export

What it represents

Behavior and useful methods

GovernmentBondFuture

Listed government bond future contract.

Stores delivery date or delivery window, contract size, tick size, standard coupon, coupon frequency, and exchange. Requires a delivery anchor. from_reference(reference, delivery_date=...) builds from futures reference data. resolved_delivery_date() picks the best date anchor. tick_value() returns the currency value of one tick.

DeliverableBond

One bond that can be delivered into a futures contract.

Clean price is percent of par. Coupon rate is a raw decimal. from_reference(), reference(), rules(), to_bond(), accrued_interest(), dirty_price(), yield_to_maturity(), price_from_yield(), and price_with_yield_shift() expose bond and delivery calculations.

DeliverableBasket

Ordered set of deliverable bonds.

Requires at least one bond, unique ids, and one common currency. currency(), instrument_ids(), and get_deliverable() expose basket data.

conversion_factor

Selects the conversion factor for one deliverable.

Computes the theoretical factor and can prefer an exchange-published factor. Returns a result object with theoretical_conversion_factor, selected conversion_factor, and used_published_override. The result type is not exported by fuggers_py.rates.

invoice_amount

Converts futures price and conversion factor into delivery cash amount.

Formula: contract_size * (futures_price * conversion_factor + accrued_interest) / 100.

cheapest_to_deliver

Ranks the basket and selects the cheapest-to-deliver bond.

Lower gross basis wins. The returned result object includes the selected id, conversion factor, gross basis, delivery payoff, and ranked candidates. The result type is not exported by fuggers_py.rates.

 
from decimal import Decimal

from fuggers_py import Currency, Date, Frequency
from fuggers_py.rates import (
    DeliverableBasket,
    DeliverableBond,
    GovernmentBondFuture,
    cheapest_to_deliver,
    conversion_factor,
    invoice_amount,
)

future = GovernmentBondFuture(
    delivery_month="2026-06",
    instrument_id="USM6",
    currency=Currency.USD,
    contract_size=Decimal("100000"),
    tick_size=Decimal("0.015625"),
    standard_coupon_rate=Decimal("0.06"),
    coupon_frequency=Frequency.SEMI_ANNUAL,
    exchange="CBOT",
)

# Use this form when reference data gives you a contract reference object.
# reference_contract = GovernmentBondFuture.from_reference(reference)

bond_a = DeliverableBond(
    instrument_id="91282C-example-A",
    issue_date=Date.from_ymd(2021, 5, 15),
    maturity_date=Date.from_ymd(2031, 5, 15),
    coupon_rate=Decimal("0.0375"),
    clean_price=Decimal("101.25"),
    published_conversion_factor=Decimal("0.8750"),
)
bond_b = DeliverableBond(
    instrument_id="91282C-example-B",
    issue_date=Date.from_ymd(2020, 8, 15),
    maturity_date=Date.from_ymd(2030, 8, 15),
    coupon_rate=Decimal("0.0300"),
    clean_price=Decimal("98.75"),
    published_conversion_factor=Decimal("0.8420"),
)

basket = DeliverableBasket(as_of=Date.from_ymd(2026, 1, 15), deliverables=(bond_a, bond_b))

tick_value = future.tick_value()
selected_factor = conversion_factor(future, bond_a).conversion_factor
cash_due = invoice_amount(
    future.contract_size,
    futures_price=Decimal("112.50"),
    conversion_factor=selected_factor,
    accrued_interest=bond_a.accrued_interest(future.resolved_delivery_date()),
)
ctd = cheapest_to_deliver(future, basket, futures_price=Decimal("112.50"))
selected_bond = basket.get_deliverable(ctd.cheapest_to_deliver)

Rates Options

Rates options include swaptions, caps/floors, and options on government bond futures.

Export

What it represents

Behavior and useful methods

CapFloorType

Cap or floor label.

parse() accepts "CAP", "CAPLET_STRIP", "FLOOR", and "FLOORLET_STRIP". option_type() maps caps to calls and floors to puts.

CapFloor

Cap or floor on a floating leg.

Strike is a raw decimal and must be non-negative. Maturity must be after effective date. currency(), option_type(), and optionlet_periods() expose derived data.

Swaption

European option on a fixed-float swap.

Strike is a raw decimal and must be non-negative. Expiry must be on or before the underlying swap effective date. currency(), underlying, and option_type() expose derived data. Payer swaptions are calls on the swap rate; receiver swaptions are puts.

FuturesOption

Option on a government bond future.

Strike is in futures price points and must be positive. Expiry must be on or before delivery. currency(), underlying, and contract_multiplier() expose derived data.

Black76Pricer

Lognormal rates option pricer.

Assumes positive forwards and strikes. formula() prices a simple call or put. swaption(), cap_floor(), and futures_option() price products. Volatility is raw decimal lognormal volatility.

BachelierPricer

Normal rates option pricer.

Works with additive moves and can handle low or negative forwards. Methods mirror Black76Pricer. Volatility is raw decimal normal volatility.

HullWhiteOptionPricer

Lightweight Hull-White style proxy.

Converts model parameters into an approximate normal volatility, then delegates to BachelierPricer. The helper model class HullWhiteRateOptionModel is not exported by fuggers_py.rates; pass any object with normal_volatility(expiry_years=..., underlying_tenor_years=...), or import the model from the deeper options module when you intentionally leave the one-layer facade.

HasExpiry

Typing helper for objects with expiry_date.

Use in type hints when a function only needs an expiry date.

HasOptionType

Typing helper for option-like objects.

Use in type hints when a function only needs an option_type() method.

HasUnderlyingInstrument

Typing helper for option-like objects with underlying.

Use in type hints when a function only needs the underlying product.

Option formula and option pricing result records are returned by methods, but they are not exported from fuggers_py.rates. Use their attributes directly.

from dataclasses import dataclass
from decimal import Decimal

from fuggers_py import Date, OptionType, PayReceive
from fuggers_py.rates import (
    BachelierPricer,
    Black76Pricer,
    CapFloor,
    CapFloorType,
    FuturesOption,
    HasExpiry,
    HullWhiteOptionPricer,
    Swaption,
)

normal_result = BachelierPricer().formula(
    forward=Decimal("0.04"),
    strike=Decimal("0.0425"),
    volatility=Decimal("0.01"),
    expiry_years=Decimal("1.0"),
    option_type=OptionType.CALL,
)
lognormal_result = Black76Pricer().formula(
    forward=Decimal("0.04"),
    strike=Decimal("0.0425"),
    volatility=Decimal("0.20"),
    expiry_years=Decimal("1.0"),
    option_type=OptionType.CALL,
)

swaption = Swaption(
    expiry_date=Date.from_ymd(2026, 1, 15),
    underlying_swap=swap,
    strike=Decimal("0.04"),
    exercise_into=PayReceive.PAY,
)
swaption_price = BachelierPricer().swaption(
    swaption,
    curves,
    volatility=Decimal("0.01"),
)

cap = CapFloor(
    effective_date=Date.from_ymd(2026, 1, 15),
    maturity_date=Date.from_ymd(2028, 1, 15),
    floating_leg=swap.floating_leg,
    strike=Decimal("0.045"),
    cap_floor_type=CapFloorType.parse("caplet_strip"),
)
cap_price = BachelierPricer().cap_floor(cap, curves, volatility=Decimal("0.012"))

future_option = FuturesOption(
    expiry_date=Date.from_ymd(2026, 5, 15),
    underlying_future=future,
    strike=Decimal("112.0"),
    option_type=OptionType.CALL,
)
future_option_price = BachelierPricer().futures_option(
    future_option,
    futures_price=Decimal("112.50"),
    volatility=Decimal("1.25"),
)


@dataclass(frozen=True)
class FlatHullWhiteProxy:
    normal_vol: Decimal

    def normal_volatility(self, *, expiry_years: object, underlying_tenor_years: object) -> Decimal:
        return self.normal_vol


hull_white_price = HullWhiteOptionPricer(
    model=FlatHullWhiteProxy(Decimal("0.01")),
).swaption(swaption, curves)


def expires_on(option: HasExpiry) -> Date:
    return option.expiry_date


option_outputs = {
    "normal_formula_pv": normal_result.present_value,
    "black_formula_pv": lognormal_result.present_value,
    "swaption_pv": swaption_price.present_value,
    "cap_pv": cap_price.present_value,
    "futures_option_pv": future_option_price.present_value,
    "futures_option_multiplier": future_option.contract_multiplier(),
    "swaption_expiry": expires_on(swaption),
    "swaption_underlying": swaption.underlying,
}

Aliases

These exports are alternate names. They do not add behavior.

Alias

Same object as

InterestRateSwap

FixedFloatSwap

ForwardRateAgreement

Fra

SameCurrencyBasisSwap

BasisSwap

OvernightIndexedSwap

Ois

ShiftType

ObservationShiftType

Use the alias when it makes the calling code easier to read. Use the base name when you want the most direct link to the implementation.

Boundaries

  • Built curves live in fuggers_py.curves.

  • Bond instruments delivered into futures baskets live in fuggers_py.bonds.

  • Inflation swaps and CPI history live in fuggers_py.inflation.

  • Volatility surface records live in fuggers_py.vol_surfaces.

  • Low-level option formula result records and futures helper result records are returned by rates methods, but they are not exported from fuggers_py.rates.

First-layer public facade for nominal rates-domain objects.

class fuggers_py.rates.AccrualPeriod(start_date, end_date, payment_date, year_fraction)

One accrual period in a generated schedule.

Parameters:

  • start_date (Date)

  • end_date (Date)

  • payment_date (Date)

  • year_fraction (Decimal)

start_date

Unadjusted start date used for accrual calculation.

end_date

Unadjusted end date used for accrual calculation.

payment_date

Business-day-adjusted payment date.

year_fraction

Day-count accrual factor for the period, stored as a raw decimal.

class fuggers_py.rates.ArrearConvention(value)

Coupon reset timing relative to the accrual period.

class fuggers_py.rates.AssetSwap(bond, settlement_date, floating_leg, quoted_spread=Decimal('0'), asset_swap_type=ASWType.PAR_PAR, market_clean_price=None, market_dirty_price=None, repo_rate=None, general_collateral_rate=None, unsecured_overnight_rate=None, term_rate=None, compounding_convexity_adjustment=Decimal('0'), instrument_id=None)

Asset swap around a fixed-rate bond.

Parameters:

  • bond (FixedBond)

  • settlement_date (Date)

  • floating_leg (FloatingLegSpec)

  • quoted_spread (Decimal)

  • asset_swap_type (ASWType)

  • market_clean_price (Decimal | None)

  • market_dirty_price (Decimal | None)

  • repo_rate (Decimal | None)

  • general_collateral_rate (Decimal | None)

  • unsecured_overnight_rate (Decimal | None)

  • term_rate (Decimal | None)

  • compounding_convexity_adjustment (Decimal)

  • instrument_id (InstrumentId | None)

bond

Fixed-rate bond being swapped into floating-rate exposure.

settlement_date

Valuation settlement date used for accrued interest and dirty price.

floating_leg

Floating leg that replaces the bond coupon stream.

quoted_spread

Quoted spread as a raw decimal.

market_clean_price, market_dirty_price

Exactly one market price input in percent of par.

asset_swap_type

Asset-swap flavor controlling how the floating notional is scaled.

Notes

quoted_spread and the funding-rate fields are raw decimals. The market price inputs are quoted in percent of par.

currency()

Return the bond currency.

maturity_date()

Return the bond maturity date.

Return type:

Date

accrued_interest()

Return accrued interest at the settlement date.

Return type:

Decimal

dirty_price()

Return the market dirty price in percent of par.

Return type:

Decimal

clean_price()

Return the market clean price in percent of par.

Return type:

Decimal

effective_floating_notional()

Return the floating-leg notional used in PV calculations.

Return type:

Decimal

class fuggers_py.rates.AssetSwapBreakdown(market_clean_price, market_dirty_price, accrued_interest, quoted_spread, normalized_annuity, spread_pv_factor, effective_floating_notional, reference_rates, funding_component_pv, credit_component_pv)

Detailed asset-swap decomposition.

Parameters:

  • market_clean_price (Decimal)

  • market_dirty_price (Decimal)

  • accrued_interest (Decimal)

  • quoted_spread (Decimal)

  • normalized_annuity (Decimal)

  • spread_pv_factor (Decimal)

  • effective_floating_notional (Decimal)

  • reference_rates (ReferenceRateBreakdown)

  • funding_component_pv (Decimal)

  • credit_component_pv (Decimal)

market_clean_price, market_dirty_price

Bond market prices in percent of par.

accrued_interest

Accrued interest in currency units.

quoted_spread

Asset-swap spread as a raw decimal.

normalized_annuity

Discounted fixed-leg annuity used to convert spread to PV.

spread_pv_factor

Currency PV per unit spread.

effective_floating_notional

Floating-leg notional after any proceeds-style scaling.

reference_rates

Funding decomposition from the analytics spread helper.

funding_component_pv, credit_component_pv

PV contributions of the funding and credit components.

class fuggers_py.rates.AssetSwapPricer

Price asset swaps against the resolved curve set.

The pricer decomposes the asset-swap spread into par, funding, and credit components using the resolved projection and discount curves.

par_spread(asset_swap, curves)

Return the par asset-swap spread as a raw decimal.

The spread is the quoted fixed/floating spread that would zero the asset-swap PV under the resolved curves.

Return type:

Decimal

Parameters:
funding_component(asset_swap, curves)

Return the funding component of the par spread.

Return type:

Decimal

Parameters:
credit_component(asset_swap, curves)

Return the credit component of the par spread.

Return type:

Decimal

Parameters:
pv(asset_swap, curves)

Return the asset-swap present value.

Return type:

Decimal

Parameters:
price(asset_swap, curves)

Return the full asset-swap pricing result.

The result includes the par spread, PV, funding and credit spread components, and a detailed breakdown of the pricing inputs.

Return type:

AssetSwapPricingResult

Parameters:
class fuggers_py.rates.AssetSwapPricingResult(par_spread, present_value, funding_component, credit_component, breakdown)

Asset-swap pricing output.

Parameters:

  • par_spread (Decimal)

  • present_value (Decimal)

  • funding_component (Decimal)

  • credit_component (Decimal)

  • breakdown (AssetSwapBreakdown)

par_spread

Par asset-swap spread as a raw decimal.

present_value

Present value in the asset-swap currency.

funding_component

Funding spread component as a raw decimal.

credit_component

Credit spread component as a raw decimal.

breakdown

Detailed breakdown of the price decomposition.

class fuggers_py.rates.BachelierPricer

Bachelier pricer for rates options.

The pricer assumes additive forward dynamics and uses normal volatility quotes for swaption, cap/floor, and futures-option valuation.

formula(*, forward, strike, volatility, expiry_years, option_type, discount_factor=Decimal('1'))

Proxy to bachelier_formula().

The formula works in additive units and returns a currency-scaled present value plus greeks in the same scaling.

Return type:

OptionFormulaResult

Parameters:

  • forward (object)

  • strike (object)

  • volatility (object)

  • expiry_years (object)

  • option_type (OptionType | str)

  • discount_factor (object)

swaption(swaption, curves, *, volatility=None, vol_surface=None, valuation_date=None, swap_pricer=None)

Price a swaption using normal-volatility quotes.

The result is scaled by the swap annuity and uses either an explicit volatility quote or the matched surface quote.

Return type:

SwaptionPricingResult

Parameters:
cap_floor(cap_floor, curves, *, volatility=None, vol_surface=None, valuation_date=None)

Price a cap or floor by summing Bachelier optionlets.

Return type:

CapFloorPricingResult

Parameters:
futures_option(option, *, curves=None, futures_price=None, basket=None, delivery_option_model=None, volatility=None, vol_surface=None, valuation_date=None)

Price a futures option using the futures quote as the forward.

Return type:

FuturesOptionPricingResult

Parameters:
class fuggers_py.rates.BasisSwap(effective_date, maturity_date, pay_leg, receive_leg, quoted_leg=PayReceive.RECEIVE, instrument_id=None)

Same-currency floating-versus-floating basis swap.

Parameters:

  • effective_date (Date) – Contract start and end dates.

  • maturity_date (Date) – Contract start and end dates.

  • pay_leg (FloatingLegSpec) – Floating-leg specifications for the two swap legs.

  • receive_leg (FloatingLegSpec) – Floating-leg specifications for the two swap legs.

  • quoted_leg (PayReceive | str) – Leg whose spread is the market quote.

  • instrument_id (InstrumentId | None) – Optional stable identifier for the swap.

currency()

Return the common swap currency.

pay_periods()

Return the pay-leg accrual periods.

receive_periods()

Return the receive-leg accrual periods.

quoted_leg_spec()

Return the leg whose spread is quoted.

Return type:

FloatingLegSpec

class fuggers_py.rates.BasisSwapPricer

Price same-currency basis swaps.

The pricer discounts both floating legs in the swap currency and solves for the quoted-leg spread that zeroes the PV.

pay_leg_pv(swap, curves)

Return the discounted PV of the pay leg.

Return type:

Decimal

Parameters:
receive_leg_pv(swap, curves)

Return the discounted PV of the receive leg.

Return type:

Decimal

Parameters:
pv(swap, curves)

Return the total present value of the swap.

Return type:

Decimal

Parameters:
par_spread(swap, curves)

Return the par spread on the quoted leg as a raw decimal.

The quoted leg is whichever leg the contract designates as spread-quoted.

Return type:

Decimal

Parameters:
price(swap, curves)

Return the pricing result for the basis swap.

The result bundles the quoted-leg par spread, total PV, per-leg PVs, and the quoted-leg annuity.

Return type:

BasisSwapPricingResult

Parameters:
class fuggers_py.rates.BasisSwapPricingResult(par_spread, present_value, pay_leg_pv, receive_leg_pv, spread_annuity)

Basis-swap pricing output.

par_spread is a raw decimal quoted-leg spread and the PV fields are in currency units.

Parameters:

  • par_spread (Decimal)

  • present_value (Decimal)

  • pay_leg_pv (Decimal)

  • receive_leg_pv (Decimal)

  • spread_annuity (Decimal)

class fuggers_py.rates.BasisSwapQuote(instrument_id, basis=None, tenor=None, pay_index=None, receive_index=None, as_of=None, currency=None, source=None, bid=None, ask=None, mid=None)

Basis swap quote record with basis expressed as a raw decimal.

Parameters:

  • instrument_id (InstrumentId)

  • basis (Decimal | None)

  • tenor (str | None)

  • pay_index (str | None)

  • receive_index (str | None)

  • as_of (Date | None)

  • currency (Currency | None)

  • source (str | None)

  • bid (Decimal | None)

  • ask (Decimal | None)

  • mid (Decimal | None)

quoted_value(side=QuoteSide.MID)

Return the side-specific basis when present.

Return type:

Decimal | None

Parameters:

side (QuoteSide)

for_side(side)

Return a copy normalized to a different quote side.

Return type:

BasisSwapQuote’ | None

Parameters:

side (QuoteSide)

class fuggers_py.rates.Black76Pricer

Black-76 pricer for rates options.

The pricer assumes lognormal forward dynamics and uses the Black-76 closed form for swaps, caps/floors, and futures options.

formula(*, forward, strike, volatility, expiry_years, option_type, discount_factor=Decimal('1'))

Proxy to black76_formula().

The formula works on a strictly positive forward, strike, and discount factor, with lognormal volatility quoted in raw decimal form.

Return type:

OptionFormulaResult

Parameters:

  • forward (object)

  • strike (object)

  • volatility (object)

  • expiry_years (object)

  • option_type (OptionType | str)

  • discount_factor (object)

swaption(swaption, curves, *, volatility=None, vol_surface=None, valuation_date=None, swap_pricer=None)

Price a swaption using lognormal volatility.

The result is scaled by the swap annuity and uses either an explicit volatility quote or the matched surface quote.

Return type:

SwaptionPricingResult

Parameters:
cap_floor(cap_floor, curves, *, volatility=None, vol_surface=None, valuation_date=None)

Price a cap or floor by summing Black-76 optionlets.

Return type:

CapFloorPricingResult

Parameters:
futures_option(option, *, curves=None, futures_price=None, basket=None, delivery_option_model=None, volatility=None, vol_surface=None, valuation_date=None)

Price a futures option using the futures quote as the forward.

Return type:

FuturesOptionPricingResult

Parameters:
class fuggers_py.rates.BondFutureQuote(instrument_id, price=None, delivery_month=None, conversion_factor=None, implied_repo_rate=None, cheapest_to_deliver=None, as_of=None, currency=None, source=None, bid=None, ask=None, mid=None)

Bond future quote record.

Parameters:

  • instrument_id (InstrumentId)

  • price (Decimal | None)

  • delivery_month (YearMonth | None)

  • conversion_factor (Decimal | None)

  • implied_repo_rate (Decimal | None)

  • cheapest_to_deliver (InstrumentId | None)

  • as_of (Date | None)

  • currency (Currency | None)

  • source (str | None)

  • bid (Decimal | None)

  • ask (Decimal | None)

  • mid (Decimal | None)

quoted_value(side=QuoteSide.MID)

Return the side-specific futures price when present.

Return type:

Decimal | None

Parameters:

side (QuoteSide)

for_side(side)

Return a copy normalized to a different quote side.

Return type:

BondFutureQuote’ | None

Parameters:

side (QuoteSide)

class fuggers_py.rates.BondIndex(name, rate_index=None, currency=None, source=IndexSource.MANUAL, conventions=<factory>, fixing_store=None)

Reference-rate definition backed by an optional fixing store.

Parameters:
fixing(fixing_date, *, store=None)

Return the stored fixing for fixing_date when available.

Return type:

Decimal | None

Parameters:
rate_for_period(start_date, end_date, *, store=None, fallback_rate=None, forward_curve=None, as_of=None)

Return the rate applied to an accrual period.

Return type:

Decimal

Parameters:

  • start_date (Date)

  • end_date (Date)

  • store (IndexFixingStore | None)

  • fallback_rate (Decimal | None)

  • forward_curve (YieldCurve | object | None)

  • as_of (Date | None)

class fuggers_py.rates.CapFloor(effective_date, maturity_date, floating_leg, strike, cap_floor_type=CapFloorType.CAP, instrument_id=None)

Interest-rate cap or floor keyed to a floating leg specification.

Parameters:

  • effective_date (Date) – Optionlet window.

  • maturity_date (Date) – Optionlet window.

  • floating_leg (FloatingLegSpec) – Floating-leg specification the cap or floor is written on.

  • strike (Decimal) – Strike rate as a raw decimal.

  • cap_floor_type (CapFloorType | str) – Whether the contract is a cap or a floor.

  • instrument_id (InstrumentId | None) – Optional stable identifier for the contract.

currency()

Return the currency of the floating leg.

option_type()

Return the cap/floor as a call/put option type.

Return type:

OptionType

optionlet_periods()

Return the optionlet accrual periods for the cap/floor.

class fuggers_py.rates.CapFloorType(value)

Cap or floor product type.

classmethod parse(value)

Parse a cap/floor label or strip-style alias.

Return type:

CapFloorType

Parameters:

value ('CapFloorType' | str)

option_type()

Return the corresponding call/put option type.

Return type:

OptionType

class fuggers_py.rates.CrossCurrencyBasisSwap(effective_date, maturity_date, pay_leg, receive_leg, spot_fx_rate, quoted_leg=PayReceive.RECEIVE, initial_exchange=True, final_exchange=True, instrument_id=None)

Cross-currency floating-versus-floating basis swap.

Parameters:

  • effective_date (Date) – Contract start and end dates.

  • maturity_date (Date) – Contract start and end dates.

  • pay_leg (FloatingLegSpec) – Floating-leg specifications for the two currencies.

  • receive_leg (FloatingLegSpec) – Floating-leg specifications for the two currencies.

  • spot_fx_rate (Decimal) – Spot FX quote expressed as receive-currency units per one pay-currency unit.

  • quoted_leg (PayReceive | str) – Leg whose spread is the market quote.

  • initial_exchange (bool) – Whether principal is exchanged at the start and end of the swap.

  • final_exchange (bool) – Whether principal is exchanged at the start and end of the swap.

  • instrument_id (InstrumentId | None) – Optional stable identifier for the swap.

currency_pair()

Return the pay/receive currency pair.

Return type:

CurrencyPair

pay_periods()

Return the pay-leg accrual periods.

receive_periods()

Return the receive-leg accrual periods.

quoted_leg_spec()

Return the leg whose spread is quoted.

Return type:

FloatingLegSpec

class fuggers_py.rates.CrossCurrencyBasisSwapPricer

Price cross-currency basis swaps.

The pricer values each leg in a chosen valuation currency and converts cash flows using either explicit FX forwards or discount-curve parity.

pay_leg_pv(swap, curves, *, valuation_currency=None)

Return the discounted PV of the pay leg in the valuation currency.

Return type:

Decimal

Parameters:
receive_leg_pv(swap, curves, *, valuation_currency=None)

Return the discounted PV of the receive leg in the valuation currency.

Return type:

Decimal

Parameters:
principal_exchange_pv(swap, curves, *, valuation_currency=None)

Return the PV of the principal exchanges.

Return type:

Decimal

Parameters:
pv(swap, curves, *, valuation_currency=None)

Return the total present value in the valuation currency.

Return type:

Decimal

Parameters:
par_spread(swap, curves, *, valuation_currency=None)

Return the par spread on the quoted leg as a raw decimal.

The spread is solved so that the total PV in the valuation currency is zero.

Return type:

Decimal

Parameters:
price(swap, curves, *, valuation_currency=None)

Return the full cross-currency basis-swap pricing result.

The result includes the chosen valuation currency, total PV, leg PVs, the principal-exchange PV, and the quoted-leg annuity.

Return type:

CrossCurrencyBasisSwapPricingResult

Parameters:
class fuggers_py.rates.CrossCurrencyBasisSwapPricingResult(valuation_currency, par_spread, present_value, pay_leg_pv, receive_leg_pv, principal_exchange_pv, spread_annuity)

Cross-currency basis-swap pricing output.

All PV fields are expressed in valuation_currency and the quoted spread is a raw decimal.

Parameters:

  • valuation_currency (Currency)

  • par_spread (Decimal)

  • present_value (Decimal)

  • pay_leg_pv (Decimal)

  • receive_leg_pv (Decimal)

  • principal_exchange_pv (Decimal)

  • spread_annuity (Decimal)

class fuggers_py.rates.DeliverableBasket(as_of, deliverables=<factory>)

Ordered deliverable basket for a government bond futures contract.

Parameters:
currency()

Return the common basket currency.

Return type:

Currency

instrument_ids()

Return basket instrument identifiers in deterministic order.

Return type:

tuple[InstrumentId, ...]

get_deliverable(instrument_id)

Return the deliverable matching instrument_id.

Return type:

DeliverableBond

Parameters:

instrument_id (InstrumentId | str)

class fuggers_py.rates.DeliverableBond(instrument_id, issue_date, maturity_date, coupon_rate, clean_price, currency=Currency.<bound method Currency.name of <Currency.USD: 'USD'>>, frequency=Frequency.SEMI_ANNUAL, notional=Decimal('100'), yield_rules=None, published_conversion_factor=None)

A bond deliverable into a government bond futures contract.

Parameters:

  • clean_price (Decimal) – Clean price quoted in percent of par.

  • coupon_rate (Decimal) – Coupon rate as a raw decimal.

  • notional (Decimal) – Bond face amount in currency units.

  • published_conversion_factor (Decimal | None) – Optional exchange-published conversion factor, if available.

  • instrument_id (InstrumentId)

  • issue_date (Date)

  • maturity_date (Date)

  • currency (Currency | str)

  • frequency (Frequency | str)

  • yield_rules (YieldCalculationRules | None)

Notes

clean_price is quoted in percent of par. Yield calculations reuse the bond pricer rules aligned to the bond’s coupon frequency.

classmethod from_reference(reference, *, clean_price)

Build a deliverable bond from reference data and a live clean price.

Return type:

DeliverableBond

Parameters:

  • reference (DeliverableBondReference)

  • clean_price (object)

reference()

Return the reference-data view of the bond.

Return type:

DeliverableBondReference

rules()

Return yield rules aligned to the bond coupon frequency.

Return type:

YieldCalculationRules

to_bond()

Build the corresponding fixed-coupon bond instrument.

accrued_interest(settlement_date)

Return accrued interest at settlement_date in currency units.

Return type:

Decimal

Parameters:

settlement_date (Date)

dirty_price(settlement_date)

Return dirty price as clean price plus accrued interest.

Return type:

Decimal

Parameters:

settlement_date (Date)

yield_to_maturity(settlement_date, *, pricer=None)

Return the bond yield as a raw decimal.

Return type:

Decimal

Parameters:

  • settlement_date (Date)

  • pricer (BondPricer | None)

price_from_yield(yield_rate, settlement_date, *, pricer=None)

Return the clean price implied by a raw-decimal yield.

Return type:

Decimal

Parameters:

  • yield_rate (object)

  • settlement_date (Date)

  • pricer (BondPricer | None)

price_with_yield_shift(settlement_date, *, base_settlement_date, yield_shift_bps=Decimal('0'), pricer=None)

Return the clean price after shifting the yield by basis points.

Return type:

Decimal

Parameters:

  • settlement_date (Date)

  • base_settlement_date (Date)

  • yield_shift_bps (object)

  • pricer (BondPricer | None)

class fuggers_py.rates.FixedFloatSwap(effective_date, maturity_date, fixed_leg, floating_leg, instrument_id=None)

Plain fixed-for-floating interest-rate swap.

Parameters:

  • effective_date (Date) – Contract start and end dates. maturity_date must be after effective_date.

  • maturity_date (Date) – Contract start and end dates. maturity_date must be after effective_date.

  • fixed_leg (FixedLegSpec) – Leg specifications sharing the same currency and opposite pay/receive directions.

  • floating_leg (FloatingLegSpec) – Leg specifications sharing the same currency and opposite pay/receive directions.

  • instrument_id (InstrumentId | None) – Optional stable identifier for the swap.

currency()

Return the common swap currency.

fixed_periods()

Return the fixed-leg accrual periods.

floating_periods()

Return the floating-leg accrual periods.

class fuggers_py.rates.FixedLegSpec(pay_receive, notional, fixed_rate, currency=Currency.<bound method Currency.name of <Currency.USD: 'USD'>>, day_count_convention=DayCountConvention.<bound method DayCountConvention.name of <DayCountConvention.ACT_365_FIXED: 'ACT_365_FIXED'>>, schedule=<factory>)

Fixed-rate cash-flow leg.

Parameters:

  • pay_receive (PayReceive | str) – Direction of the leg cash flows.

  • notional (Decimal) – Contract notional in currency units.

  • fixed_rate (Decimal) – Coupon rate as a raw decimal.

  • currency (Currency | str) – Currency of the cash flows.

  • day_count_convention (DayCountConvention | str) – Day-count rule used to compute accrual factors.

  • schedule (ScheduleDefinition) – Schedule definition used to generate coupon dates.

accrual_periods(start_date, end_date)

Return the fixed-leg accrual periods.

Return type:

tuple[AccrualPeriod, ...]

Parameters:

  • start_date (Date)

  • end_date (Date)

class fuggers_py.rates.FloatingLegSpec(pay_receive, notional, index_name, index_tenor, spread=Decimal('0'), currency=Currency.<bound method Currency.name of <Currency.USD: 'USD'>>, day_count_convention=DayCountConvention.<bound method DayCountConvention.name of <DayCountConvention.ACT_360: 'ACT_360'>>, schedule=<factory>)

Floating-rate cash-flow leg.

The floating coupon is forward + spread where both inputs are raw decimals. The leg is also normalized to a rate index for curve resolution.

Parameters:

  • pay_receive (PayReceive | str)

  • notional (Decimal)

  • index_name (str)

  • index_tenor (Tenor | str)

  • spread (Decimal)

  • currency (Currency | str)

  • day_count_convention (DayCountConvention | str)

  • schedule (ScheduleDefinition)

rate_index()

Return the normalized rate index for the leg.

Return type:

RateIndex

accrual_periods(start_date, end_date)

Return the floating-leg accrual periods.

Return type:

tuple[AccrualPeriod, ...]

Parameters:

  • start_date (Date)

  • end_date (Date)

fuggers_py.rates.ForwardRateAgreement

alias of Fra

class fuggers_py.rates.Fra(start_date, end_date, notional, fixed_rate, pay_receive=PayReceive.RECEIVE, currency=Currency.<bound method Currency.name of <Currency.USD: 'USD'>>, day_count_convention=DayCountConvention.<bound method DayCountConvention.name of <DayCountConvention.ACT_360: 'ACT_360'>>, index_name='LIBOR', index_tenor=None, instrument_id=None)

Forward-rate agreement.

Parameters:

  • start_date (Date)

  • end_date (Date)

  • notional (Decimal)

  • fixed_rate (Decimal)

  • pay_receive (PayReceive | str)

  • currency (Currency | str)

  • day_count_convention (DayCountConvention | str)

  • index_name (str)

  • index_tenor (Tenor | str | None)

  • instrument_id (InstrumentId | None)

start_date, end_date

FRA accrual window.

fixed_rate

Contract strike rate as a raw decimal.

pay_receive

Direction of the payoff relative to the holder.

index_name, index_tenor

Optional projection index metadata used for curve lookup.

Notes

fixed_rate and the premium conventions are raw decimals. The pay_receive flag describes the holder’s payoff direction.

year_fraction()

Return the accrual factor between start_date and end_date.

Return type:

Decimal

rate_index()

Return the normalized rate index, if one is defined.

Return type:

RateIndex | None

class fuggers_py.rates.FraPricer

Price forward-rate agreements against resolved curves.

forward_rate(fra, curves)

Return the projected forward rate for the FRA accrual window.

Return type:

Decimal

Parameters:

  • fra (Fra)

  • curves (object)

pv(fra, curves)

Return the FRA present value.

Return type:

Decimal

Parameters:

  • fra (Fra)

  • curves (object)

price(fra, curves)

Return the full FRA pricing result.

Return type:

FraPricingResult

Parameters:

  • fra (Fra)

  • curves (object)

class fuggers_py.rates.FraPricingResult(forward_rate, present_value, year_fraction, discount_factor)

FRA pricing output.

Parameters:

  • forward_rate (Decimal)

  • present_value (Decimal)

  • year_fraction (Decimal)

  • discount_factor (Decimal)

class fuggers_py.rates.FuturesOption(expiry_date, underlying_future, strike, option_type=OptionType.CALL, instrument_id=None)

Option on a government bond futures contract.

Parameters:

  • expiry_date (Date) – Option expiry date.

  • underlying_future (GovernmentBondFuture) – Government bond futures contract referenced by the option.

  • strike (Decimal) – Futures price strike in price points.

  • option_type (OptionType | str) – Call or put direction of the option.

  • instrument_id (InstrumentId | None) – Optional stable identifier for the option.

currency()

Return the underlying futures currency.

property underlying: GovernmentBondFuture

Return the underlying futures contract.

contract_multiplier()

Return the currency value of one futures price point.

Return type:

Decimal

class fuggers_py.rates.FxForwardQuote(currency_pair, forward_rate=None, points=None, spot_rate=None, as_of=None, source=None, bid=None, ask=None, mid=None)

FX forward quote record.

Parameters:

  • currency_pair (CurrencyPair)

  • forward_rate (Decimal | None)

  • points (Decimal | None)

  • spot_rate (Decimal | None)

  • as_of (Date | None)

  • source (str | None)

  • bid (Decimal | None)

  • ask (Decimal | None)

  • mid (Decimal | None)

property instrument_id: InstrumentId

Expose the currency pair through the common instrument-id surface.

property currency: Currency

Return the quote currency for the outright forward rate.

quoted_value(side=QuoteSide.MID)

Return the side-specific forward rate when present.

Return type:

Decimal | None

Parameters:

side (QuoteSide)

for_side(side)

Return a copy normalized to a different quote side.

Return type:

FxForwardQuote’ | None

Parameters:

side (QuoteSide)

class fuggers_py.rates.GovernmentBondFuture(delivery_date=None, first_delivery_date=None, last_delivery_date=None, instrument_id=None, currency=Currency.<bound method Currency.name of <Currency.USD: 'USD'>>, delivery_month=None, contract_size=Decimal('100000'), tick_size=Decimal('0.015625'), standard_coupon_rate=Decimal('0.06'), coupon_frequency=Frequency.SEMI_ANNUAL, exchange=None)

Government bond futures contract metadata.

Parameters:

  • delivery_date (Date | None) – Delivery anchors for the contract. At least one delivery anchor or a delivery_month must be supplied.

  • first_delivery_date (Date | None) – Delivery anchors for the contract. At least one delivery anchor or a delivery_month must be supplied.

  • last_delivery_date (Date | None) – Delivery anchors for the contract. At least one delivery anchor or a delivery_month must be supplied.

  • instrument_id (InstrumentId | None) – Stable instrument identifier for the listed contract.

  • currency (Currency | str) – Contract currency.

  • delivery_month (YearMonth | str | None) – Delivery month if the exact first/last delivery dates are not known.

  • contract_size (Decimal) – Currency notional per contract.

  • tick_size (Decimal) – Minimum price increment in percent of par.

  • standard_coupon_rate (Decimal) – Standardized coupon rate used for conversion-factor calculations as a raw decimal, for example Decimal("0.06") for 6%.

  • coupon_frequency (Frequency | str) – Coupon frequency of the standardized deliverable bond.

  • exchange (str | None) – Optional exchange code normalized to upper case.

Notes

Delivery anchors are intentionally flexible because the reference data may provide either a single delivery date, a delivery window, or only a delivery month. Contract prices remain quoted in percent of par.

classmethod from_reference(reference, *, delivery_date=None)

Build a contract from reference data.

Return type:

GovernmentBondFuture

Parameters:

  • reference (BondFutureReferenceData)

  • delivery_date (Date | None)

resolved_delivery_date()

Return the best available delivery date anchor for the contract.

Return type:

Date

tick_value()

Return the currency value of one tick.

Return type:

Decimal

class fuggers_py.rates.HasExpiry(*args, **kwargs)

Capability for objects exposing an option expiry date.

property expiry_date: Date

Return the expiry date.

class fuggers_py.rates.HasOptionType(*args, **kwargs)

Capability for option-like instruments exposing call/put direction.

option_type()

Return the option type label.

Return type:

str

class fuggers_py.rates.HasUnderlyingInstrument(*args, **kwargs)

Capability for objects exposing an underlying contract object.

property underlying: object

Return the underlying contract object.

class fuggers_py.rates.HullWhiteOptionPricer(model, bachelier_pricer=BachelierPricer())

Hull-White style pricer that delegates to the Bachelier engine.

The class converts Hull-White proxy parameters into a normal-volatility quote and then prices through the Bachelier pricer.

Parameters:
swaption(swaption, curves, *, valuation_date=None, swap_pricer=None)

Price a swaption using the Hull-White normal-volatility proxy.

Return type:

SwaptionPricingResult

Parameters:
cap_floor(cap_floor, curves, *, valuation_date=None)

Price a cap or floor using the Hull-White normal-volatility proxy.

Return type:

CapFloorPricingResult

Parameters:
class fuggers_py.rates.IndexConventions(day_count=DayCountConvention.<bound method DayCountConvention.name of <DayCountConvention.ACT_360: 'ACT_360'>>, arrear_convention=ArrearConvention.IN_ARREARS, overnight_compounding=None, publication_time=None, publication_lag_days=0, shift_type=ObservationShiftType.NONE, lookback_days=0, lockout_days=0, rate_cutoff_days=0)

Conventions for floating-rate and overnight reference indices.

Parameters:
property observation_shift_type: ObservationShiftType

Return the configured observation-shift mode.

property observation_shift_days: int

Return the effective observation shift in business days.

class fuggers_py.rates.IndexFixing(index_name, fixing_date, rate, publication_date=None, source=IndexSource.MANUAL)

Stored fixing for a reference index on a specific fixing date.

Parameters:

  • index_name (str)

  • fixing_date (Date)

  • rate (Decimal)

  • publication_date (Date | None)

  • source (IndexSource)

class fuggers_py.rates.IndexFixingStore(_fixings=<factory>)

In-memory storage for historical reference-index fixings.

Parameters:

_fixings (dict[str, dict[Date, IndexFixing]])

classmethod from_rates(index_name, mapping_or_sequence)

Build a store from raw date-to-rate pairs for one index.

Return type:

IndexFixingStore

Parameters:

  • index_name (str)

  • mapping_or_sequence (Mapping[Date, object] | Sequence[tuple[Date, object]])

add_fixing(index_name, fixing_date, rate, *, publication_date=None, source=IndexSource.MANUAL)

Insert or overwrite a single fixing.

Return type:

IndexFixingStore

Parameters:

  • index_name (str)

  • fixing_date (Date)

  • rate (object)

  • publication_date (Date | None)

  • source (IndexSource)

add_fixings(fixings)

Insert multiple fixings.

Return type:

IndexFixingStore

Parameters:

fixings (Iterable[IndexFixing])

get_fixing(index_name, fixing_date)

Return the fixing record for index_name and fixing_date.

Return type:

IndexFixing | None

Parameters:

  • index_name (str)

  • fixing_date (Date)

get_rate(index_name, fixing_date)

Return the raw fixing rate for index_name and fixing_date.

Return type:

Decimal | None

Parameters:

  • index_name (str)

  • fixing_date (Date)

history(index_name, *, start=None, end=None)

Return stored fixings for index_name ordered by fixing date.

Return type:

list[IndexFixing]

Parameters:

  • index_name (str)

  • start (Date | None)

  • end (Date | None)

get_range(index_name, start_date, end_date)

Return fixings between start_date and end_date inclusive.

Return type:

list[IndexFixing]

Parameters:

  • index_name (str)

  • start_date (Date)

  • end_date (Date)

last_fixing_before(index_name, date)

Return the latest stored fixing strictly before date.

Return type:

IndexFixing | None

Parameters:

  • index_name (str)

  • date (Date)

indices()

Return normalized index names held by the store.

Return type:

tuple[str, ...]

count(index=None)

Return the number of stored fixings, optionally for one index.

Return type:

int

Parameters:

index (str | None)

has_index(index_name)

Return whether the store contains any fixings for index_name.

Return type:

bool

Parameters:

index_name (str)

clear()

Remove all stored fixings.

Return type:

None

rate_for_period(index_name, start_date, end_date, *, conventions, fallback_rate=None, calendar=None, forward_curve=None, as_of=None)

Compute the period rate implied by stored overnight fixings.

Return type:

Decimal

Parameters:

  • index_name (str)

  • start_date (Date)

  • end_date (Date)

  • conventions (IndexConventions)

  • fallback_rate (Decimal | None)

  • calendar (Calendar | None)

  • forward_curve (YieldCurve | object | None)

  • as_of (Date | None)

class fuggers_py.rates.IndexSource(value)

Origin of an index fixing used in coupon calculations.

fuggers_py.rates.InterestRateSwap

alias of FixedFloatSwap

class fuggers_py.rates.LockoutDays(days=0)

Final business days that reuse an earlier overnight fixing.

Parameters:

days (int)

class fuggers_py.rates.LookbackDays(days=0)

Business-day lookback applied to overnight observations.

Parameters:

days (int)

class fuggers_py.rates.ObservationShiftType(value)

Observation-date adjustment applied to overnight fixings.

class fuggers_py.rates.Ois(effective_date, maturity_date, fixed_leg, floating_leg, instrument_id=None)

Overnight indexed swap.

Parameters:

  • effective_date (Date)

  • maturity_date (Date)

  • fixed_leg (FixedLegSpec)

  • floating_leg (FloatingLegSpec)

  • instrument_id (InstrumentId | None)

class fuggers_py.rates.OvernightCompounding(value)

Overnight coupon aggregation method for floating-rate instruments.

compounded_rate(start_date, end_date, *, index_name, fixing_store, conventions, calendar=None, fallback_rate=None, forward_curve=None, as_of=None)

Return the compounded overnight rate over an accrual window.

Return type:

Decimal

Parameters:

  • start_date (Date)

  • end_date (Date)

  • index_name (str)

  • fixing_store (IndexFixingStore)

  • conventions (IndexConventions)

  • calendar (Calendar | None)

  • fallback_rate (Decimal | None)

  • forward_curve (object | None)

  • as_of (Date | None)

simple_average_rate(start_date, end_date, *, index_name, fixing_store, conventions, calendar=None, fallback_rate=None, forward_curve=None, as_of=None)

Return the simple weighted-average overnight rate over a period.

Return type:

Decimal

Parameters:

  • start_date (Date)

  • end_date (Date)

  • index_name (str)

  • fixing_store (IndexFixingStore)

  • conventions (IndexConventions)

  • calendar (Calendar | None)

  • fallback_rate (Decimal | None)

  • forward_curve (object | None)

  • as_of (Date | None)

required_fixing_dates(start_date, end_date, *, conventions, calendar=None)

Return the fixing dates needed to value the accrual window.

Return type:

list[Date]

Parameters:

  • start_date (Date)

  • end_date (Date)

  • conventions (IndexConventions)

  • calendar (Calendar | None)

accrual_factor(start_date, end_date, *, conventions)

Return the accrual year fraction for the coupon window.

Return type:

Decimal

Parameters:
fuggers_py.rates.OvernightIndexedSwap

alias of Ois

class fuggers_py.rates.PublicationTime(value)

Publication timing for daily overnight fixings.

fuggers_py.rates.SameCurrencyBasisSwap

alias of BasisSwap

class fuggers_py.rates.ScheduleDefinition(frequency=Frequency.QUARTERLY, calendar=CalendarId(value='WEEKEND'), business_day_convention=BusinessDayConvention.MODIFIED_FOLLOWING, end_of_month=True, stub_rules=<factory>)

Schedule-construction rules for rates legs.

The definition wraps frequency, calendar, business-day convention, and stub handling so leg objects can generate accrual periods consistently.

Parameters:

  • frequency (Frequency | str)

  • calendar (CalendarId | str)

  • business_day_convention (BusinessDayConvention | str)

  • end_of_month (bool)

  • stub_rules (StubPeriodRules)

generate(start_date, end_date)

Generate the adjusted schedule between two dates.

Return type:

Schedule

Parameters:

  • start_date (Date)

  • end_date (Date)

accrual_periods(start_date, end_date, *, day_count_convention)

Return accrual periods for the schedule.

The accrual fraction is measured on the unadjusted schedule dates, while the payment date is the adjusted business-day date from the generated schedule.

Return type:

tuple[AccrualPeriod, ...]

Parameters:

  • start_date (Date)

  • end_date (Date)

  • day_count_convention (DayCountConvention | str)

fuggers_py.rates.ShiftType

alias of ObservationShiftType

class fuggers_py.rates.SwapPricer

Price fixed-for-floating interest-rate swaps.

The pricer discounts fixed and floating cash flows in the swap currency using the resolved discount and projection curves.

annuity(swap, curves)

Return the discounted fixed-leg annuity.

The annuity is the discounted sum of fixed-leg accrual factors times notional, in swap-currency units.

Return type:

Decimal

Parameters:
fixed_leg_pv(swap, curves)

Return the discounted PV of the fixed leg.

The sign follows the leg’s pay/receive direction.

Return type:

Decimal

Parameters:
floating_leg_pv(swap, curves)

Return the discounted PV of the floating leg.

The floating coupon uses the resolved projection curve for the leg’s index and tenor, plus the leg spread if present.

Return type:

Decimal

Parameters:
par_rate(swap, curves)

Return the par swap rate as a raw decimal.

The rate is the fixed coupon that sets the swap PV to zero.

Return type:

Decimal

Parameters:
pv(swap, curves)

Return the total present value of the swap.

The result is the sum of the signed fixed and floating leg PVs in swap currency.

Return type:

Decimal

Parameters:
price(swap, curves)

Return the full swap pricing result.

The result includes the par rate, total PV, leg PVs, and the fixed-leg annuity used to convert between rate and value.

Return type:

SwapPricingResult

Parameters:
class fuggers_py.rates.SwapPricingResult(par_rate, present_value, fixed_leg_pv, floating_leg_pv, annuity)

Swap pricing output.

par_rate is a raw decimal fixed rate that zeros the swap PV. All PV values are in the swap currency.

Parameters:

  • par_rate (Decimal)

  • present_value (Decimal)

  • fixed_leg_pv (Decimal)

  • floating_leg_pv (Decimal)

  • annuity (Decimal)

class fuggers_py.rates.SwapQuote(instrument_id, rate=None, tenor=None, floating_index=None, fixed_frequency=None, as_of=None, currency=None, source=None, bid=None, ask=None, mid=None)

Swap quote record with rate expressed as a raw decimal.

Parameters:

  • instrument_id (InstrumentId)

  • rate (Decimal | None)

  • tenor (str | None)

  • floating_index (str | None)

  • fixed_frequency (str | None)

  • as_of (Date | None)

  • currency (Currency | None)

  • source (str | None)

  • bid (Decimal | None)

  • ask (Decimal | None)

  • mid (Decimal | None)

quoted_value(side=QuoteSide.MID)

Return the side-specific swap rate when present.

Return type:

Decimal | None

Parameters:

side (QuoteSide)

for_side(side)

Return a copy normalized to a different quote side.

Return type:

SwapQuote’ | None

Parameters:

side (QuoteSide)

class fuggers_py.rates.SwapReferenceData(instrument_id, currency=Currency.<bound method Currency.name of <Currency.USD: 'USD'>>, tenor=None, floating_index=None, fixed_frequency=None, floating_frequency=None, day_count=None, calendar=None)

Swap reference metadata with normalized role descriptors.

Parameters:

  • instrument_id (InstrumentId)

  • currency (Currency)

  • tenor (str | None)

  • floating_index (str | None)

  • fixed_frequency (Frequency | None)

  • floating_frequency (Frequency | None)

  • day_count (str | None)

  • calendar (str | None)

class fuggers_py.rates.Swaption(expiry_date, underlying_swap, strike, exercise_into=PayReceive.PAY, instrument_id=None, cash_settled=False)

European swaption on a fixed-float underlying swap.

Parameters:

  • expiry_date (Date) – Option expiry date.

  • underlying_swap (FixedFloatSwap) – Fixed-float swap that becomes effective if the option is exercised.

  • strike (Decimal) – Exercise strike as a raw decimal.

  • exercise_into (PayReceive | str) – Direction of the underlying swap entered at exercise.

  • instrument_id (InstrumentId | None) – Optional stable identifier for the swaption.

  • cash_settled (bool) – Whether the option is cash settled instead of physically exercised.

currency()

Return the underlying swap currency.

property underlying: FixedFloatSwap

Return the underlying swap.

option_type()

Return the call/put type implied by the exercise direction.

Return type:

OptionType

fuggers_py.rates.cheapest_to_deliver(contract, basket, futures_price, *, prefer_published_conversion_factor=True)

Rank the deliverables and return the CTD bond.

Return type:

CheapestToDeliverResult

Parameters:
fuggers_py.rates.conversion_factor(contract, deliverable, *, prefer_published_override=True, pricer=None)

Return the selected conversion factor and the theoretical reference.

Return type:

ConversionFactorResult

Parameters:
fuggers_py.rates.invoice_amount(contract_size, futures_price, conversion_factor, accrued_interest=Decimal('0'))

Return the delivery cash amount in currency units.

Return type:

Decimal

Parameters:

  • contract_size (object)

  • futures_price (object)

  • conversion_factor (object)

  • accrued_interest (object)

fuggers_py.rates.key_rate_risk(instrument, curves, *, tenor_grid=None, bump=Decimal('0.0001'), pricer=None)

Return a tenor-by-tenor key-rate risk profile.

Parameters:

  • instrument – Supported rates instrument to analyze.

  • curves (object) – Analytics curves used for valuation.

  • tenor_grid (tuple[Tenor | str, ...] | list[Tenor | str] | None) – Tenor nodes to bump. If omitted, a standard 6M to 30Y grid is used.

  • bump (object) – Raw decimal curve bump applied at each tenor node.

  • pricer (object | None) – Optional pricer instance matching the instrument type.

Returns:

Mapping from tenor label to finite-difference sensitivity in currency units per one basis point of bump, signed positive when the instrument gains value as the targeted tenor is bumped lower.

Return type:

dict[str, Decimal]

fuggers_py.rates.swap_dv01(instrument, curves, *, bump=Decimal('0.0001'), pricer=None)

Return the PV01 for a fixed-float or overnight-indexed swap.

Return type:

Decimal

Parameters: