Loan Payment
Calculates the monthly payment of a new 30-year fixed-rate mortgage at every weekly US mortgage rate: what the same loan costs a buyer at each date, with the total interest over its life and the interest in its first payment. By default the loan is 400,000 US dollars, so the payment of the same house at the same price can be followed through the rate cycle (1,611.86 a month at the 2.65% of January 2021, 2,709.74 at 7.18%).
The loan is an annuity, repaid in equal payments. The formula is as follows:
\[\text{Payment} = L \cdot r / (1 - (1 + r) ^{-n}),\;\; \text{or}\; L / n \;\text{when}\; r \;\text{is zero}\] \[\text{Total Interest} = \text{Payment} \cdot n - L\] \[\text{First Payment Interest} = L \cdot r\]Where:
\[L = \text{Principal},\;\; \text{the amount borrowed}\] \[r = \text{Rate} / \text{payments per year},\;\; \text{the rate per payment}\] \[n = \text{years} \cdot \text{payments per year},\;\; \text{the number of payments}\]US mortgage rates are quoted as a nominal annual rate compounded monthly, so the rate per payment is the annual rate divided by twelve (7.18% is 0.5983% a month). The rate is the weekly average 30-year fixed rate of Freddie Mac’s Primary Mortgage Market Survey (the rate of Economics.get_mortgage_rate_30_year), from FRED when a FRED API key is set and from Freddie Mac otherwise. For a rate of your own, use loan_model.get_loan_payment, which takes a number or a series of rates.
Also known as: mortgage payment, monthly payment, annuity payment, mortgage calculator, loan calculator, cost of a mortgage.
Loan Payment in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_loan_payment as shown below.
from financetoolkit import FixedIncome
fixedincome = FixedIncome(start_date='2021-01-01', end_date='2026-11-06')
fixedincome.get_loan_payment().iloc[[0, -1]]
Or, after setting up the Finance Toolkit MCP, ask:
What was the monthly payment on a new 400,000 dollar 30-year US mortgage at the rate of 7 January 2021, and at the rate of 5 November 2026?
Which returns:
| Date | Rate | Payment | Total Interest | First Payment Interest |
|---|---|---|---|---|
| 2021-01-07 | 0.0265 | 1611.8552 | 180267.8595 | 883.3333 |
| 2026-11-05 | 0.0718 | 2709.7393 | 575506.1579 | 2393.3333 |
Parameters
get_loan_payment accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
principal | float | The amount borrowed. Defaults to 400,000. | 400,000 |
years | float | The term of the loan in years. The rate stays the 30-year fixed mortgage rate for another term. Defaults to 30. | 30 |
payments_per_year | int | The number of payments per year. Defaults to 12. | 12 |
rounding | int | None | The number of decimals to round the results to. Defaults to None, which uses the rounding of the class. | 2 |
show_columns | str | list[str] | None | The columns to keep, a name or a list of names, matched on every column level, or the rows when no column has those names (such as the line items of a financial statement). Names that do not exist are logged, and when none exist the result is returned in full. Defaults to None, which keeps every column. | None, which keeps every column |