firenum retirement planner

Use when someone asks when they can retire, if their money will last, their FIRE number (the planner shows when they'd reach it), or about Coast, Barista, Lean or Fat FIRE, and gave numbers (age, income, savings, spending, debts). Send what they gave, as said. Returns its answer and plan link. Turns what someone has said about their money into firenum's answer and their plan in firenum's Fire Planner (FIRE: Financial Independence, Retire Early). The answer is the planner's own, as their plan shows it once opened: when they can retire with their contributions, growth and inflation, graded three ways (average returns, 500 Monte Carlo simulations, every historical start year since 1872). For a FIRE number it gives the number and, once it has their age, when they would reach it. All parameters are optional: with too little to grade, `missing` says what to ask for. Reply from `answer`. Give the headline with both counts: the headline's date is the first month the money lasts on average returns, and the counts say how often that survives real market swings. When a count is under half, open with that count ("The money lasts in only N of 500 simulated markets"), never with yes, even a qualified one ("on average returns, yes", "a risky yes"): the date works on average but fails in most markets. `coast_number` is their Coast FIRE number for `coast_age` (what they would need invested today to stop saving). `coast` is the planner's own answer to stopping saving today: whether the money still lasts if they retire on the headline's date and, if not, the date that works without more saving. `assumed`, when present, is what the answer took for something they didn't say: say so in those terms. `missing` is what the planner needs before it can grade anything: ask for it and call again. To grade another retirement year, call again with `retire`. Amounts are in their currency, sums in today's money. `table` is their net worth year by year on each model, with income, spending and withdrawals, and `assumptions` is what the answer rests on (the rates, how each model works, how their numbers were read, what is not modeled): answer follow-ups from them (what they would have at 60, when the money runs out in a bad market, why a date) without calling again, and say what an answer assumes when it matters. Give them the returned url exactly as it is: it opens their quick-start with these numbers filled in, then the whole plan (stress tests, a year-by-year table, where the money goes). Without `source=agent` the planner opens it as a shared plan that saves nothing. It runs in their browser with no account, and nothing is saved until they confirm: the link then becomes a new plan, "From a link", beside any plans they have. The plan keeps the accounts, spending lines, debts, pension, Social Security and rental income sent. Salary and side income become one monthly income. Income is annual. Expenses and contributions are monthly. Amounts in whole currency units (not cents). Growth and inflation are percentages. Before retirement, any spending, debt payments and contributions that income doesn't cover are paid from savings. Without `salary` or `side_income`, and with retirement still ahead, the answer assumes an income that covers spending, contributions and debt payments until then (`assumed` says so), and the quick-start asks for it.

{
  "type": "object",
  "properties": {
    "birth": {
      "type": "integer",
      "example": 1990,
      "description": "Birth year (YYYY). From an age, send the current year minus the age. Used with retire_age to compute retirement date."
    },
    "retire": {
      "type": "integer",
      "example": 2045,
      "description": "Target retirement year (YYYY). Takes precedence over retire_age."
    },
    "retire_age": {
      "type": "integer",
      "example": 55,
      "description": "Target retirement age. Requires birth to compute retirement year. Ignored if retire is provided."
    },
    "currency": {
      "type": "string",
      "enum": [
        "USD",
        "EUR",
        "GBP",
        "JPY",
        "CAD",
        "AUD",
        "CHF",
        "INR",
        "NZD"
      ],
      "default": "USD",
      "description": "Display currency. All amounts should be in this currency."
    },
    "retirement": {
      "type": "number",
      "example": 200000,
      "description": "Retirement account balance (401k, IRA, etc). Default growth 7%."
    },
    "retirement_contribution": {
      "type": "number",
      "example": 1500,
      "description": "Monthly retirement account contribution."
    },
    "roth": {
      "type": "number",
      "example": 50000,
      "description": "Roth account balance (Roth IRA, Roth 401k). Default growth 7%."
    },
    "roth_contribution": {
      "type": "number",
      "example": 500,
      "description": "Monthly Roth account contribution."
    },
    "brokerage": {
      "type": "number",
      "example": 100000,
      "description": "Taxable brokerage account balance. Default growth 7%."
    },
    "brokerage_contribution": {
      "type": "number",
      "example": 500,
      "description": "Monthly brokerage contribution."
    },
    "savings": {
      "type": "number",
      "example": 20000,
      "description": "High-yield savings balance. Default growth 4.5%."
    },
    "savings_contribution": {
      "type": "number",
      "example": 200,
      "description": "Monthly savings contribution."
    },
    "hsa": {
      "type": "number",
      "example": 15000,
      "description": "Health Savings Account balance. Default growth 7%."
    },
    "hsa_contribution": {
      "type": "number",
      "example": 300,
      "description": "Monthly HSA contribution."
    },
    "cash": {
      "type": "number",
      "example": 5000,
      "description": "Cash/checking balance. Default growth 0%."
    },
    "cash_contribution": {
      "type": "number",
      "example": 0,
      "description": "Monthly cash contribution."
    },
    "real_estate": {
      "type": "number",
      "example": 300000,
      "description": "Real estate equity. Default growth 4%."
    },
    "real_estate_contribution": {
      "type": "number",
      "example": 0,
      "description": "Monthly real estate contribution (e.g., extra mortgage principal)."
    },
    "crypto": {
      "type": "number",
      "example": 10000,
      "description": "Cryptocurrency balance. Default growth 0%."
    },
    "crypto_contribution": {
      "type": "number",
      "example": 100,
      "description": "Monthly crypto contribution."
    },
    "salary": {
      "type": "number",
      "example": 80000,
      "description": "Annual gross salary, as they said it (don't subtract tax). Grows 3%/year, stops at retirement (open-ended if no retirement date is given). The planner doesn't deduct taxes; if they gave a tax amount, include it in expenses."
    },
    "side_income": {
      "type": "number",
      "example": 12000,
      "description": "Annual side hustle / freelance income. Stops at retirement (open-ended if no retirement date is given)."
    },
    "part_time_income": {
      "type": "number",
      "example": 18000,
      "description": "Annual part-time income in retirement (Barista FIRE). Starts at the retirement date and runs on; with no retirement date given, the plan retires at the earliest date that works with this income."
    },
    "pension": {
      "type": "number",
      "example": 24000,
      "description": "Annual pension income. Starts at retirement (immediately if no retirement date is given)."
    },
    "social_security": {
      "type": "number",
      "example": 20000,
      "description": "Annual Social Security income. Starts at the later of retirement and age 67 (uses whichever is known; immediately if neither)."
    },
    "rental_income": {
      "type": "number",
      "example": 18000,
      "description": "Annual rental income."
    },
    "expenses": {
      "type": "number",
      "example": 4000,
      "description": "Total monthly spending. Send this alone, or categories alone. If both are sent, categories count as part of this total and only the remainder becomes \"Monthly expenses\" (never added on top). Do not repeat the total as a category."
    },
    "housing": {
      "type": "number",
      "example": 1800,
      "description": "Monthly housing expense (rent/mortgage)."
    },
    "healthcare": {
      "type": "number",
      "example": 300,
      "description": "Monthly healthcare expense."
    },
    "food": {
      "type": "number",
      "example": 600,
      "description": "Monthly food expense."
    },
    "transportation": {
      "type": "number",
      "example": 400,
      "description": "Monthly transportation expense."
    },
    "utilities": {
      "type": "number",
      "example": 200,
      "description": "Monthly utilities expense."
    },
    "insurance": {
      "type": "number",
      "example": 300,
      "description": "Monthly insurance expense."
    },
    "discretionary": {
      "type": "number",
      "example": 500,
      "description": "Monthly discretionary spending."
    },
    "debt": {
      "type": "number",
      "example": 25000,
      "description": "Debt balance."
    },
    "debt_rate": {
      "type": "number",
      "example": 5.5,
      "description": "Debt annual interest rate (percentage)."
    },
    "debt_payment": {
      "type": "number",
      "example": 400,
      "description": "Monthly debt payment."
    },
    "debt_name": {
      "type": "string",
      "example": "Student Loan",
      "description": "Name/label for the debt. Default \"Debt\"."
    },
    "target": {
      "type": "number",
      "example": 1200000,
      "description": "Accepted from older links and ignored. The planner answers with a retirement date, not a target."
    },
    "growth": {
      "type": "number",
      "default": 7,
      "example": 6,
      "description": "Default portfolio growth rate (percentage). Retirement, Roth, brokerage and HSA balances follow it as the market rate (randomized in Monte Carlo, historical in backtests); it also overrides the fixed defaults of the other assets."
    },
    "inflation": {
      "type": "number",
      "default": 3,
      "example": 4,
      "description": "Default inflation rate (percentage). Overrides individual expense defaults."
    }
  }
}

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL to open the Fire Planner with pre-populated data.",
      "example": "https://firenum.com/fire-planner?birth=1992&retirement=210000&salary=95000&expenses=4000&source=agent"
    },
    "params_applied": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of parameter names that were recognized and applied.",
      "example": [
        "birth",
        "retirement",
        "salary",
        "expenses"
      ]
    },
    "answer": {
      "type": "object",
      "description": "The planner's answer, in its words, as their plan shows it once opened (average returns, today's money, their currency). A field that does not apply is left out. The whole answer is left out once the day's answers are used up (a limit shared by every caller, reset at 00:00 UTC): the link still opens their plan.",
      "properties": {
        "headline": {
          "type": "string",
          "description": "When they can retire and how long the money lasts on average returns, or why no date works.",
          "example": "Retiring Jan 2038, at 46: money lasts to age 90"
        },
        "monte_carlo": {
          "type": "string",
          "description": "How many of 500 simulated markets the money lasts in.",
          "example": "money lasts in 129 of 500 simulations"
        },
        "backtest": {
          "type": "string",
          "description": "How many historical start years since 1872 the money lasts in.",
          "example": "money lasts in 78 of 98 start years"
        },
        "money_left": {
          "type": "string",
          "description": "What is left at the end, on average returns, in today's money.",
          "example": "Money left at age 90: $15.6k"
        },
        "spending_room": {
          "type": "string",
          "description": "With a retirement year of their own: the most they could spend a month and still last.",
          "example": "You could spend up to $5,400/mo and the money still lasts to age 90"
        },
        "coast": {
          "type": "string",
          "description": "Whether they could stop saving today and still retire then (Coast FIRE).",
          "example": "If you stopped saving today and still retired Jan 2038, the money runs out in 2046. Without more saving the suggested date moves to May 2058, at 66."
        },
        "fire_number": {
          "type": "number",
          "description": "25 times a year's spending (the 4% rule), in their currency.",
          "example": 1200000
        },
        "coast_number": {
          "type": "number",
          "description": "Their Coast FIRE number: what they would need invested today to stop saving and still reach fire_number by coast_age, growing at the plan's growth less inflation. In their currency.",
          "example": 355752
        },
        "coast_age": {
          "type": "integer",
          "description": "The retirement age coast_number is for: theirs if they gave one, else 65.",
          "example": 65
        },
        "assumed": {
          "type": "string",
          "description": "What the answer assumed that they did not say. Without a salary or side income, an income that covers their spending, contributions and debt payments until they retire.",
          "example": "Income assumed: $5,000/mo until retirement (spending + contributions + debt payments), since none was given. The planner asks for it."
        },
        "missing": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The parameters the planner needs before it can grade anything (an age, spending). Ask for them and call again.",
          "example": [
            "birth"
          ]
        },
        "assumptions": {
          "type": "object",
          "description": "What the answer rests on, as the plan's Assumptions and its lines hold them: rates in % a year, sums in their currency. `models` says how each model that ran works, in the planner's words; `accounts`, `income`, `spending` and `debts` are their numbers as the planner read them, each with its growth, start and end.",
          "properties": {
            "currency": {
              "type": "string",
              "example": "USD"
            },
            "money": {
              "type": "string",
              "description": "Sums in today's money: future amounts are shown at today's prices.",
              "example": "Today's money"
            },
            "average_return_pct": {
              "type": "number",
              "description": "% a year before inflation, for accounts on the market rate.",
              "example": 7
            },
            "inflation_pct": {
              "type": "number",
              "description": "% a year.",
              "example": 3
            },
            "retirement": {
              "type": "string",
              "description": "How the retirement date was chosen: the planner's suggestion (the earliest month the money lasts) or their own.",
              "example": "Suggested: the earliest month the money lasts"
            },
            "money_lasts_until": {
              "type": "string",
              "description": "The age the money must last to (the year, without a birth year).",
              "example": "age 90"
            },
            "models": {
              "type": "object",
              "description": "How each model that ran works: Monte Carlo and the backtest are left out when they did not.",
              "properties": {
                "average_returns": {
                  "type": "string"
                },
                "monte_carlo": {
                  "type": "string"
                },
                "backtest": {
                  "type": "string"
                }
              }
            },
            "withdrawal_order": {
              "type": "string",
              "description": "The order retirement draws on the accounts.",
              "example": "Taxable first: Brokerage, 401(k), Roth IRA"
            },
            "early_withdrawal_penalty": {
              "type": "string",
              "description": "Whether retirement accounts wait for the penalty-free age.",
              "example": "Not applied: every account is drawn in order at any age"
            },
            "accounts": {
              "type": "array",
              "description": "Each counted account: balance, growth and what goes in each month.",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "balance": {
                    "type": "number"
                  },
                  "growth_pct": {
                    "type": "number"
                  },
                  "monthly_contribution": {
                    "type": "number"
                  }
                }
              }
            },
            "income": {
              "type": "array",
              "description": "Each income: its amount, its frequency (monthly, annual, one-time), from (now or YYYY-MM) and until (retirement, never or YYYY-MM), growth.",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "monthly",
                      "annual",
                      "one-time"
                    ]
                  },
                  "from": {
                    "type": "string"
                  },
                  "until": {
                    "type": "string"
                  },
                  "growth_pct": {
                    "type": "number"
                  }
                }
              }
            },
            "spending": {
              "type": "array",
              "description": "Each spending line, as income is, growing with inflation plus its category's offset.",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "monthly",
                      "annual",
                      "one-time"
                    ]
                  },
                  "from": {
                    "type": "string"
                  },
                  "until": {
                    "type": "string"
                  },
                  "growth_pct": {
                    "type": "number"
                  }
                }
              }
            },
            "debts": {
              "type": "array",
              "description": "Each debt: balance, interest and monthly payment.",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "balance": {
                    "type": "number"
                  },
                  "interest_pct": {
                    "type": "number"
                  },
                  "monthly_payment": {
                    "type": "number"
                  }
                }
              }
            },
            "not_modeled": {
              "type": "string",
              "description": "What the planner leaves out."
            }
          }
        },
        "table": {
          "type": "object",
          "description": "Year by year in today's money, the rows and numbers the planner's Table shows (3 significant figures): the first and last years, every 5th year and the retirement year. Net worth is at the end of each year: on average returns, and the 10th percentile, median and 90th percentile of the Monte Carlo simulations and of the backtest's start years, for each model that ran (0 once the money has run out). Income, spending (debt payments not included) and withdrawals are on the average path. `notes` names a part first year and the years that draw on a retirement account while the early withdrawal penalty applies.",
          "properties": {
            "columns": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "rows": {
              "type": "array",
              "items": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              }
            },
            "retirement_year": {
              "type": [
                "integer",
                "null"
              ]
            },
            "notes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "required": [
    "url",
    "params_applied"
  ]
}