{"openapi":"3.1.0","info":{"title":"PaycheckMath API","version":"0.1.0","description":"US gross-to-net paycheck calculators: simplified annualized-percentage-method federal withholding, full FICA (Social Security wage-base capping, Medicare, Additional Medicare Tax), pre-tax 401(k)/health-premium handling, a full-year pay-period schedule, and a glossary — all local, from bundled verified IRS/SSA figures.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://paycheckmath.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/paycheckmath/docs"},"termsOfService":"https://connectorbay.com/paycheckmath/terms"},"servers":[{"url":"https://paycheckmath.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/paycheckmath/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/federal_withholding_estimate":{"post":{"operationId":"federal_withholding_estimate","summary":"Simplified annualized-percentage-method federal income tax withholding estimate for one paycheck: not the","description":"Simplified annualized-percentage-method federal income tax withholding estimate for one paycheck: not the\n    official IRS Publication 15-T table (no Form W-4 modeled), but real bracket/standard-deduction math. Use for\n    \"federal withholding on $90,000 salary paid semimonthly, married filing jointly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"gross_pay":{"description":"Gross pay for one pay period.","exclusiveMinimum":0,"title":"Gross Pay","type":"number"},"pay_frequency":{"description":"weekly | biweekly | semimonthly | monthly","title":"Pay Frequency","type":"string"},"filing_status":{"description":"single | head_of_household | married_joint | married_separate","title":"Filing Status","type":"string"},"pretax_401k_pct":{"default":0.0,"description":"Traditional 401(k) contribution, % of gross pay.","maximum":100,"minimum":0,"title":"Pretax 401K Pct","type":"number"},"pretax_health_premium":{"default":0.0,"description":"Pre-tax (Section 125) health premium this pay period, in dollars.","minimum":0,"title":"Pretax Health Premium","type":"number"},"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"}},"required":["gross_pay","pay_frequency","filing_status"],"title":"federal_withholding_estimateArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/fica_calculator":{"post":{"operationId":"fica_calculator","summary":"Social Security (6.2%, capped at the annual wage base), Medicare (1.45%, uncapped), and Additional Medicare","description":"Social Security (6.2%, capped at the annual wage base), Medicare (1.45%, uncapped), and Additional Medicare\n    Tax (extra 0.9% once this employer's YTD wages exceed $200,000) for one paycheck, wage-base aware via a\n    year-to-date figure. Use for \"did my Social Security withholding stop yet\", \"Additional Medicare Tax on a\n    $220k salary\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"this_period_fica_wages":{"description":"FICA-taxable wages THIS pay period (gross pay minus any pre-tax cafeteria-plan health premium; 401(k) does not reduce this).","minimum":0,"title":"This Period Fica Wages","type":"number"},"filing_status":{"description":"single | head_of_household | married_joint | married_separate","title":"Filing Status","type":"string"},"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"},"ytd_fica_wages_before_this_check":{"default":0.0,"description":"FICA wages already paid this employer so far this year, BEFORE this check.","minimum":0,"title":"Ytd Fica Wages Before This Check","type":"number"}},"required":["this_period_fica_wages","filing_status"],"title":"fica_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/paycheck_calculator":{"post":{"operationId":"paycheck_calculator","summary":"Full gross-to-net breakdown for one paycheck: federal withholding, FICA, pre-tax deductions, and net pay,","description":"Full gross-to-net breakdown for one paycheck: federal withholding, FICA, pre-tax deductions, and net pay,\n    plus a flagged (not guessed) state-tax placeholder. Use for \"what's my take-home pay on $4,000 biweekly,\n    single, 6% to 401k and $150 health premium\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"gross_pay":{"description":"Gross pay for one pay period.","exclusiveMinimum":0,"title":"Gross Pay","type":"number"},"pay_frequency":{"description":"weekly | biweekly | semimonthly | monthly","title":"Pay Frequency","type":"string"},"filing_status":{"description":"single | head_of_household | married_joint | married_separate","title":"Filing Status","type":"string"},"pretax_401k_pct":{"default":0.0,"description":"Traditional 401(k) contribution, % of gross pay.","maximum":100,"minimum":0,"title":"Pretax 401K Pct","type":"number"},"pretax_health_premium":{"default":0.0,"description":"Pre-tax (Section 125) health premium this pay period, in dollars.","minimum":0,"title":"Pretax Health Premium","type":"number"},"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"},"ytd_fica_wages_before_this_check":{"default":0.0,"description":"FICA wages already paid this employer so far this year, BEFORE this check (for wage-base accuracy).","minimum":0,"title":"Ytd Fica Wages Before This Check","type":"number"}},"required":["gross_pay","pay_frequency","filing_status"],"title":"paycheck_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/annual_paycheck_projection":{"post":{"operationId":"annual_paycheck_projection","summary":"Runs a full year of identical paychecks and returns a per-period schedule plus annual totals, correctly","description":"Runs a full year of identical paychecks and returns a per-period schedule plus annual totals, correctly\n    modeling the pay period where the Social Security wage base is reached (SS withholding stops for the rest of\n    the year). Use for \"when does my paycheck get bigger because Social Security caps out on $260k salary\n    biweekly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"gross_pay":{"description":"Gross pay for one pay period, assumed constant all year.","exclusiveMinimum":0,"title":"Gross Pay","type":"number"},"pay_frequency":{"description":"weekly | biweekly | semimonthly | monthly","title":"Pay Frequency","type":"string"},"filing_status":{"description":"single | head_of_household | married_joint | married_separate","title":"Filing Status","type":"string"},"pretax_401k_pct":{"default":0.0,"description":"Traditional 401(k) contribution, % of gross pay.","maximum":100,"minimum":0,"title":"Pretax 401K Pct","type":"number"},"pretax_health_premium":{"default":0.0,"description":"Pre-tax (Section 125) health premium each pay period, in dollars.","minimum":0,"title":"Pretax Health Premium","type":"number"},"year":{"default":"2026","description":"Tax year: 2025 | 2026","title":"Year","type":"string"}},"required":["gross_pay","pay_frequency","filing_status"],"title":"annual_paycheck_projectionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/paycheck_glossary":{"post":{"operationId":"paycheck_glossary","summary":"Definitions of common payroll terms (FICA, Social Security wage base, Additional Medicare Tax, pre-tax","description":"Definitions of common payroll terms (FICA, Social Security wage base, Additional Medicare Tax, pre-tax\n    deduction, Section 125 cafeteria plan, Form W-4, pay frequency, ...). Use for \"what's the wage base\", \"what's\n    a cafeteria plan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"paycheck_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}