{
  "openapi": "3.1.0",
  "info": {
    "title": "WealthCompounds Coast FIRE API",
    "version": "1.0.0",
    "description": "Educational Coast FIRE math for https://wealthcompounds.com. Rates are decimals: 0.07 means 7%. The model assumes no new contributions, a constant return, and a withdrawal-rate portfolio at retirement. It is not a forecast and not investment advice.",
    "license": {
      "name": "Use is subject to the site terms",
      "url": "https://wealthcompounds.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://wealthcompounds.com"
    }
  ],
  "paths": {
    "/api/coast-fire": {
      "post": {
        "operationId": "calculateCoastFire",
        "summary": "Calculate a Coast FIRE number",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CoastRequest"
              },
              "example": {
                "currentBalance": 200000,
                "annualSpending": 60000,
                "withdrawalRate": 0.04,
                "currentAge": 35,
                "retireAge": 60,
                "annualReturn": 0.07,
                "inflation": 0.03,
                "mode": "real",
                "socialSecurityAnnual": 24000,
                "socialSecurityAge": 67,
                "sideIncomeAnnual": 0,
                "sideIncomeYears": 0,
                "partialWithdrawalAnnual": 0
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Coast FIRE result in USD.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CoastResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or a field outside its range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CoastRequest": {
        "type": "object",
        "required": [
          "currentBalance",
          "annualSpending",
          "currentAge",
          "retireAge"
        ],
        "properties": {
          "currentBalance": {
            "type": "number",
            "minimum": 0,
            "maximum": 100000000
          },
          "annualSpending": {
            "type": "number",
            "minimum": 0,
            "maximum": 10000000,
            "description": "Annual spending in today's dollars."
          },
          "withdrawalRate": {
            "type": "number",
            "minimum": 0.01,
            "maximum": 0.15,
            "default": 0.04
          },
          "currentAge": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "retireAge": {
            "type": "integer",
            "minimum": 0,
            "maximum": 110
          },
          "annualReturn": {
            "type": "number",
            "minimum": 0,
            "maximum": 0.2,
            "default": 0.07,
            "description": "Nominal return. 0.07 is 7%."
          },
          "inflation": {
            "type": "number",
            "minimum": 0,
            "maximum": 0.15,
            "default": 0.03
          },
          "mode": {
            "type": "string",
            "enum": [
              "real",
              "nominal"
            ],
            "default": "real"
          },
          "socialSecurityAnnual": {
            "type": "number",
            "minimum": 0,
            "maximum": 500000,
            "default": 0,
            "description": "Benefit you type in. Not estimated."
          },
          "socialSecurityAge": {
            "type": "integer",
            "minimum": 50,
            "maximum": 80,
            "default": 67
          },
          "sideIncomeAnnual": {
            "type": "number",
            "minimum": 0,
            "maximum": 5000000,
            "default": 0
          },
          "sideIncomeYears": {
            "type": "integer",
            "minimum": 0,
            "maximum": 80,
            "default": 0
          },
          "partialWithdrawalAnnual": {
            "type": "number",
            "minimum": 0,
            "maximum": 5000000,
            "default": 0,
            "description": "Taken from the portfolio before retirement."
          }
        }
      },
      "CoastPoint": {
        "type": "object",
        "required": [
          "age",
          "balance",
          "withdrawal"
        ],
        "properties": {
          "age": {
            "type": "integer"
          },
          "balance": {
            "type": "number"
          },
          "withdrawal": {
            "type": "number"
          }
        }
      },
      "CoastResponse": {
        "type": "object",
        "required": [
          "coastNumber",
          "fireNumber",
          "retirementTarget",
          "gap",
          "onTrack",
          "series",
          "assumptions"
        ],
        "properties": {
          "coastNumber": {
            "type": "number",
            "description": "Dollars needed today, with no new contributions."
          },
          "fireNumber": {
            "type": "number",
            "description": "annualSpending / withdrawalRate, before Social Security."
          },
          "retirementTarget": {
            "type": "number"
          },
          "retirementDollars": {
            "type": "string",
            "enum": [
              "today",
              "future"
            ]
          },
          "gap": {
            "type": "number"
          },
          "onTrack": {
            "type": "boolean"
          },
          "projectedAtRetirement": {
            "type": "number"
          },
          "depletedAge": {
            "type": [
              "integer",
              "null"
            ]
          },
          "growthRate": {
            "type": "number"
          },
          "yearsToRetirement": {
            "type": "integer"
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoastPoint"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}