{"id":"bond-duration-convexity","version":"1.0.0","description":"Macaulay and modified duration, convexity and DV01 of a fixed-coupon bond at a yield (Excel DURATION, MDURATION).","supported_operations":["macaulay duration of a bond","modified duration from yield","bond convexity calculation","bond DV01 price value of a basis point","Excel DURATION and MDURATION equivalent","interest rate sensitivity of a coupon bond","how much does a bond price move when yields rise 1 percent","duration of a semiannual coupon bond","משך חיים ומשך חיים מתוקן של אגרת חוב"],"unsupported_operations":["bond price or yield solving (use bond-price-from-yield or bond-yield-from-price)","effective duration with a shifted curve and key-rate durations","odd first or last coupon periods, callable and putable bonds","portfolio duration or immunization"],"semantics":["Dates are strict ISO YYYY-MM-DD real dates in years 1900 to 2200 with settlement strictly before maturity. frequency is the JSON integer 1, 2, 4 or 12; basis is 30-360-us (Excel 0, default), act-act (1), act-360 (2), act-365f (3) or 30e-360 (4). Coupon dates, N (above 1200 is limit_exceeded), A, DSC and E follow bond-price-from-yield (Excel COUP* rules).","yield is the annual yield to maturity compounded frequency times a year with -frequency < yield <= 10 (\"0.09\" is 9 percent); coupon_rate is a fraction from 0 to 1; redemption per 100 is 0 < redemption <= 1000 (default \"100\"). All prices are per 100 of face; there is no face input. A JSON number for a decimal field is invalid_input.","With c = 100*coupon_rate/frequency, i = yield/frequency and tau_k = k - 1 + DSC/E (negative only in the odd 30e-360 February case): CF_k = c (plus redemption at k = N), PV_k = CF_k/(1+i)^tau_k for every N including N = 1, and dirty_price P = sum of PV_k. For N = 1 this differs slightly from the simple-yield price of bond-price-from-yield by design.","macaulay_duration = (sum tau_k*PV_k)/P/frequency in years (Excel DURATION); modified_duration = macaulay_duration/(1+i) (Excel MDURATION); convexity = (sum tau_k*(tau_k+1)*PV_k)/(P*(1+i)^2*frequency^2) in years squared; dv01 = modified_duration*P/10000, the dirty-price change per 100 of face for one basis point. Formulas are applied as written with no clamping.","scale (0 to 12, default 6) sets the digits of dirty_price and dv01; rate_scale (0 to 12, default 10) sets the digits of the three duration and convexity values. rounding is half-up (default, half away from zero), half-even, half-down, up, down, ceiling or floor, applied once to each exact value. Outputs never contain -0.","A zero-coupon bond settled on a coupon date has macaulay_duration exactly N/frequency. Fractional exponents use exp/ln in a 40-digit BigInt engine accurate to better than 1e-35 relative; integer exponents are exact.","If the exact dirty price P, or the magnitude of the exact dv01, reaches 1e20 the result is not_computable (details.reason overflow); this can happen only for a yield close to -frequency. It is detected from exact ratios without building the oversized value, so the call costs no more than a regular call with the same coupon count. Under a fractional exponent a value within 1e-30 relative of 1e20 is outside the guarantee. macaulay_duration, modified_duration and convexity are ratios and are not bounded by this rule: near -frequency they can be very large and are still rounded once from their exact values. dirty_price and dv01 are rounded once from exact rationals for an integer exponent (dv01 = (sum tau_k*PV_k)/(frequency*(1+i)*10000)); the three ratios are exact rationals for every exponent because the settlement shift cancels.","Any string input over 64 UTF-8 bytes is limit_exceeded, checked before parsing; a lone surrogate is invalid_input.","Disclaimer: arithmetic calculation only; not financial, tax, legal, or investment advice."],"limits":{"max_string_bytes":64,"max_coupons":1200},"pricing":{"status":"unpriced","charge_usd":null},"input_schema":{"type":"object","additionalProperties":false,"required":["settlement","maturity","coupon_rate","frequency","yield"],"properties":{"settlement":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10},"maturity":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10},"coupon_rate":{"type":"string","pattern":"^(0|[1-9][0-9]{0,19})(\\.[0-9]{1,20})?$","maxLength":64},"frequency":{"type":"integer","enum":[1,2,4,12]},"basis":{"type":"string","enum":["30-360-us","act-act","act-360","act-365f","30e-360"]},"yield":{"type":"string","pattern":"^-?(0|[1-9][0-9]{0,19})(\\.[0-9]{1,20})?$","maxLength":64},"redemption":{"type":"string","pattern":"^(0|[1-9][0-9]{0,19})(\\.[0-9]{1,20})?$","maxLength":64},"rate_scale":{"type":"integer","minimum":0,"maximum":12},"scale":{"type":"integer","minimum":0,"maximum":12},"rounding":{"type":"string","enum":["half-up","half-even","half-down","up","down","ceiling","floor"]}}},"output_schema":{"type":"object","additionalProperties":false,"required":["macaulay_duration","modified_duration","convexity","dv01","dirty_price","coupons_remaining"],"properties":{"macaulay_duration":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$"},"modified_duration":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$"},"convexity":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$"},"dv01":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$"},"dirty_price":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$"},"coupons_remaining":{"type":"integer","minimum":1,"maximum":1200}}},"examples":[{"input":{"settlement":"2008-01-01","maturity":"2016-01-01","coupon_rate":"0.08","frequency":2,"yield":"0.09","basis":"act-act"},"output":{"macaulay_duration":"5.9937749555","modified_duration":"5.7356698139","convexity":"41.9576028358","dv01":"0.054135","dirty_price":"94.382992","coupons_remaining":16}},{"input":{"settlement":"2020-05-15","maturity":"2030-05-15","coupon_rate":"0.05","frequency":2,"yield":"0.06","rate_scale":6},"output":{"macaulay_duration":"7.894997","modified_duration":"7.665046","convexity":"71.785398","dv01":"0.070949","dirty_price":"92.561263","coupons_remaining":20}},{"input":{"settlement":"2020-05-15","maturity":"2025-05-15","coupon_rate":"0","frequency":1,"yield":"0.04","rate_scale":8,"scale":4},"output":{"macaulay_duration":"5.00000000","modified_duration":"4.80769231","convexity":"27.73668639","dv01":"0.0395","dirty_price":"82.1927","coupons_remaining":5}}],"execute_url":"/v1/tools/bond-duration-convexity/versions/1.0.0/execute"}