{ "openapi": "3.1.0", "info": { "title": "Canadian Retirement Calculator API", "version": "1.0.0", "description": "Backtests a Canadian retirement plan (CPP, OAS with clawback, RRSP, TFSA, FHSA, non-registered) against every starting year from 1871 to 2022. Amounts are in today's Canadian dollars. Educational estimate, not financial advice." }, "servers": [ { "url": "https://www.caficalc.app" } ], "paths": { "/api/calculate": { "get": { "operationId": "calculateRetirementPlan", "summary": "Run a Canadian retirement plan and get its historical success rate", "description": "All parameters are optional; omitted ones use a typical 35-year-old Canadian. Returns success rate, savings at retirement, ending balance percentiles, CPP and OAS, the leanest year of income, the worst start year, the 95%-safe value for the chosen strategy, and an openInCalculator link.", "parameters": [ { "name": "age", "in": "query", "required": false, "description": "Current age", "schema": { "type": "integer", "default": 35 } }, { "name": "retAge", "in": "query", "required": false, "description": "Retirement age", "schema": { "type": "integer", "default": 65 } }, { "name": "endAge", "in": "query", "required": false, "description": "Plan until this age", "schema": { "type": "integer", "default": 95 } }, { "name": "rrsp", "in": "query", "required": false, "description": "RRSP/RRIF/LIRA balance today", "schema": { "type": "number", "default": 30000 } }, { "name": "rrspC", "in": "query", "required": false, "description": "RRSP contributions per year until retirement", "schema": { "type": "number", "default": 4000 } }, { "name": "tfsa", "in": "query", "required": false, "description": "TFSA balance today", "schema": { "type": "number", "default": 19000 } }, { "name": "tfsaC", "in": "query", "required": false, "description": "TFSA contributions per year until retirement", "schema": { "type": "number", "default": 5000 } }, { "name": "fhsa", "in": "query", "required": false, "description": "FHSA balance today", "schema": { "type": "number", "default": 0 } }, { "name": "fhsaC", "in": "query", "required": false, "description": "FHSA contributions per year (max 8000)", "schema": { "type": "number", "default": 0 } }, { "name": "fhsaUsed", "in": "query", "required": false, "description": "FHSA lifetime contributions so far (max 40000)", "schema": { "type": "number", "default": 0 } }, { "name": "fhsaUse", "in": "query", "required": false, "description": "What happens to the FHSA: home (buy a first home) or rrsp (move to RRSP)", "schema": { "type": "string", "default": "home", "enum": [ "home", "rrsp" ] } }, { "name": "fhsaAge", "in": "query", "required": false, "description": "Age the FHSA is used for a home or moved to the RRSP", "schema": { "type": "integer", "default": 40 } }, { "name": "nonreg", "in": "query", "required": false, "description": "Non-registered investments today", "schema": { "type": "number", "default": 5000 } }, { "name": "nonregC", "in": "query", "required": false, "description": "Non-registered contributions per year", "schema": { "type": "number", "default": 0 } }, { "name": "nonregAcb", "in": "query", "required": false, "description": "Amount originally invested in non-registered accounts (cost base)", "schema": { "type": "number", "default": 4500 } }, { "name": "strat", "in": "query", "required": false, "description": "Withdrawal strategy: target, cd (4% rule), fixed, vpw", "schema": { "type": "string", "default": "target", "enum": [ "target", "cd", "fixed", "vpw" ] } }, { "name": "spend", "in": "query", "required": false, "description": "Yearly spending before tax, today's dollars (strat=target)", "schema": { "type": "number", "default": 45000 } }, { "name": "wr", "in": "query", "required": false, "description": "First-year withdrawal rate in percent (strat=cd)", "schema": { "type": "number", "default": 4 } }, { "name": "wAmt", "in": "query", "required": false, "description": "Yearly amount taken from savings (strat=fixed)", "schema": { "type": "number", "default": 20000 } }, { "name": "pension", "in": "query", "required": false, "description": "Workplace pension per year from retirement", "schema": { "type": "number", "default": 0 } }, { "name": "cppAge", "in": "query", "required": false, "description": "CPP start age, 60 to 70", "schema": { "type": "integer", "default": 65 } }, { "name": "cppPct", "in": "query", "required": false, "description": "Your CPP as a percent of the maximum", "schema": { "type": "number", "default": 60 } }, { "name": "oasAge", "in": "query", "required": false, "description": "OAS start age, 65 to 70", "schema": { "type": "integer", "default": 65 } }, { "name": "res", "in": "query", "required": false, "description": "Years living in Canada after 18 by 65 (40 = full OAS)", "schema": { "type": "integer", "default": 40 } }, { "name": "stock", "in": "query", "required": false, "description": "Percent in stocks (rest in bonds)", "schema": { "type": "number", "default": 70 } }, { "name": "fee", "in": "query", "required": false, "description": "Yearly investment fees in percent", "schema": { "type": "number", "default": 0.25 } }, { "name": "mode", "in": "query", "required": false, "description": "hist (backtest every start year 1871-2022) or fixed (one fixed-return scenario)", "schema": { "type": "string", "default": "hist", "enum": [ "hist", "fixed" ] } }, { "name": "ret", "in": "query", "required": false, "description": "Fixed yearly return in percent (mode=fixed)", "schema": { "type": "number", "default": 6 } }, { "name": "inf", "in": "query", "required": false, "description": "Fixed inflation in percent (mode=fixed)", "schema": { "type": "number", "default": 2.5 } } ], "responses": { "200": { "description": "Plan results", "content": { "application/json": { "schema": { "type": "object", "properties": { "inputs": { "type": "object" }, "results": { "type": "object" }, "units": { "type": "string" }, "openInCalculator": { "type": "string", "format": "uri" }, "assumptions": { "type": "object" }, "disclaimer": { "type": "string" } } } } } } } } } } }