Internal Rate of Return

Overview

You send cashflows numbered by period; we search for the rate whose net present value is zero, using halving over the fixed range -0.999999 to 10 so the same series always gives the same rate. When a series has more than one sign change it may have several real answers, and we say so instead of picking one: you get converged false and a reason rather than a number nobody can defend. Discounting is shared with finance.npv, so both skills agree on what a rate means.

Spreadsheet rate functions start from a guess, so two people with the same cashflows can get two different rates and neither can prove which is right. We fix the range, halve it in exact decimals, and tell you when your series simply does not have one answer.

When to use it

Scope

Non-goals

• Does not pick one answer when a series has several real ones
• Does not use your starting guess, so it cannot drift to a different root
• Does not convert dates to periods or handle several currencies
• Does not compare the result against a hurdle rate for you

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"finance.irr","input":{"cashflows":[{"period":0,"amount":"-1000.00"},{"period":1,"amount":"500.00"},{"period":2,"amount":"500.00"},{"period":3,"amount":"500.00"}]}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("finance.irr", {"cashflows":[{"period":0,"amount":"-1000.00"},{"period":1,"amount":"500.00"},{"period":2,"amount":"500.00"},{"period":3,"amount":"500.00"}]});

Errors

Other limits

Limitations

• Does not pick one answer when a series has several real ones
• Does not use your starting guess, so it cannot drift to a different root
• Does not convert dates to periods or handle several currencies
• Does not compare the result against a hurdle rate for you
• Series that swing between paying out and paying in repeatedly
• Cashflows still expressed as calendar dates
• Comparing projects of different sizes, where the rate flatters the smaller one

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "finance.irr",
  "input": {
    "cashflows": [
      {
        "period": 0,
        "amount": "-1000.00"
      },
      {
        "period": 1,
        "amount": "500.00"
      },
      {
        "period": 2,
        "amount": "500.00"
      },
      {
        "period": 3,
        "amount": "500.00"
      }
    ]
  }
}

Examples

{
  "cashflows": [
    {
      "period": 0,
      "amount": "-1000.00"
    },
    {
      "period": 1,
      "amount": "500.00"
    },
    {
      "period": 2,
      "amount": "500.00"
    },
    {
      "period": 3,
      "amount": "500.00"
    }
  ]
}

{
  "bracket": {
    "low": "-0.999999",
    "high": "10"
  },
  "irr": "0.233751928528",
  "tolerance": "0.000000000001",
  "residualNpv": "0.00000000089",
  "reasonCode": "CONVERGED",
  "converged": true,
  "iterations": 44,
  "signChanges": 1
}

{
  "cashflows": [
    {
      "period": 0,
      "amount": "-100.00"
    },
    {
      "period": 1,
      "amount": "300.00"
    },
    {
      "period": 2,
      "amount": "-250.00"
    }
  ]
}

{
  "signChanges": 2,
  "converged": false,
  "tolerance": "0.000000000001",
  "bracket": {
    "low": "-0.999999",
    "high": "10"
  },
  "reasonCode": "MULTIPLE_SIGN_CHANGES",
  "iterations": 0
}

Recommended use cases

• Report the return on an investment with one outlay and later receipts
• Check whether a payment plan clears an agreed hurdle rate
• Reproduce a spreadsheet rate with an answer you can audit

Avoid for

• Series that swing between paying out and paying in repeatedly
• Cashflows still expressed as calendar dates
• Comparing projects of different sizes, where the rate flatters the smaller one

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags