Key Rate Duration
Calculates the key rate durations of individual bonds on the Treasury zero-coupon curve: the price sensitivity to a shock at a single maturity (“key rate”) of the curve while every other point is held fixed. Whereas get_duration with duration_type='effective' assumes the entire curve shifts in parallel, key rate durations show which segment of the curve a bond’s price is exposed to. Because cash flows are discounted using linear interpolation between the curve’s maturities, a shock at an inner maturity tapers off towards its neighbours and has no effect beyond them. The curve is held flat beyond its first and last maturities, so a shock at the first maturity moves every cash flow paid before it in full (and a shock at the last maturity every cash flow paid after it).
Summing the key rate durations across every maturity of the curve approximately reproduces the bond’s effective (parallel-shift) duration on the curve. A barbell and a bullet with the same duration have very different key rate profiles and react differently when the curve steepens or flattens, which is why key rate durations are hedged with instruments at each key maturity. The profile also depends on which maturities the curve contains: the same bond shows different key rate durations on a curve with more or fewer points.
The formula is as follows:
\[\text{Dirty Price} = \operatorname{SUM}(\text{Cash Flow} (t) / (1 + \text{Spot Rate} (t) / 2) ^{2t})\] \[\text{Key Rate Duration} = - (\text{Dirty Price} (\text{Key Rate} + \Delta y) - \text{Dirty Price} (\text{Key Rate} - \Delta y)) / (2 \cdot \text{Dirty Price} \cdot \Delta y)\]Where each coupon is 100 * Coupon / 2, the principal is repaid with the last coupon, t is each remaining payment time in years on the bond’s actual coupon dates, Spot Rate(t) is the Treasury zero-coupon rate of the price date (get_zero_coupon_curve), restated from annual to semi-annual compounding and interpolated linearly between its maturities, and Δy is the shock applied to the key rate only (1 basis point by default).
The bonds are selected as in collect_bond_statistics; TIPS have no key rate durations on the nominal curve. For terms or a curve of your own, use bond_model.get_key_rate_duration.
Also known as: partial duration, rate-specific duration, curve risk.
Key Rate Duration in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_key_rate_duration as shown below.
from financetoolkit import FixedIncome
fixedincome = FixedIncome()
key_rates = fixedincome.get_key_rate_duration(
key_rate_maturity=["2Y", "5Y", "10Y", "30Y"], date="2026-11-05"
)
key_rates[["Coupon", "Maturity", "2Y", "5Y", "10Y", "30Y"]]
Or, after setting up the Finance Toolkit MCP, ask:
What were the 2-, 5-, 10- and 30-year key rate durations of the benchmark US Treasuries on 5 November 2026?
Which returns:
| Coupon | Maturity | 2Y | 5Y | 10Y | 30Y | |
|---|---|---|---|---|---|---|
| 91282CRU7 | 0.0462 | 2028-10-31 | 1.8043 | 0 | 0 | 0 |
| 91282CLR0 | 0.0412 | 2029-10-31 | 0.1101 | 0 | 0 | 0 |
| 91282CRT0 | 0.0475 | 2031-10-31 | 0.0842 | 4.0372 | 0 | 0 |
| 91282CRV5 | 0.0488 | 2033-10-31 | 0.0861 | 0.4068 | 0 | 0 |
| 91282CRF0 | 0.0462 | 2036-08-15 | 0.083 | 0.3598 | 5.9559 | 0 |
| 912810RU4 | 0.0288 | 2046-11-15 | 0.072 | 0.3122 | 1.6649 | 0.0255 |
| 912810UW6 | 0.0512 | 2056-08-15 | 0.0922 | 0.3998 | 2.1327 | 7.5183 |
Parameters
get_key_rate_duration accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
key_rate_maturity | float | str | list | None | The maturities of the Treasury curve to shock, in years or as labels such as ‘2Y’ (one of the curve’s maturities: 1M, 1.5M, 2M, 3M, 4M, 6M, 1Y, 2Y, 3Y, 5Y, 7Y, 10Y, 20Y and 30Y). Defaults to None, which shocks every maturity of the curve. | [2, 5, 10] |
yield_change | float | The shock to each key rate (decimal). Defaults to 0.0001. | 0.001 |
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 |