Return on investment (ROI) API
Gain, ROI percentage and annualized return (CAGR) of an investment.
POST https://api.curatedapi.com/v1/calc/finance/roi
- Version 1
- MCP tool
calc_finance_roi - Try it in the browser
ROI = (amount returned − amount invested) ÷ amount invested. With the holding period in years, also returns the annualized return (compound annual growth rate): (returned ÷ invested)^(1 ÷ years) − 1.
Formula
ROI = (R − I) ÷ I; annualized = (R ÷ I)^(1/years) − 1
- Amounts are plain numbers in any single currency; no currency conversion is done.
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
amount_invested required |
decimal (string) | Total amount put in. Allowed: > 0 and <= 1000000000000000. Unit: currency. |
amount_returned required |
decimal (string) | Total amount received back (sale value plus income). Allowed: >= 0 and <= 1000000000000000. Unit: currency. |
years |
decimal (string) | Holding period in years, for the annualized return. Allowed: > 0 and <= 1000. Unit: years. |
options.rounding |
half_even | half_up | half_down | up | down | ceiling | floor | Rounding mode applied once to each result. Default half_even. |
options.decimals |
integer | Round results to this many digits after the decimal point. |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
gain | decimal (string) | Amount returned minus amount invested. Unit: currency. |
roi_percent | decimal (string) | Return on investment in percent. Unit: percent. |
annualized_roi_percent | decimal (string) | Compound annual growth rate in percent. Unit: percent. |
Examples
10,000 grows to 14,500 in 3 years
curl https://api.curatedapi.com/v1/calc/finance/roi \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_invested": "10000",
"amount_returned": "14500",
"years": "3"
}'
{
"calculator": "finance/roi@1",
"result": {
"gain": "4500.00",
"roi_percent": "45.00",
"annualized_roi_percent": "13.19"
},
"exactness": {
"gain": "exact",
"roi_percent": "exact",
"annualized_roi_percent": "rounded"
},
"precision": {
"rounding": "half_even",
"decimals": 2
},
"inputs": {
"amount_invested": "10000",
"amount_returned": "14500",
"years": "3"
},
"formula": "ROI = (R − I) ÷ I; annualized = (R ÷ I)^(1/years) − 1",
"references": [
{
"title": "Compound annual growth rate (CAGR)",
"url": "https://en.wikipedia.org/wiki/Compound_annual_growth_rate"
}
],
"warnings": []
}
References
Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.
Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.