{
  "openapi": "3.1.0",
  "info": {
    "title": "Paycheck API (estimatemypaycheck.com)",
    "version": "1.0.0",
    "description": "Free API and MCP server for US take-home pay in 2026: federal income tax, Social Security, Medicare, state income tax and state payroll levies (SDI, PFML) for the 50 states and DC, per paycheck and per year, plus a 51-state comparison and the bonus check after the 22% supplemental withholding. No key, CORS open. Estimates, not tax advice.",
    "contact": {
      "email": "contact@estimatemypaycheck.com",
      "url": "https://estimatemypaycheck.com/paycheck-api/"
    }
  },
  "servers": [
    {
      "url": "https://estimatemypaycheck.com"
    }
  ],
  "externalDocs": {
    "url": "https://estimatemypaycheck.com/paycheck-api/"
  },
  "paths": {
    "/api/v1/paycheck": {
      "get": {
        "operationId": "calculate_paycheck",
        "summary": "Calculate take-home pay",
        "description": "Compute a US paycheck for 2026: gross, each tax and pre-tax deduction, and take-home pay per paycheck and per year, for a salary or an hourly rate (overtime over 40 hours at 1.5 times) in any state or DC. Federal withholding follows the annual tax on wages; local city and county taxes are not included (the answer names them when material).",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "description": "Two-letter state code or name: TX, CA, new-york, DC.",
            "schema": {
              "type": "string",
              "description": "Two-letter state code or name: TX, CA, new-york, DC.",
              "example": "CA"
            }
          },
          {
            "name": "salary",
            "in": "query",
            "required": false,
            "description": "Annual gross salary in dollars. Give this or hourly_rate.",
            "schema": {
              "type": "number",
              "description": "Annual gross salary in dollars. Give this or hourly_rate.",
              "example": 60000
            }
          },
          {
            "name": "hourly_rate",
            "in": "query",
            "required": false,
            "description": "Hourly rate in dollars, instead of salary.",
            "schema": {
              "type": "number",
              "description": "Hourly rate in dollars, instead of salary.",
              "example": 25
            }
          },
          {
            "name": "hours_per_week",
            "in": "query",
            "required": false,
            "description": "Hours a week with hourly_rate (over 40 paid at 1.5 times). Default 40.",
            "schema": {
              "type": "number",
              "description": "Hours a week with hourly_rate (over 40 paid at 1.5 times). Default 40.",
              "example": 40
            }
          },
          {
            "name": "pay_frequency",
            "in": "query",
            "required": false,
            "description": "Default biweekly.",
            "schema": {
              "type": "string",
              "description": "Default biweekly.",
              "enum": [
                "weekly",
                "biweekly",
                "semimonthly",
                "monthly"
              ],
              "example": "biweekly"
            }
          },
          {
            "name": "filing_status",
            "in": "query",
            "required": false,
            "description": "Default single.",
            "schema": {
              "type": "string",
              "description": "Default single.",
              "enum": [
                "single",
                "joint",
                "head"
              ],
              "example": "single"
            }
          },
          {
            "name": "k401_percent",
            "in": "query",
            "required": false,
            "description": "Pre-tax 401(k) contribution, percent of gross. Default 0.",
            "schema": {
              "type": "number",
              "description": "Pre-tax 401(k) contribution, percent of gross. Default 0.",
              "example": 5
            }
          },
          {
            "name": "health_per_paycheck",
            "in": "query",
            "required": false,
            "description": "Pre-tax health premium per paycheck, dollars. Default 0.",
            "schema": {
              "type": "number",
              "description": "Pre-tax health premium per paycheck, dollars. Default 0.",
              "example": 0
            }
          },
          {
            "name": "residency",
            "in": "query",
            "required": false,
            "description": "resident (default), nonresident (e.g. H-1B first year: taxed as single), student (F/J/M/Q nonresident: no FICA).",
            "schema": {
              "type": "string",
              "description": "resident (default), nonresident (e.g. H-1B first year: taxed as single), student (F/J/M/Q nonresident: no FICA).",
              "enum": [
                "resident",
                "nonresident",
                "student"
              ],
              "example": "resident"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit: 60 requests per minute per IP"
          }
        }
      },
      "post": {
        "operationId": "calculate_paycheck_post",
        "summary": "Calculate take-home pay (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "state": {
                    "type": "string",
                    "description": "Two-letter state code or name: TX, CA, new-york, DC.",
                    "example": "CA"
                  },
                  "salary": {
                    "type": "number",
                    "description": "Annual gross salary in dollars. Give this or hourly_rate.",
                    "example": 60000
                  },
                  "hourly_rate": {
                    "type": "number",
                    "description": "Hourly rate in dollars, instead of salary.",
                    "example": 25
                  },
                  "hours_per_week": {
                    "type": "number",
                    "description": "Hours a week with hourly_rate (over 40 paid at 1.5 times). Default 40.",
                    "example": 40
                  },
                  "pay_frequency": {
                    "type": "string",
                    "description": "Default biweekly.",
                    "enum": [
                      "weekly",
                      "biweekly",
                      "semimonthly",
                      "monthly"
                    ],
                    "example": "biweekly"
                  },
                  "filing_status": {
                    "type": "string",
                    "description": "Default single.",
                    "enum": [
                      "single",
                      "joint",
                      "head"
                    ],
                    "example": "single"
                  },
                  "k401_percent": {
                    "type": "number",
                    "description": "Pre-tax 401(k) contribution, percent of gross. Default 0.",
                    "example": 5
                  },
                  "health_per_paycheck": {
                    "type": "number",
                    "description": "Pre-tax health premium per paycheck, dollars. Default 0.",
                    "example": 0
                  },
                  "residency": {
                    "type": "string",
                    "description": "resident (default), nonresident (e.g. H-1B first year: taxed as single), student (F/J/M/Q nonresident: no FICA).",
                    "enum": [
                      "resident",
                      "nonresident",
                      "student"
                    ],
                    "example": "resident"
                  }
                },
                "required": [
                  "state"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/compare-states": {
      "get": {
        "operationId": "compare_states",
        "summary": "Compare take-home pay in every state",
        "description": "Take-home pay for the same salary in the 50 states and DC in 2026, sorted from the highest. Useful to answer \"which state lets me keep the most\" or to price a move.",
        "parameters": [
          {
            "name": "salary",
            "in": "query",
            "required": true,
            "description": "Annual gross salary in dollars. Give this or hourly_rate.",
            "schema": {
              "type": "number",
              "description": "Annual gross salary in dollars. Give this or hourly_rate.",
              "example": 60000
            }
          },
          {
            "name": "filing_status",
            "in": "query",
            "required": false,
            "description": "Default single.",
            "schema": {
              "type": "string",
              "description": "Default single.",
              "enum": [
                "single",
                "joint",
                "head"
              ],
              "example": "single"
            }
          },
          {
            "name": "pay_frequency",
            "in": "query",
            "required": false,
            "description": "Default biweekly.",
            "schema": {
              "type": "string",
              "description": "Default biweekly.",
              "enum": [
                "weekly",
                "biweekly",
                "semimonthly",
                "monthly"
              ],
              "example": "biweekly"
            }
          },
          {
            "name": "k401_percent",
            "in": "query",
            "required": false,
            "description": "Pre-tax 401(k) contribution, percent of gross. Default 0.",
            "schema": {
              "type": "number",
              "description": "Pre-tax 401(k) contribution, percent of gross. Default 0.",
              "example": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit: 60 requests per minute per IP"
          }
        }
      },
      "post": {
        "operationId": "compare_states_post",
        "summary": "Compare take-home pay in every state (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "salary": {
                    "type": "number",
                    "description": "Annual gross salary in dollars. Give this or hourly_rate.",
                    "example": 60000
                  },
                  "filing_status": {
                    "type": "string",
                    "description": "Default single.",
                    "enum": [
                      "single",
                      "joint",
                      "head"
                    ],
                    "example": "single"
                  },
                  "pay_frequency": {
                    "type": "string",
                    "description": "Default biweekly.",
                    "enum": [
                      "weekly",
                      "biweekly",
                      "semimonthly",
                      "monthly"
                    ],
                    "example": "biweekly"
                  },
                  "k401_percent": {
                    "type": "number",
                    "description": "Pre-tax 401(k) contribution, percent of gross. Default 0.",
                    "example": 5
                  }
                },
                "required": [
                  "salary"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/bonus": {
      "get": {
        "operationId": "calculate_bonus_tax",
        "summary": "Bonus after taxes",
        "description": "What a bonus check pays after the flat 22% federal supplemental withholding, FICA and state tax, and how much of the federal withholding comes back (or is still owed) at tax time, on top of a salary, 2026 rules (IRS Pub. 15).",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "description": "Two-letter state code or name: TX, CA, new-york, DC.",
            "schema": {
              "type": "string",
              "description": "Two-letter state code or name: TX, CA, new-york, DC.",
              "example": "CA"
            }
          },
          {
            "name": "bonus",
            "in": "query",
            "required": true,
            "description": "Bonus in dollars.",
            "schema": {
              "type": "number",
              "description": "Bonus in dollars.",
              "example": 5000
            }
          },
          {
            "name": "salary",
            "in": "query",
            "required": true,
            "description": "Annual gross salary in dollars. Give this or hourly_rate.",
            "schema": {
              "type": "number",
              "description": "Annual gross salary in dollars. Give this or hourly_rate.",
              "example": 60000
            }
          },
          {
            "name": "filing_status",
            "in": "query",
            "required": false,
            "description": "Default single.",
            "schema": {
              "type": "string",
              "description": "Default single.",
              "enum": [
                "single",
                "joint",
                "head"
              ],
              "example": "single"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit: 60 requests per minute per IP"
          }
        }
      },
      "post": {
        "operationId": "calculate_bonus_tax_post",
        "summary": "Bonus after taxes (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "state": {
                    "type": "string",
                    "description": "Two-letter state code or name: TX, CA, new-york, DC.",
                    "example": "CA"
                  },
                  "bonus": {
                    "type": "number",
                    "description": "Bonus in dollars.",
                    "example": 5000
                  },
                  "salary": {
                    "type": "number",
                    "description": "Annual gross salary in dollars. Give this or hourly_rate.",
                    "example": 60000
                  },
                  "filing_status": {
                    "type": "string",
                    "description": "Default single.",
                    "enum": [
                      "single",
                      "joint",
                      "head"
                    ],
                    "example": "single"
                  }
                },
                "required": [
                  "state",
                  "bonus",
                  "salary"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "docs": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ]
      }
    }
  }
}