# Bond Duration Calculator

> Prices a fixed-coupon bond from its yield to maturity and computes Macaulay duration, modified duration, convexity, DV01 and the estimated price change for a 1 percentage-point rise in yield.

- Calculator id: `bond-duration` · Category: Investing & Real Estate (`investing`) · Tool name: `calculate_bond_duration`
- Canonical page: https://tttkmbb.com/investing/bond-duration · This document: https://tttkmbb.com/investing/bond-duration.md · JSON definition: https://tttkmbb.com/investing/bond-duration.json

## Purpose

Prices a fixed-coupon bond from its yield to maturity and computes Macaulay duration, modified duration, convexity, DV01 and the estimated price change for a 1 percentage-point rise in yield.

**Use when:** You want to know how sensitive a bond's price is to interest-rate changes, or need duration and convexity for hedging or portfolio matching.

**Do not use when:** You know the price and want the yield (use bond-yield), or the bond is callable, floating-rate or amortizing. Informational only; not financial advice.

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `face_value` | number |  | optional, default 1000 | Amount repaid at maturity. (> 0, max 1000000000000) |
| `coupon_rate_percent` | number | % per year | required | Annual coupon as a percent of face value. (min 0, max 100) |
| `yield_to_maturity_percent` | number | % per year | required | Nominal annual yield, compounded once per coupon period. (min -10, max 100) |
| `years_to_maturity` | number | years | required | Time until redemption; rounded to whole coupon periods. (> 0, max 100) |
| `coupons_per_year` | enum: annual \| semiannual \| quarterly \| monthly |  | optional, default "semiannual" | Coupon payment frequency (2 for US Treasuries and most corporates, 1 for many European bonds). |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `price` | number |  | Present value of coupons and face value at the yield. |
| `number_of_coupons` | integer |  | round(years_to_maturity × coupons per year). |
| `macaulay_duration_years` | number | years | PV-weighted average time to each cash flow. |
| `modified_duration_years` | number | years | Macaulay duration / (1 + y/m): percent price change per 1 unit (100 %) change in yield. |
| `convexity` | number | years² | Σ t(t+1)·PV_t / (P·(1 + y/m)²·m²). |
| `dv01` | number |  | modified_duration × price × 0.0001: price change per 0.01 % yield move. |
| `price_change_for_1pct_yield_rise_percent` | number | % | −modified_duration × 1. |
| `price_change_for_1pct_yield_rise_with_convexity_percent` | number | % | (−modified_duration × 0.01 + ½ × convexity × 0.01²) × 100. |
| `current_yield_percent` | number | % | Annual coupon / price × 100. |

## Formula

`y = yield/m per period, n = years × m, C = face × coupon/m; P = Σ_{t=1..n} CF_t/(1+y)^t; D_mac = Σ t·PV_t / (P·m); D_mod = D_mac / (1 + y); convexity = Σ t(t+1)·PV_t / (P·(1+y)²·m²); ΔP/P ≈ −D_mod·Δy + ½·convexity·Δy²`

Standard bond mathematics with level coupons at the end of each period and settlement on a coupon date (no accrued interest); the yield is nominal annual compounded m times a year. Informational mathematics only; not financial advice.

## Data Sources

- Wikipedia – Bond duration — https://en.wikipedia.org/wiki/Bond_duration (reference, retrieved 2026-09-24)
- Wikipedia – Bond convexity — https://en.wikipedia.org/wiki/Bond_convexity (reference, retrieved 2026-09-24)

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/bond-duration?coupon_rate_percent=…&yield_to_maturity_percent=…&years_to_maturity=…`
- `POST https://tttkmbb.com/api/v1/calculate/bond-duration` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/bond-duration · OpenAPI operationId `calculate_bond_duration` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "bond-duration", "inputs": {…}}`

## Example

- 5 % annual coupon, 5 % yield, 3 years, face 1,000: inputs `{"face_value":1000,"coupon_rate_percent":5,"yield_to_maturity_percent":5,"years_to_maturity":3,"coupons_per_year":"annual"}` → `{"price":1000,"number_of_coupons":3,"macaulay_duration_years":2.8594,"modified_duration_years":2.7232,"convexity":10.2056,"dv01":0.2723,"price_change_for_1pct_yield_rise_percent":-2.72,"price_change_for_1pct_yield_rise_with_convexity_percent":-2.67,"current_yield_percent":5}`
- 6 % semiannual coupon, 8 % yield, 10 years: inputs `{"face_value":1000,"coupon_rate_percent":6,"yield_to_maturity_percent":8,"years_to_maturity":10,"coupons_per_year":"semiannual"}` → `{"price":864.1,"number_of_coupons":20,"macaulay_duration_years":7.4543,"modified_duration_years":7.1675,"convexity":65.044,"current_yield_percent":6.94}`

```
GET https://tttkmbb.com/api/v1/calculate/bond-duration?face_value=1000&coupon_rate_percent=5&yield_to_maturity_percent=5&years_to_maturity=3&coupons_per_year=annual
```

## Limitations

You know the price and want the yield (use bond-yield), or the bond is callable, floating-rate or amortizing. Informational only; not financial advice. Standard bond mathematics with level coupons at the end of each period and settlement on a coupon date (no accrued interest); the yield is nominal annual compounded m times a year. Informational mathematics only; not financial advice. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**What is the difference between Macaulay and modified duration?**

Macaulay duration is a weighted average time in years; modified duration divides it by (1 + y/m) and gives the percentage price change for a 1-point yield change, which is what risk managers use.

**Why add convexity?**

Duration is a straight-line estimate; the price-yield curve bends upward, so the duration-only estimate overstates losses when yields rise and understates gains when they fall. Convexity corrects part of that error.

## Related

- [Bond Yield Calculator](https://tttkmbb.com/finance/bond-yield.md) — Solve for the yield when the price is known.
- [Present Value Calculator](https://tttkmbb.com/finance/present-value.md) — Discounting of a single cash flow.
- [NPV Calculator](https://tttkmbb.com/finance/npv.md) — Present value of an arbitrary cash-flow list.