{"name":"finance","intro":"Money arithmetic, done the way a bank's back office does it rather than the way a language model approximates it: instalments that come from the rounded schedule and reconcile to zero, GST halves whose rounding difference is reported instead of hidden, an IRR found by bisection rather than recalled. Every figure is a `Decimal`. The two readings that silently ruin money maths — is the rate per year or per month, is the amount inclusive of tax — are never guessed: leave them out and the tool asks.","when_to_use":["Quoting an EMI, total interest or an amortisation schedule.","Projecting compound growth, with or without a monthly contribution.","Turning a start and end value into an annualised growth rate.","Valuing a cash-flow series at a discount rate, or finding the rate that makes it break even.","Splitting an Indian invoice amount into base and CGST/SGST or IGST.","Any percentage question where points and percent, or stacked and added discounts, get confused."],"network":false,"related":"[`numbers`](/docs/tools/numbers) for rounding rules, locale formatting and exact allocation · [`math`](/docs/tools/math) for the formulas themselves · [`convert`](/docs/tools/convert) `currency` when the money is in another currency.","docs_url":"/docs/tools/finance","modes":[{"name":"emi","purpose":"Loan instalment, total interest and the amortisation schedule.","description":"The equal monthly instalment for a reducing-balance loan, from the standard formula `P·r·(1+r)ⁿ / ((1+r)ⁿ−1)`. The instalment is rounded with the stated rule, then the schedule is built month by month with that rounded figure, and the last instalment clears the remaining balance exactly — so `total_interest` and `total_payment` are the sums of what would actually be paid, not the formula times *n*. `decimals: 0` with `rounding: ceil` gives whole-rupee instalments rounded up, as many Indian lenders do. `schedule: true` returns every row.","parameters":[{"name":"principal","type":"string \\| number \\| integer","required":true,"doc":"Loan amount.","default":null},{"name":"rate","type":"string \\| number \\| integer","required":true,"doc":"Interest rate in percent.","default":null},{"name":"rate_period","type":"string","required":true,"doc":"`annual` or `monthly` — what the rate is per. Required; never inferred.","default":null},{"name":"months","type":"string \\| number \\| integer","required":false,"doc":"Term in months (or give `years`).","default":null},{"name":"years","type":"string \\| number \\| integer","required":false,"doc":"Term in years; may be fractional if it is a whole number of months.","default":null},{"name":"schedule","type":"boolean","required":false,"doc":"Return the month-by-month rows.","default":"`false`"},{"name":"decimals","type":"integer","required":false,"doc":"Rounding of each instalment and interest figure.","default":"2"},{"name":"rounding","type":"string","required":false,"doc":"`half_up`, `half_even`, `ceil`, `floor`, `truncate`…","default":"`half_up`"}],"examples":[{"mode":"emi","principal":1000000,"rate":8.5,"rate_period":"annual","years":20},{"mode":"emi","principal":120000,"rate":12,"rate_period":"annual","months":12,"schedule":true},{"mode":"emi","principal":100000,"rate":1,"rate_period":"monthly","months":12},{"mode":"emi","principal":500000,"rate":9,"rate_period":"annual","years":5,"decimals":0,"rounding":"ceil"},{"mode":"emi","principal":100000,"rate":8.5,"months":12},{"mode":"emi","principal":100000,"rate":8.5,"rate_period":"annual"}]},{"name":"compound","purpose":"Future value under compound interest, optionally with regular contributions.","description":"Grows a principal at a rate compounded `annual`, `semiannual`, `quarterly`, `monthly`, `weekly`, `daily` or `continuous`, over a term in years or months, and reports the future value, the interest earned and the effective annual rate the compounding implies. A `contribution` is added every compounding period, at its `end` (ordinary annuity) or `begin` (annuity due) — the SIP case. When no compounding is given, annual is used and said so in `assumptions`. A term over 10 000 years is refused: the power overflows before the answer means anything.","parameters":[{"name":"principal","type":"string \\| number \\| integer","required":true,"doc":"Opening balance; may be 0 for a pure contribution plan.","default":null},{"name":"rate","type":"string \\| number \\| integer","required":true,"doc":"Interest rate in percent.","default":null},{"name":"rate_period","type":"string","required":true,"doc":"`annual` or `monthly` — what the rate is per. Required.","default":null},{"name":"years","type":"string \\| number \\| integer","required":false,"doc":"Term in years (or give `months`).","default":null},{"name":"months","type":"string \\| number \\| integer","required":false,"doc":"Term in months.","default":null},{"name":"compounding","type":"string","required":false,"doc":"How often interest is credited.","default":"`annual`"},{"name":"contribution","type":"string \\| number \\| integer","required":false,"doc":"Amount added each compounding period.","default":"0"},{"name":"contribution_timing","type":"string","required":false,"doc":"`end` or `begin` of each period.","default":"`end`"},{"name":"decimals","type":"integer","required":false,"doc":"Rounding of the money figures.","default":"2"},{"name":"rounding","type":"string","required":false,"doc":"Rounding rule.","default":"`half_up`"}],"examples":[{"mode":"compound","principal":100000,"rate":10,"rate_period":"annual","years":3},{"mode":"compound","principal":100000,"rate":12,"rate_period":"annual","years":1,"compounding":"monthly"},{"mode":"compound","contribution":5000,"rate":12,"rate_period":"annual","years":10,"compounding":"monthly"},{"mode":"compound","principal":100000,"rate":12,"rate_period":"annual","months":12,"compounding":"monthly","contribution":1000},{"mode":"compound","principal":1000,"rate":5,"rate_period":"annual","years":2,"compounding":"continuous"},{"mode":"compound","principal":1000,"rate":5,"years":2},{"mode":"compound","principal":1000,"rate":5,"rate_period":"annual","years":2,"compounding":"continuous","contribution":10}]},{"name":"cagr","purpose":"Compound annual growth rate between two values.","description":"`(end / start)^(1 / years) − 1`, as a percentage to four decimals, alongside the total growth and the multiple. A decline is a negative rate; a zero or negative start value has no growth rate and is refused.","parameters":[{"name":"start_value","type":"string \\| number \\| integer","required":true,"doc":"Value at the start.","default":null},{"name":"end_value","type":"string \\| number \\| integer","required":true,"doc":"Value at the end.","default":null},{"name":"years","type":"string \\| number \\| integer","required":true,"doc":"Elapsed years; fractional is fine.","default":null}],"examples":[{"mode":"cagr","start_value":100,"end_value":200,"years":5},{"mode":"cagr","start_value":200,"end_value":150,"years":2},{"mode":"cagr","start_value":0,"end_value":200,"years":5}]},{"name":"npv_irr","purpose":"Net present value at a rate, and the internal rate of return.","description":"Takes a cash-flow series with the first entry at time 0 (an outlay is negative) and one entry per period after it. With `rate`, returns the NPV at that rate per period. The IRR is always attempted: the rate at which NPV is zero, found by bisection between −99.99% and 1000% — deterministic, no starting guess, no dependence on a spreadsheet's solver. Flows that never change sign have no IRR and say so. `sign_changes` is reported, and when there is more than one the response warns: by Descartes' rule there may be that many IRRs, and the one found is whichever bisection reached first — compare on NPV at your cost of capital instead.","parameters":[{"name":"cashflows","type":"array","required":true,"doc":"Amounts per period, time 0 first.","default":null},{"name":"rate","type":"string \\| number \\| integer","required":false,"doc":"Discount rate in percent per period, for the NPV.","default":null},{"name":"decimals","type":"integer","required":false,"doc":"Rounding of the NPV.","default":"2"},{"name":"rounding","type":"string","required":false,"doc":"Rounding rule.","default":"`half_up`"}],"examples":[{"mode":"npv_irr","cashflows":[-1000,500,500,500],"rate":10},{"mode":"npv_irr","cashflows":[-100,110]},{"mode":"npv_irr","cashflows":[100,110,120]}]},{"name":"gst","purpose":"Split an amount into base and GST, with CGST/SGST or IGST.","description":"Works out the tax-exclusive base and the tax from an amount that is either `inclusive` or `exclusive` of GST — which one is required, because guessing wrong changes the invoice. Intra-state supply splits the tax into equal CGST and SGST halves; `supply: inter` gives a single IGST. Each half is rounded on its own, so when the halves do not add up to the rounded total the difference is reported in `rounding_difference` and a warning, instead of being quietly absorbed. The exact unrounded tax is always included.","parameters":[{"name":"amount","type":"string \\| number \\| integer","required":true,"doc":"The amount to split.","default":null},{"name":"rate","type":"string \\| number \\| integer","required":true,"doc":"GST rate in percent (5, 12, 18, 28…).","default":null},{"name":"amount_is","type":"string","required":true,"doc":"`inclusive` or `exclusive` of GST. Required; never inferred.","default":null},{"name":"supply","type":"string","required":false,"doc":"`intra` (CGST + SGST) or `inter` (IGST).","default":"`intra`"},{"name":"decimals","type":"integer","required":false,"doc":"Rounding of the tax figures.","default":"2"},{"name":"rounding","type":"string","required":false,"doc":"Rounding rule.","default":"`half_up`"}],"examples":[{"mode":"gst","amount":1180,"rate":18,"amount_is":"inclusive"},{"mode":"gst","amount":1000,"rate":18,"amount_is":"exclusive","supply":"inter"},{"mode":"gst","amount":999,"rate":5,"amount_is":"exclusive"},{"mode":"gst","amount":1000,"rate":18}]},{"name":"percent","purpose":"Percentage arithmetic that people get wrong in the same four ways.","description":"`op` picks the calculation. `change` from `a` to `b` reports the relative percent change *and* the difference in percentage points, because 10% → 12.5% is both a 25% change and 2.5 points. `of` is `percent` of `value`. `discount` applies a list of percentages `stacked` (each on the already-discounted price, as shops do) and `additive` (percentages summed first, as people expect), with the effective rate of each. `split` divides a bill plus an optional `tip` percent among `people` using largest-remainder allocation so the shares add up to the total exactly.","parameters":[{"name":"op","type":"string","required":true,"doc":"`change`, `of`, `discount` or `split`.","default":null},{"name":"a","type":"string \\| number \\| integer","required":false,"doc":"Starting value, for `change`.","default":null},{"name":"b","type":"string \\| number \\| integer","required":false,"doc":"Ending value, for `change`.","default":null},{"name":"percent","type":"string \\| number \\| integer","required":false,"doc":"The percentage, for `of` (or a single discount).","default":null},{"name":"value","type":"string \\| number \\| integer","required":false,"doc":"The base value, for `of`.","default":null},{"name":"price","type":"string \\| number \\| integer","required":false,"doc":"List price, for `discount`.","default":null},{"name":"discounts","type":"array","required":false,"doc":"Percentages applied in order, for `discount`.","default":null},{"name":"total","type":"string \\| number \\| integer","required":false,"doc":"The bill, for `split`.","default":null},{"name":"tip","type":"string \\| number \\| integer","required":false,"doc":"Tip in percent, for `split`.","default":"0"},{"name":"people","type":"integer","required":false,"doc":"How many ways to split.","default":null},{"name":"decimals","type":"integer","required":false,"doc":"Rounding of money figures.","default":"2"},{"name":"rounding","type":"string","required":false,"doc":"Rounding rule.","default":"`half_up`"}],"examples":[{"mode":"percent","op":"change","a":50,"b":75},{"mode":"percent","op":"change","a":10,"b":12.5},{"mode":"percent","op":"of","percent":15,"value":200},{"mode":"percent","op":"discount","price":1000,"discounts":[20,10]},{"mode":"percent","op":"split","total":1000,"tip":10,"people":3},{"mode":"percent","op":"change","a":0,"b":5},{"mode":"percent","op":"halve","value":2}]}]}