Skip to content

Tax

Federal income tax, capital gains, after-tax projections, and resident state and local income tax for all 50 states + DC.

apply_after_tax_to_projection_result

Apply withdrawal taxes to a projection result, computing after-tax spendable values.

Parameter Type Default Description
projection_result_json object required The 'projection_result' object from run_projection's output. Pass the value of the 'projection_result' key directly.
account_tax_treatment string required Account tax treatment category. pre_tax: Traditional 401k/IRA (withdrawals taxed as ordinary income). post_tax_deferred: Roth 401k/IRA (tax-free withdrawals). taxable: Brokerage or savings (capital gains on liquidation). tax_advantaged: HSA, 529 (tax-free for qualified expenses).
marginal_ordinary_rate float required Marginal ordinary income tax rate as decimal (e.g., 0.22 = 22%).
ltcg_rate float required Long-term capital gains tax rate as decimal (e.g., 0.15 = 15%).
taxable_income_type string "none" How income from this account is taxed on withdrawal. none: Tax-deferred accounts (Traditional IRA, Roth). ordinary_income: Cash accounts (savings, checking). investment_income: Brokerage accounts (capital gains on sale).
initial_cost_basis_cents int null For taxable brokerage accounts: the original invested amount in cents. Cost basis stays fixed as the portfolio grows, so the taxable gain fraction increases over time. Ignored for non-brokerage accounts.

Returns the adjusted projection result with corrected after_tax_percentiles.

calculate_amt

Calculate the Alternative Minimum Tax (Form 6251).

Parameter Type Default Description
regular_taxable_income_cents int required Regular taxable income in cents
regular_tax_cents int required Regular federal income tax (the AMT comparison baseline) in cents
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
iso_exercise_spread_cents int 0 Bargain element (spread) on incentive stock options exercised and held past year end, in cents. A deferral preference that generates a recoverable minimum tax credit.
other_deferral_preferences_cents int 0 Other deferral (timing) AMT preference items in cents
salt_addback_cents int 0 State and local taxes added back for AMT, in cents. An exclusion preference that does not generate a recoverable credit.
other_exclusion_preferences_cents int 0 Other exclusion (permanent) AMT preference items in cents
tax_year int 2026 Tax year. Options: 2026

Returns AMTI, the phased-out exemption, the tentative minimum tax, the AMT owed, and the minimum-tax-credit (Form 8801) carryforward generated by deferral preferences such as the ISO exercise-and-hold spread.

model_iso_exercise

Model the tax effect of an incentive stock option (ISO) exercise.

Parameter Type Default Description
strike_cents int required Per-share strike (exercise) price in cents
fmv_cents int required Per-share fair market value at exercise, in cents
shares int required Number of options exercised
intent string required Disposition intent for the year of exercise. 'hold' = exercise-and-hold (qualifying path; generates an AMT preference, no regular-tax ordinary income, FICA-exempt, Form 8801 minimum-tax-credit eligible). 'disqualify_same_year' = sell in the same calendar year (ordinary income = spread, no AMT preference; FICA-exempt).
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
ytd_supplemental_paid_cents int 0 Year-to-date supplemental wages already paid before this event, in cents. Unused for ISO directly (ISO income is not subject to federal supplemental withholding); accepted for API symmetry with the NQSO/RSU tools.
tax_year int 2026 Tax year. Options: 2026

Returns the AMT preference (for the exercise-and-hold path) or ordinary income (for a same-year disqualifying disposition), in both _cents and _dollars form, plus a plain-English explanation of which path was taken. Cash exercise is assumed, so the share-surrender fields are always zero.

model_rsu_vest

Model the tax effect of a restricted stock unit (RSU) vest.

Parameter Type Default Description
fmv_cents int required Per-share fair market value at vest, in cents
shares_vesting int required Number of shares vesting
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
ytd_supplemental_paid_cents int 0 Year-to-date supplemental wages already paid before this event, in cents. Positions the vest value against the $1M aggregate supplemental-wage cap for the 22%/37% withholding split.
tax_year int 2026 Tax year. Options: 2026

Returns the vest value (FMV × shares_vesting) as FICA-subject ordinary (W-2) income, the mandatory federal supplemental-wage withholding (flat 22% up to the $1M aggregate YTD cap, mandatory 37% above), and zero AMT preference — in both _cents and _dollars form, plus a plain-English explanation.

model_nqso_exercise

Model the tax effect of a non-qualified stock option (NQSO) exercise.

Parameter Type Default Description
strike_cents int required Per-share strike (exercise) price in cents
fmv_cents int required Per-share fair market value at exercise, in cents
shares int required Number of options exercised
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
ytd_supplemental_paid_cents int 0 Year-to-date supplemental wages already paid before this event, in cents. Positions the bargain element against the $1M aggregate supplemental-wage cap for the 22%/37% withholding split.
tax_year int 2026 Tax year. Options: 2026

Returns the bargain element ((FMV − strike) × shares) as FICA-subject ordinary (W-2) income, the mandatory federal supplemental-wage withholding (flat 22% up to the $1M aggregate YTD cap, mandatory 37% above), and zero AMT preference — in both _cents and _dollars form, plus a plain-English explanation.

calculate_federal_tax_liability

Calculate the full federal tax liability — AGI, deductions, taxable income, ordinary-bracket tax, preferential-rate (LTCG/qualified-dividend) stacking, NIIT, Additional Medicare, and AMT — for a single tax year.

Parameter Type Default Description
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
wages_cents int 0 Regular W-2 wages in cents. Must exclude RSU/NQSO supplemental compensation reported in W-2 Box 1 — those go in supplemental_ordinary_fica_subject_cents to avoid double-counting.
supplemental_ordinary_fica_subject_cents int 0 RSU vest / NQSO exercise ordinary income, in cents. FICA-subject (included in the Additional Medicare base).
supplemental_ordinary_fica_exempt_cents int 0 ISO disqualifying-disposition ordinary-income portion, in cents. FICA-exempt (excluded from the Additional Medicare base).
qualified_dividends_cents int 0 Qualified dividends in cents. Must be the subset of ordinary_dividends_cents that qualifies for preferential rates.
ordinary_dividends_cents int 0 Total ordinary dividends in cents (1099-DIV Box 1a).
short_term_capital_gains_cents int 0 Short-term capital gains in cents.
long_term_capital_gains_cents int 0 Long-term capital gains in cents.
interest_income_cents int 0 Taxable interest income in cents.
other_ordinary_cents int 0 Other ordinary income in cents (e.g., taxable distributions).
above_the_line_adjustments_cents int 0 Above-the-line adjustments in cents (traditional 401(k) deferral, HSA, SE tax/2, student-loan interest, etc.).
salt_paid_state_cents int 0 State income tax paid in cents (for itemized deduction).
salt_paid_local_cents int 0 Local income tax paid in cents.
salt_paid_property_cents int 0 Property tax paid in cents.
mortgage_interest_cents int 0 Home mortgage interest paid in cents.
mortgage_principal_balance_cents int 0 Average mortgage principal balance for the year, in cents.
mortgage_origination_year int null Mortgage origination year. Pre-2018 originations get the grandfathered $1M acquisition-debt cap; 2018+ get $750K. Required when mortgage_interest_cents > 0; ignored otherwise.
charitable_cash_cents int 0 Charitable cash contributions in cents (itemized deduction, subject to the IRC §170 AGI ceiling for cash gifts).
charitable_appreciated_asset_cents int 0 Charitable contributions of appreciated long-term capital-gain property (e.g. stock) in cents, subject to the lower IRC §170 AGI ceiling for such gifts.
charitable_other_property_cents int 0 Charitable contributions of other (non-cash, non-appreciated) property in cents.
medical_expenses_cents int 0 Unreimbursed medical and dental expenses in cents. Only the amount exceeding 7.5% of AGI is deductible (IRC §213(a)).
casualty_theft_loss_cents int 0 Gross personal casualty or theft loss in cents from a single federally declared disaster event. Post-TCJA, deductible only when federally_declared_disaster is True (IRC §165(h)). The $100 per-event floor and the 10%-of-AGI floor are applied automatically — pass the gross loss, not a pre-reduced amount. For multiple events, sum the gross per-event losses (a single $100 floor is applied to the aggregate).
federally_declared_disaster bool false True when the casualty/theft loss arises from a federally declared disaster. Required for casualty_theft_loss_cents to be deductible post-TCJA.
iso_preference_cents int 0 ISO exercise-and-hold bargain element, in cents. AMT deferral preference that generates a recoverable Form 8801 credit.
tax_year int 2026 Tax year. Options: 2026

Returns every component in both _cents and _dollars form, plus the chosen deduction, marginal ordinary rate, effective rate, and the AMT Form 8801 credit carryforward.

calculate_federal_income_tax

Calculate federal income tax for the given taxable income and filing status.

Parameter Type Default Description
taxable_income_cents int required Taxable income in cents
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
tax_year int 2026 Tax year. Options: 2024, 2025, or 2026

Returns tax owed, effective rate, and marginal rate.

calculate_capital_gains_tax_rate

Get the long-term capital gains tax rate based on income and filing status.

Parameter Type Default Description
taxable_income_cents int required Taxable income in cents (before capital gains)
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
tax_year int 2026 Tax year. Options: 2024, 2025, or 2026

Returns the applicable LTCG rate for the given income level.

calculate_state_and_local_income_tax

Calculate resident state and (optionally) local income tax. Covers all 50 states + DC on each state's own brackets (resident returns, before state credits), plus the local layers: NYC, Yonkers, every Maryland county, Philadelphia, Detroit, Columbus/Cleveland/Cincinnati/Toledo, St. Louis, Kansas City, Louisville, Birmingham, and Wilmington.

Parameter Type Default Description
state_code string required Two-letter US state code.
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
wages_cents int 0 Wages, salary, and other compensation in cents, after any state deduction the caller applies. Exception: WI (sliding-scale standard deduction) and CT (personal exemption) apply their deduction internally — it is already reflected in the returned state_taxable_income and must NOT be pre-subtracted here, or it is double-counted.
social_security_cents int 0 Social Security benefits in cents. Most states exempt these.
pension_cents int 0 Pension and annuity income in cents. On a joint return this is the taxpayer's; put the spouse's in spouse_pension_cents.
retirement_distribution_cents int 0 IRA / 401(k) / 403(b) distributions in cents. On a joint return this is the taxpayer's; put the spouse's in spouse_retirement_distribution_cents.
interest_dividends_cents int 0 Taxable interest and dividend income in cents.
capital_gains_cents int 0 Net capital gains in cents.
business_income_cents int 0 Sole-proprietorship, partnership, and S-corp income in cents.
other_income_cents int 0 Ordinary income not covered by the other components, in cents. No state exclusion attaches to it.
age float 0 Taxpayer age at the end of the tax year. Retirement exclusions are age-gated (NY's pension exclusion requires 59.5), so leaving this at 0 forfeits them. Fractional ages are accepted.
spouse_age float 0 Spouse's age at the end of the tax year, on a joint return. The retirement exclusions are per filer, so each spouse who clears the age gate claims their own against their own retirement income (a NY couple both 59.5+, each with a pension, excludes $40,000, not $20,000). Leaving this at 0 claims only the taxpayer's. Ignored unless filing_status is married_joint.
spouse_pension_cents int 0 Spouse's pension and annuity income in cents, on a joint return. Kept separate from pension_cents because the exclusion caps each spouse against their OWN income — an unused spouse's cap is not transferable, so pooling both pensions into pension_cents forfeits the second exclusion. Ignored unless filing_status is married_joint.
spouse_retirement_distribution_cents int 0 Spouse's IRA / 401(k) / 403(b) distributions in cents, on a joint return. Kept separate from retirement_distribution_cents for the same reason as spouse_pension_cents. Ignored unless filing_status is married_joint.
federal_agi_cents int 0 Federal AGI in cents, for states whose exclusions carry an income cutoff. 0 means not supplied.
federal_taxable_income_cents int 0 Federal taxable income in cents, for states that start from it rather than from AGI. 0 means not supplied.
federal_tax_paid_cents int 0 Federal income tax liability in cents, for the states that subtract it (OR, AL, MO). 0 means not supplied.
locality string "" Optional resident locality slug for local income tax. Leave empty for state-only calculation. Recognized values depend on the state.
tax_year int 2026 Tax year

Returns state and local tax amounts, the state taxable income the state actually landed on (after its exclusions), marginal/effective rates, and the state standard deduction.

get_tax_parameters

Look up year- and filing-status-specific federal tax scalars.

Parameter Type Default Description
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
tax_year int 2026 Tax year. Options: 2026

Returns SALT cap and phase-down, AMT exemption / phase-out / rate breakpoint, NIIT and Additional Medicare thresholds, supplemental wage withholding rates, mortgage acquisition-debt caps, and the 402(g) / 401(a)(17) / 414(v) / 415(c) retirement limits. Each scalar is returned in both _cents and _dollars form, plus a source citation string.

analyze_roth_conversion

Analyze converting a traditional IRA/401(k) amount to Roth this year.

Parameter Type Default Description
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
traditional_balance_cents int required Traditional IRA/401(k) balance available to convert, in cents.
birth_year int required Account owner's birth year.
time_horizon_years int required Number of years to project RMDs and terminal values.
future_marginal_rate float required Assumed marginal ordinary rate at future withdrawal, as a decimal.
wages_cents int 0 Regular W-2 wages in cents. Must exclude RSU/NQSO supplemental compensation reported in W-2 Box 1 — those go in supplemental_ordinary_fica_subject_cents to avoid double-counting.
supplemental_ordinary_fica_subject_cents int 0 RSU vest / NQSO exercise ordinary income, in cents. FICA-subject (included in the Additional Medicare base).
supplemental_ordinary_fica_exempt_cents int 0 ISO disqualifying-disposition ordinary-income portion, in cents. FICA-exempt (excluded from the Additional Medicare base).
qualified_dividends_cents int 0 Qualified dividends in cents. Must be the subset of ordinary_dividends_cents that qualifies for preferential rates.
ordinary_dividends_cents int 0 Total ordinary dividends in cents (1099-DIV Box 1a).
short_term_capital_gains_cents int 0 Short-term capital gains in cents.
long_term_capital_gains_cents int 0 Long-term capital gains in cents.
interest_income_cents int 0 Taxable interest income in cents.
other_ordinary_cents int 0 Other ordinary income in cents (e.g., taxable distributions).
above_the_line_adjustments_cents int 0 Above-the-line adjustments in cents (traditional 401(k) deferral, HSA, SE tax/2, student-loan interest, etc.).
salt_paid_state_cents int 0 State income tax paid in cents (for itemized deduction).
salt_paid_local_cents int 0 Local income tax paid in cents.
salt_paid_property_cents int 0 Property tax paid in cents.
mortgage_interest_cents int 0 Home mortgage interest paid in cents.
mortgage_principal_balance_cents int 0 Average mortgage principal balance for the year, in cents.
mortgage_origination_year int null Mortgage origination year. Pre-2018 originations get the grandfathered $1M acquisition-debt cap; 2018+ get $750K. Required when mortgage_interest_cents > 0; ignored otherwise.
charitable_cash_cents int 0 Charitable cash contributions in cents (itemized deduction, subject to the IRC §170 AGI ceiling for cash gifts).
charitable_appreciated_asset_cents int 0 Charitable contributions of appreciated long-term capital-gain property (e.g. stock) in cents, subject to the lower IRC §170 AGI ceiling for such gifts.
charitable_other_property_cents int 0 Charitable contributions of other (non-cash, non-appreciated) property in cents.
medical_expenses_cents int 0 Unreimbursed medical and dental expenses in cents. Only the amount exceeding 7.5% of AGI is deductible (IRC §213(a)).
casualty_theft_loss_cents int 0 Gross personal casualty or theft loss in cents from a single federally declared disaster event. Post-TCJA, deductible only when federally_declared_disaster is True (IRC §165(h)). The $100 per-event floor and the 10%-of-AGI floor are applied automatically — pass the gross loss, not a pre-reduced amount. For multiple events, sum the gross per-event losses (a single $100 floor is applied to the aggregate).
federally_declared_disaster bool false True when the casualty/theft loss arises from a federally declared disaster. Required for casualty_theft_loss_cents to be deductible post-TCJA.
iso_preference_cents int 0 ISO exercise-and-hold bargain element, in cents. AMT deferral preference that generates a recoverable Form 8801 credit.
expected_annual_return float 0.06 Assumed nominal annual return, as a decimal (e.g. 0.06 = 6%).
conversion_amount_cents int null Explicit conversion amount in cents. Provide exactly one of conversion_amount_cents, fill_to_marginal_rate, or recommend.
fill_to_marginal_rate float null Fill-bracket mode: convert enough to raise ordinary taxable income to the top of the bracket with this marginal rate, e.g. 0.24. Provide exactly one of conversion_amount_cents, fill_to_marginal_rate, or recommend.
recommend bool false Recommend mode — answers 'how much should I convert?'. Returns the largest conversion whose next-dollar marginal cost rate stays at or below future_marginal_rate (0 if converting nothing is best). Federal-only and cliff-unaware (no IRMAA/ACA surcharge edges). Provide exactly one of conversion_amount_cents, fill_to_marginal_rate, or recommend.
state_code string null Two-letter resident state code (e.g. 'NY'). When provided, resident state+local income tax on the conversion is folded into the cost and break-even. Omit for a federal-only analysis. Unsupported states return success: false.
locality string "" Resident locality slug for local income tax (e.g. 'nyc', 'yonkers'). Leave empty for state-only. Ignored when state_code is omitted.
state_wages_cents int 0 Wages, salary, and other compensation in cents, after any state deduction the caller applies. Part of the state income base. Every state_* component defaults to 0; state_code with all of them left at 0 is accepted as a (degenerate) all-zero state base.
state_social_security_cents int 0 Social Security benefits in cents. Most states exempt these.
state_pension_cents int 0 Pension and annuity income in cents, before the conversion. On a joint return this is the taxpayer's; put the spouse's in state_spouse_pension_cents.
state_retirement_distribution_cents int 0 IRA / 401(k) / 403(b) distributions already received this year, before the conversion, in cents. The conversion amount itself is added automatically as an additional taxpayer retirement distribution — it is not entered here.
state_interest_dividends_cents int 0 Taxable interest and dividend income in cents.
state_capital_gains_cents int 0 Net capital gains in cents.
state_business_income_cents int 0 Sole-proprietorship, partnership, and S-corp income in cents.
state_other_income_cents int 0 State ordinary income not covered by the other state_* fields, in cents. No state exclusion attaches to it.
state_age float 0 Taxpayer age at the end of the tax year, for age-gated state retirement exclusions (e.g. NY's pension exclusion requires 59.5). This also gates the exclusion for the converted amount itself, since it is classified as a retirement distribution. Leaving this at 0 forfeits the exclusion.
state_spouse_age float 0 Spouse's age at the end of the tax year, on a joint return. Ignored unless filing_status is married_joint.
state_spouse_pension_cents int 0 Spouse's pension and annuity income in cents, on a joint return.
state_spouse_retirement_distribution_cents int 0 Spouse's IRA / 401(k) / 403(b) distributions in cents, on a joint return, before the conversion. The conversion is attributed to the taxpayer, not the spouse; see state_retirement_distribution_cents.
state_federal_agi_cents int 0 Federal AGI in cents, for state exclusions with an income cutoff. 0 means not supplied.
state_federal_taxable_income_cents int 0 Federal taxable income in cents, for states that start from it rather than from AGI. 0 means not supplied.
state_federal_tax_paid_cents int 0 Federal income tax liability in cents, for the states that subtract it (OR, AL, MO). 0 means not supplied.
future_state_marginal_rate float null Assumed resident state+local marginal rate at future withdrawal, as a decimal (e.g. 0.0685). When state_code is provided but this is omitted, the conversion's own state+local marginal cost rate is used as the proxy (state is then a wash in the decision).
tax_year int 2026 Tax year. Options: 2026

Returns: assumptions, marginal_cost_rate, baseline_marginal_ordinary_rate, post_conversion_marginal_ordinary_rate, rmd_reduction, break_even, and summary.

estimate_underpayment_safe_harbor

Estimate whether withholding meets the IRS safe-harbor threshold for avoiding underpayment penalties.

Parameter Type Default Description
prior_year_total_tax_cents int required Total tax from the prior year's return, in cents
prior_year_agi_cents int required Adjusted gross income from the prior year's return, in cents
current_year_projected_tax_cents int required Projected total federal tax for the current year, in cents
withholding_cents int required Year-to-date plus expected remaining withholding for the current year, in cents
filing_status string required Tax filing status. Options: single, married_joint, married_separate, head_of_household, or qualifying_widow
tax_year int 2026 Current tax year

Returns the safe-harbor target, the basis used (90% of current-year tax or 100/110% of prior-year tax), whether a penalty would apply, and suggested quarterly 1040-ES payments to close any gap.