Tax¶
Federal income tax, capital gains, and after-tax projections.
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, or head_of_household |
tax_year |
int | 2025 |
Tax year (2024 or 2025) |
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, or head_of_household |
tax_year |
int | 2025 |
Tax year (2024 or 2025) |
Returns the LTCG rate (0%, 15%, or 20%) that applies to the given income level.
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.