{"success":true,"version":"v1","request":{"tool":"get_calculator_schema","calculator_id":"bond-duration"},"result":{"entity_type":"calculator","id":"bond-duration","calculator_id":"bond-duration","canonical_url":"https://tttkmbb.com/investing/bond-duration","name":"Bond Duration Calculator","title":"Bond Duration Calculator – Price, Macaulay and Modified Duration, Convexity and DV01","category":"investing","category_name":"Investing & Real Estate","tool_name":"calculate_bond_duration","featured_mcp_tool":false,"description":"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.","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":"yield_to_maturity_percent","label":"Yield to maturity","type":"number","unit":"% per year","required":true,"min":-10,"max":100,"description":"Nominal annual yield, compounded once per coupon period.","example":5},{"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":3},{"name":"coupons_per_year","label":"Coupons per year","type":"enum","required":false,"default":"semiannual","values":[{"value":"annual","label":"Annual (1)","aliases":["1","yearly"]},{"value":"semiannual","label":"Semiannual (2)","aliases":["2","semi-annual"]},{"value":"quarterly","label":"Quarterly (4)","aliases":["4"]},{"value":"monthly","label":"Monthly (12)","aliases":["12"]}],"description":"Coupon payment frequency (2 for US Treasuries and most corporates, 1 for many European bonds).","example":"annual"}],"outputs":[{"name":"price","label":"Bond price","type":"number","decimals":2,"description":"Present value of coupons and face value at the yield."},{"name":"number_of_coupons","label":"Number of coupon payments","type":"integer","decimals":0,"description":"round(years_to_maturity × coupons per year)."},{"name":"macaulay_duration_years","label":"Macaulay duration","type":"number","unit":"years","decimals":4,"description":"PV-weighted average time to each cash flow."},{"name":"modified_duration_years","label":"Modified duration","type":"number","unit":"years","decimals":4,"description":"Macaulay duration / (1 + y/m): percent price change per 1 unit (100 %) change in yield."},{"name":"convexity","label":"Convexity","type":"number","unit":"years²","decimals":4,"description":"Σ t(t+1)·PV_t / (P·(1 + y/m)²·m²)."},{"name":"dv01","label":"DV01 (price value of a basis point)","type":"number","decimals":4,"description":"modified_duration × price × 0.0001: price change per 0.01 % yield move."},{"name":"price_change_for_1pct_yield_rise_percent","label":"Price change for +1 % yield (duration only)","type":"number","unit":"%","decimals":2,"description":"−modified_duration × 1."},{"name":"price_change_for_1pct_yield_rise_with_convexity_percent","label":"Price change for +1 % yield (duration + convexity)","type":"number","unit":"%","decimals":2,"description":"(−modified_duration × 0.01 + ½ × convexity × 0.01²) × 100."},{"name":"current_yield_percent","label":"Current yield","type":"number","unit":"%","decimals":2,"description":"Annual coupon / price × 100."}],"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"},"yield_to_maturity_percent":{"description":"Nominal annual yield, compounded once per coupon period. Unit: % per year.","type":"number","minimum":-10,"maximum":100,"examples":[5],"x-unit":"% per year"},"years_to_maturity":{"description":"Time until redemption; rounded to whole coupon periods. Unit: years.","type":"number","maximum":100,"exclusiveMinimum":0,"examples":[3],"x-unit":"years"},"coupons_per_year":{"description":"Coupon payment frequency (2 for US Treasuries and most corporates, 1 for many European bonds).","type":"string","enum":["annual","semiannual","quarterly","monthly"],"default":"semiannual","examples":["annual"]}},"additionalProperties":false,"required":["coupon_rate_percent","yield_to_maturity_percent","years_to_maturity"]},"output_schema":{"type":"object","properties":{"price":{"description":"Present value of coupons and face value at the yield.","type":"number"},"number_of_coupons":{"description":"round(years_to_maturity × coupons per year).","type":"integer"},"macaulay_duration_years":{"description":"PV-weighted average time to each cash flow. Unit: years.","type":"number","x-unit":"years"},"modified_duration_years":{"description":"Macaulay duration / (1 + y/m): percent price change per 1 unit (100 %) change in yield. Unit: years.","type":"number","x-unit":"years"},"convexity":{"description":"Σ t(t+1)·PV_t / (P·(1 + y/m)²·m²). Unit: years².","type":"number","x-unit":"years²"},"dv01":{"description":"modified_duration × price × 0.0001: price change per 0.01 % yield move.","type":"number"},"price_change_for_1pct_yield_rise_percent":{"description":"−modified_duration × 1. Unit: %.","type":"number","x-unit":"%"},"price_change_for_1pct_yield_rise_with_convexity_percent":{"description":"(−modified_duration × 0.01 + ½ × convexity × 0.01²) × 100. Unit: %.","type":"number","x-unit":"%"},"current_yield_percent":{"description":"Annual coupon / price × 100. Unit: %.","type":"number","x-unit":"%"}}},"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²","method":"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.","sources":[{"name":"Wikipedia – Bond duration","url":"https://en.wikipedia.org/wiki/Bond_duration","type":"reference","retrieved_at":"2026-09-24"},{"name":"Wikipedia – Bond convexity","url":"https://en.wikipedia.org/wiki/Bond_convexity","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":"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"},"expected":{"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},"url":"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"},{"name":"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"},"expected":{"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},"url":"https://tttkmbb.com/api/v1/calculate/bond-duration?face_value=1000&coupon_rate_percent=6&yield_to_maturity_percent=8&years_to_maturity=10&coupons_per_year=semiannual"}],"faq":[{"q":"What is the difference between Macaulay and modified duration?","a":"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."},{"q":"Why add convexity?","a":"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."}],"tags":["bond duration","macaulay duration","modified duration","convexity","dv01","interest rate risk"],"related":[{"calculator_id":"bond-yield","reason":"Solve for the yield when the price is known."},{"calculator_id":"present-value","reason":"Discounting of a single cash flow."},{"calculator_id":"npv","reason":"Present value of an arbitrary cash-flow list."}],"links":{"html":"https://tttkmbb.com/investing/bond-duration","markdown":"https://tttkmbb.com/investing/bond-duration.md","json":"https://tttkmbb.com/investing/bond-duration.json","api":"https://tttkmbb.com/api/v1/calculate/bond-duration","schema":"https://tttkmbb.com/api/v1/calculators/bond-duration","openapi":"https://tttkmbb.com/openapi.json","mcp":"https://tttkmbb.com/mcp"},"version":"v1","updated_at":"2026-09-24"},"timestamp":"2026-09-24T03:45:39Z","next_actions":[{"tool":"run_calculator","calculator_id":"bond-duration","reason":"Run Bond Duration Calculator with the inputs above."}],"links":{"markdown":"https://tttkmbb.com/investing/bond-duration.md"}}