# 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](/v1/tools/bond-duration-convexity/versions/1.0.0) 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:

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

Response:

```json
{
  "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](/docs#connect)), then call `execute` with:

```json
{
  "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)

```sh
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](/v1/tools/bond-duration-convexity/versions/1.0.0).

### CLI

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

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Bond price from yield](/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](/tools/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](/tools/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](/tools/cashflow-mirr): MIRR of periodic cash flows from a finance rate and a reinvestment rate, with compounded and discounted totals.
- [Cashflow npv](/tools/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](/tools/bond-cashflow-schedule): Coupon dates, coupons remaining, accrued days and accrued interest for a regular fixed-coupon bond (Excel COUP* rules).