{"id":"bond-yield-from-price","version":"1.0.0","description":"Yield to maturity of a fixed-coupon bond from its clean price, with accrued and dirty price (Excel YIELD / SIA).","supported_operations":["implied yield to maturity of a bond quoted at a price","YTM of a coupon bond","yield from clean price","what yield does a bond price of 95 imply","Excel YIELD function equivalent","implied yield of a semiannual coupon bond","solve bond yield given price and coupon","yield to maturity between coupon dates","תשואה לפדיון של אגרת חוב לפי מחיר"],"unsupported_operations":["price from a yield (use bond-price-from-yield)","current yield, simple yield, yield to call or yield to worst","Treasury bill yields (use tbill-yield-convert)","odd first or last coupon periods, callable and putable bonds"],"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).","clean_price is the quoted price per 100 of face with 0 < clean_price <= 1e9; redemption is per 100 with 0 < redemption <= 1000 (default \"100\"); coupon_rate is a fraction from 0 to 1. A JSON number for a decimal field is invalid_input.","accrued_interest = c*A/E with c = 100*coupon_rate/frequency, and the target dirty price is clean_price + accrued_interest exactly. The output yield is the annual yield (compounded frequency times a year) whose bond-price-from-yield dirty price equals that target; for N > 1 the price is strictly decreasing in the yield, so the root is unique.","N = 1 (method closed-form): yield = frequency*((redemption + c)/dirty - 1)*(E/DSC), the Excel YIELD single-coupon formula, exact and rounded once; DSC = 0 is not_computable (division_by_zero).","N > 1 (method root-finding): the periodic rate i = yield/frequency is bracketed on the pinned grid [-0.99, -0.95, -0.9, -0.8, -0.7, -0.6, -0.5, -0.4, -0.3, -0.25, -0.2, -0.15, -0.1, -0.075, -0.05, -0.025, -0.01, 0, 0.005, 0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09, 0.1, 0.125, 0.15, 0.175, 0.2, 0.25, 0.3, 0.4, 0.5, 0.75, 1, 1.5, 2, 3, 5, 10, 20, 50, 100, 1000] and solved with Brent's method (absolute tolerance 1e-14 on i, at most 200 iterations) on binary64 arithmetic. A target outside the price range of the grid (no_root_in_range) or a non-converging solve (no_convergence) is not_computable. Two roots inside one grid interval could be missed, but the price is monotonic so this cannot occur here.","The yield agrees with the exact root within 2e-12 absolute, and is rounded from the float root converted exactly; a root within 2e-12 of a rounding boundary at rate_scale digits may round either way. It can lie outside (-frequency, 10] (up to 1000*frequency) and is reported as found. dirty_price and accrued_interest are exact-path values rounded once to scale.","scale (0 to 12, default 6) sets the digits of dirty_price and accrued_interest; rate_scale (0 to 10, default 10) sets the digits of yield; rounding is half-up (default, half away from zero), half-even, half-down, up, down, ceiling or floor. Iteration counts are not reported. Outputs never contain -0.","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,"max_iterations":200},"pricing":{"status":"unpriced","charge_usd":null},"input_schema":{"type":"object","additionalProperties":false,"required":["settlement","maturity","coupon_rate","frequency","clean_price"],"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"]},"clean_price":{"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":10},"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":["yield","dirty_price","accrued_interest","coupons_remaining","method"],"properties":{"yield":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$"},"dirty_price":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$"},"accrued_interest":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$"},"coupons_remaining":{"type":"integer","minimum":1,"maximum":1200},"method":{"type":"string","enum":["closed-form","root-finding"]}}},"examples":[{"input":{"settlement":"2008-02-15","maturity":"2016-11-15","coupon_rate":"0.0575","frequency":2,"clean_price":"95.04287","basis":"30-360-us","rate_scale":6},"output":{"yield":"0.065000","dirty_price":"96.480370","accrued_interest":"1.437500","coupons_remaining":18,"method":"root-finding"}},{"input":{"settlement":"2020-05-15","maturity":"2030-05-15","coupon_rate":"0.05","frequency":2,"clean_price":"92.5","rate_scale":8},"output":{"yield":"0.06008638","dirty_price":"92.500000","accrued_interest":"0.000000","coupons_remaining":20,"method":"root-finding"}},{"input":{"settlement":"2022-08-01","maturity":"2022-11-15","coupon_rate":"0.06","frequency":2,"clean_price":"99.25","scale":4},"output":{"yield":"0.0855196867","dirty_price":"100.5167","accrued_interest":"1.2667","coupons_remaining":1,"method":"closed-form"}}],"execute_url":"/v1/tools/bond-yield-from-price/versions/1.0.0/execute"}