Yield to call API
The yield of a callable bond if the issuer redeems it on the call date at the call price, found as a proven root of the price equation.
POST https://api.curatedapi.com/v1/calc/finance/yield-to-call
- Version 1
- MCP tool
calc_finance_yield_to_call - Try it in the browser
A callable bond can be repaid early at a set price. Yield to call is the yield the buyer earns if that happens: the rate at which the coupons up to the call date and the call price are worth today's price. It is the same equation as yield to maturity (Excel's YIELD) with the call date in place of maturity and the call price in place of the redemption value. Compare it with the yield to maturity; the lower of the two is the yield to worst.
Formula
the y with PRICE(settlement, call date, coupon, y, call price, frequency, basis) = price
- The result is Excel's YIELD for the same dates with the call price as redemption, to the digits shown.
- Coupon dates are counted back from the call date, so the call date should be a coupon date.
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
settlement required |
date (YYYY-MM-DD) | Settlement date (when the buyer gets the bond). |
call_date required |
date (YYYY-MM-DD) | The date the bond can be called. |
coupon_rate_percent required |
decimal (string) | Annual coupon rate in percent of face value. Allowed: >= 0 and <= 1000. Unit: percent. |
price required |
decimal (string) | Clean price paid per 100 of face value. Allowed: > 0 and <= 1000000. |
call_price required |
decimal (string) | Amount paid per 100 of face value if the bond is called. Allowed: > 0 and <= 1000000. |
frequency |
integer default 2 |
Coupons per year: 1, 2 or 4. Allowed: >= 1 and <= 4. |
day_count |
30/360 | actual/actual | actual/360 | actual/365 | 30e/360 default 30/360 |
How days are counted for accrued interest. Options: 30/360: US (NASD) 30/360; actual/actual: actual days over the actual length of the coupon period; actual/360: actual days over a 360-day year; actual/365: actual days over a 365-day year; 30e/360: European 30/360 |
options.rounding |
half_even | half_up | half_down | up | down | ceiling | floor | Rounding mode applied once to each result. Default half_even. |
options.decimals |
integer | Round results to this many digits after the decimal point. |
options.significant_digits |
integer | Round results to this many significant digits. |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
yield_to_call_percent | decimal (string) | Annual yield to the call date. Unit: percent. |
coupons_until_call | integer | Coupons from settlement to the call date. |
Examples
A 5% bond bought at 104, callable in five years at 102
curl https://api.curatedapi.com/v1/calc/finance/yield-to-call \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"settlement": "2026-03-15",
"call_date": "2031-03-15",
"coupon_rate_percent": "5",
"price": "104",
"call_price": "102"
}'
{
"calculator": "finance/yield-to-call@1",
"result": {
"yield_to_call_percent": "4.460115",
"coupons_until_call": 10
},
"exactness": {
"yield_to_call_percent": "rounded"
},
"precision": {
"rounding": "half_even",
"decimals": 6
},
"inputs": {
"settlement": "2026-03-15",
"call_date": "2031-03-15",
"coupon_rate_percent": "5",
"price": "104",
"call_price": "102",
"frequency": 2,
"day_count": "30/360"
},
"formula": "the y with PRICE(settlement, call date, coupon, y, call price, frequency, basis) = price",
"references": [
{
"title": "FINRA: Bond yield and return (yield to maturity and yield to call)",
"url": "https://www.finra.org/investors/insights/bond-yield-return"
},
{
"title": "Microsoft Excel YIELD function",
"url": "https://support.microsoft.com/en-us/excel/functions/yield-function"
}
],
"warnings": []
}
References
Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.
Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.