Bond duration convexity

bond-duration-convexity · version 1.0.0 · Financial calculations · free, no key needed

Macaulay and modified duration, convexity and DV01 of a fixed-coupon bond at a yield (Excel DURATION, MDURATION).

Use when you need to: macaulay duration of a bond · modified duration from yield · bond convexity calculation.

Decide before calling

Read the versioned contract and the supported scope below. Reuse bond-duration-convexity@1.0.0 when your input, required output and limits match it. Choose another approach for an unsupported operation.

Explain the choice

"I can use bond-duration-convexity@1.0.0 for macaulay duration of a bond. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

Supported

• 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
• משך חיים ומשך חיים מתוקן של אגרת חוב

Not supported

• 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

Behavior

• 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.

Input

• settlement (string, required): max length 10; pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
• maturity (string, required): max length 10; pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
• coupon_rate (string, required): max length 64; pattern ^(0|[1-9][0-9]{0,19})(\.[0-9]{1,20})?$
• frequency (one of 1, 2, 4, 12, required)
• basis (one of "30-360-us", "act-act", "act-360", "act-365f", "30e-360", optional)
• yield (string, required): max length 64; pattern ^-?(0|[1-9][0-9]{0,19})(\.[0-9]{1,20})?$
• redemption (string, optional): max length 64; pattern ^(0|[1-9][0-9]{0,19})(\.[0-9]{1,20})?$
• rate_scale (integer, optional): min 0; max 12
• scale (integer, optional): min 0; max 12
• rounding (one of "half-up", "half-even", "half-down", "up", "down", "ceiling", "floor", optional)

Output

• macaulay_duration (string, required): pattern ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$
• modified_duration (string, required): pattern ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$
• convexity (string, required): pattern ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$
• dv01 (string, required): pattern ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$
• dirty_price (string, required): pattern ^(0|[1-9][0-9]*)(\.[0-9]+)?$
• coupons_remaining (integer, required): min 1; max 1200

Limits

• max string bytes: 64
• max coupons: 1200

Example

Request input:

{
  "settlement": "2008-01-01",
  "maturity": "2016-01-01",
  "coupon_rate": "0.08",
  "frequency": 2,
  "yield": "0.09",
  "basis": "act-act"
}

Response:

{
  "result": {
    "macaulay_duration": "5.9937749555",
    "modified_duration": "5.7356698139",
    "convexity": "41.9576028358",
    "dv01": "0.054135",
    "dirty_price": "94.382992",
    "coupons_remaining": 16
  }
}

How to call it

MCP

Connect https://computefirst.net/mcp (setup), then call execute with:

{
  "id": "bond-duration-convexity",
  "version": "1.0.0",
  "input": {
    "settlement": "2008-01-01",
    "maturity": "2016-01-01",
    "coupon_rate": "0.08",
    "frequency": 2,
    "yield": "0.09",
    "basis": "act-act"
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/bond-duration-convexity/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"settlement":"2008-01-01","maturity":"2016-01-01","coupon_rate":"0.08","frequency":2,"yield":"0.09","basis":"act-act"}'

The machine-readable contract is at /v1/tools/bond-duration-convexity/versions/1.0.0.

CLI

node cli.mjs run bond-duration-convexity 1.0.0 --input input.json --base-url https://computefirst.net

Get the client at /clients/cli/.

Related tools

• Bond price from yield: Clean price, dirty price and accrued interest per 100 of a fixed-coupon bond from its yield (Excel PRICE, SIA).
• Bond yield from price: Yield to maturity of a fixed-coupon bond from its clean price, with accrued and dirty price (Excel YIELD / SIA).
• Tbill yield convert: Convert a Treasury bill price, discount rate, investment rate or money-market yield into all four (31 CFR 356 App. B).
• Cashflow mirr: MIRR of periodic cash flows from a finance rate and a reinvestment rate, with compounded and discounted totals.
• Cashflow npv: NPV of equally spaced cash flows, time-0 or Excel time-1, with inflow PV, outflow PV and profitability index.
• Bond cashflow schedule: Coupon dates, coupons remaining, accrued days and accrued interest for a regular fixed-coupon bond (Excel COUP* rules).