{"success":true,"version":"v1","request":{"tool":"get_calculator_schema","calculator_id":"bond-yield"},"result":{"entity_type":"calculator","id":"bond-yield","calculator_id":"bond-yield","canonical_url":"https://tttkmbb.com/finance/bond-yield","name":"Bond Yield Calculator","title":"Bond Yield Calculator – Current Yield and Yield to Maturity from Price, Coupon and Term","category":"finance","category_name":"Finance","tool_name":"calculate_bond_yield","featured_mcp_tool":false,"description":"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).","inputs":[{"name":"face_value","label":"Face (par) value","type":"number","required":false,"default":1000,"max":1000000000000,"exclusive_min":0,"description":"Amount repaid at maturity.","example":1000},{"name":"coupon_rate_percent","label":"Coupon rate","type":"number","unit":"% per year","required":true,"min":0,"max":100,"description":"Annual coupon as a percent of face value.","example":5},{"name":"price","label":"Market price","type":"number","required":true,"max":1000000000000,"exclusive_min":0,"description":"Current clean price in currency (e.g. 950 for a 1,000 bond quoted at 95).","example":950},{"name":"years_to_maturity","label":"Years to maturity","type":"number","unit":"years","required":true,"max":100,"exclusive_min":0,"description":"Time until redemption; rounded to whole coupon periods.","example":10},{"name":"payments_per_year","label":"Coupon payments per year","type":"integer","required":false,"default":2,"min":1,"max":12,"description":"2 for semiannual (US Treasuries and most corporates), 1 for annual (many European bonds).","example":2}],"outputs":[{"name":"annual_coupon","label":"Annual coupon","type":"number","decimals":2,"description":"face_value × coupon_rate_percent / 100."},{"name":"coupon_payment","label":"Coupon per payment","type":"number","decimals":2,"description":"annual_coupon / payments_per_year."},{"name":"number_of_payments","label":"Number of coupon payments","type":"integer","decimals":0,"description":"round(years_to_maturity × payments_per_year)."},{"name":"current_yield_percent","label":"Current yield","type":"number","unit":"%","decimals":2,"description":"annual_coupon / price × 100."},{"name":"yield_to_maturity_percent","label":"Yield to maturity (nominal annual)","type":"number","unit":"%","decimals":2,"description":"Periodic yield × payments_per_year (bond-equivalent yield)."},{"name":"effective_annual_yield_percent","label":"Effective annual yield","type":"number","unit":"%","decimals":2,"description":"(1 + periodic yield)^payments_per_year − 1."},{"name":"total_coupon_income","label":"Total coupon income","type":"number","decimals":2,"description":"coupon_payment × number_of_payments."},{"name":"total_return_to_maturity","label":"Total return if held to maturity","type":"number","decimals":2,"description":"total_coupon_income + face_value − price."},{"name":"price_status","label":"Price status","type":"string","decimals":4,"description":"Discount (price below face), premium (above) or par."}],"input_schema":{"type":"object","properties":{"face_value":{"description":"Amount repaid at maturity.","type":"number","maximum":1000000000000,"exclusiveMinimum":0,"default":1000,"examples":[1000]},"coupon_rate_percent":{"description":"Annual coupon as a percent of face value. Unit: % per year.","type":"number","minimum":0,"maximum":100,"examples":[5],"x-unit":"% per year"},"price":{"description":"Current clean price in currency (e.g. 950 for a 1,000 bond quoted at 95).","type":"number","maximum":1000000000000,"exclusiveMinimum":0,"examples":[950]},"years_to_maturity":{"description":"Time until redemption; rounded to whole coupon periods. Unit: years.","type":"number","maximum":100,"exclusiveMinimum":0,"examples":[10],"x-unit":"years"},"payments_per_year":{"description":"2 for semiannual (US Treasuries and most corporates), 1 for annual (many European bonds).","type":"integer","minimum":1,"maximum":12,"default":2,"examples":[2]}},"additionalProperties":false,"required":["coupon_rate_percent","price","years_to_maturity"]},"output_schema":{"type":"object","properties":{"annual_coupon":{"description":"face_value × coupon_rate_percent / 100.","type":"number"},"coupon_payment":{"description":"annual_coupon / payments_per_year.","type":"number"},"number_of_payments":{"description":"round(years_to_maturity × payments_per_year).","type":"integer"},"current_yield_percent":{"description":"annual_coupon / price × 100. Unit: %.","type":"number","x-unit":"%"},"yield_to_maturity_percent":{"description":"Periodic yield × payments_per_year (bond-equivalent yield). Unit: %.","type":"number","x-unit":"%"},"effective_annual_yield_percent":{"description":"(1 + periodic yield)^payments_per_year − 1. Unit: %.","type":"number","x-unit":"%"},"total_coupon_income":{"description":"coupon_payment × number_of_payments.","type":"number"},"total_return_to_maturity":{"description":"total_coupon_income + face_value − price.","type":"number"},"price_status":{"description":"Discount (price below face), premium (above) or par.","type":"string"}}},"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","method":"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.","sources":[{"name":"Investopedia – Yield to Maturity (YTM): What It Is and How It Works","url":"https://www.investopedia.com/terms/y/yieldtomaturity.asp","type":"reference","retrieved_at":"2026-09-24"},{"name":"Wikipedia – Yield to maturity","url":"https://en.wikipedia.org/wiki/Yield_to_maturity","type":"reference","retrieved_at":"2026-09-24"},{"name":"Investopedia – Current Yield","url":"https://www.investopedia.com/terms/c/currentyield.asp","type":"reference","retrieved_at":"2026-09-24"}],"freshness":{"type":"static","max_age_seconds":null,"note":"Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output."},"examples":[{"name":"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},"expected":{"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)"},"url":"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"},{"name":"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},"expected":{"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)"},"url":"https://tttkmbb.com/api/v1/calculate/bond-yield?face_value=1000&coupon_rate_percent=6&price=1050&years_to_maturity=5&payments_per_year=1"}],"faq":[{"q":"Why is YTM above the current yield for a discount bond?","a":"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."},{"q":"Is YTM the same as the bond-equivalent yield?","a":"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."}],"tags":["bond yield","yield to maturity","ytm","current yield","bond price","coupon"],"related":[{"calculator_id":"apy","reason":"Nominal versus effective annual rates."},{"calculator_id":"present-value","reason":"Discount a single future amount."},{"calculator_id":"irr","reason":"YTM is the IRR of the bond's cash flows."}],"links":{"html":"https://tttkmbb.com/finance/bond-yield","markdown":"https://tttkmbb.com/finance/bond-yield.md","json":"https://tttkmbb.com/finance/bond-yield.json","api":"https://tttkmbb.com/api/v1/calculate/bond-yield","schema":"https://tttkmbb.com/api/v1/calculators/bond-yield","openapi":"https://tttkmbb.com/openapi.json","mcp":"https://tttkmbb.com/mcp"},"version":"v1","updated_at":"2026-09-24"},"timestamp":"2026-09-24T01:46:40Z","next_actions":[{"tool":"run_calculator","calculator_id":"bond-yield","reason":"Run Bond Yield Calculator with the inputs above."}],"links":{"markdown":"https://tttkmbb.com/finance/bond-yield.md"}}