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 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:

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

Response:

{
  "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), then call execute with:

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

HTTP (no key)

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.

CLI

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

Get the client at /clients/cli/.

Related tools

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