Guides by outcome

Compute federal tax for a W-2 employee

The most common case: a household whose income is wages. You will send the W-2 figures and get back the 1040's taxable income, total tax, and the balance due or refund.

Facts to collect

FromFieldNotes
The returnyear, filingStatus, canBeClaimedAsDependent, noForeignOrTerritoryExclusionAffirmedRequired on every call.
W-2 box 1wagesAdd box 1 across all of the return's W-2s.
W-2 box 5medicareWagesRequired whenever wages are positive. Add box 5 across all W-2s.
W-2 box 2federalWithholdingOptional. With it, the response includes the balance due or refund.
W-2 box 3socialSecurityWagesOnly with self-employment income, and then notsummed: it is the self-employed person's own box 3 (see self-employment).

Compute the return

A married couple filing jointly with $180,000 of combined wages:
Request
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2025,
    "filingStatus": "married_filing_jointly",
    "canBeClaimedAsDependent": false,
    "noForeignOrTerritoryExclusionAffirmed": true,
    "wages": 180000,
    "medicareWages": 180000,
    "federalWithholding": 21000
  }'
Response 200 · COMPUTED
{
  "computed": true,
  "year": 2025,
  "filingStatus": "married_filing_jointly",
  "taxableIncome": 148500,
  "incomeTax": 22498,
  "totalTax": 22498,
  "lines": [
    { "lineId": "1040:15", "label": "Taxable income", "amount": 148500 },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 22498,
      "derivation": "<3 derivation steps — see full response>"
    },
    { "lineId": "1040:24", "label": "Total tax", "amount": 22498 }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "owedOrRefund": 1498,
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "<computation-support notice — see full response>"
  }
}
Full response, including line derivations
{
  "computed": true,
  "year": 2025,
  "filingStatus": "married_filing_jointly",
  "taxableIncome": 148500,
  "incomeTax": 22498,
  "totalTax": 22498,
  "lines": [
    {
      "lineId": "1040:15",
      "label": "Taxable income",
      "amount": 148500,
      "derivation": []
    },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 22498,
      "derivation": [
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 10% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 23850 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2025/married_filing_jointly",
              "value": "10% (up to $23,850)",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.1 × $23,850 = $2,385",
          "result": 2385
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 12% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 73100 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2025/married_filing_jointly",
              "value": "12% (up to $96,950)",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.12 × $73,100 = $8,772",
          "result": 8772
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 22% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 51550 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2025/married_filing_jointly",
              "value": "22% (up to $206,700)",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.22 × $51,550 = $11,341",
          "result": 11341
        }
      ]
    },
    {
      "lineId": "1040:24",
      "label": "Total tax",
      "amount": 22498,
      "derivation": []
    }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "owedOrRefund": 1498,
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
  }
}

totalTax is $22,498. The engine chose the standard deduction because no itemized deductions were sent; when you send them, it uses whichever is larger. A 2025-2026 qualified disaster loss (qualifiedDisasterCasualties, Form 4684) is deducted on top of either, outside Schedule A. From 2026, itemized deductions are first reduced under §68: by 2/37 of the smaller of the itemized total and the amount by which income before itemized deductions (AGI less the QBI deduction, the senior deduction and any qualified disaster loss) exceeds where the 37% bracket starts. The AMT ignores that reduction.

Read the balance due or refund

owedOrRefund is total tax minus withholding (and any refundable credit). Positive means the taxpayer owes; negative means a refund.

A head of household with $6,000 withheld gets owedOrRefund: -1375, a $1,375 refund:
Request
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2025,
    "filingStatus": "head_of_household",
    "canBeClaimedAsDependent": false,
    "noForeignOrTerritoryExclusionAffirmed": true,
    "wages": 65000,
    "medicareWages": 65000,
    "federalWithholding": 6000
  }'
Response 200 · COMPUTED
{
  "computed": true,
  "year": 2025,
  "filingStatus": "head_of_household",
  "taxableIncome": 41375,
  "incomeTax": 4625,
  "totalTax": 4625,
  "lines": [
    { "lineId": "1040:15", "label": "Taxable income", "amount": 41375 },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 4625,
      "derivation": "<3 derivation steps — see full response>"
    },
    { "lineId": "1040:24", "label": "Total tax", "amount": 4625 }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "owedOrRefund": -1375,
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "<computation-support notice — see full response>"
  }
}
Full response, including line derivations
{
  "computed": true,
  "year": 2025,
  "filingStatus": "head_of_household",
  "taxableIncome": 41375,
  "incomeTax": 4625,
  "totalTax": 4625,
  "lines": [
    {
      "lineId": "1040:15",
      "label": "Taxable income",
      "amount": 41375,
      "derivation": []
    },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 4625,
      "derivation": [
        {
          "lineId": "1040:16",
          "label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
          "inputs": [
            { "name": "taxableIncome", "value": 41375 }
          ],
          "rule": {
            "description": "Form 1040 instructions require the published Tax Table — a lookup on the midpoint of a narrow taxable-income band — for taxable income under $100,000; the exact bracket formula (Tax Computation Worksheet) applies only at $100,000 or more.",
            "authority": "Form 1040 instructions — Tax Table"
          },
          "computation": "taxable income $41,375 → Tax Table band midpoint $41,375",
          "result": 0
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 10% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 17000 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2025/head_of_household",
              "value": "10% (up to $17,000)",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.1 × $17,000 = $1,700",
          "result": 1700
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 12% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 24375 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2025/head_of_household",
              "value": "12% (up to $64,850)",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.12 × $24,375 = $2,925",
          "result": 2925
        }
      ]
    },
    {
      "lineId": "1040:24",
      "label": "Total tax",
      "amount": 4625,
      "derivation": []
    }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "owedOrRefund": -1375,
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2025 },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
  }
}

Next year's estimated tax (2026 returns)

Add estimatedTaxNextYearto a 2026 return to get the 2027 Form 1040-ES prior-year safe harbor: 100% of this return's tax shown (total tax minus the additional child tax credit and the net premium tax credit), or 110% when AGI is over $150,000 ($75,000 if next year's return is married filing separately). Because the engine cannot know how the filed return rounds, it uses 110% unless AGI is at least $1,000 below that line, and figures the amount on tax shown plus $100. Paid in four installments by their due dates, it avoids next year's underpayment penalty whatever next year's income turns out to be, provided the filed return shows the same total tax. It is not the least the taxpayer could pay: 90% of next year's tax may be smaller, and the engine does not compute that.

$36,734 of tax shown, plus $100, at 110% is $40,518; after $20,000 of expected withholding, four installments of $5,130:
Request
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2026,
    "filingStatus": "single",
    "canBeClaimedAsDependent": false,
    "noForeignOrTerritoryExclusionAffirmed": true,
    "wages": 200000,
    "medicareWages": 200000,
    "federalWithholding": 38000,
    "estimatedTaxNextYear": {
      "filingStatus": "single",
      "expectedWithholding": 20000,
      "thisReturnWillBeFiledCovering12Months": true
    }
  }'
Response 200 · COMPUTED
{
  "computed": true,
  "year": 2026,
  "filingStatus": "single",
  "taxableIncome": 183900,
  "incomeTax": 36734,
  "totalTax": 36734,
  "lines": [
    { "lineId": "1040:15", "label": "Taxable income", "amount": 183900 },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 36734,
      "derivation": "<4 derivation steps — see full response>"
    },
    { "lineId": "1040:24", "label": "Total tax", "amount": 36734 }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "owedOrRefund": -1266,
  "estimatedTaxNextYear": {
    "computed": true,
    "year": 2027,
    "priorYearTaxShown": 36734,
    "safeHarborPercent": 110,
    "priorYearSafeHarborAmount": 40518,
    "expectedWithholding": 20000,
    "remainingAfterWithholding": 20518,
    "quarterlyInstallment": 5130,
    "dueDates": ["2027-04-15", "2027-06-15", "2027-09-15", "2028-01-15"]
  },
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2026 },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "<computation-support notice — see full response>"
  }
}
Full response, including line derivations
{
  "computed": true,
  "year": 2026,
  "filingStatus": "single",
  "taxableIncome": 183900,
  "incomeTax": 36734,
  "totalTax": 36734,
  "lines": [
    {
      "lineId": "1040:15",
      "label": "Taxable income",
      "amount": 183900,
      "derivation": []
    },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 36734,
      "derivation": [
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 10% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 12400 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2026/single",
              "value": "10% (up to $12,400)",
              "revProc": "Rev. Proc. 2025-32"
            }
          },
          "computation": "0.1 × $12,400 = $1,240",
          "result": 1240
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 12% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 38000 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2026/single",
              "value": "12% (up to $50,400)",
              "revProc": "Rev. Proc. 2025-32"
            }
          },
          "computation": "0.12 × $38,000 = $4,560",
          "result": 4560
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 22% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 55300 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2026/single",
              "value": "22% (up to $105,700)",
              "revProc": "Rev. Proc. 2025-32"
            }
          },
          "computation": "0.22 × $55,300 = $12,166",
          "result": 12166
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 24% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 78200 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2026/single",
              "value": "24% (up to $201,775)",
              "revProc": "Rev. Proc. 2025-32"
            }
          },
          "computation": "0.24 × $78,200 = $18,768",
          "result": 18768
        }
      ]
    },
    {
      "lineId": "1040:24",
      "label": "Total tax",
      "amount": 36734,
      "derivation": []
    }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "owedOrRefund": -1266,
  "estimatedTaxNextYear": {
    "computed": true,
    "year": 2027,
    "priorYearTaxShown": 36734,
    "safeHarborPercent": 110,
    "priorYearSafeHarborAmount": 40518,
    "expectedWithholding": 20000,
    "remainingAfterWithholding": 20518,
    "quarterlyInstallment": 5130,
    "dueDates": ["2027-04-15", "2027-06-15", "2027-09-15", "2028-01-15"]
  },
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": { "engine": "deterministic", "jurisdiction": "federal", "tax_year": 2026 },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
  }
}

Send thisReturnWillBeFiledCovering12Months: true. The block computes only from a request without Social Security benefits, since the engine keeps cents in the Social Security worksheet. Otherwise it declines with a code, and the return itself still computes. A change between a joint and a separate return declines too, and a joint return both years also needs sameSpouseAsThisReturn: true. A return with an additional child tax credit needs federalPublicBenefitAffirmed: true: a No answer on Schedule 3-A withholds part of that credit, which would make the tax shown higher. A due date on a weekend or legal holiday moves to the next business day, and a refund applied to next year counts toward the first installment. What can make the amount too low is listed under not_modeled.estimated_tax_next_year in the capabilities response.

Common declines and how to fix them

Leaving out W-2 box 5 declines the whole return. Add medicareWages and resend:
Request
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2025,
    "filingStatus": "single",
    "canBeClaimedAsDependent": false,
    "noForeignOrTerritoryExclusionAffirmed": true,
    "wages": 75000
  }'
Response 200 · DECLINED · surtax_additional_medicare
{
  "computed": false,
  "code": "surtax_additional_medicare",
  "reason": "box-5 Medicare wages were not supplied, but the return shows other objective W-2 evidence (positive wages) — box 5 can exceed box 1 or diverge from box 2/3/6 by an unbounded amount for real filers (401(k)/403(b)/457(b) elective deferrals reduce box 1 but remain subject to FICA/Medicare tax, inflating box 5 relative to box 1), so no finite margin can rule out the Additional Medicare Tax threshold ($200,000 for single) being crossed at box 5 — supply medicareWages to compute, or a preparer must review; computing without it could under-state tax",
  "billed": true,
  "retry_safe": false,
  "next_action": "review_inputs"
}
Full response, including line derivations
{
  "computed": false,
  "code": "surtax_additional_medicare",
  "reason": "box-5 Medicare wages were not supplied, but the return shows other objective W-2 evidence (positive wages) — box 5 can exceed box 1 or diverge from box 2/3/6 by an unbounded amount for real filers (401(k)/403(b)/457(b) elective deferrals reduce box 1 but remain subject to FICA/Medicare tax, inflating box 5 relative to box 1), so no finite margin can rule out the Additional Medicare Tax threshold ($200,000 for single) being crossed at box 5 — supply medicareWages to compute, or a preparer must review; computing without it could under-state tax",
  "billed": true,
  "retry_safe": false,
  "next_action": "review_inputs"
}

Other income on the return?

Interest and dividends need an extra affirmation (guide), and self-employment income needs two (guide). Everything the federal endpoint accepts is in the federal reference.

See also: State income tax and /tax-compute/federal.

Roadmap status for this page

Generated from the roadmap (updated 2026-10-30). Shipped & certified means live and independently checked against primary tax sources; certifying means live, with those checks still in progress.

Federal income tax — core 1040
CapabilityStatus
Federal withholding → owed / refundComputes the federal amount owed or refund from tax withheld on Form 1040.✅ shipped & certified
Lifecycle — projection, estimates, amendments
CapabilityStatus
Next year's estimated tax (Form 1040-ES) with the prior-year safe harborNext year's 1040-ES prior-year safe harbor on 2026 returns.◐ certifying