# IRR Calculator

> Solves numerically for the discount rate at which the net present value of an initial investment and its subsequent cash flows equals zero, and reports the undiscounted gain and the number of sign changes (a warning for multiple IRRs).

- Calculator id: `irr` · Category: Finance (`finance`) · Tool name: `calculate_irr`
- Canonical page: https://tttkmbb.com/finance/irr · This document: https://tttkmbb.com/finance/irr.md · JSON definition: https://tttkmbb.com/finance/irr.json

## Purpose

Solves numerically for the discount rate at which the net present value of an initial investment and its subsequent cash flows equals zero, and reports the undiscounted gain and the number of sign changes (a warning for multiple IRRs).

**Use when:** You want the annualized (per-period) return implied by an investment's cash-flow pattern, e.g. to compare projects or check a fund's stated return.

**Do not use when:** Cash flows change sign more than once (multiple IRRs may exist; use npv at your hurdle rate), or there are only two values (use cagr).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `initial_investment` | number |  | required | Outlay at time 0, entered as a positive number. (> 0, max 1000000000000000) |
| `cash_flows` | number_list |  | required | Net cash flow at the end of periods 1, 2, 3 … (negative values allowed). |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `irr_percent` | number | % per period | Rate at which NPV = 0 (annual if the cash flows are yearly). |
| `net_undiscounted_gain` | number |  | Σ cash_flows − initial_investment (NPV at 0 %). |
| `total_cash_flows` | number |  | Σ cash_flows. |
| `number_of_periods` | integer |  | Length of cash_flows. |
| `sign_changes` | integer |  | Sign changes in the series (−investment, CF_1 … CF_n); more than 1 means several IRRs can exist. |

## Formula

`Solve −initial_investment + Σ_{t=1..n} cash_flows[t] / (1 + IRR)^t = 0 for IRR by bisection on (−99 %, 1000 %)`

Bisection to machine precision on the NPV function, which is guaranteed to converge when the series has one sign change (conventional investment). The IRR is a per-period rate and assumes interim cash flows are reinvested at the IRR.

## Data Sources

- Investopedia – Internal Rate of Return (IRR): Formula and Examples — https://www.investopedia.com/terms/i/irr.asp (reference, retrieved 2026-09-24)
- Wikipedia – Internal rate of return — https://en.wikipedia.org/wiki/Internal_rate_of_return (reference, retrieved 2026-09-24)

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/irr?initial_investment=…&cash_flows=…`
- `POST https://tttkmbb.com/api/v1/calculate/irr` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/irr · OpenAPI operationId `calculate_irr` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "irr", "inputs": {…}}`

## Example

- −1,000 then 500, 400, 300: inputs `{"initial_investment":1000,"cash_flows":[500,400,300]}` → `{"irr_percent":10.65,"net_undiscounted_gain":200,"total_cash_flows":1200,"number_of_periods":3,"sign_changes":1}`
- −10,000 then 3,000, 4,000, 5,000, 2,000: inputs `{"initial_investment":10000,"cash_flows":[3000,4000,5000,2000]}` → `{"irr_percent":15.32,"net_undiscounted_gain":4000,"sign_changes":1}`

```
GET https://tttkmbb.com/api/v1/calculate/irr?initial_investment=1000&cash_flows=500%2C400%2C300
```

## Limitations

Cash flows change sign more than once (multiple IRRs may exist; use npv at your hurdle rate), or there are only two values (use cagr). Bisection to machine precision on the NPV function, which is guaranteed to converge when the series has one sign change (conventional investment). The IRR is a per-period rate and assumes interim cash flows are reinvested at the IRR. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why can there be no IRR?**

If the cash flows never turn positive (or the series never changes sign) NPV never crosses zero, so no rate satisfies the equation; the calculator returns CALCULATION_ERROR in that case.

**IRR or NPV?**

NPV measures value created at your required return and ranks mutually exclusive projects correctly; IRR is a convenient rate for comparing against a hurdle rate but can mislead when project sizes or timings differ.

## Related

- [NPV Calculator](https://tttkmbb.com/finance/npv.md) — Value of the same cash flows at a chosen rate.
- [CAGR Calculator](https://tttkmbb.com/finance/cagr.md) — Return between a single start and end value.
- [ROI Calculator](https://tttkmbb.com/finance/roi.md) — Simple total return without timing.