# Bond Yield Calculator

> Computes a bond's current yield and solves numerically for its yield to maturity from face value, coupon rate, market price, years to maturity and coupon frequency, and reports total coupon income and total return if held to maturity.

- Calculator id: `bond-yield` · Category: Finance (`finance`) · Tool name: `calculate_bond_yield`
- Canonical page: https://tttkmbb.com/finance/bond-yield · This document: https://tttkmbb.com/finance/bond-yield.md · JSON definition: https://tttkmbb.com/finance/bond-yield.json

## Purpose

Computes a bond's current yield and solves numerically for its yield to maturity from face value, coupon rate, market price, years to maturity and coupon frequency, and reports total coupon income and total return if held to maturity.

**Use when:** You know a bond's price and coupon and want its yield to maturity (the annualized return if held to redemption) or want to compare bonds trading at different prices.

**Do not use when:** The bond is callable, floating-rate or amortizing (yield to call / worst differ), or you want the price from a yield (invert with present-value style discounting).

## 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) |
| `price` | number |  | required | Current clean price in currency (e.g. 950 for a 1,000 bond quoted at 95). (> 0, max 1000000000000) |
| `years_to_maturity` | number | years | required | Time until redemption; rounded to whole coupon periods. (> 0, max 100) |
| `payments_per_year` | integer |  | optional, default 2 | 2 for semiannual (US Treasuries and most corporates), 1 for annual (many European bonds). (min 1, max 12) |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `annual_coupon` | number |  | face_value × coupon_rate_percent / 100. |
| `coupon_payment` | number |  | annual_coupon / payments_per_year. |
| `number_of_payments` | integer |  | round(years_to_maturity × payments_per_year). |
| `current_yield_percent` | number | % | annual_coupon / price × 100. |
| `yield_to_maturity_percent` | number | % | Periodic yield × payments_per_year (bond-equivalent yield). |
| `effective_annual_yield_percent` | number | % | (1 + periodic yield)^payments_per_year − 1. |
| `total_coupon_income` | number |  | coupon_payment × number_of_payments. |
| `total_return_to_maturity` | number |  | total_coupon_income + face_value − price. |
| `price_status` | string |  | Discount (price below face), premium (above) or par. |

## Formula

`C = face_value × coupon_rate_percent/100 / m; N = years_to_maturity × m; solve price = Σ_{k=1..N} C/(1 + y)^k + face_value/(1 + y)^N for the periodic yield y; YTM = y × m; current_yield = annual coupon / price`

Standard bond pricing with level coupons at the end of each period, settlement on a coupon date (no accrued interest) and the yield found by bisection. YTM assumes coupons are reinvested at the same yield.

## Data Sources

- Investopedia – Yield to Maturity (YTM): What It Is and How It Works — https://www.investopedia.com/terms/y/yieldtomaturity.asp (reference, retrieved 2026-09-24)
- Wikipedia – Yield to maturity — https://en.wikipedia.org/wiki/Yield_to_maturity (reference, retrieved 2026-09-24)
- Investopedia – Current Yield — https://www.investopedia.com/terms/c/currentyield.asp (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-yield?coupon_rate_percent=…&price=…&years_to_maturity=…`
- `POST https://tttkmbb.com/api/v1/calculate/bond-yield` 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-yield · OpenAPI operationId `calculate_bond_yield` 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-yield", "inputs": {…}}`

## Example

- 1,000 face, 5 % coupon, price 950, 10 years, semiannual: inputs `{"face_value":1000,"coupon_rate_percent":5,"price":950,"years_to_maturity":10,"payments_per_year":2}` → `{"annual_coupon":50,"coupon_payment":25,"number_of_payments":20,"current_yield_percent":5.26,"yield_to_maturity_percent":5.66,"effective_annual_yield_percent":5.74,"total_coupon_income":500,"total_return_to_maturity":550,"price_status":"Discount (price below face value)"}`
- 1,000 face, 6 % annual coupon, price 1,050, 5 years: inputs `{"face_value":1000,"coupon_rate_percent":6,"price":1050,"years_to_maturity":5,"payments_per_year":1}` → `{"current_yield_percent":5.71,"yield_to_maturity_percent":4.85,"total_coupon_income":300,"total_return_to_maturity":250,"price_status":"Premium (price above face value)"}`

```
GET https://tttkmbb.com/api/v1/calculate/bond-yield?face_value=1000&coupon_rate_percent=5&price=950&years_to_maturity=10&payments_per_year=2
```

## Limitations

The bond is callable, floating-rate or amortizing (yield to call / worst differ), or you want the price from a yield (invert with present-value style discounting). Standard bond pricing with level coupons at the end of each period, settlement on a coupon date (no accrued interest) and the yield found by bisection. YTM assumes coupons are reinvested at the same yield. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why is YTM above the current yield for a discount bond?**

Current yield counts only coupons; YTM also includes the gain from being repaid 1,000 for a bond bought at 950, spread over the remaining years.

**Is YTM the same as the bond-equivalent yield?**

Yes for semiannual bonds: YTM here is the periodic yield times the number of periods per year (nominal), which is how US bond yields are quoted; effective_annual_yield_percent compounds it.

## Related

- [APY Calculator](https://tttkmbb.com/finance/apy.md) — Nominal versus effective annual rates.
- [Present Value Calculator](https://tttkmbb.com/finance/present-value.md) — Discount a single future amount.
- [IRR Calculator](https://tttkmbb.com/finance/irr.md) — YTM is the IRR of the bond's cash flows.