curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

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

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).

InputTypeDescription
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.

ResultTypeDescription
irr_percentdecimal (string)IRR per period, in percent. Unit: percent.
all_irr_percentlist of stringEvery IRR found, lowest first, in percent.
irr_is_uniquebooleanTrue when there is exactly one IRR.
sign_changesintegerHow many times the cash flows change sign.
annual_effective_irr_percentdecimal (string)(1 + IRR)^periods_per_year − 1, in percent. Unit: percent.

Examples

ECMA-376 example

Requestcurl
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"]
  }'
200 OKResponse
{
  "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%

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/irr \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cash_flows": ["-100", "110"]
  }'
200 OKResponse
{
  "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.