Savings goal API
How much to save each month (or week, or year) to reach a goal, or how long it takes with a given contribution.
POST https://api.curatedapi.com/v1/calc/finance/savings-goal
- Version 1
- MCP tool
calc_finance_savings_goal - Try it in the browser
Solves the future-value-of-annuity equation either for the regular contribution or for the number of contributions. Interest compounds once per contribution period. The final balance is recomputed exactly with the rounded contribution, so you can see whether it lands on, above or below the goal.
Formula
FV = PV·(1+i)^n + PMT·((1+i)^n − 1)/i [× (1+i) when paid at the start], i = annual rate ÷ periods per year
- 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 |
|---|---|---|
goal_amount required |
decimal (string) | The amount you want to reach. Allowed: > 0 and <= 1000000000000000. Unit: currency. |
current_savings |
decimal (string) default 0 |
Amount already saved. Allowed: >= 0 and <= 1000000000000000. Unit: currency. |
annual_rate_percent required |
decimal (string) | Expected annual interest or return in percent. Allowed: >= 0 and <= 100. Unit: percent. |
solve_for |
contribution | time default contribution |
What to calculate. Options: contribution: the contribution needed to reach the goal in a given time; time: how many contributions are needed with a given contribution |
years |
decimal (string) | Time to reach the goal, in years (solve_for = contribution). Allowed: > 0 and <= 100. Unit: years. |
contribution |
decimal (string) | Contribution per period (solve_for = time). Allowed: > 0 and <= 1000000000000000. Unit: currency. |
contribution_frequency |
monthly | semimonthly | biweekly | weekly | quarterly | annually default monthly |
How often you contribute. Options: monthly: 12 contributions a year; semimonthly: 24 contributions a year; biweekly: 26 contributions a year; weekly: 52 contributions a year; quarterly: 4 contributions a year; annually: 1 contribution a year |
contribution_timing |
end | beginning default end |
When in each period you contribute. Options: end: at the end of each period (ordinary annuity); beginning: at the start of each period (annuity due) |
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 |
|---|---|---|
contribution | decimal (string) | Contribution per period. Unit: currency. |
number_of_contributions | integer | Number of contributions. |
years | string | Number of contributions ÷ contributions per year. |
total_contributions | decimal (string) | Contribution × number of contributions. Unit: currency. |
interest_earned | decimal (string) | Final balance minus savings and contributions. Unit: currency. |
final_balance | decimal (string) | Balance after the last contribution. Unit: currency. |
Examples
20,000 in 3 years at 4%, monthly
curl https://api.curatedapi.com/v1/calc/finance/savings-goal \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"goal_amount": "20000",
"annual_rate_percent": "4",
"years": "3"
}'
{
"calculator": "finance/savings-goal@1",
"result": {
"contribution": "523.81",
"number_of_contributions": 36,
"years": "3",
"total_contributions": "18857.16",
"interest_earned": "1142.72",
"final_balance": "19999.88"
},
"exactness": {
"contribution": "exact",
"total_contributions": "exact",
"interest_earned": "rounded",
"final_balance": "rounded"
},
"precision": {
"rounding": "half_even",
"decimals": 2
},
"inputs": {
"goal_amount": "20000",
"current_savings": "0",
"annual_rate_percent": "4",
"solve_for": "contribution",
"years": "3",
"contribution_frequency": "monthly",
"contribution_timing": "end"
},
"formula": "FV = PV·(1+i)^n + PMT·((1+i)^n − 1)/i [× (1+i) when paid at the start], i = annual rate ÷ periods per year",
"references": [
{
"title": "Future value of an annuity (ordinary annuity and annuity due)",
"url": "https://en.wikipedia.org/wiki/Annuity#Valuation"
}
],
"warnings": [
{
"code": "ROUNDED_SHORT",
"message": "With the contribution rounded to 523.81, the final balance is 0.12 short of the goal; use options.rounding = 'ceiling' to stay at or above it."
}
]
}
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.