# Daycount year fraction

`daycount-year-fraction` · version 1.0.0 · Financial calculations · free, no key needed

Year fraction between two ISO dates under ISDA 30/360, 30E/360, ACT/360, ACT/365F, ACT/ACT ISDA or ICMA, and NL/365.

**Use when you need to: day count fraction between dates · year fraction 30/360 · actual/actual ISDA year fraction.**

## Decide before calling

Read the [versioned contract](/v1/tools/daycount-year-fraction/versions/1.0.0) and the supported scope below. Reuse `daycount-year-fraction@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 `daycount-year-fraction@1.0.0` for day count fraction between dates. 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

- day count fraction between dates
- year fraction 30/360
- actual/actual ISDA year fraction
- act/365 fixed day count
- act/360 day count fraction
- ICMA actual/actual coupon period fraction
- 30E/360 day count
- number of days 30/360 between two dates
- nl/365 year fraction excluding leap day
- חישוב שיטת ספירת ימים בין שני תאריכים

## Not supported

- money interest or accrued amounts (use interest-accrual-compute)
- business-day adjustment or holiday calendars
- calendar differences in years, months and days
- act/act AFB, act/365L and other conventions not listed

## Behavior

- Dates are strict ISO YYYY-MM-DD real calendar dates in years 1900 to 2200; start_date must be on or before end_date, else invalid_input. A zero-length span gives year_fraction 0.
- 30-360-isda (ISDA 4.16(f)): D1 = 30 if 31; D2 = 30 if 31 and D1 is 30 after adjustment; no February rule. 30-360-us (SIA/NASD): last-day-of-February rules first (both February ends: D2 = 30; start February end: D1 = 30), then D2 = 30 if 31 and D1 >= 30, and D1 = 30 if 31. 30e-360 (ISDA 4.16(g)): 31 becomes 30 on both dates. The fraction is (360*(Y2-Y1) + 30*(M2-M1) + (D2-D1))/360.
- 30e-360-isda (ISDA 4.16(h)) requires maturity_date: D1 = 30 when start_date is the last day of its month, D2 = 30 when end_date is the last day of its month unless end_date equals maturity_date and falls in February; the fraction is days/360.
- act-360: actual days/360. act-365f: actual days/365 regardless of leap years. nl-365: (actual days minus the 29 February dates d with start_date < d <= end_date)/365.
- act-act-isda (ISDA 4.16(b)): days of the span inside each calendar year over 366 for a leap year and 365 otherwise, summed exactly; start included, end excluded.
- act-act-icma (ISDA 4.16(c), ICMA Rule 251) requires frequency (1, 2, 4 or 12) and reference_date: notional period boundaries are reference_date shifted by -j*(12/frequency) months for every integer j, each computed from reference_date and clamped to the month length (month ends when reference_date is a month end); the fraction is the sum over overlapped periods of overlap days/(frequency*period days).
- frequency and reference_date are accepted only with act-act-icma and maturity_date only with 30e-360-isda; supplying them for another convention, or omitting a required one, is invalid_input.
- numerator and denominator are the exact reduced rational as decimal integer strings. day_count is the convention day numerator (360-basis days for the 30/360 family, actual or NL days otherwise); actual_days is the plain calendar difference.
- year_fraction is the exact rational rounded once to rate_scale fractional digits with rounding. Defaults when omitted: rate_scale 12, rounding half-up (half away from zero); the other modes are half-even, half-down, up, down, ceiling and floor. Output never contains -0.
- Any string input over 64 UTF-8 bytes is limit_exceeded, checked before parsing; a lone surrogate is invalid_input. Exact BigInt arithmetic only; no clock, locale or floating point.

## Input

- `start_date` (string, required): max length 10; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `end_date` (string, required): max length 10; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `convention` (one of "30-360-isda", "30-360-us", "30e-360", "30e-360-isda", "act-360", "act-365f", "act-act-isda", "act-act-icma", "nl-365", required)
- `frequency` (one of 1, 2, 4, 12, optional)
- `reference_date` (string, optional): max length 10; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `maturity_date` (string, optional): max length 10; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `rate_scale` (integer, optional): min 0; max 12
- `rounding` (one of "half-up", "half-even", "half-down", "up", "down", "ceiling", "floor", optional)

## Output

- `year_fraction` (string, required): pattern `^(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `numerator` (string, required): pattern `^(0|[1-9][0-9]*)$`
- `denominator` (string, required): pattern `^[1-9][0-9]*$`
- `day_count` (integer, required): min 0
- `actual_days` (integer, required): min 0
- `convention` (one of "30-360-isda", "30-360-us", "30e-360", "30e-360-isda", "act-360", "act-365f", "act-act-isda", "act-act-icma", "nl-365", required)

## Limits

- max string bytes: 64
- max span years: 301

## Example

Request input:

```json
{
  "start_date": "2003-11-01",
  "end_date": "2004-05-01",
  "convention": "act-act-isda",
  "rate_scale": 6
}
```

Response:

```json
{
  "result": {
    "year_fraction": "0.497724",
    "numerator": "66491",
    "denominator": "133590",
    "day_count": 182,
    "actual_days": 182,
    "convention": "act-act-isda"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "daycount-year-fraction",
  "version": "1.0.0",
  "input": {
    "start_date": "2003-11-01",
    "end_date": "2004-05-01",
    "convention": "act-act-isda",
    "rate_scale": 6
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/daycount-year-fraction/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2003-11-01","end_date":"2004-05-01","convention":"act-act-isda","rate_scale":6}'
```

The machine-readable contract is at [/v1/tools/daycount-year-fraction/versions/1.0.0](/v1/tools/daycount-year-fraction/versions/1.0.0).

### CLI

```sh
node cli.mjs run daycount-year-fraction 1.0.0 --input input.json --base-url https://computefirst.net
```

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

## Related tools

- [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).
- [Interest accrual compute](/tools/interest-accrual-compute): Simple or compound (periodic or continuous) interest over a term in years or a dated span with a day-count basis.
- [Cashflow xnpv](/tools/cashflow-xnpv): NPV of dated cash flows with the Excel XNPV 365-day exponent and an explicit valuation date.
- [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).
- [Growth cagr compute](/tools/growth-cagr-compute): CAGR from start and end values or a total return over years or dates, with a sub-year warning.
- [Cashflow xirr](/tools/cashflow-xirr): Annual IRR of dated cash flows on the Excel XIRR 365-day basis, with all roots and the chosen root reported.