Tax
Federal income tax, payroll tax (FICA/SECA), capital gains, after-tax projections, and resident state and local income tax for all 50 states + DC.
apply_after_tax_to_projection_result
Section titled “apply_after_tax_to_projection_result”Apply withdrawal taxes to a projection result, computing after-tax spendable values.
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
projection_ref |
string | null | The projection_ref from run_projection’s response (or its urls.data URL). The full projection, percentiles included, is loaded from the server’s file store, so the time series never enters context. Preferred input. Provide exactly one of projection_ref or projection_result_json. run_projection called with summary_only=true writes no file and returns no projection_ref. |
projection_result_json |
object | null | A complete projection_result object, passed inline, including its ‘percentiles’ time series. run_projection’s inline summary.projection_result omits ‘percentiles’ and is rejected here; pass projection_ref instead. Provide exactly one of projection_ref or projection_result_json. |
Returns {success, urls, final_balance_percentiles, summary, ...}: the adjusted projection result (with after_tax_percentiles) is written to the file at urls.data; only the final-month pre-/after-tax values are returned inline.
calculate_amt
Section titled “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 when itemizing (Form 6251 line 2a), 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. When the standard deduction was claimed, include it here: Form 6251 line 2a adds it back in place of SALT. |
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
Section titled “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
Section titled “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
Section titled “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
Section titled “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). Must exclude Social Security benefits, gross and taxable alike — those go in social_security_benefits_cents. |
social_security_benefits_cents |
int | 0 |
GROSS Social Security benefits for the year (Form SSA-1099 box 5), in cents, summed across the filers on the return. Only the IRC §86 taxable portion enters AGI and this tool derives it — so pass the gross benefit, never the taxable part, and keep it out of other_ordinary_cents. The taxable portion is reported as taxable_social_security_cents. |
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.). |
foreign_earned_income_exclusion_cents |
int | 0 |
IRC §911 foreign-earned-income exclusion in cents. Excluded from AGI but added back to reach MAGI for the Net Investment Income Tax and the OBBBA §70120 SALT-cap phase-down. The excluded income must be omitted from wages_cents, or AGI is overstated and MAGI double-counts it. |
net_earnings_from_self_employment_cents |
int | 0 |
Net earnings from self-employment in cents (92.35% of net profit; calculate_payroll_tax’s net_earnings_from_self_employment_cents), summed across the filers on the return; enter a loss as 0. Feeds only the Additional Medicare base (Form 8959 Part II, threshold reduced by wages first), not AGI — put the profit itself in other_ordinary_cents. |
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. |
prior_minimum_tax_credit_cents |
int | 0 |
Minimum tax credit carried in from prior years, in cents — the prior year’s Form 8801 line 26. The part usable this year (IRC §53(c): capped at regular tax minus tentative minimum tax) is returned as minimum_tax_credit_allowed_cents; ISO spread in iso_preference_cents uses up the same room. |
aged_65_or_older_count |
int | 0 |
How many filers on the return are aged 65 or older at the end of the tax year. Each one raises the standard deduction by the additional amount for age; a filer who is also blind is counted again in blind_count. Two is the maximum on a joint or married-filing-separately return (a separate return may claim the spouse only when the spouse has no gross income and is not another taxpayer’s dependent), one otherwise. The standard-deduction increase does nothing for a filer who itemizes. Each one also brings the 2025-2028 senior deduction, which itemizers take too, except on a married-filing-separately return. |
blind_count |
int | 0 |
How many filers on the return are blind. Counted separately from aged_65_or_older_count, so a filer who is both 65+ and blind belongs in both. Same per-return maximum. |
tax_year |
int | 2026 |
Tax year. Options: 2026 |
Returns every component in both _cents and _dollars form, plus the chosen deduction, the age/blindness slice of the standard deduction, the senior deduction, marginal ordinary rate, effective rate, and the AMT Form 8801 credit carryforward. Pass prior_minimum_tax_credit_cents (last year’s Form 8801 line 26) to get minimum_tax_credit_allowed_cents (Form 8801 line 25, capped at regular tax minus tentative minimum tax), minimum_tax_credit_remaining_cents (the unused prior credit; next year’s credit is this plus amt_credit_carryforward_cents), and total_federal_liability_net_of_credit_cents. total_federal_liability_cents and effective_rate stay before the credit. itemized_deduction_limitation_cents reports the itemized deduction disallowed by IRC §68 — from 2026, 2/37 of the lesser of the deductions and the income above the 37% bracket floor; deduction_taken_cents is already net of it. AMT detail: amti_cents, amt_exemption_cents, tentative_minimum_tax_cents, regular_tax_for_amt_cents (ordinary plus preferential tax, the comparison baseline), amt_cushion_cents (regular minus tentative minimum tax; negative exactly when AMT is owed), and salt_deduction_allowed_cents (SALT after its cap and phase-down, before the §68 limitation; 0 under the standard deduction). Pass social_security_benefits_cents to have the IRC §86 taxable portion of Social Security benefits included in AGI and reported as taxable_social_security_cents with social_security_inclusion_rate.
calculate_federal_income_tax
Section titled “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
Section titled “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
Section titled “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 — the tool applies none of its own. Exceptions: WI (sliding-scale standard deduction) and CT (personal exemption) apply their deduction internally, and NY does when ny_itemized_deductions is given. Those deductions are already reflected in the returned state_taxable_income and must NOT be pre-subtracted here, or they are 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. |
long_term_capital_gains_cents |
int | 0 |
The long-term part of the gains, in cents, for Washington’s capital gains excise tax (RCW 82.87) — the only state tax that reads it. These dollars belong in capital_gains_cents too; this field is not added to total income. State it BEFORE Washington’s capital gains standard deduction (the tool subtracts it) and after the statute’s exemptions (real estate, retirement-account assets, and the rest of RCW 82.87.050). Leaving it at 0 owes no Washington capital gains tax. |
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, and as NY AGI for NY’s supplemental tax. 0 means not supplied; NY then reads its taxable income as NY AGI, which can understate that tax. |
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. |
plan_529_contributions |
list[Plan529ContributionInput] | null | 529 contributions made this tax year, each with the sponsoring plan’s state, a beneficiary label and the amount. Give them to see the state’s 529 deduction or credit and the tax it saves, reported in plan_529_benefit. A deduction lowers state_taxable_income and state_tax_cents, and the local tax where the locality starts from the state base (NYC, the Maryland counties). A credit is not in state_tax_cents, which is before state credits; plan_529_benefit reports it and the tax it saves. A credit that phases out by income (Minnesota’s) needs federal_agi_cents; without it the credit is lost. |
ny_itemized_deductions |
NyItemizedDeductionInput | null | NY only. Give it to have the tool compute and apply the NY deduction: the NY itemized deduction under NY’s own rules and its high-income limitations, or the NY standard deduction if larger. Pass an empty object for the standard deduction alone. Income amounts are then stated BEFORE any deduction. Reported in ny_deduction. Without it no NY deduction is applied, and the income must already be net of one. Also give federal_agi_cents, which one of the limitations reads. |
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
Section titled “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 |
age |
int | null | Optional: the person’s age at the end of tax_year. When given, the response adds retirement_contribution_limit, their 401(k)/403(b) elective deferral limit (402(g)) with the catch-up tier that age falls in, and ira_contribution_limit_for_age, their IRA limit (219(b)(5)) with the age-50 IRA catch-up when it applies. It also adds simple_ira_limit_for_age (408(p)(2)(E) SIMPLE IRA limit with the age-50 or age 60-63 catch-up) and hsa_limit_for_age (223(b) HSA limits with the age-55 catch-up). A governmental 457(b) has its own separate limit of the same amount; a tax-exempt-organization 457(b) gets no age-based catch-up. |
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, the 402(g) / 401(a)(17) / 414(v) / 415(c) retirement limits, including the SECURE 2.0 age 60-63 catch-up (super_catchup_limit), the 219(b)(5) IRA limit and age-50 IRA catch-up (ira_contribution_limit, ira_catchup_limit), the 408(p)(2)(E) SIMPLE IRA limits (simple_deferral_limit; the higher simple_small_employer_deferral_limit for an employer with 25 or fewer employees, or 26-100 that elects it; simple_catchup_limit, simple_small_employer_catchup_limit, simple_super_catchup_limit), the 402(h)(2) SEP-IRA rate (sep_contribution_rate: an employer may contribute the lesser of that share of compensation, counted up to compensation_limit, and total_annual_additions_limit), and the 223(b) HSA limits (hsa_self_only_limit, hsa_family_limit, and the age-55 hsa_catchup_limit). Each dollar scalar is returned in both _cents and _dollars form, plus a source citation string.
calculate_payroll_tax
Section titled “calculate_payroll_tax”Calculate one person’s payroll tax for a year: employee FICA (6.2% Social Security up to the wage base, 1.45% Medicare) on W-2 wages and self-employment tax (SECA) on net self-employment profit.
| Parameter | Type | Default | Description |
|---|---|---|---|
wages_cents |
int | 0 |
This one person’s W-2 wages subject to FICA, in cents (Form W-2 box 5, Medicare wages; 401(k) deferrals included). Never a spouse’s wages. |
net_self_employment_profit_cents |
int | 0 |
This one person’s net self-employment profit in cents (Schedule C/F net profit, before the 92.35% reduction). A loss yields no SE tax. |
tax_year |
int | 2026 |
Tax year. Options: 2024, 2025, or 2026 |
Returns social_security_wage_base, wages, employee_social_security, employee_medicare, employee_fica, net_self_employment_profit, net_earnings_from_self_employment, self_employment_social_security, self_employment_medicare, self_employment_tax, deductible_half_of_self_employment_tax, and total_payroll_tax, each as _cents and _dollars, plus tax_year, additional_medicare_tax_included (always false), and explanation.
analyze_roth_conversion
Section titled “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%). |
tax_paid_from |
string | "converted_funds" |
Where the cash to pay the conversion tax comes from. ‘converted_funds’ (default) withholds it from the conversion, so the Roth is funded net of tax and an owner under 59.5 pays the IRC 72(t) penalty on the withheld dollars. ‘external’ pays it from outside the retirement accounts (e.g. a taxable brokerage), so the full amount reaches the Roth and no penalty applies — use this when the household has taxable savings it would actually pay from. |
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 (the inputs echoed back, including tax_paid_from and notes), incremental_tax_cost and early_withdrawal_penalty (each as _cents and _dollars), marginal_cost_rate, baseline_marginal_ordinary_rate, post_conversion_marginal_ordinary_rate, rmd_reduction (per year), total_rmd_reduction, break_even, and summary; with state_code, also the state and combined cost and rate fields.
estimate_underpayment_safe_harbor
Section titled “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.