{
  "openapi": "3.0.3",
  "info": {
    "title": "Retirement and Debt Planning API",
    "version": "1.5.1",
    "description": "Retirement and FIRE projections, debt payoff, 401(k), IRA and HSA limits, RMD, Social Security, 529 and student loans. Planning maths for savings and debt: retirement projection in today's dollars, FIRE number, avalanche against snowball debt payoff, 401(k), SIMPLE, IRA and HSA limits by tax year with catch-ups, required minimum distributions, Social Security claiming, 529 and college cost, student-loan repayment plans and SIP. Return, inflation and withdrawal rate are your assumptions, never market data. Limits and tables carry a taxYear, sources and dataStatus and are reviewed each year. Estimates for information, not financial advice. Nothing you send is stored. One X-API-Key header authenticates every call, and the same key works across every FreeDailyPro API. Every 4xx response is documented and none of them is billed.",
    "contact": {
      "name": "FreeDailyPro",
      "url": "https://www.freedailypro.com/developers",
      "email": "support@freedailypro.com"
    },
    "termsOfService": "https://www.freedailypro.com/terms",
    "x-logo": {
      "url": "https://www.freedailypro.com/favicon.ico"
    }
  },
  "servers": [
    {
      "url": "https://api.freedailypro.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer hub, plans and MCP setup",
    "url": "https://www.freedailypro.com/developers"
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "tags": [
    {
      "name": "Retirement & Debt Planning",
      "description": "Retirement and FIRE projections, debt payoff, 401(k), IRA and HSA limits, RMD, Social Security, 529 and student loans."
    }
  ],
  "paths": {
    "/v1/converters/sip": {
      "post": {
        "summary": "Project the future value of a monthly SIP investment",
        "operationId": "convertersSip",
        "description": "Project the future value of a monthly SIP investment. Send JSON with monthlyInvestment, annualRatePercent, years (required); optional: startDate. Returns JSON with futureValue, totalInvested, estimatedReturns, months, firstContributionDate, lastContributionDate, maturityDate (inside result). Limits: annualRatePercent: at most 100; years: at most 100. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "monthlyInvestment": {
                    "type": "number",
                    "minimum": 0
                  },
                  "annualRatePercent": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "years": {
                    "type": "number",
                    "maximum": 100,
                    "minimum": 0
                  },
                  "startDate": {
                    "description": "Optional date of the first monthly contribution, as YYYY-MM-DD. Adds firstContributionDate, lastContributionDate and maturityDate. It only labels the plan; the amounts do not change. A day of 29 to 31 moves to the last day of shorter months.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "monthlyInvestment",
                  "annualRatePercent",
                  "years"
                ],
                "additionalProperties": false
              },
              "example": {
                "monthlyInvestment": 500,
                "annualRatePercent": 12,
                "years": 10,
                "startDate": "2026-11-01"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Sip calculator client and server side from freedailypro",
                  "result": {
                    "futureValue": 116169.54,
                    "totalInvested": 60000,
                    "estimatedReturns": 56169.54,
                    "months": 120,
                    "firstContributionDate": "2026-11-01",
                    "lastContributionDate": "2036-10-01",
                    "maturityDate": "2036-11-01"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/fire": {
      "post": {
        "summary": "Estimate the savings target and years needed to reach financial independence",
        "operationId": "convertersFire",
        "description": "Estimate the savings target and years needed to reach financial independence. Send JSON with annualSpend (required); optional: currentSavings, annualContribution, expectedReturnPct, withdrawalRatePct, startDate. Returns JSON with targetNestEgg, yearsToFire, projected, withdrawalRatePct, startDate, fireDate (inside result). Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "annualSpend": {
                    "type": "number"
                  },
                  "currentSavings": {
                    "type": "number",
                    "minimum": 0
                  },
                  "annualContribution": {
                    "type": "number",
                    "minimum": 0
                  },
                  "expectedReturnPct": {
                    "type": "number"
                  },
                  "withdrawalRatePct": {
                    "type": "number",
                    "minimum": 0
                  },
                  "startDate": {
                    "description": "Optional plan start date, as YYYY-MM-DD. When the target is reached, adds startDate and fireDate (the start plus yearsToFire years). It only labels the timeline; the amounts do not change.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "annualSpend"
                ],
                "additionalProperties": false
              },
              "example": {
                "annualSpend": 40000,
                "currentSavings": 50000,
                "annualContribution": 20000,
                "expectedReturnPct": 7,
                "startDate": "2026-11-01"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "FIRE calculator client and server side from freedailypro",
                  "result": {
                    "targetNestEgg": 1000000,
                    "yearsToFire": 20,
                    "projected": 1013394.07,
                    "withdrawalRatePct": 4,
                    "startDate": "2026-11-01",
                    "fireDate": "2046-11-01"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/401k": {
      "post": {
        "summary": "Project a 401(k) balance with the 2026 IRS contribution limits",
        "operationId": "converters401k",
        "description": "Projects a 401(k) balance from the current balance, a yearly employee contribution, an optional employer match (a percent of your own contribution), an expected return and a number of years. The response now includes the 2026 IRS employee deferral limit ($24,500; plus $8,000 catch-up from age 50, or $11,250 at ages 60 to 63) in 'irsLimits', the limit that applies to the 'age' you send (base limit without it), 'contributionExceedsIrsLimit' and a note. The contribution is used as sent unless you set 'applyIrsLimit': true, which caps it at the limit. 'startDate' still only labels the plan. Where the data comes from: IRS Notice 2025-67 for tax year 2026. Update process: limits live in one table file shared with the FreeDailyPro website and are updated by FreeDailyPro every November when the IRS announces next year's limits. Not modelled: the overall section 415(c) limit, future limit increases, salary growth. Estimate, not financial advice. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "currentBalance": {
                    "type": "number",
                    "minimum": 0
                  },
                  "annualContribution": {
                    "type": "number",
                    "minimum": 0
                  },
                  "employerMatchPct": {
                    "description": "Employer match as a percent of your own contribution (50 = 50 cents per dollar).",
                    "type": "number",
                    "minimum": 0
                  },
                  "expectedReturnPct": {
                    "type": "number"
                  },
                  "years": {
                    "type": "number"
                  },
                  "age": {
                    "description": "Your age. Used to pick the 2026 IRS employee limit ($24,500; plus $8,000 catch-up at 50-59 and 64+, $11,250 at 60-63). Without it the base limit is used.",
                    "type": "number"
                  },
                  "applyIrsLimit": {
                    "description": "true caps annualContribution at the IRS limit for your age. Default false: the contribution is used as sent and a warning is returned if it is over the limit.",
                    "type": "boolean"
                  },
                  "startDate": {
                    "description": "Optional date the first contribution year starts, as YYYY-MM-DD. Adds startDate and endDate (when the projection ends). It only labels the plan; the amounts do not change.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "currentBalance",
                  "annualContribution",
                  "years"
                ],
                "additionalProperties": false
              },
              "example": {
                "currentBalance": 20000,
                "annualContribution": 7500,
                "employerMatchPct": 50,
                "expectedReturnPct": 7,
                "years": 30,
                "age": 45,
                "startDate": "2026-11-01"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "401(k) projection with the 2026 IRS contribution limits",
                  "result": {
                    "projectedBalance": 1214928.95,
                    "years": 30,
                    "totalContributed": 357500,
                    "taxYear": 2026,
                    "annualContributionUsed": 7500,
                    "irsLimits": {
                      "employeeDeferral": 24500,
                      "catchUpAge50": 8000,
                      "catchUpAge60to63": 11250,
                      "limitForAge": 24500,
                      "ageUsed": 45
                    },
                    "contributionExceedsIrsLimit": false,
                    "sources": "IRS Notice 2025-67 (2026 401(k) elective deferral limit $24,500; catch-up $8,000 at 50+, $11,250 at 60-63). FreeDailyPro updates these tables once a year, in November, when the IRS and SSA publish next year's figures.",
                    "dataStatus": "checked",
                    "notes": [
                      "annualContribution is within the 2026 employee limit of $24,500 for age 45.",
                      "annualContribution is the employee's own yearly deferral; employerMatchPct is the employer's extra percent of that deferral (50 means 50 cents per dollar), with no match cap. The same amount is assumed every year and the limit is not indexed for future years. The overall 415(c) limit on employee plu..."
                    ],
                    "disclaimer": "Estimate for information only. Not tax, legal or financial advice; check the figures with the tax authority or a qualified adviser.",
                    "startDate": "2026-11-01",
                    "endDate": "2056-11-01"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing balance, contribution or years, a negative value, an invalid startDate, or an age outside 0 to 120 Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/rmd": {
      "post": {
        "summary": "Calculate a required minimum distribution from the IRS Uniform Lifetime Table",
        "operationId": "convertersRmd",
        "description": "Divides the prior year-end 'accountBalance' by the IRS Uniform Lifetime Table divisor for the 'age' you reach this year (72 to 120, for example 75 gives 24.6). Optional 'birthYear' adds the SECURE 2.0 start age (73 if born 1951 to 1959, 75 if born 1960 or later, 72 before) and 'rmdRequiredThisYear'. The first version used a straight-line approximation of the table; this version uses the real table. The table is for account owners; it is not right for an owner whose only beneficiary is a spouse more than 10 years younger (Joint and Last Survivor table) or for inherited accounts (Single Life table). Where the data comes from: IRS Publication 590-B (Uniform Lifetime Table, in force since 2022); the table has not changed for 2026. Update process: one table file shared with the FreeDailyPro website; FreeDailyPro re-checks it every November and whenever the IRS publishes a new table. Estimate, not tax advice. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "accountBalance": {
                    "type": "number",
                    "description": "Account balance on 31 December of the previous year."
                  },
                  "age": {
                    "type": "number",
                    "description": "Age you reach this year (72 to 120). The IRS Uniform Lifetime Table divisor for that age is used."
                  },
                  "birthYear": {
                    "description": "Birth year. Adds the SECURE 2.0 RMD start age (73 for 1951-1959, 75 for 1960 or later) and whether an RMD is required yet.",
                    "type": "number"
                  }
                },
                "required": [
                  "accountBalance",
                  "age"
                ],
                "additionalProperties": false
              },
              "example": {
                "accountBalance": 500000,
                "age": 75,
                "birthYear": 1951
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "RMD estimator using the IRS Uniform Lifetime Table",
                  "result": {
                    "factor": 24.6,
                    "rmd": 20325.2,
                    "age": 75,
                    "accountBalance": 500000,
                    "table": "IRS Uniform Lifetime Table (2022 onward)",
                    "taxYear": 2026,
                    "rmdStartAge": 73,
                    "rmdRequiredThisYear": true,
                    "sources": "IRS Publication 590-B Uniform Lifetime Table (in force since 2022) and SECURE 2.0 start ages (73 if born 1951-1959, 75 if born 1960 or later). FreeDailyPro updates these tables once a year, in November, when the IRS and SSA publish next year's figures.",
                    "dataStatus": "checked",
                    "notes": [
                      "Divisor 24.6 is the IRS Uniform Lifetime Table (in force since 2022) for the age you reach this year. The table is for account owners; it is not for an owner whose only beneficiary is a spouse more than 10 years younger (Joint and Last Survivor table) or for inherited accounts (Single Life table).",
                      "Use the account balance on 31 December of the previous year. Several IRAs are added together; each 401(k) is calculated on its own.",
                      "SECURE 2.0: RMDs start at age 73 for someone born in 1951."
                    ],
                    "disclaimer": "Estimate for information only. Not tax, legal or financial advice; check the figures with the tax authority or a qualified adviser."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Negative balance, an age that is not a whole number from 72 to 120, or an invalid birthYear Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/529": {
      "post": {
        "summary": "Project the balance of a 529 college savings plan from monthly contributions",
        "operationId": "converters529",
        "description": "Project the balance of a 529 college savings plan from monthly contributions. Send JSON with currentBalance, monthlyContribution, years (required); optional: expectedReturnPct, firstContributionDate. Returns JSON with projected, months, totalContributed, firstContributionDate, lastContributionDate, targetDate (inside result). Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "currentBalance": {
                    "type": "number",
                    "minimum": 0
                  },
                  "monthlyContribution": {
                    "type": "number",
                    "minimum": 0
                  },
                  "years": {
                    "type": "number"
                  },
                  "expectedReturnPct": {
                    "type": "number"
                  },
                  "firstContributionDate": {
                    "description": "Optional date of the first monthly contribution, as YYYY-MM-DD. Adds firstContributionDate, lastContributionDate and targetDate (when the projected balance is reached). It only labels the plan; the amounts do not change. A day of 29 to 31 moves to the last day of shorter months.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "currentBalance",
                  "monthlyContribution",
                  "years"
                ],
                "additionalProperties": false
              },
              "example": {
                "currentBalance": 5000,
                "monthlyContribution": 300,
                "years": 15,
                "expectedReturnPct": 6,
                "firstContributionDate": "2026-11-01"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "529 calculator client and server side from freedailypro",
                  "result": {
                    "projected": 99516.08,
                    "months": 180,
                    "totalContributed": 59000,
                    "firstContributionDate": "2026-11-01",
                    "lastContributionDate": "2041-10-01",
                    "targetDate": "2041-11-01"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/social-security": {
      "post": {
        "summary": "Estimate a Social Security retirement benefit with the 2026 bend points",
        "operationId": "convertersSocialSecurity",
        "description": "Estimates the monthly retirement benefit. Send your AIME as 'averageIndexedMonthlyEarnings' (from your SSA statement), or 'annualEarnings' with optional 'yearsWorked' to have AIME estimated. The primary insurance amount (PIA) uses the 2026 bend points: 90% of AIME up to $1,286, 32% up to $7,749 and 15% above. 'birthYear' sets full retirement age (67 for 1960 or later; default 1960) and 'claimAge' (62 to 70, default 67) applies the early-claim reduction (5/9 of 1% a month for the first 36 months, 5/12 of 1% after) or the delayed-retirement credit (8% a year). First-version fields estimatedPIA, monthlyAtClaimAge and claimAge are unchanged; exact values are in piaExact and monthlyExact. Where the data comes from: SSA 2026 bend points and contribution and benefit base ($184,500). Bend points are those for people first eligible in 2026; other eligibility years use other bend points. Update process: one table file shared with the FreeDailyPro website, updated by FreeDailyPro every November when the SSA announces the next year's figures. Not an SSA statement: earnings are not indexed, and cost-of-living adjustments, spousal benefits, the earnings test and benefit taxation are not modelled. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "averageIndexedMonthlyEarnings": {
                    "description": "Your AIME (average indexed monthly earnings) from your SSA statement. Send this or annualEarnings.",
                    "type": "number"
                  },
                  "annualEarnings": {
                    "description": "Alternative to AIME: current yearly earnings (capped at the 2026 wage base of $184,500). AIME is estimated from it.",
                    "type": "number",
                    "minimum": 0
                  },
                  "yearsWorked": {
                    "description": "With annualEarnings: years of work, up to 35 (default 35).",
                    "type": "number",
                    "minimum": 0
                  },
                  "claimAge": {
                    "description": "Age you start benefits, 62 to 70 (decimals such as 62.5 are rounded to whole months). Default 67.",
                    "type": "number"
                  },
                  "birthYear": {
                    "description": "Birth year, which sets full retirement age (67 if born 1960 or later). Default 1960.",
                    "type": "number"
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "averageIndexedMonthlyEarnings": 6000,
                "claimAge": 67,
                "birthYear": 1962
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Social Security retirement benefit estimate with 2026 bend points",
                  "result": {
                    "aime": 6000,
                    "estimatedPIA": 2666,
                    "piaExact": 2665.8,
                    "monthlyAtClaimAge": 2666,
                    "monthlyExact": 2665.8,
                    "annualAtClaimAge": 31989.6,
                    "claimAge": 67,
                    "birthYear": 1962,
                    "fullRetirementAge": "67",
                    "fullRetirementAgeMonths": 804,
                    "bendPoints": {
                      "first": 1286,
                      "second": 7749
                    },
                    "wageBase": 184500,
                    "taxYear": 2026,
                    "sources": "SSA 2026 PIA bend points ($1,286 and $7,749) and 2026 contribution and benefit base ($184,500); SSA full-retirement-age and delayed-credit rules. FreeDailyPro updates these tables once a year, in November, when the IRS and SSA publish next year's figures.",
                    "dataStatus": "checked",
                    "notes": [
                      "PIA = 90% of AIME up to $1,286, 32% from there to $7,749, 15% above (2026 bend points, which apply to people first eligible, at 62, in 2026; other years use different bend points). Full retirement age 67.",
                      "Before full retirement age the benefit is cut by 5/9 of 1% per month for the first 36 months and 5/12 of 1% after that; after it, it grows 8% a year (to age 70). Cost-of-living adjustments, spousal benefits, the earnings test and taxation of benefits are not modelled."
                    ],
                    "disclaimer": "Estimate for information only. Not tax, legal or financial advice; check the figures with the tax authority or a qualified adviser. This is not an SSA estimate; see your my Social Security statement for official figures."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither averageIndexedMonthlyEarnings nor annualEarnings, a negative value, a claimAge outside 62 to 70, or an invalid birthYear Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/student-loan": {
      "post": {
        "summary": "Calculate the payoff time and total interest of a student loan",
        "operationId": "convertersStudentLoan",
        "description": "Send 'principal', 'annualRatePct' and EITHER 'monthlyPayment' (the payment you make) or 'standardTermYears' (use the standard payment for that term). Returns the payoff 'months', 'years', 'totalInterest' and 'totalPaid' as before, and 'payoffDate' with 'firstPaymentDate'. Additive fields (B-0135): 'income' (yearly adjusted gross income) adds 'incomeDriven': the Repayment Assistance Plan (RAP) payment, and with 'ibr' (10 or 15) the Income-Based Repayment payment, beside the standard plan, each with months paying, total paid, interest paid and the balance forgiven at the end; 'dependents' (RAP takes $50 a month off for each), 'householdSize' and 'state' (AK and HI use their own poverty guideline for IBR) refine it. 'refinance' { annualRatePct, years } adds 'refinance': the new payment, total interest and 'interestSaved' (negative when a longer term costs more), with a warning that refinancing federal loans with a private lender ends federal protections. Plan rules, read 30 Oct 2026: RAP payment = the share of AGI for its $10,000 band (1% for $10,001 to $20,000 rising 1 point per band to 9%, 10% above $100,000) / 12, less $50 per dependent, minimum $10 a month, forgiveness after 30 years, unpaid interest not charged; IBR is 10% or 15% of discretionary income (AGI less 150% of the 2026 HHS poverty guideline: 48 states and DC 15,960 plus 5,680 per extra person, Alaska 19,950 plus 7,100, Hawaii 18,360 plus 6,530) never above the 10-year standard payment, forgiven after 20 or 25 years. Plan lineup: SAVE ended by court order on 10 March 2026; PAYE and ICR close on 1 July 2028; a borrower with a new federal loan on or after 1 July 2026 can choose only RAP or the Tiered Standard plan, so ibr is only for borrowers whose loans were all made before that date. Sources: the FSA servicer page edfinancial.studentaid.gov, the Illinois Attorney General's RAP handout, NerdWallet's RAP guide and Federal Register 2026-00755; studentaid.gov itself could not be fetched, so check it for your own loans. Not modelled: the RAP principal match (sources differ on how it works, so a real RAP payoff can be slightly faster), income growth, annual recalculation, subsidised-loan interest benefits, spouse income, the Tiered Standard plan's tiers. Unpaid IBR interest is modelled as accruing without compounding, with payments going to interest first. Who calls it: student-finance and loan-comparison sites, university financial-aid offices, budgeting and net-worth apps, and chatbots or MCP agents. Worked example: {\"principal\":30000,\"annualRatePct\":5.5,\"standardTermYears\":10,\"income\":45000,\"householdSize\":1,\"ibr\":10,\"refinance\":{\"annualRatePct\":4,\"years\":10}} returns RAP 150.00 a month (4% band) with 54,000 paid over 360 months and 18,579.85 forgiven, IBR 175.50 a month (discretionary income 21,060), and a refinance payment of 303.74 that saves 2,620.61 in interest. Integration scenario: a graduate-aid site shows a recent graduate their standard payment, the RAP payment from their salary and what a refinance would change, with the federal-protections warning beside it. The plan figures change by law and by year: update the table file and the poverty guideline each January. Illustration, not advice. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "principal": {
                    "type": "number"
                  },
                  "annualRatePct": {
                    "type": "number"
                  },
                  "monthlyPayment": {
                    "description": "The payment you make. Send this or standardTermYears.",
                    "type": "number"
                  },
                  "standardTermYears": {
                    "description": "Use the standard payment for this many years instead of sending monthlyPayment.",
                    "type": "number"
                  },
                  "income": {
                    "description": "Yearly adjusted gross income. Adds incomeDriven: the Repayment Assistance Plan payment (and IBR with ibr) beside the standard plan, with total paid, term and forgiven balance.",
                    "type": "number",
                    "minimum": 0
                  },
                  "dependents": {
                    "description": "Dependents claimed on the tax return (RAP takes $50 a month off for each). With income.",
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "householdSize": {
                    "description": "Household size for the IBR poverty guideline. With income. Default 1.",
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 9007199254740991
                  },
                  "state": {
                    "description": "Two-letter state code. AK and HI use their own poverty guideline for IBR; anything else the 48-state figure.",
                    "type": "string"
                  },
                  "ibr": {
                    "description": "Also show IBR at 10% (loans from 1 July 2014, 20 years) or 15% (older loans, 25 years) of discretionary income. Only for borrowers whose loans were all made before 1 July 2026.",
                    "anyOf": [
                      {
                        "type": "number",
                        "enum": [
                          10
                        ]
                      },
                      {
                        "type": "number",
                        "enum": [
                          15
                        ]
                      }
                    ]
                  },
                  "refinance": {
                    "description": "A private refinance on the same balance: returns the new payment and the interest saved or added.",
                    "type": "object",
                    "properties": {
                      "annualRatePct": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "years": {
                        "type": "number",
                        "minimum": 1,
                        "maximum": 40
                      }
                    },
                    "required": [
                      "annualRatePct",
                      "years"
                    ],
                    "additionalProperties": false
                  },
                  "firstPaymentDate": {
                    "description": "Optional date the first payment is due, as YYYY-MM-DD. Adds firstPaymentDate, lastPaymentDate and payoffDate to the result. It only labels the result; the months, interest and totals do not change. A payment day of 29 to 31 moves to the last day of shorter months.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "principal",
                  "annualRatePct"
                ],
                "additionalProperties": false
              },
              "example": {
                "principal": 30000,
                "annualRatePct": 5.5,
                "monthlyPayment": 400,
                "firstPaymentDate": "2027-05-01"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Student loan calculator client and server side from freedailypro",
                  "result": {
                    "months": 93,
                    "years": 7.8,
                    "totalInterest": 6844.72,
                    "totalPaid": 36844.72,
                    "firstPaymentDate": "2027-05-01",
                    "lastPaymentDate": "2035-01-01",
                    "payoffDate": "2035-01"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing both monthlyPayment and standardTermYears, or both sent; a payment that does not cover the interest; ibr, dependents, householdSize or state without income; a household size or dependents out of range; a refinance rate or term out of range; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/college-cost": {
      "post": {
        "summary": "Project the total cost of college year by year with inflation",
        "operationId": "convertersCollegeCost",
        "description": "Project the total cost of college year by year with inflation. Send JSON with annualCost, years (required); optional: inflationPct, startDate. Returns JSON with total, byYear, startDate, endDate (inside result). Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "annualCost": {
                    "type": "number",
                    "minimum": 0
                  },
                  "years": {
                    "type": "number",
                    "minimum": 0
                  },
                  "inflationPct": {
                    "type": "number"
                  },
                  "startDate": {
                    "description": "Optional date the first year starts, as YYYY-MM-DD. Adds the start date of each year to byYear, plus startDate and endDate for the whole program. It only labels the years; the costs do not change.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "annualCost",
                  "years"
                ],
                "additionalProperties": false
              },
              "example": {
                "annualCost": 30000,
                "years": 4,
                "inflationPct": 4,
                "startDate": "2027-08-15"
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "College cost calculator client and server side from freedailypro",
                  "result": {
                    "total": 127393.92,
                    "byYear": [
                      {
                        "year": 1,
                        "cost": 30000,
                        "startDate": "2027-08-15"
                      },
                      {
                        "year": 2,
                        "cost": 31200,
                        "startDate": "2028-08-15"
                      },
                      {
                        "year": 3,
                        "cost": 32448,
                        "startDate": "2029-08-15"
                      },
                      "..."
                    ],
                    "startDate": "2027-08-15",
                    "endDate": "2031-08-15"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input; the body explains what to fix Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/debt-payoff": {
      "post": {
        "summary": "Debt payoff: avalanche and snowball side by side with payoff dates, total interest, order and a minimums-only baseline",
        "operationId": "convertersDebtPayoff",
        "description": "Send 'debts' (each with 'balance', 'aprPct', 'minPayment' and an optional 'name'; 1 to 30 debts) and either 'extraMonthly' (on top of the minimums) or 'totalMonthlyBudget' (the whole monthly amount, which must cover the minimums). 'strategy' avalanche, snowball or both (default both) chooses which plans are simulated; they come back beside 'minimumsOnly' (each debt paid on its own minimum with no rollover). Each plan has 'debtFreeInMonths', 'debtFreeIn', 'debtFreeDate' (counted from 'startDate'), 'totalInterest', 'totalPaid', 'payoffOrder' (month, date and interest per debt) and 'totalBalanceAtEndOfEachYear'. Freed-up minimums roll into the next debt. Who calls it: budgeting and debt-help apps, credit counselling tools, banks' financial-wellness features, chatbots and MCP agents. Worked example: three debts (5,000 at 22%, 3,000 at 15%, 800 at 8%, minimums 150, 90, 40) with 300 extra a month: avalanche 18 months and 1,200.11 interest, snowball 18 months and 1,443.55, minimums only 52 months and 3,764.66 (checked with an independent month-by-month script). Integration scenario: a wellness app lets the user add cards and shows how much the avalanche saves over the snowball, with the date the last debt is paid off. APRs and balances are your inputs; interest is monthly at APR / 12. Pure arithmetic from the request: no customer data is stored. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "debts": {
                    "minItems": 1,
                    "maxItems": 30,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "balance": {
                          "type": "number",
                          "description": "Current balance."
                        },
                        "aprPct": {
                          "type": "number",
                          "description": "Annual interest rate in percent."
                        },
                        "minPayment": {
                          "type": "number",
                          "description": "Required minimum monthly payment."
                        }
                      },
                      "required": [
                        "balance",
                        "aprPct",
                        "minPayment"
                      ],
                      "additionalProperties": false
                    },
                    "description": "The debts to pay off, 1 to 30."
                  },
                  "extraMonthly": {
                    "description": "Money you can add each month on top of all the minimums. Send this or totalMonthlyBudget.",
                    "type": "number"
                  },
                  "totalMonthlyBudget": {
                    "description": "Total you can pay each month across all debts (at least the sum of the minimums).",
                    "type": "number"
                  },
                  "strategy": {
                    "description": "avalanche = highest rate first, snowball = smallest balance first, both (default) returns both and compares them.",
                    "type": "string",
                    "enum": [
                      "avalanche",
                      "snowball",
                      "both"
                    ]
                  },
                  "startDate": {
                    "description": "Date of the first payment, YYYY-MM-DD. Adds a payoff date for every debt and the date the last debt is paid off.",
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "debts"
                ],
                "additionalProperties": false
              },
              "example": {
                "debts": [
                  {
                    "balance": 1,
                    "aprPct": 1,
                    "minPayment": 1
                  }
                ]
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Debt payoff planner: avalanche and snowball plans with payoff dates, interest and a minimums-only baseline",
                  "result": {
                    "totalStartingBalance": 8800,
                    "sumOfMinimumPayments": 280,
                    "extraMonthly": 300,
                    "monthlyBudget": 580,
                    "avalanche": {
                      "rule": "Extra money goes to the highest interest rate first.",
                      "debtFreeInMonths": 18,
                      "debtFreeIn": "1 year 6 months",
                      "debtFreeDate": "2028-05-01",
                      "totalInterest": 1200.11,
                      "totalPaid": 10000.11,
                      "payoffOrder": [
                        {
                          "debt": "Card A",
                          "payoffMonth": 13,
                          "payoffDate": "2027-12-01",
                          "interestPaid": 643.17
                        }
                      ],
                      "totalBalanceAtEndOfEachYear": [
                        2932.03
                      ]
                    },
                    "snowball": {
                      "rule": "Extra money goes to the smallest balance first.",
                      "debtFreeInMonths": 18,
                      "debtFreeIn": "1 year 6 months",
                      "debtFreeDate": "2028-05-01",
                      "totalInterest": 1443.55,
                      "totalPaid": 10243.55,
                      "payoffOrder": [
                        {
                          "debt": "Car",
                          "payoffMonth": 3,
                          "payoffDate": "2027-02-01",
                          "interestPaid": 9.29
                        }
                      ],
                      "totalBalanceAtEndOfEachYear": [
                        3091.02
                      ]
                    },
                    "minimumsOnly": {
                      "rule": "Each debt gets only its own minimum, with no money rolled over when one is paid off.",
                      "debtFreeInMonths": 52,
                      "debtFreeIn": "4 years 4 months",
                      "debtFreeDate": "2031-03-01",
                      "totalInterest": 3764.66,
                      "totalPaid": 12564.66,
                      "payoffOrder": [
                        {
                          "debt": "Car",
                          "payoffMonth": 22,
                          "payoffDate": "2028-09-01",
                          "interestPaid": 61.5
                        }
                      ],
                      "totalBalanceAtEndOfEachYear": [
                        6918.15
                      ]
                    },
                    "comparison": {
                      "interestSavedByAvalanche": 243.44,
                      "monthsDifference": 0,
                      "lowerInterest": "avalanche",
                      "note": "Avalanche never costs more interest than snowball; snowball clears the first debt sooner, which some people find easier to stick with."
                    },
                    "savingsVsMinimumsOnly": {
                      "interest": 2564.55,
                      "monthsSooner": 34
                    },
                    "method": "Each month: interest = balance x APR / 12 on every open debt; every open debt gets its minimum (or what is left of the balance); the rest of the monthly budget goes to the target debt in order, carrying over to the next debt when one is cleared.",
                    "notes": [
                      "Interest is a plain monthly APR / 12 on the balance; real cards compound daily and add fees or new purchases, so statements differ by a little."
                    ],
                    "sources": "Calculation only; no rate table is used. Balances, rates and minimums are what you send.",
                    "disclaimer": "Estimate for information only. Not financial, tax or legal advice; lenders, servicers and tax rules differ, so confirm the figures with the lender or a qualified adviser."
                  }
                }
              }
            }
          },
          "400": {
            "description": "No debts or more than 30, a balance or minimum payment of 0 or less, an APR outside 0 to 100, extraMonthly together with totalMonthlyBudget, or a budget below the sum of the minimums; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/contribution-limits": {
      "post": {
        "summary": "Contribution limits: 401(k), SIMPLE, IRA and HSA limits by tax year with catch-ups, Roth phase-outs and IRA deduction limits",
        "operationId": "convertersContributionLimits",
        "description": "Send nothing for the latest table, or 'taxYear' (2025 and 2026 are in the table), 'age' (adds catch-up amounts: 50 and over, 60 to 63 super catch-up, HSA 55 and over), 'hsaCoverage' self or family, and optionally 'magi' with 'filingStatus' (and 'coveredByWorkplacePlan') to compute the reduced Roth IRA contribution and the traditional IRA deduction. Returns 'k401', 'simple', 'ira' and 'hsa' sections with 'totalForYourAge', plus 'taxYear', 'tableAsOf', 'availableYears', 'sources' (the notices the numbers come from), 'dataStatus' and 'nextReview'. An unsupported 'taxYear' is a 400 that lists the years held; the API does not guess future limits. Who calls it: payroll and HR tools, financial-planning and robo-advisor apps, benefits portals, chatbots and MCP agents. Worked example: {\"taxYear\":2026,\"age\":61,\"hsaCoverage\":\"family\"} returns 401(k) deferral 24,500 plus the 11,250 age 60 to 63 catch-up (35,750), IRA 7,500 plus 1,100 (8,600) and family HSA 8,750 plus 1,000 (9,750). Where the data comes from: IRS Notice 2025-67 (2026 retirement plan and IRA limits) and Rev. Proc. 2025-19 (2026 HSA), IRS Notice 2024-80 and Rev. Proc. 2024-25 (2025); the figures were read from secondary summaries and marked 'estimate' in dataStatus, so confirm them on irs.gov. Update process: one table file shared with the website, reviewed each November when the IRS publishes the next year's limits. Pure arithmetic from the request: no customer data is stored. Stateless: the request is processed in memory and nothing is stored.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "taxYear": {
                    "description": "Tax year, 2025 or 2026 (default: the latest in the table). Other years are a 400 that lists the years available.",
                    "type": "number"
                  },
                  "age": {
                    "description": "Age reached by the end of the year: adds the catch-up for 401(k) (50, and the larger 60 to 63 amount), IRA (50) and HSA (55) and the total for that age.",
                    "type": "number"
                  },
                  "hsaCoverage": {
                    "description": "HSA coverage in December: adds the limit for it.",
                    "type": "string",
                    "enum": [
                      "self",
                      "family"
                    ]
                  },
                  "magi": {
                    "description": "Modified adjusted gross income. With filingStatus: the Roth IRA contribution you are allowed after the income phase-out (and, with coveredByWorkplacePlan, the traditional IRA deduction). Phase-out ranges are in the table for 2026 only.",
                    "type": "number"
                  },
                  "filingStatus": {
                    "description": "Needed with magi.",
                    "type": "string",
                    "enum": [
                      "single",
                      "married-joint",
                      "married-separate",
                      "head-of-household"
                    ]
                  },
                  "coveredByWorkplacePlan": {
                    "description": "true adds the traditional IRA deduction phase-out for someone covered by a workplace plan.",
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Retirement and HSA contribution limits by tax year: 401(k), SIMPLE, IRA, Roth phase-out and HSA",
                  "result": {
                    "taxYear": 2026,
                    "tableAsOf": "2026-10-30",
                    "availableYears": [
                      2025
                    ],
                    "age": 61,
                    "k401": {
                      "employeeDeferral": 24500,
                      "catchUp50": 8000,
                      "catchUp60to63": 11250,
                      "annualAdditionsLimit": 72000,
                      "compensationLimit": 360000,
                      "catchUpForYourAge": 11250,
                      "totalForYourAge": 35750
                    },
                    "simple": {
                      "employeeDeferral": 17000,
                      "catchUp50": 4000,
                      "catchUp60to63": 5250,
                      "totalForYourAge": 22250
                    },
                    "ira": {
                      "limit": 7500,
                      "catchUp50": 1100,
                      "totalForYourAge": 8600
                    },
                    "hsa": {
                      "selfOnly": 4400,
                      "family": 8750,
                      "catchUp55": 1000,
                      "yourCoverage": "family",
                      "limitForYourCoverage": 8750,
                      "totalForYourAge": 9750
                    },
                    "sources": {
                      "retirement": "IRS Notice 2025-67 (2026 retirement plan and IRA limits); read via an Ascensus summary",
                      "hsa": "IRS Rev. Proc. 2025-19 (2026 HSA); read via a Keiter CPA summary",
                      "table": "IRS Notice 2025-67 (2026 retirement plans and IRAs), Rev. Proc. 2025-19 (2026 HSA), Notice 2024-80 and Rev. Proc. 2024-25 (2025). Tax year 2025 and 2026. FreeDailyPro table last checked 2026-10-30 (compiled from secondary sources, confirm with the authority). Next review: November, when the IRS publishes next year's limits."
                    },
                    "dataStatus": "estimate",
                    "nextUpdate": "November, when the IRS publishes next year's limits",
                    "notes": [
                      "Catch-up rules: 401(k), 403(b) and governmental 457(b) catch-up from age 50, a larger one at 60 to 63; IRA catch-up from 50; HSA catch-up from 55. Ages are the age reached by the end of the calendar year."
                    ],
                    "disclaimer": "Estimate for information only. Not tax, legal or financial advice; check the figures with the tax authority or a qualified adviser."
                  }
                }
              }
            }
          },
          "400": {
            "description": "A taxYear not in the table (the body lists the available years), an age outside 0 to 120, a negative MAGI, or magi without filingStatus Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    },
    "/v1/converters/retirement": {
      "post": {
        "summary": "Retirement and FIRE projection: nest egg in today's dollars, sustainable income, goal gap, FIRE number and drawdown by age",
        "operationId": "convertersRetirement",
        "description": "Send 'currentAge', 'retirementAge', 'currentSavings', 'annualContribution' and your assumptions ('expectedReturnPct', 'returnInRetirementPct', 'inflationPct', 'withdrawalRatePct', 'contributionGrowthPct', 'lifeExpectancyAge'), plus optionally 'desiredAnnualIncome' and 'otherAnnualIncome' (Social Security, pension; today's dollars). Returns 'atRetirement' (nest egg in today's dollars and nominal, contributions and growth), 'income' (what the withdrawal rate supports, yearly and monthly), 'goal' (nest egg needed, surplus or shortfall, extra yearly saving needed, and a 'financialIndependence' block with the FIRE number, years and age reached) and a 'drawdown' by age showing whether the money lasts to 'lifeExpectancyAge'. Returns are real (after inflation): (1 + return) / (1 + inflation) - 1. Return, inflation and withdrawal rate are assumptions you control (defaults 7%, 2.5%, 4%), never market data or a forecast; the response says so. Who calls it: retirement and robo-advisor tools, HR and benefits portals, FIRE communities, personal-finance apps, chatbots and MCP agents. Worked example: {\"currentAge\":35,\"retirementAge\":65,\"currentSavings\":100000,\"annualContribution\":10000,\"expectedReturnPct\":7,\"inflationPct\":2.5,\"withdrawalRatePct\":4,\"desiredAnnualIncome\":60000} returns a nest egg of 961,756.26 in today's dollars, 38,470.25 a year of sustainable income, a 1,500,000 requirement, a shortfall of 538,243.74 and 8,987.99 more to save each year (verified with an independent Python projection). Integration scenario: a benefits portal shows each employee whether they are on track and how much more per year closes the gap. Illustration, not investment advice. Pure arithmetic from the request: no customer data is stored. Stateless: the request is processed in memory and nothing is stored. Errors: 400 when a field is missing or invalid (the body says which), 401 without a valid X-API-Key header, 429 when the plan's call limit is reached.",
        "tags": [
          "Retirement & Debt Planning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "currentAge": {
                    "type": "number",
                    "description": "Your age now (whole years)."
                  },
                  "retirementAge": {
                    "type": "number",
                    "description": "Age you plan to stop working."
                  },
                  "lifeExpectancyAge": {
                    "description": "Age the money must last to (default 95).",
                    "type": "number"
                  },
                  "currentSavings": {
                    "description": "Invested savings now.",
                    "type": "number"
                  },
                  "annualContribution": {
                    "description": "What you add each year, in today's dollars.",
                    "type": "number"
                  },
                  "contributionGrowthPct": {
                    "description": "Yearly real increase of the contribution in percent (default 0).",
                    "type": "number"
                  },
                  "expectedReturnPct": {
                    "description": "Expected nominal return before retirement, percent a year (default 7). An assumption, not market data.",
                    "type": "number"
                  },
                  "returnInRetirementPct": {
                    "description": "Expected nominal return during retirement (default: same as before retirement).",
                    "type": "number"
                  },
                  "inflationPct": {
                    "description": "Expected inflation, percent a year (default 2.5).",
                    "type": "number"
                  },
                  "withdrawalRatePct": {
                    "description": "Share of the nest egg withdrawn in the first year (default 4).",
                    "type": "number"
                  },
                  "desiredAnnualIncome": {
                    "description": "Income you want per year in today's dollars. Adds the nest egg needed, the gap, the extra saving needed and the years to financial independence.",
                    "type": "number"
                  },
                  "otherAnnualIncome": {
                    "description": "Pension or Social Security per year in today's dollars, counted from the retirement age (default 0).",
                    "type": "number"
                  }
                },
                "required": [
                  "currentAge",
                  "retirementAge"
                ],
                "additionalProperties": false
              },
              "example": {
                "currentAge": 1,
                "retirementAge": 1
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "tool": "Retirement and FIRE projection: nest egg, sustainable income, gap and drawdown with inflation and a withdrawal rate",
                  "result": {
                    "assumptions": {
                      "currentAge": 35,
                      "retirementAge": 65,
                      "lifeExpectancyAge": 95,
                      "expectedReturnPct": 7,
                      "returnInRetirementPct": 7,
                      "inflationPct": 2.5,
                      "withdrawalRatePct": 4,
                      "realReturnPct": 4.39,
                      "contributionGrowthPct": 0,
                      "note": "Return, inflation and withdrawal rate are your assumptions (defaults 7%, 2.5%, 4%), not market data or a forecast. Amounts are in today's dollars unless the field says nominal."
                    },
                    "atRetirement": {
                      "yearsToRetirement": 30,
                      "nestEggToday": 961756.26,
                      "nestEggNominal": 2017348.76,
                      "totalContributed": 300000,
                      "growth": 561756.26
                    },
                    "income": {
                      "sustainableAtWithdrawalRate": 38470.25,
                      "sustainableMonthly": 3205.85,
                      "otherAnnualIncome": 0,
                      "totalAnnualIncomeToday": 38470.25,
                      "sustainableNominalFirstYear": 80693.95
                    },
                    "goal": {
                      "desiredAnnualIncomeToday": 60000,
                      "nestEggNeeded": 1500000,
                      "nestEggNeededNominal": 3146351.37,
                      "surplusOrShortfall": -538243.74,
                      "onTrack": false,
                      "extraAnnualSavingNeeded": 8987.99,
                      "financialIndependence": {
                        "number": 1500000,
                        "yearsToReach": 38.68,
                        "ageReached": 73.68,
                        "method": "Site FIRE calculator: contributions held constant in today's dollars, target = (desired income - other income) / withdrawal rate."
                      }
                    },
                    "drawdown": {
                      "annualSpendingToday": 60000,
                      "fundsLastToAge": 91,
                      "runsOutAtAge": 91,
                      "balanceAtLifeExpectancyToday": 0,
                      "rule": "Withdrawals are taken at the start of each year and rise with inflation; the rest grows at the retirement real return."
                    },
                    "accumulation": [
                      {
                        "age": 36,
                        "contribution": 10000,
                        "endBalanceReal": 114390.24,
                        "endBalanceNominal": 117250
                      }
                    ],
                    "drawdownByYear": [
                      {
                        "age": 65,
                        "startBalanceReal": 961756.26,
                        "withdrawalReal": 60000,
                        "withdrawalNominal": 125854.05,
                        "endBalanceReal": 941345.56
                      }
                    ],
                    "sources": "Calculation only; no tax table or market data. The 4% default is the common withdrawal-rate rule of thumb from the Trinity study; it is not a guarantee.",
                    "disclaimer": "Estimate for information only. Not financial, tax or legal advice; lenders, servicers and tax rules differ, so confirm the figures with the lender or a qualified adviser."
                  }
                }
              }
            }
          },
          "400": {
            "description": "A retirementAge below currentAge, a lifeExpectancyAge not above retirementAge, non-whole ages, or a value outside its allowed range; the body says which Not billed: a failed call does not count against your plan's calls."
          },
          "401": {
            "description": "Missing or invalid API key Not billed: a failed call does not count against your plan's calls."
          },
          "429": {
            "description": "Rate limit exceeded for your plan Not billed: a failed call does not count against your plan's calls."
          }
        }
      }
    }
  }
}