# Cashflow npv

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

NPV of equally spaced cash flows, time-0 or Excel time-1, with inflow PV, outflow PV and profitability index.

**Use when you need to: net present value of cash flows · NPV calculator with initial investment at time zero · Excel NPV function equivalent.**

## Decide before calling

Read the [versioned contract](/v1/tools/cashflow-npv/versions/1.0.0) and the supported scope below. Reuse `cashflow-npv@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 `cashflow-npv@1.0.0` for net present value of cash flows. 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

- net present value of cash flows
- NPV calculator with initial investment at time zero
- Excel NPV function equivalent
- present value of inflows and outflows
- profitability index of a project
- discount a series of yearly cash flows
- NPV t0 versus t1 convention
- is this project worth it at a 10 percent discount rate

## Not supported

- dated cash flows with irregular spacing (use cashflow-xnpv)
- solving the rate that makes NPV zero (use cashflow-irr)
- terminal value, mid-year timing or equity bridge (use dcf-valuation-compute)
- inflation, tax or currency adjustment of flows

## Behavior

- Inputs: rate (the periodic discount rate as a decimal fraction, greater than -1 and at most 100), cash_flows (array of 2 to 2000 decimal strings in time order, positive for money received and negative for money paid), timing (t0 or t1, default t0), scale (0 to 12, default 2, for amounts), rate_scale (0 to 12, default 10, for the profitability index) and rounding (default half-up).
- timing t0: flow number k (k = 0, 1, ...) is discounted by (1+rate)^k, so the first flow is undiscounted (textbook NPV with the initial outlay at time 0). timing t1: flow number k is discounted by (1+rate)^(k+1), so every flow including the first is discounted one extra period; this is exactly Excel's NPV(rate, values...). To reproduce Excel's NPV(rate, values) + initial_outlay use t0 with the outlay as the first flow.
- Each discounted term cash_flow_k / (1+rate)^(k or k+1) is computed in exact decimal arithmetic with an absolute error below 1e-30 per term (terms below 1e-30 may be 0) and the sums are formed before any rounding.
- Outputs: pv_inflows = sum of the discounted terms of the positive flows; pv_outflows = sum of the discounted terms of the negative flows (a value at most 0); npv = pv_inflows + pv_outflows (rounded from the exact sum, so the printed parts may differ from the printed npv by one unit of the last digit); profitability_index = pv_inflows / -pv_outflows rounded to rate_scale, or null when pv_outflows is exactly 0; periods is the number of cash flows supplied. Zero flows contribute nothing.
- More than 2000 cash flows or a decimal string longer than 64 UTF-8 bytes is limit_exceeded, checked before parsing. If a discounted term or sum would reach 1e20 in magnitude the result is not_computable (details.reason overflow); this needs a negative rate or very large amounts (rate -0.99 with 12 flows of 1 overflows).
- Every rounded output is rounded exactly once from the unrounded value using the rounding mode: half-up (ties away from zero, the default), half-even, half-down (ties toward zero), up (away from zero), down (toward zero), ceiling, floor. Amount outputs print exactly scale fractional digits and rate-like outputs exactly rate_scale fractional digits; a result that rounds to zero prints without a minus sign (never '-0.00').
- Decimal string fields (amounts, rates) must match ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$ with at most 20 integer digits and at most 20 fractional digits; a JSON number, exponent form, leading plus, surrounding spaces, percent sign, missing integer part or trailing dot is invalid_input. Rates are decimal fractions (0.065 means 6.5 percent; "6.5" means 650 percent). A decimal string longer than 64 UTF-8 bytes is limit_exceeded, checked before parsing.
- Disclaimer: arithmetic calculation only; not financial, tax, legal, or investment advice.

## Input

- `rate` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `cash_flows` (array of string, required): min items 2; max items 2000; each max length 64; each pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `timing` (one of "t0", "t1", optional)
- `scale` (integer, optional): min 0; max 12
- `rate_scale` (integer, optional): min 0; max 12
- `rounding` (one of "half-up", "half-even", "half-down", "up", "down", "ceiling", "floor", optional)

## Output

- `npv` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `pv_inflows` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `pv_outflows` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `profitability_index` (string or null, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `periods` (integer, required): min 2; max 5000

## Limits

- max items: 2000
- max string bytes: 64

## Example

Request input:

```json
{
  "rate": "0.08",
  "cash_flows": [
    "-40000",
    "8000",
    "9200",
    "10000",
    "12000",
    "14500"
  ]
}
```

Response:

```json
{
  "result": {
    "npv": "1922.06",
    "pv_inflows": "41922.06",
    "pv_outflows": "-40000.00",
    "profitability_index": "1.0480515389",
    "periods": 6
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "cashflow-npv",
  "version": "1.0.0",
  "input": {
    "rate": "0.08",
    "cash_flows": [
      "-40000",
      "8000",
      "9200",
      "10000",
      "12000",
      "14500"
    ]
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/cashflow-npv/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"rate":"0.08","cash_flows":["-40000","8000","9200","10000","12000","14500"]}'
```

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

### CLI

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

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

## Related tools

- [Cashflow irr](/tools/cashflow-irr): IRR of equally spaced cash flows with every root reported, the chosen root named and no-solution cases signalled.
- [Cashflow mirr](/tools/cashflow-mirr): MIRR of periodic cash flows from a finance rate and a reinvestment rate, with compounded and discounted totals.
- [Cashflow xnpv](/tools/cashflow-xnpv): NPV of dated cash flows with the Excel XNPV 365-day exponent and an explicit valuation date.
- [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).
- [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.
- [Cashflow payback period](/tools/cashflow-payback-period): Payback period of periodic cash flows with linear interpolation, optional discounting and the cumulative path.