{"id":"cashflow-npv","version":"1.0.0","description":"NPV of equally spaced cash flows, time-0 or Excel time-1, with inflow PV, outflow PV and profitability index.","supported_operations":["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"],"unsupported_operations":["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"],"semantics":["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."],"limits":{"max_items":2000,"max_string_bytes":64},"pricing":{"status":"unpriced","charge_usd":null},"input_schema":{"type":"object","additionalProperties":false,"required":["rate","cash_flows"],"properties":{"rate":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"cash_flows":{"type":"array","minItems":2,"maxItems":2000,"items":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64}},"timing":{"type":"string","enum":["t0","t1"]},"scale":{"type":"integer","minimum":0,"maximum":12},"rate_scale":{"type":"integer","minimum":0,"maximum":12},"rounding":{"type":"string","enum":["half-up","half-even","half-down","up","down","ceiling","floor"]}}},"output_schema":{"type":"object","additionalProperties":false,"required":["npv","pv_inflows","pv_outflows","profitability_index","periods"],"properties":{"npv":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"pv_inflows":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"pv_outflows":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"profitability_index":{"type":["string","null"],"pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"periods":{"type":"integer","minimum":2,"maximum":5000}}},"examples":[{"input":{"rate":"0.08","cash_flows":["-40000","8000","9200","10000","12000","14500"]},"output":{"npv":"1922.06","pv_inflows":"41922.06","pv_outflows":"-40000.00","profitability_index":"1.0480515389","periods":6}},{"input":{"rate":"0.08","cash_flows":["8000","9200","10000","12000","14500"],"timing":"t1"},"output":{"npv":"41922.06","pv_inflows":"41922.06","pv_outflows":"0.00","profitability_index":null,"periods":5}}],"execute_url":"/v1/tools/cashflow-npv/versions/1.0.0/execute"}