Yield to Maturity
Calculates the yield to maturity of individual bonds from their market price. The yield to maturity is the internal rate of return of the bond, the discount rate that equates the present value of the bond’s cash flows to its price.
The formula is as follows, solved for YTM:
\[\text{Price} + C \cdot a = \operatorname{SUM}(C / (1 + \text{YTM} / 2) ^{2 t_{i}}) + F / (1 + \text{YTM} / 2) ^{2 t_{n}},\;\; \text{over} \;\; \text{the remaining coupons}\; i = 1,\;\; \text{...},\;\; \text{n}\]where:
\[C = \text{Coupon payment per half year},\;\; 100 \cdot \text{Coupon} / 2\] \[a = \text{Elapsed fraction of the current coupon period},\;\; \text{in actual days (actual/actual)},\;\; \text{0 on a coupon date}\] \[t_{i} = \text{Time of the i-th cash flow in years},\;\; \text{on the bond's actual coupon dates}\] \[F = \text{Face value of}\; 100\]The yield is a nominal annual rate compounded twice a year (bond-equivalent), as the Treasury and US corporate bond markets quote it, solved with the secant method. For a bill it is the bond-equivalent yield of its discount price (see get_bond_equivalent_yield), for TIPS the real yield. The bonds are selected as in collect_bond_statistics. For terms of your own, use bond_model.get_yield_to_maturity.
The yield to maturity is the return of a bond bought at this price and held to maturity, if every coupon is reinvested at the same yield and the issuer pays in full. It is the standard way to quote and compare bonds, but it is one average rate for all cash flows: bonds with the same maturity but different coupons have different yields even when both are priced in line with the same spot curve, which the Z-spread (get_z_spread) accounts for. For callable bonds the yield to worst is quoted instead.
Also known as: YTM, bond return to maturity, redemption yield.
Yield to Maturity in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_yield_to_maturity as shown below.
from financetoolkit import FixedIncome
fixedincome = FixedIncome()
yields = fixedincome.get_yield_to_maturity(date="2026-11-05")
yields[["Security Type", "Coupon", "Maturity", "Price", "Yield to Maturity"]]
Or, after setting up the Finance Toolkit MCP, ask:
What yield to maturity did the benchmark 2- to 30-year US Treasuries offer on 5 November 2026?
Which returns:
| Bond | Security Type | Coupon | Maturity | Price | Yield to Maturity |
|---|---|---|---|---|---|
| 91282CRU7 | Note | 0.0462 | 2028-10-31 | 100.312 | 0.0446 |
| 91282CLR0 | Note | 0.0412 | 2029-10-31 | 98.875 | 0.0453 |
| 91282CRT0 | Note | 0.0475 | 2031-10-31 | 100.688 | 0.0459 |
| 91282CRV5 | Note | 0.0488 | 2033-10-31 | 101.062 | 0.0469 |
| 91282CRF0 | Note | 0.0462 | 2036-08-15 | 98.4375 | 0.0483 |
| 912810RU4 | Bond | 0.0288 | 2046-11-15 | 70.0312 | 0.0533 |
| 912810UW6 | Bond | 0.0512 | 2056-08-15 | 98.125 | 0.0525 |
Parameters
get_yield_to_maturity accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
bonds | list[str] | str | None | CUSIPs or ISINs, see collect_bond_statistics. Defaults to None. | None |
issuer | list[str] | str | None | Part of an issuer’s name, such as “Apple”. Defaults to None. | None |
etfs | list[str] | str | None | The bond ETFs to select bonds from, see get_bond_universe. Defaults to None. | None |
maturity_start | str | None | The earliest maturity (YYYY-MM-DD). Defaults to None. | None |
maturity_end | str | None | The latest maturity (YYYY-MM-DD). Defaults to None. | None |
date | str | None | The day of the Treasury prices (YYYY-MM-DD). Defaults to None, the latest day with prices. | "2025-03-31" |
rounding | int | None | The number of decimals to round the results to. Defaults to None, which uses the rounding of the class. | 2 |