Internal rate of return (IRR) API
Internal rate of return of periodic cash flows, with every IRR reported when there is more than one.
POST https://api.curatedapi.com/v1/calc/finance/irr
- Version 1
- MCP tool
calc_finance_irr - Try it in the browser
Finds the discount rate at which the net present value of the cash flows is zero. Unlike spreadsheet IRR(), no starting guess is needed: all IRRs between −100% and the mathematical bound are searched, each one is pinned down with exact arithmetic, and the result is correctly rounded. When the cash flows change sign more than once there can be several IRRs; all are returned and a warning explains.
Formula
Σ CFₜ / (1 + IRR)ᵗ = 0
- Cash flows are one period apart; the first one is at time 0.
- 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 |
|---|---|---|
cash_flows required |
list of decimal (string) | Cash flows in time order, one per period. Money paid out is negative, money received is positive. 2 to 600 items. Each item: >= -1000000000000000 and <= 1000000000000000. |
periods_per_year |
integer | Set to 12 for monthly flows, 4 for quarterly, ... to also get the effective annual IRR. Allowed: >= 1 and <= 365. |
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. |
options.significant_digits |
integer | Round results to this many significant digits. |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
irr_percent | decimal (string) | IRR per period, in percent. Unit: percent. |
all_irr_percent | list of string | Every IRR found, lowest first, in percent. |
irr_is_unique | boolean | True when there is exactly one IRR. |
sign_changes | integer | How many times the cash flows change sign. |
annual_effective_irr_percent | decimal (string) | (1 + IRR)^periods_per_year − 1, in percent. Unit: percent. |
Examples
ECMA-376 example
curl https://api.curatedapi.com/v1/calc/finance/irr \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"cash_flows": ["-70000", "12000", "15000", "18000", "21000", "26000"]
}'
{
"calculator": "finance/irr@1",
"result": {
"irr_percent": "8.6631",
"all_irr_percent": [
"8.6631"
],
"irr_is_unique": true,
"sign_changes": 1
},
"exactness": {
"irr_percent": "rounded"
},
"precision": {
"rounding": "half_even",
"decimals": 4
},
"inputs": {
"cash_flows": [
"-70000",
"12000",
"15000",
"18000",
"21000",
"26000"
]
},
"formula": "Σ CFₜ / (1 + IRR)ᵗ = 0",
"references": [
{
"title": "ECMA-376 (Office Open XML) spreadsheet function IRR, with worked example",
"url": "https://webapp.docx4java.org/OnlineDemo/ecma376/SpreadsheetML/IRR.html"
},
{
"title": "Descartes' rule of signs",
"url": "https://en.wikipedia.org/wiki/Descartes%27_rule_of_signs"
}
],
"warnings": []
}
Exactly 10%
curl https://api.curatedapi.com/v1/calc/finance/irr \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"cash_flows": ["-100", "110"]
}'
{
"calculator": "finance/irr@1",
"result": {
"irr_percent": "10.0000",
"all_irr_percent": [
"10.0000"
],
"irr_is_unique": true,
"sign_changes": 1
},
"exactness": {
"irr_percent": "exact"
},
"precision": {
"rounding": "half_even",
"decimals": 4
},
"inputs": {
"cash_flows": [
"-100",
"110"
]
},
"formula": "Σ CFₜ / (1 + IRR)ᵗ = 0",
"references": [
{
"title": "ECMA-376 (Office Open XML) spreadsheet function IRR, with worked example",
"url": "https://webapp.docx4java.org/OnlineDemo/ecma376/SpreadsheetML/IRR.html"
},
{
"title": "Descartes' rule of signs",
"url": "https://en.wikipedia.org/wiki/Descartes%27_rule_of_signs"
}
],
"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.