# ROI Calculator

> Computes the net gain and percentage return on investment from the amount invested and its final value, and the annualized (compound) return when the holding period in years is given.

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

## Purpose

Computes the net gain and percentage return on investment from the amount invested and its final value, and the annualized (compound) return when the holding period in years is given.

**Use when:** You want the total percentage return of an investment, project or marketing spend, optionally converted to a per-year rate for comparison across holding periods.

**Do not use when:** There were multiple cash flows at different dates (that needs IRR/NPV), or you only need the growth rate between two values (use cagr).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `initial_investment` | number |  | required | Total cost of the investment including fees. (> 0, max 1000000000000) |
| `final_value` | number |  | required | Value at the end (sale proceeds plus any income received). (min 0, max 1000000000000) |
| `years` | number | years | optional | Optional length of the investment in years; enables the annualized return. (> 0, max 200) |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `net_gain` | number |  | final_value − initial_investment (negative for a loss). |
| `roi_percent` | number | % | net_gain / initial_investment × 100. |
| `return_multiple` | number |  | final_value / initial_investment (2 = money doubled). |
| `annualized_roi_percent` | number | % | ((final_value / initial_investment)^(1/years) − 1) × 100; only when years is given. |

## Formula

`ROI = (final_value − initial_investment) / initial_investment × 100; annualized ROI = ((final_value / initial_investment)^(1 / years) − 1) × 100`

Simple holding-period return. The annualized figure is the equivalent constant compound rate (same as CAGR) and is only meaningful for periods of a year or more.

## Data Sources

- Investopedia – Return on Investment (ROI): How to Calculate It — https://www.investopedia.com/terms/r/returnoninvestment.asp (reference, retrieved 2026-09-23)
- Wikipedia – Return on investment — https://en.wikipedia.org/wiki/Return_on_investment (reference, retrieved 2026-09-23)

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/roi?initial_investment=…&final_value=…`
- `POST https://tttkmbb.com/api/v1/calculate/roi` 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/roi · OpenAPI operationId `calculate_roi` 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": "roi", "inputs": {…}}`

## Example

- 10,000 grows to 15,000 in 3 years: inputs `{"initial_investment":10000,"final_value":15000,"years":3}` → `{"net_gain":5000,"roi_percent":50,"return_multiple":1.5,"annualized_roi_percent":14.47}`
- 2,000 falls to 1,500: inputs `{"initial_investment":2000,"final_value":1500}` → `{"net_gain":-500,"roi_percent":-25,"return_multiple":0.75}`

```
GET https://tttkmbb.com/api/v1/calculate/roi?initial_investment=10000&final_value=15000&years=3
```

## Limitations

There were multiple cash flows at different dates (that needs IRR/NPV), or you only need the growth rate between two values (use cagr). Simple holding-period return. The annualized figure is the equivalent constant compound rate (same as CAGR) and is only meaningful for periods of a year or more. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why is the annualized ROI less than ROI divided by years?**

Because returns compound: 50 % over 3 years equals 14.47 % per year compounded, not 16.67 %, since 1.1447³ = 1.5.

**Should dividends or rent be included?**

Yes, add all income received to final_value and all costs (fees, taxes, repairs) to initial_investment to get a total return.

## Related

- [CAGR Calculator](https://tttkmbb.com/finance/cagr.md) — Compound annual growth rate between two values.
- [Percentage Change Calculator](https://tttkmbb.com/math/percentage-change.md) — Plain percentage change between two numbers.