# Bond cashflow schedule

`bond-cashflow-schedule` · version 1.0.0 · Financial calculations · free, no key needed

Coupon dates, coupons remaining, accrued days and accrued interest for a regular fixed-coupon bond (Excel COUP* rules).

**Use when you need to: bond coupon dates schedule · accrued interest on a bond · previous and next coupon date.**

## Decide before calling

Read the [versioned contract](/v1/tools/bond-cashflow-schedule/versions/1.0.0) and the supported scope below. Reuse `bond-cashflow-schedule@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-cashflow-schedule@1.0.0` for bond coupon dates schedule. 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

- bond coupon dates schedule
- accrued interest on a bond
- previous and next coupon date
- number of coupons remaining until maturity
- days since last coupon payment
- bond accrued days 30/360 or actual/actual
- coupon payment amount per period
- list bond coupon payments from settlement to maturity
- ריבית צוברת ולוח קופונים של אגרת חוב

## Not supported

- bond price or yield (use bond-price-from-yield or bond-yield-from-price)
- odd first or last coupon periods and issue-date accrual (Excel ACCRINT with issue date)
- business-day or holiday adjustment of coupon dates
- floating-rate, inflation-linked, callable or putable bonds

## Behavior

- Dates are strict ISO YYYY-MM-DD real calendar dates in years 1900 to 2200; settlement must be strictly before maturity. frequency is the JSON integer 1, 2, 4 or 12 (coupon step 12/frequency months). basis is 30-360-us (Excel 0), act-act (1), act-360 (2), act-365f (3) or 30e-360 (4); default 30-360-us.
- Coupon dates D(j) are maturity shifted back j*step months for j = 0, 1, 2, ..., each computed from maturity (never chained). When maturity is the last day of its month every D(j) is a month end; otherwise the day is maturity's day clamped to the month length (30 August gives 29 or 28 February and 30 August again).
- previous_coupon_date is D(j) for the smallest j >= 1 with D(j) <= settlement (a settlement on a coupon date makes it the previous date with accrued_days 0); next_coupon_date is D(j-1); coupons_remaining N = j (Excel COUPNUM). N above 1200 is limit_exceeded, computed by month arithmetic before any schedule is built.
- accrued_days A (COUPDAYBS), days_to_next_coupon DSC (COUPDAYSNC) and period_days E (COUPDAYS): 30-360-us and 30e-360: A is the 30/360 day count (US with SIA February rules, or European) from the previous coupon date to settlement, E = 360/frequency, DSC = E - A. act-act: actual days for A and DSC, E = actual days between the coupon dates. act-360 and act-365f: actual days for A and DSC, E = 360/frequency or 365/frequency (exact). DSC can be negative and A can exceed E, as in Excel; nothing is clamped.
- coupon_amount = face*coupon_rate/frequency and accrued_interest = face*coupon_rate/frequency*A/E, each rounded once from the exact value to scale; period_days is E rounded to exactly 6 fractional digits with rounding. coupons lists every coupon date d with settlement < d <= maturity in ascending order, each with coupon_amount; the redemption of face is not included.
- face is a decimal string with 0 < face <= 1e15 (default "100"); coupon_rate is a decimal fraction from 0 to 1 ("0.05" is 5 percent). scale is an integer 0 to 12 (default 6); rounding is half-up (default, half away from zero), half-even, half-down, up, down, ceiling or floor. Outputs never contain -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.
- 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)
- `face` (string, optional): max length 64; pattern `^(0|[1-9][0-9]{0,19})(\.[0-9]{1,20})?$`
- `scale` (integer, optional): min 0; max 12
- `rounding` (one of "half-up", "half-even", "half-down", "up", "down", "ceiling", "floor", optional)

## Output

- `previous_coupon_date` (string, required): pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `next_coupon_date` (string, required): pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`
- `coupons_remaining` (integer, required): min 1; max 1200
- `accrued_days` (integer, required): min 0
- `days_to_next_coupon` (integer, required)
- `period_days` (string, required): pattern `^(0|[1-9][0-9]*)\.[0-9]{6}$`
- `accrued_interest` (string, required): pattern `^(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `coupon_amount` (string, required): pattern `^(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `coupons` (array of object, required): min items 1; max items 1200

## Limits

- max string bytes: 64
- max coupons: 1200

## Example

Request input:

```json
{
  "settlement": "2011-01-25",
  "maturity": "2011-11-15",
  "coupon_rate": "0.05",
  "frequency": 2,
  "basis": "act-act"
}
```

Response:

```json
{
  "result": {
    "previous_coupon_date": "2010-11-15",
    "next_coupon_date": "2011-05-15",
    "coupons_remaining": 2,
    "accrued_days": 71,
    "days_to_next_coupon": 110,
    "period_days": "181.000000",
    "accrued_interest": "0.980663",
    "coupon_amount": "2.500000",
    "coupons": [
      {
        "date": "2011-05-15",
        "amount": "2.500000"
      },
      {
        "date": "2011-11-15",
        "amount": "2.500000"
      }
    ]
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "bond-cashflow-schedule",
  "version": "1.0.0",
  "input": {
    "settlement": "2011-01-25",
    "maturity": "2011-11-15",
    "coupon_rate": "0.05",
    "frequency": 2,
    "basis": "act-act"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/bond-cashflow-schedule/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"settlement":"2011-01-25","maturity":"2011-11-15","coupon_rate":"0.05","frequency":2,"basis":"act-act"}'
```

The machine-readable contract is at [/v1/tools/bond-cashflow-schedule/versions/1.0.0](/v1/tools/bond-cashflow-schedule/versions/1.0.0).

### CLI

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

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

## Related tools

- [Cashflow xnpv](/tools/cashflow-xnpv): NPV of dated cash flows with the Excel XNPV 365-day exponent and an explicit valuation date.
- [Loan amortization schedule](/tools/loan-amortization-schedule): Cent-exact level-payment loan schedule with per-period rounding, extra payments, dates and a row window.
- [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).
- [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.
- [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).
- [Daycount year fraction](/tools/daycount-year-fraction): Year fraction between two ISO dates under ISDA 30/360, 30E/360, ACT/360, ACT/365F, ACT/ACT ISDA or ICMA, and NL/365.