API reference

Compute a federal return

Computes a federal Form 1040 from a structured profile, or returns a deterministic decline.

POSThttps://tax-mcp.com/api/mcp/tax-compute/federal

Compute a federal 1040 return.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <API key>
Content-TypeYesapplication/json
Idempotency-KeyNo (recommended)
Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`)…

Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`) and bills exactly ONCE. The SAME key with a DIFFERENT body → 409 `idempotency_key_reused`. A concurrent in-flight duplicate → 409 `idempotency_key_in_progress` (retry). Keys are scoped per account and replay for 24h. Errors (4xx/5xx) are NOT cached — a retry after an error is a fresh request.

Request body

122 fields. year, filingStatus, canBeClaimedAsDependent and noForeignOrTerritoryExclusionAffirmed are required (and spouseItemizesDeductions on married filing separately), plus at least one income field. Long descriptions are collapsed; each states exactly when the field is required and what an affirmation attests.

FieldDescription
yearintegerrequiredTax year (2020–2026); an unsupported year declines (year_not_modeled).
filingStatus"single" | "married_filing_jointly" | "married_filing_separately" | "head_of_household"requiredFiling status.
wagesnumber1040 line 1a — total W-2 box-1 wages
medicareWagesnumber
W-2 box-5 — the Additional Medicare Tax base.

W-2 box-5 — the Additional Medicare Tax base. Box 1 does NOT determine box 5 in either direction (401(k)/403(b)/457(b) elective deferrals reduce box 1 but remain subject to FICA/Medicare tax, commonly making box 5 > box 1 — §125 cafeteria-plan and HSA payroll contributions do NOT cause this, since they're generally excluded from box 1 and box 5 together; H-2A workers, FICA-exempt nonresident-alien/student wages, and similar statutory exemptions can make box 5 = 0 while box 1 is positive). Supply the exact box-5 figure; omitting it while other W-2 evidence is present declines the Additional Medicare Tax determination.

federalWithholdingnumberW-2 box-2 federal income tax withheld — used for owed/refund
priorYearTaxnumber
Prior-year TOTAL TAX (Form 2210 line 8) — OPT-IN to the §6654 underpayment SAFE-HARBOR determination.

Prior-year TOTAL TAX (Form 2210 line 8) — OPT-IN to the §6654 underpayment SAFE-HARBOR determination. When supplied, the response carries an underpaymentPenalty field that names the §6654(e)/(d) exemption zeroing the penalty (de-minimis / withholding ≥ required / prior-year-$0) OR status:needs_preparer (a penalty may be owed) — in which case an advisory penaltyCeiling gives a conservative UPPER BOUND on the §6654 penalty (max-rate, full accrual to April 15, no estimated payments), guaranteed ≥ the true penalty and NOT a Form 1040 line-38 filed value; emitted only for a year with fully-published IRS rates. Separate line — does not change tax/AGI/refund. Federal-only.

priorYearAGInumberPrior-year AGI — selects the §6654(d)(1)(C)(i) safe-harbor percent (110% if > $150,000, or $75,000 MFS; else 100%). Absent → the engine assumes the high-income 110% (the larger-required, under-tax-safe direction).
priorYearWasFull12MonthReturnboolean
§6654(d)(1)(C)(i): the prior-year safe harbor is available ONLY if the prior year was a filed 12-month return. Absent/false → the prior-year harbor does not apply and the required annual payment = 90%…

§6654(d)(1)(C)(i): the prior-year safe harbor is available ONLY if the prior year was a filed 12-month return. Absent/false → the prior-year harbor does not apply and the required annual payment = 90% of current-year tax (the larger, under-tax-safe figure).

priorYearCitizenOrResidentAllYearboolean
§6654(e)(2)(C): the prior-year-$0 penalty exception requires the taxpayer was a US CITIZEN or RESIDENT throughout the preceding year. A nonresident alien whose prior-year US tax was $0 because they…

§6654(e)(2)(C): the prior-year-$0 penalty exception requires the taxpayer was a US CITIZEN or RESIDENT throughout the preceding year. A nonresident alien whose prior-year US tax was $0 because they were an NRA does NOT qualify; engine-invisible, so the (e)(2) exception is granted only when this is true (absent/false → not (e)(2)).

estimatedTaxNextYearobjectOpt-in, 2026 returns: next year's 1040-ES prior-year safe harbor (§6654(d)(1)(B)(ii), (C)).
medicareTaxWithheldnumberW-2 box 6 Medicare tax withheld, summed across W-2s. Used with medicareWages for the Additional Medicare withholding credit.
taxableInterestnumberForm 1040 line 2b: taxable interest (as figured on Schedule B line 4).
ordinaryDividendsnumberForm 1040 line 3b: total ordinary dividends (as figured on Schedule B line 6), including the qualified subset.
qualifiedDividendsnumberForm 1040 line 3a: qualified dividends (≤ ordinaryDividends) — taxed at preferential LTCG/QDIV rates
reit199ADividendsnumberQualified REIT dividends as Form 8995 defines them — §199A REIT dividends (≤ ordinaryDividends). 20% QBI deduction (REIT box-5 ONLY; PTP/business QBI out of scope, declines).
netShortTermCapGainnumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Pre-netted scalar net short-term capital gain/loss (Schedule D). CONTRACT: this is the CURRENT-YEAR net, BEFORE any prior-year capital-loss carryover — NOT Schedule D line 15/16. "Pre-netted" means across LOTS (the alternative to capGainAggregates), never against a carryover; a carryover goes in priorYearCapLossCarryoverST/LT and is applied on top. Netting it in here as well applies it twice (an executed $12,120 under-tax). Lot-level/8949 detail and covered-basis decline on the scalar path (a broker-reported wash-sale disallowance computes via the capGainAggregates washSaleDisallowed path — see that field; it cannot be expressed as a pre-netted scalar); an affirmed §1256 aggregate is modeled via section1256NetGain (positive net, or no-election loss with the additional loss attestation; 40/60 split — see that field).

netLongTermCapGainnumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Pre-netted scalar net long-term capital gain/loss (Schedule D). CONTRACT: this is the CURRENT-YEAR net, BEFORE any prior-year capital-loss carryover — NOT Schedule D line 15/16. "Pre-netted" means across LOTS (the alternative to capGainAggregates), never against a carryover; a carryover goes in priorYearCapLossCarryoverST/LT and is applied on top. Netting it in here as well applies it twice (an executed $12,120 under-tax). The §1250-unrecaptured (25%) and 28%-collectibles special-rate PORTIONS of this gain are asserted separately via sec1250UnrecapturedGain / collectibles28Gain (any SUPPORTED_TAX_YEARS year with a derivable 24%-bracket ceiling — currently all of 2020-2026; see those fields).

section1256NetGainnumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. §1256 contracts (regulated futures / broad-based index options) — Form 6781 Part I. TAX YEAR 2025 ONLY (certification-evidence boundary, not an arithmetic one — other SUPPORTED_TAX_YEARS years decline). An IRS-reported aggregate (Form 6781 LINE 7 / the split-eligible amount, NOT necessarily line 1 / 1099-B box 11 verbatim — see section1256AggregateIsFinalNoAdjustmentOrDeferralAffirmed) split STATUTORILY 40% short-term / 60% long-term through Schedule D + the §1411 NIIT base. A POSITIVE net requires section1256CleanBrokerReportedAffirmed:true, section1256AggregateIsFinalNoAdjustmentOrDeferralAffirmed:true, section1256TaxpayerIsNotOptionsOrCommoditiesDealerAffirmed:true, AND section1256NotLimitedPartnerDealerEquityOptionAffirmed:true (a §1256(f)(4) dealer-equity-option gain/loss allocable to a limited partner must be 100% short-term, not 40/60 split). C-slice-2b: a net LOSS also computes — the Form 6781 NO-ELECTION default (box D unchecked; the full loss splits 40/60 into the §1211(b) −$3,000 cap + carryover; NIIT is reduced ONLY by the capped amount) — and additionally requires section1256LossCurrentlyDeductibleAffirmed:true. A net of exactly ZERO declines (nothing to compute). Cannot compute alongside a special-rate capital gain (sec1250UnrecapturedGain / collectibles28Gain) — that interaction is not independently certified (decline). Any affirmation supplied without section1256NetGain declines. Separate from a capGainAggregates §1256-flagged box (which declines). Federal-only.

section1256CleanBrokerReportedAffirmedtrue
§6694 affirmation REQUIRED with section1256NetGain (gain OR loss — for a loss its box-11-provenance vector fences the loss MAGNITUDE and its no-straddle vector duplicates the §1092 fence).

§6694 affirmation REQUIRED with section1256NetGain (gain OR loss — for a loss its box-11-provenance vector fences the loss MAGNITUDE and its no-straddle vector duplicates the §1092 fence). Attests the amount is the IRS-REPORTED Form 6781 line-1 / 1099-B box-11 aggregate on §1256 contracts, AND: NO §475(f) mark-to-market election (→100% ordinary on Form 4797), NO straddle (Form 6781 Parts II/III), NOT a §988 foreign-currency contract, and the amount is CAPITAL not ordinary. Absent/false → decline (section_1256_needs_review).

section1256LossCurrentlyDeductibleAffirmedtrue
C-slice-2b §6694 LOSS-side attestation — REQUIRED (in addition to section1256CleanBrokerReportedAffirmed) for a NEGATIVE section1256NetGain.

C-slice-2b §6694 LOSS-side attestation — REQUIRED (in addition to section1256CleanBrokerReportedAffirmed) for a NEGATIVE section1256NetGain. Attests the FULL box-11 §1256 loss is CURRENTLY DEDUCTIBLE: no §1092 straddle-loss deferral applies (Form 6781 Part II runs BEFORE the Part I entry — unrecognized gain in an offsetting non-§1256 position defers the loss and broker box 11 cannot see it; deducting a deferred loss now would UNDER-tax), and no §1212(c) 3-year carryback election is being made (Form 6781 box D unchecked — the no-election default). Absent/false → the loss declines.

section1256AggregateIsFinalNoAdjustmentOrDeferralAffirmedtrue
§6694 affirmation REQUIRED with section1256NetGain (gain OR loss).

§6694 affirmation REQUIRED with section1256NetGain (gain OR loss). Two-clause invariant: (a) the supplied aggregate IS the final Form 6781 LINE-7 amount — no line-4 (1099-B) adjustment and no line-6 carryback applied upstream of it — AND (b) no QOF (§1400Z-2) deferral of the resulting line-8/9 amounts, and no hedging-transaction or ordinary-character treatment. Line 4 and QOF act at DIFFERENT Form 6781 stages (line 4 pre-split, QOF deferral post-split on lines 8/9) — this single affirmation fences both, plus the catch-all case where the raw box-11 aggregate is not the final split amount. Absent/false → decline (section_1256_needs_review).

section1256TaxpayerIsNotOptionsOrCommoditiesDealerAffirmedtrue
§6694 affirmation REQUIRED with section1256NetGain (gain OR loss).

§6694 affirmation REQUIRED with section1256NetGain (gain OR loss). §1402(i) carves capital-gain exclusion back out of net earnings from self-employment for a registered options dealer (§1256(g)(8)) or commodities dealer (a person actively trading §1256 contracts, registered with a domestic board of trade designated as a contract market by the CFTC — §1402(i)(2), not "registered with the CFTC" directly) — their §1256 gain/loss stays CAPITAL (the 40/60 split is unaffected) but ALSO owes §1401 self-employment tax, which this engine does not compute. Attests the taxpayer is NOT such a dealer for this §1256 activity. Absent/false → decline (section_1256_needs_review); this engine does not compute Schedule SE for §1256 dealer activity.

section1256NotLimitedPartnerDealerEquityOptionAffirmedtrue
§6694 affirmation REQUIRED with section1256NetGain (gain OR loss).

§6694 affirmation REQUIRED with section1256NetGain (gain OR loss). §1256(f)(4): gain or loss on dealer equity options or dealer securities futures contracts allocable to a LIMITED PARTNER or limited entrepreneur is NOT subject to the standard 40/60 split (§1256(a)(3) doesn't apply) — it must be treated as 100% SHORT-TERM capital instead. Delivery vector: Schedule K-1 (Form 1065) box 11 code C, reported on Form 6781 Part I line 1 exactly like a broker 1099-B amount. A DIFFERENT rule than section1256TaxpayerIsNotOptionsOrCommoditiesDealerAffirmed above — a limited partner is not himself a dealer; (f)(4) attaches to the contracts' allocation, not the taxpayer's own registration. Attests NO part of this aggregate is such an allocation. Absent/false → decline (section_1256_needs_review); this engine does not compute the §1256(f)(4)(B) 100%-short-term override.

capGainAggregatesarray of object
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Schedule D / Form 8949 lot/evidence entries (v0 contract). The engine nets covered-clean NON-DIGITAL boxes into ST/LT itself (form8949Box A/D = short/long COVERED, basis reported to IRS). v0 COMPUTES a box/lot ONLY if: form8949Box ∈ {A,D}, a positive reportedBasis, NO correctedBasis / adjustmentCode / lotId / replacementForLotId (washSaleDisallowed COMPUTES narrowly with BOTH wash affirmations — washSaleDisallowedIsCompleteAffirmed + washSaleLotsNotSpecialRateAffirmed — and WITHOUT cleanCoveredNoAdjustmentsAffirmed; see the field descriptions), an active non-conflicting sourceDocumentRef (if any), any acquiredDate/soldDate consistent with the box term, and — REQUIRED — cleanCoveredNoAdjustmentsAffirmed:true (a WASH box carries the two wash affirmations INSTEAD — never both). ANY other input (noncovered B/E, no-1099 C/F, digital G–L, an adjustment code, a corrected basis, a box↔lot mix in one broker/account/owner scope, a date-vs-term mismatch, a superseded source) → whole-return decline, no tax-number leakage. Mutually exclusive with netShortTermCapGain/netLongTermCapGain. Supply EITHER boxType (legacy A/B/D/E) OR form8949Box (A–L).

digitalAssetAllAcquiredByPurchasetrue
§6694 affirmation (#1 of 3) to COMPUTE a covered digital-asset (crypto) disposition.

§6694 affirmation (#1 of 3) to COMPUTE a covered digital-asset (crypto) disposition. Attests every unit in every capGainAggregates digitalAsset box was acquired by PURCHASE — none via staking, mining, airdrop/hard fork, or as payment (those carry separate ordinary income at FMV, Rev. Rul. 2023-14, invisible to a disposition compute). Only a TY2026+ COVERED (box A/D) crypto box with ALL THREE affirmations computes; pre-2026, noncovered B/E, wash-flagged, or missing-affirmation crypto → digital_asset_needs_review decline. Federal-only (state schemas reject it).

digitalAssetNoneAreCollectibletrue
§6694 affirmation (#2 of 3) to COMPUTE a covered digital-asset disposition.

§6694 affirmation (#2 of 3) to COMPUTE a covered digital-asset disposition. Attests NO disposed unit is a §408(m) COLLECTIBLE — none is an NFT treated as a collectible under the Notice 2023-27 look-through, which would tax the long-term gain at 28% instead of the §1(h) 0/15/20 bands. Absent → the crypto box declines (the engine nets at 0/15/20 and cannot see collectible character). Federal-only.

digitalAssetIsCapitalNotOrdinarytrue
§6694 affirmation (#3 of 3) to COMPUTE a covered digital-asset disposition.

§6694 affirmation (#3 of 3) to COMPUTE a covered digital-asset disposition. Attests the gain is CAPITAL, not ordinary: every unit is a §1221 capital asset (NOT dealer/inventory/customer property held for sale — crypto held that way is ordinary per Notice 2014-21), there is no Form 1099-DA Box-6 ordinary gain/loss, and no non-USD/§988 foreign-currency ordinary treatment. Absent → decline (the engine nets at preferential capital rates and cannot see dealer/inventory/§988 ordinary character). Crypto affirmations require a tagged capGainAggregates digitalAsset box (they decline on scalar netLongTermCapGain). Federal-only.

priorYearCapLossCarryoverSTnumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year SHORT-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Applied with the §1211(b) −$3,000 (−$1,500 MFS) annual limit; ending carryover returned as endingCapLossCarryoverST. This field is the PRIOR-YEAR carryover only — do NOT also net it into netShortTermCapGain/netLongTermCapGain, which are CURRENT-YEAR nets before any carryover; doing both applies it twice (an executed $12,120 under-tax). Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. If only an AMT-side carryover exists, send 0 (the return declines).

priorYearCapLossCarryoverLTnumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Prior-year LONG-term capital-loss carryover — POSITIVE magnitude (caller-asserted). Nets against long-term gain; ending carryover returned as endingCapLossCarryoverLT. Any Schedule D input on the return REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true - the trigger is PRESENCE, not a positive value: a carryover of exactly $0 arms it. If only an AMT-side carryover exists, send 0 (the return declines).

capLossCarryoverNoAmtDifferenceAffirmedtrue
§6694 affirmation REQUIRED whenever the return carries ANY Schedule D input at all — the PRESENCE of any of netShortTermCapGain, netLongTermCapGain, capGainAggregates, collectibles28Gain,…

§6694 affirmation REQUIRED whenever the return carries ANY Schedule D input at all — the PRESENCE of any of netShortTermCapGain, netLongTermCapGain, capGainAggregates, collectibles28Gain, sec1250UnrecapturedGain, priorYearCapLossCarryoverST, priorYearCapLossCarryoverLT or section1256NetGain, of any sign or magnitude, INCLUDING exactly $0. DO NOT read this as a positive-carryover test: round 4 keyed the trigger on a positive supplied carryover, and round 12 proved that defeatable — a caller who nets the carryover into netLongTermCapGain BEFORE it reaches this engine and supplies no carryover field leaves the trigger silent while regular tax stays CORRECT, so nothing looks wrong; an executed $10,600 AMT under-tax. The trigger is Schedule-D presence because a pre-netted carryover is invisible to any predicate on the carryover field. Form 6251's own "Lines 13, 14, and 15" instruction names a different AMT-side capital-loss carryover as an independent trigger for the AMT-side Schedule D Tax Worksheet this engine does not model. ATTEST EITHER: (a) this return has NO prior-year capital-loss carryover at all, for regular tax or AMT — the common case, and attesting true is how you say so; or (b) a carryover exists and its ENTERING AMT-SIDE amount equals the regular-tax amount. Covers a carryover HOWEVER it reached this engine: supplied as priorYearCapLossCarryoverST/LT, or already netted by the caller into netShortTermCapGain/netLongTermCapGain/capGainAggregates. It ALSO attests the carryover was NOT supplied BOTH ways — netted into a scalar AND supplied as priorYearCapLossCarryover* — which applies it twice (an executed $12,120 under-tax this engine cannot detect, because that shape is identical in its inputs to correct usage). Supplied on a return with NO Schedule D input at all → orphan-affirmation decline. Absent/false on a return with any Schedule D input → decline. An AMT-only carryover (none left on the regular side) is NOT covered: send priorYearCapLossCarryoverST/LT as 0, and the return declines.

mortgageInterestnumber
Schedule A — home mortgage interest (1098 box 1).

Schedule A — home mortgage interest (1098 box 1). Requires mortgageAvgBalance and, if positive, mortgageInterestExcludesExcessRefinancingProceeds AND EITHER mortgageInterestSecuresAmtQualifiedDwelling OR mortgageInterestSecuresSec121PrincipalResidence.

mortgageAvgBalancenumberAverage home-acquisition-debt balance — basis for the §163(h)(3) $750k limit; the engine prorates interest above it. Required with mortgageInterest.
mortgageInterestExcludesExcessRefinancingProceedsboolean
§6694 affirmation: attests mortgageInterest/mortgageAvgBalance are attributable solely to acquisition indebtedness, excluding any interest on principal from a refinancing that exceeds the refinanced…

§6694 affirmation: attests mortgageInterest/mortgageAvgBalance are attributable solely to acquisition indebtedness, excluding any interest on principal from a refinancing that exceeds the refinanced debt's balance immediately before that refinancing (§56(e)(1)'s flush sentence; §163(h)(3)(B)(i) imposes the identical cap for REGULAR TAX -- not an AMT-only concern). A never-refinanced or rate-and-term-only refinanced loan satisfies this trivially. REQUIRED for a positive mortgageInterest; absent, a cash-out refinance's excess proceeds cannot be ruled out, which would under-state tax on BOTH regular tax and AMT. Absent declines (fail-closed).

mortgageInterestSecuresAmtQualifiedDwellingboolean
§6694 affirmation, prong (B) of §56(e)(1)'s two disjunctive prongs:

§6694 affirmation, prong (B) of §56(e)(1)'s two disjunctive prongs: attests the mortgage secures an AMT-qualified dwelling under §56(e)(2) (house/apartment/condo/mobile-home, not transient-use) that is also a §163(h)(5) qualified residence. A houseboat/RV/transient-use property does not qualify under THIS prong specifically (see mortgageInterestSecuresSec121PrincipalResidence for the separate prong it may still qualify under). §56(e)(3) (pre-July-1982 indebtedness) is a THIRD, unmodeled qualifying category -- over-decline direction only, disclosed not fixed. REQUIRED for a positive mortgageInterest unless the other prong is affirmed instead; absent BOTH declines (fail-closed).

mortgageInterestSecuresSec121PrincipalResidenceboolean
§6694 affirmation, prong (A) of §56(e)(1)'s two disjunctive prongs:

§6694 affirmation, prong (A) of §56(e)(1)'s two disjunctive prongs: attests the mortgaged property is the taxpayer's actual §121 principal residence at the time the interest accrued — no dwelling-type restriction (a genuine principal-residence houseboat qualifies, per IRS Pub 523). Either this OR mortgageInterestSecuresAmtQualifiedDwelling being true is sufficient (an ordinary home is typically true under both). If neither applies, mortgage interest is a positive AMT preference (Form 6251 Line 3) this engine does not model; absent both declines (fail-closed). See mortgageInterestExcludesExcessRefinancingProceeds for a SEPARATE gate on the debt amount (not the property).

foreignTaxPaidnumber
Foreign tax WITHHELD (1099-DIV box 7) -- NOT necessarily the creditable amount, see foreignTaxIsFullyCreditableAffirmed.

Foreign tax WITHHELD (1099-DIV box 7) -- NOT necessarily the creditable amount, see foreignTaxIsFullyCreditableAffirmed. §904(j) de-minimis (≤$300/$600 MFJ) computes the full credit; ABOVE the ceiling the return declines and a preparer completes Form 1116. Requires foreignIncomeAllPassive1099, foreignTaxIsFullyCreditableAffirmed AND foreignTaxNoForm1116Line12ReductionAffirmed.

foreignIncomeAllPassive1099true
Required with foreignTaxPaid (the de-minimis election):

Required with foreignTaxPaid (the de-minimis election): affirm ALL foreign income is passive + shown on a QUALIFIED PAYEE STATEMENT (§904(j)(3)(A)(ii)/(C) via §6724(d)(2) — broader than the 1099 family; the Form 1116 instructions list Schedule K-1 (Form 1041) and Schedule K-3 (Forms 1065/1120-S) among them, so a partnership K-1 WITHOUT an accompanying K-3 does not by itself carry the foreign-tax items).

foreignTaxIsFullyCreditableAffirmedtrue
Required with foreignTaxPaid (the de-minimis election, per the 2025 Instructions' own creditability rules applying regardless of the §904(j) election):

Required with foreignTaxPaid (the de-minimis election, per the 2025 Instructions' own creditability rules applying regardless of the §904(j) election): attests the amount is NET of every 'Foreign Taxes Not Eligible for a Credit' item -- legally owed under any applicable treaty with remedies exhausted, the §901(k)/(l) 16-day holding-period requirement met, no related payments on substantially similar/related positions, not paid to a §901(j) sanctioned country, and not itself subsidized. The withheld amount (1099-DIV box 7) is not necessarily 100% creditable. Absent → decline (foreign_tax_credit_needs_review).

foreignSourceGrossIncomenumberSafe-harbor input. Foreign tax above the §904(j) de-minimis ceiling now always declines, so this field is not needed; omit it on a de-minimis return.
foreignQualifiedDividendsAndCapGainsnumberSafe-harbor input. Foreign tax above the §904(j) de-minimis ceiling now always declines, so this field is not needed; omit it on a de-minimis return.
foreignTaxNoCarryoverAffirmedtrueSafe-harbor input. Foreign tax above the §904(j) de-minimis ceiling now always declines (founder decision, 2026-10-06), so this field is not needed; omit it on a de-minimis return.
foreignSourceNoForm1116PartILines2Through5EntryAffirmedtrueSafe-harbor input. Foreign tax above the §904(j) de-minimis ceiling now always declines (founder decision, 2026-10-06), so this field is not needed; omit it on a de-minimis return.
foreignSourceNoForm1116Line16AdjustmentAffirmedtrueSafe-harbor input. Foreign tax above the §904(j) de-minimis ceiling now always declines (founder decision, 2026-10-06), so this field is not needed; omit it on a de-minimis return.
foreignTaxNoForm1116Line12ReductionAffirmedtrue
Required (true) with foreignTaxPaid on the §904(j) de-minimis election:

Required (true) with foreignTaxPaid on the §904(j) de-minimis election: attests that Form 1116 Part III LINE 12 ('Reduction in foreign taxes') is $0 for this return. Line 12 carries reductions for failure to file Forms 5471/8865, taxes on boycott-related operations (§908), foreign-tax-credit splitting events (§909), and the other items the Form 1116 instructions enumerate there. This engine models line 12 as ZERO, so any of them silently OVER-CREDITS. The de-minimis path is where the primary source binds most directly: the instructions' own 'Election To Claim the Foreign Tax Credit Without Filing Form 1116' section says you are still required to reduce the taxes available for credit by any amount you would have entered on line 12 — skipping Form 1116 does not skip line 12. A reduction that DOES apply declines rather than being subtracted: §909 splitting events suspend taxes until the related income is taken into account and §908 interacts with the separate categories, neither modelled. Absent/false → decline (foreign_tax_credit_needs_review). certify-leaf round-11, 2026-09-07: executed $250 under-tax on the limitation path, $29 on the de-minimis path.

stateLocalIncomeTaxnumberSchedule A — state/local income tax (W-2 box 17). Part of the OBBBA-2025 SALT cap.
realEstateTaxnumberSchedule A — real-estate (property) tax. Part of the SALT cap.
medicalExpensesnumber
Schedule A line 1: medical and dental expenses (§213). The deduction is the amount above 7.5% of AGI (whole dollars). Counts as an itemized input (married filing separately declines). Requires…

Schedule A line 1: medical and dental expenses (§213). The deduction is the amount above 7.5% of AGI (whole dollars). Counts as an itemized input (married filing separately declines). Requires medicalExpensesQualifyingUnreimbursedAffirmed and medicalExpensesNotCompensatedOtherwiseAffirmed. Federal only.

medicalExpensesQualifyingUnreimbursedAffirmedtrue
§6694 affirmation REQUIRED with medicalExpenses:

§6694 affirmation REQUIRED with medicalExpenses: the amount is §213 medical and dental care paid this year for the filer, spouse and dependents; none of it was reimbursed or paid by insurance, an employer, an HSA, FSA, HRA, MSA or QSEHRA, or pre-tax payroll; premiums count less any advance premium tax credit payments not repaid and any net premium tax credit (Pub. 502); it excludes long-term-care premiums above the §213(d)(10) age limit, and health insurance deducted on Schedule 1; and no reimbursement was received this year for medical expenses deducted in an earlier year. Absent or false declines (itemized_deduction_needs_review); supplied without medicalExpenses declines.

medicalExpensesNotCompensatedOtherwiseAffirmedtrue
§6694 affirmation REQUIRED with medicalExpenses (§213(a):

§6694 affirmation REQUIRED with medicalExpenses (§213(a): not compensated for by insurance or otherwise): no part of medicalExpenses was compensated for by insurance or otherwise: not by a damages award or settlement, a qualified wildfire relief payment excluded under §139M, a disaster-relief or other government program, a payment from another person, or any other source.

charitableCashContributionsnumber
Schedule A line 11: cash gifts to §170(b)(1)(A) organizations, deducted up to 60% of AGI (§170(b)(1)(G)); from 2026 this engine limits it to 30% of AGI unless…

Schedule A line 11: cash gifts to §170(b)(1)(A) organizations, deducted up to 60% of AGI (§170(b)(1)(G)); from 2026 this engine limits it to 30% of AGI unless charitableNoOtherContributionsOrCarryoverAffirmed or charitableContributionsCompleteAffirmed is true (then 60%; with non-cash gifts, only while the year's gifts total at most 60% of AGI); the deduction is then reduced by 0.5% of AGI either way (§170(b)(1)(I)). Any excess over the limit is not carried forward by this engine (over-tax). The 2026 deduction for non-itemizers (§170(p)) is not modeled (over-tax). Counts as an itemized input. Requires charitableCashToPublicCharitiesSubstantiatedAffirmed. Federal only.

charitableCashToPublicCharitiesSubstantiatedAffirmedtrue
§6694 affirmation REQUIRED with charitableCashContributions:

§6694 affirmation REQUIRED with charitableCashContributions: the amount is cash, check or card gifts actually paid this year (not pledges) to U.S. §170(b)(1)(A) organizations (no private non-operating foundation, no gift 'for the use of' an organization, no non-cash property); it is net of any goods or services received or expected, and of the maximum state or local tax credits allowable for each gift (received or expected, even if not usable this year) unless that gift's credits total at most 15% of it; no gift's state or local tax deduction exceeds the amount paid for it; it excludes IRA qualified charitable distributions and gifts deducted on Schedule C; each gift has a bank record or receipt, and each gift of $250 or more a contemporaneous written acknowledgment; and it includes no charitable carryover from an earlier year; and any gift to a donor-advised fund has the sponsor's contemporaneous written acknowledgment that it has exclusive legal control over the gift, from a sponsor that is neither described in §170(c)(3), (4) or (5) nor a Type III supporting organization other than a functionally integrated one (§170(f)(18)); and no payment buys a right to purchase athletic-event seating (§170(l)); and none of it is a contribution Pub. 526 lists as not deductible (for example a gift earmarked for a particular person, family or foreign organization, a raffle, bingo or lottery ticket, or a payment for a specific patient or in place of tuition); and, from 2026, no non-cash gift of the year to a §170(b)(1)(A) organization and no gift carried over into the year was deductible at less than its value (for example a vehicle limited to its sale proceeds, property limited to its basis, or a gift reduced for anything received), before the percentage limits, the 0.5% floor and §68. Absent or false declines (itemized_deduction_needs_review); supplied without charitableCashContributions declines.

charitableNoOtherContributionsOrCarryoverAffirmedboolean
Optional with charitableCashContributions;

Optional with charitableCashContributions; from 2026 it lifts the 30%-of-AGI cash cap to 60%. The 2026 cash limit (§170(b)(1)(G)(i) as amended) is cut by other contributions taken into account under §170(b)(1)(A); without an attestation that lifts it (see charitableCashContributions) the engine caps cash at 30% of AGI. Attests: charitableCashContributions is the taxpayer's only charitable contribution for the year: no non-cash gift, no gift to any other kind of organization or for the use of one, and no charitable contribution carryover into the year.

charitableNonCashNotAppreciatednumber
Schedule A line 12 (Pub 526 Worksheet 2 line 9):

Schedule A line 12 (Pub 526 Worksheet 2 line 9): non-cash gifts of personal-use property at fair market value no higher than basis, 50%-of-AGI limit coordinated with cash. Requires charitableNonCashNotAppreciatedAffirmed; from 2026 also charitableContributionsCompleteAffirmed. Counts as an itemized input. Federal only.

charitableNonCashNotAppreciatedAffirmedtrue
§6694 affirmation REQUIRED with charitableNonCashNotAppreciated:

§6694 affirmation REQUIRED with charitableNonCashNotAppreciated: charitableNonCashNotAppreciated is property given outright this year to U.S. §170(b)(1)(A) organizations (not for the use of one, not to a private non-operating foundation, and kept under the donee's control: not earmarked, designated or given under a commitment or understanding for a particular person or family, or to pass to any organization other than a U.S. §170(b)(1)(A) organization), each item at fair market value no higher than its adjusted basis on the gift date; every item used only personally (never used in a trade, business or rental, and never held for investment, the production of income or sale) and never depreciated; clothing and household items in good used condition or better; no vehicle, boat, airplane, taxidermy, property subject to a debt, partial, fractional or future interest, or conservation easement; no item or group of similar items (across all donees) over $5,000; each gift substantiated as §170(f)(8) and Treas. Reg. §1.170A-16 require (including a receipt from the donee, or reliable written records where a receipt is impracticable, for a gift under $250, a contemporaneous written acknowledgment for a gift of $250 or more, and Form 8283 Section A for any item or group over $500); and net of any goods or services received or expected, and of the maximum state or local tax credits allowable for each gift (received or expected, even if not usable this year) unless that gift's credits total at most 15% of its value; no gift's state or local tax deduction exceeds its value; and any gift to a donor-advised fund has the sponsor's contemporaneous written acknowledgment that it has exclusive legal control over the gift, from a sponsor that is neither described in §170(c)(3), (4) or (5) nor a Type III supporting organization other than a functionally integrated one (§170(f)(18)).

charitableNonCashPublicSecuritiesLongTermnumber
Schedule A line 12 (Pub 526 Worksheet 2 line 8):

Schedule A line 12 (Pub 526 Worksheet 2 line 8): long-term appreciated listed corporate stock at fair market value, 30%-of-AGI limit coordinated with cash and line 9. Requires charitableNonCashPublicSecuritiesAffirmed; from 2026 also charitableContributionsCompleteAffirmed. Counts as an itemized input. Federal only.

charitableNonCashPublicSecuritiesAffirmedtrue
§6694 affirmation REQUIRED with charitableNonCashPublicSecuritiesLongTerm:

§6694 affirmation REQUIRED with charitableNonCashPublicSecuritiesLongTerm: charitableNonCashPublicSecuritiesLongTerm is the fair market value on the gift date, which is that day's market quotation (the mean of its high and low sale prices) with nothing, such as the size of the block, making the fair market value differ from it (Treas. Reg. §1.170A-13(c)(7)(xi)(C)(2), (D)), of shares of stock in a corporation listed on an exchange (publicly traded securities, Treas. Reg. §1.170A-13(c)(7)(xi), including ETF and closed-end fund shares of a regulated investment company, and no grantor-trust or partnership share such as a metal, commodity or crypto trust), the entire interest given outright this year to U.S. §170(b)(1)(A) organizations (not for the use of one, not to a private non-operating foundation, and kept under the donee's control: not earmarked, designated or given under a commitment or understanding for a particular person or family, or to pass to any organization other than a U.S. §170(b)(1)(A) organization), each held more than one year with no suspended holding period (straddle, collar, short sale against the box) and shares received for services (including restricted stock and RSUs, PSUs or other units settled in shares) held more than one year from when they were both delivered and substantially vested (Treas. Reg. §1.83-4(a)); nothing was received or expected in return (no gift annuity, charitable remainder or lead trust, pooled income fund, goods or services), and no gift brings state or local tax credits above 15% of its value or a state or local tax deduction above its value; no share would produce ordinary income if sold (no §475(f) trader or dealer holding, ISO stock before its holding periods, ESPP stock, PFIC, PTP unit, §306 or §1248 stock, digital asset), none is S corporation stock or encumbered, and every share is freely tradable with no restriction that materially affects its value; Form 8283 Section A filed when the securities exceed $500; a contemporaneous written acknowledgment for each gift; no disposition of the shares for cash or other property (including a sale, redemption, liquidation, merger or tender offer) agreed, approved, announced or practically certain before the gift (a sale the donee decides on later, with none of these pending at the gift, is not one); and no election to deduct basis instead (§170(b)(1)(C)(iii)); and any gift to a donor-advised fund has the sponsor's contemporaneous written acknowledgment that it has exclusive legal control over the gift, from a sponsor that is neither described in §170(c)(3), (4) or (5) nor a Type III supporting organization other than a functionally integrated one (§170(f)(18)).

charitableContributionsCompleteAffirmedboolean
Required from 2026 with any non-cash charitable amount;

Required from 2026 with any non-cash charitable amount; it can lift the 2026 30%-of-AGI cash cap (see charitableCashContributions). From 2026, when the year's gifts, with non-cash gifts among them, total more than 60% of AGI, non-cash is not deducted and cash keeps the 30% cap (over-tax). Attests: every charitable contribution of the year, deductible or not and including any passed through a Schedule K-1, is in charitableCashContributions, charitableNonCashNotAppreciated or charitableNonCashPublicSecuritiesLongTerm; there is no gift to any other kind of organization or for the use of one; and there is no charitable contribution carryover into the year.

gamblingWinningsnumber
Schedule 1: gambling winnings for the year, figured wager by wager (see the attestation), added to AGI. Requires gamblingWinningsGrossAndLossesSubstantiatedAffirmed. W-2G box 4 withholding has no…

Schedule 1: gambling winnings for the year, figured wager by wager (see the attestation), added to AGI. Requires gamblingWinningsGrossAndLossesSubstantiatedAffirmed. W-2G box 4 withholding has no input and is not subtracted from owedOrRefund (over-states the amount owed). Federal only.

gamblingLossesnumber
Schedule A: wagering losses, deducted up to gamblingWinnings; from 2026, 90% of losses up to winnings (§165(d)). Requires gamblingWinnings (0 if none) and the attestation. Counts as an itemized input…

Schedule A: wagering losses, deducted up to gamblingWinnings; from 2026, 90% of losses up to winnings (§165(d)). Requires gamblingWinnings (0 if none) and the attestation. Counts as an itemized input (married filing separately declines). Federal only.

gamblingWinningsGrossAndLossesSubstantiatedAffirmedtrue
§6694 affirmation REQUIRED with gamblingWinnings:

§6694 affirmation REQUIRED with gamblingWinnings: gamblingWinnings and gamblingLosses cover every wager of the year, whether or not on a Form W-2G, each figured on its own: a wager is each separately settled bet (each slot-machine play is one; a cash-game buy-in or chip purchase is not one), and its result is its payout before withholding (including any returned stake, and non-cash prizes at fair market value) minus its substantiated cost, never subtracted twice (some W-2G amounts are already net of it); gamblingWinnings is the sum of the positive results and gamblingLosses the sum of the negative results as positive amounts, with no wager offset against another and no W-2G amount counted twice; on a joint return both spouses' wagers are included; losses include no travel, meals or other personal expenses; neither spouse is in the trade or business of gambling; no gambling income or loss reaches this return through a partnership, S corporation, estate or trust; and the return has no foreign-source gambling winnings, sale of a right to future lottery payments, interest part of a lottery installment, or prize won without a wager.

investmentInterestPaidnumber
Form 4952 line 1: investment interest paid. Deducted on Schedule A up to line 6 (taxable interest + ordinary dividends − qualified dividends); the excess is endingInvestmentInterestCarryforward.…

Form 4952 line 1: investment interest paid. Deducted on Schedule A up to line 6 (taxable interest + ordinary dividends − qualified dividends); the excess is endingInvestmentInterestCarryforward. Requires investmentInterestQualifiesAffirmed and taxExemptInterest; declines with a positive taxExemptInterest (§265), with any current-year short-term input, including 0 (netShortTermCapGain, a short-term Form 8949 box, a K-1 box 3), a §1256 net, or a pension distribution not classified pensionDistributionIsNonqualifiedAnnuityNii:false (capital-loss carryovers are admitted). Counts as an itemized input. Federal only.

investmentInterestCarryforwardnumberForm 4952 line 2: the prior year's disallowed investment interest (its line 7, or this API's endingInvestmentInterestCarryforward). Same requirements as investmentInterestPaid.
investmentInterestQualifiesAffirmedtrue
§6694 affirmation REQUIRED with investmentInterestPaid or investmentInterestCarryforward:

§6694 affirmation REQUIRED with investmentInterestPaid or investmentInterestCarryforward: investmentInterestPaid and investmentInterestCarryforward are interest on debt traced to property held for investment (Treas. Reg. §1.163-8T), and investmentInterestCarryforward is the prior year's Form 4952 line 7; none of it is qualified residence, passive-activity or trade-or-business interest, interest passed through a Schedule K-1, interest attributable to an activity in which any amount isn't at risk (interest that goes on Form 6198 line 4, §465), interest on debt to buy or carry tax-exempt obligations or shares of a fund paying exempt-interest dividends (§265(a)(2), (a)(4), including a margin account holding them), market-discount bonds or short-term obligations (§1277, §1282), straddle or §266 carrying charges, short-sale payments, §264 or §72(p)(3) interest, or capitalized or prepaid interest; whatever the debt is traced to (Treas. Reg. §1.163-8T(m)), each exclusion above other than passive-activity and trade-or-business interest applies, and no provision other than §163(d) and §68 disallows, defers or capitalizes any of it; every dollar of taxableInterest and ordinaryDividends is investment income (none from the ordinary course of a trade or business, none passive-activity income including self-charged interest, no Alaska Permanent Fund dividend or payment in lieu of a dividend); and the return has no other Form 4952 investment income (annuities, royalties, a partnership's or PTP's investment income, Form 8814 amounts), no investment expenses, and no election to treat qualified dividends or capital gains as investment income.

qualifiedDisasterCasualtiesarray of object
Form 4684 Section A, TY2025-2026, one entry per casualty and declaration:

Form 4684 Section A, TY2025-2026, one entry per casualty and declaration: personal-use property damaged in a FEMA major disaster (DR) whose incident began on or after 2019-12-28. The qualified net disaster loss (each entry's loss less $500) reduces taxable income whether or not the return itemizes (§63(b)(8)); it is not itemized and not added back for the AMT. Declines: a number not in the engine's FEMA snapshot (emergency and state declarations, newer ones), COVID-19, a state or start-date mismatch, an incident beginning after the tax year or ending before the prior year, a declaration listed twice, any gain, married filing separately, other years, a loss larger than taxable income before it. Requires qualifiedDisasterCasualtyAffirmed. Federal only.

qualifiedDisasterCasualtyAffirmedtrue
§6694 affirmation REQUIRED with qualifiedDisasterCasualties:

§6694 affirmation REQUIRED with qualifiedDisasterCasualties: each casualty is one event from the named FEMA major disaster, the property was personal-use (not business, income-producing or rental, wholly or partly), owned only by the filer or, on a joint return, by one or both spouses, with no one else holding any ownership interest in it when the casualty occurred and when the loss was sustained (including a co-owner, life tenant, remainderman or decedent's estate), and located in the declared area, and the loss arose in the incident period and is attributable to the disaster (not theft or progressive deterioration); the loss is sustained in this tax year: the disaster struck in it, or a reimbursement claim with a reasonable prospect of recovery deferred the loss into it (Treas. Reg. §1.165-1(d)), and no part of it was sustained in an earlier year (a part no such claim covered, such as a deductible or underinsurance, was sustained in the casualty year); each item is measured separately (real property as one item); adjustedBasis is the item's adjusted basis for determining loss (Treas. Reg. §1.165-7(b)(1)(ii), §1.1011-1): its cost or other basis (for a gift, the smaller of the donor's adjusted basis and its value when given, §1015(a), and for what was acquired from a decedent, its §1014 or §1022 basis) after every increase and decrease to basis, including depreciation allowed or allowable, earlier casualty loss deductions and reimbursements, postponed gain, credits that reduce basis and excluded canceled debt; the decrease in value is measured by before-and-after fair market value or a Rev. Proc. 2018-08 safe harbor used only where that procedure's §§3-5 allow it, with no general market decline; reimbursement is the total received or expected for that item — insurance whether or not a claim was filed, grants that must be used for the property (FEMA, state, wildfire payments), forgiven federal loans, the value of repairs at no or token cost (by an employer, relief agency, lessee, volunteers or donors), and court or settlement awards net of fees, with a lump sum allocated across items by fair market value; no claim with a reasonable prospect of recovery is pending (including utility litigation); the return has no personal casualty or theft gain from any event; the loss is not deducted for another year (no §165(i) election) and was not claimed on an estate-tax return.

sec1250UnrecapturedGainnumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Caller-asserted UNRECAPTURED §1250 gain (Schedule D line 19, ALREADY reduced per the IRS Unrecaptured §1250 Gain Worksheet — the caller attests this final line-19 figure, the engine does not re-derive it) — the depreciation-recapture PORTION of long-term capital gain taxed at a MAX 25% rate (§1(h)(1)(E)). NOT required to be ≤ netLongTermCapGain: a current-year non-§1250, non-28%-rate long-term capital loss from an unrelated sale can legitimately reduce netLongTermCapGain (Schedule D line 15) without reducing this figure (Schedule D line 19), since that loss is not one of the three reductions (28%-group absorption, current-year net ST loss, LT loss carryovers) the Unrecaptured §1250 Gain Worksheet applies (a real-estate-plus-stock-loss pattern, not a rare edge case). The Schedule D Tax Worksheet's own line 12 (min(line 9, line 11)) safely caps the amount actually taxed at 25/28% regardless of how large this assertion is relative to netLongTermCapGain. Present → the FULL Schedule D Tax Worksheet computes (the 25% slice stacked above the 0/15/20 bands, floored at ordinary tax on all taxable income). §6694: omitting a real §1250 portion UNDER-taxes it at 0/15/20, so the preparer must assert it. MODELED for any SUPPORTED_TAX_YEARS year whose ordinary brackets have a derivable 24%-rate entry (currently all of 2020-2026, verified; other years → special_rate_gain_unmodeled decline); scalar netLongTermCapGain path (not capGainAggregates).

collectibles28Gainnumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Caller-asserted 28%-RATE gain (Schedule D line 18, ALREADY reduced per the 28% Rate Gain Worksheet) — collectibles (§408(m)) plus the taxable portion of §1202 QSBS gain, taxed at a MAX 28% rate (§1(h)(1)(F)/(4)). NOT required to be ≤ netLongTermCapGain — see sec1250UnrecapturedGain's own description for why (the Schedule D Tax Worksheet's own line-12 cap, not a pre-worksheet bound, is what safely limits the amount actually taxed at 25/28%). Present → the FULL Schedule D Tax Worksheet computes (the 28% slice stacked above the 0/15/20 bands, floored at ordinary tax on all taxable income). §6694: omitting real 28%-rate gain UNDER-taxes it at 0/15/20. MODELED for any SUPPORTED_TAX_YEARS year whose ordinary brackets have a derivable 24%-rate entry (currently all of 2020-2026); scalar netLongTermCapGain path. collectibles28NoSec1202ExclusionPreferenceAffirmed:true is REQUIRED whenever the return carries ANY Schedule D input at all — including this field supplied as exactly $0, and regardless of sign or magnitude (the §1202 preference is 7% of the EXCLUDED gain, which survives netting that drives every reported operand to $0) — see that field's own description.

specialRateGainNoAmtScheduleDDifferenceAffirmedboolean
PRESENCE-KEYED. REQUIRED whenever sec1250UnrecapturedGain or collectibles28Gain is PRESENT on the return - of ANY amount, INCLUDING exactly $0. NOT a positive-amount test: a figure that exists and…

PRESENCE-KEYED. REQUIRED whenever sec1250UnrecapturedGain or collectibles28Gain is PRESENT on the return - of ANY amount, INCLUDING exactly $0. NOT a positive-amount test: a figure that exists and nets to zero still has an AMT-side Schedule D Tax Worksheet this engine does not model, so the attestation is still owed. Form 6251's "Lines 13, 14, and 15" instruction conditions substituting the regular-tax Schedule D Tax Worksheet into Part III on three statements not applying; true attests that statements (1) and (3) do not apply (the engine itself handles statement (2), taxable income zero). Absent/false with either figure present declines; supplied with NEITHER present also declines (orphan affirmation, same contract as the section 1256 / section 1202 affirmations).

collectibles28NoSec1202ExclusionPreferenceAffirmedtrue
§6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the PRESENCE of any of netShortTermCapGain, netLongTermCapGain, capGainAggregates, collectibles28Gain,…

§6694 affirmation REQUIRED whenever this return carries ANY Schedule D input at all — the PRESENCE of any of netShortTermCapGain, netLongTermCapGain, capGainAggregates, collectibles28Gain, sec1250UnrecapturedGain, priorYearCapLossCarryoverST, priorYearCapLossCarryoverLT or section1256NetGain, whatever its sign or magnitude, INCLUDING a value of exactly $0. DO NOT read this as a positive-amount test: round 9 keyed the trigger on the union of netLongTermCapGain>0 and collectibles28Gain>0 and round 10 proved that defeatable — an unrelated collectibles LOSS under §1(h)(4) nets BOTH operands to exactly $0 while a live §57(a)(7) preference survives whole, an executed $10,227 under-tax. Supplying the affirmation on a return with NO Schedule D input at all is an orphan and declines. Form 6251 Line 2h's §57(a)(7) preference is keyed to the §1202 EXCLUDED gain (Form 8949 column (g)), not to collectibles28Gain (the NETTED TAXABLE 28%-rate residue this affirmation previously keyed on) — the IRS 28% Rate Gain Worksheet's own lines 5/6 (a net current-year short-term loss, or a long-term capital-loss carryover) can drive collectibles28Gain to exactly $0 while a large §1202 exclusion (and preference) survives; a confirmed $11,375 executed under-tax on this exact shape motivated the widening. collectibles28Gain itself still conflates two populations: ordinary §408(m) collectibles gain, and the TAXABLE portion of §1202 qualified-small-business-stock gain — only the latter can carry the preference (7% of the EXCLUDED §1202 gain, for stock acquired BEFORE 2010-09-28; post-2010-09-27 stock is preference-free because §57(a)(7) reaches only stock acquired ON OR BEFORE 2010-09-27 -- Pub. L. 119-21 (OBBBA) §70431(a)(4) struck §1202(a)(4)(C) and wrote that acquisition limit into §57(a)(7) itself, RETROACTIVE to 2010-09-27 under §70431(a)(6)(B) (captioned 'Continued treatment as not item of tax preference'), so amended §57(a)(7) is the operative authority for EVERY supported year, not a TY2026+ rule. The limits are NOT identical: old §1202(a)(4)(C) reached only stock within (a)(4), while amended §57(a)(7) has no upper bound -- which is why the §1202(a)(5) tiers added for stock acquired after 2025-07-04 (50% at 3 years, 75% at 4, 100% at 5) are preference-free too, though NOT 100%-excluded). This engine hardcodes AMT otherPreferences to 0 and does not model the excluded-gain operand, so an unaffirmed pre-2010 §1202 stack would silently UNDER-TAX AMT, regardless of whether collectibles28Gain nets to a positive taxable residue. true attests EITHER no §1202 exclusion is involved at all on this return, OR every §1202 exclusion claimed arises solely from post-2010-09-27 stock. Absent/false on a return carrying ANY Schedule D input declines; supplied on a return carrying NO Schedule D input at all also declines (orphan affirmation, same contract as the §1256 affirmations).

scheduleCIncomenumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Schedule C line-31 net (sole-proprietor). A POSITIVE net COMPUTES self-employment tax (Schedule SE §1401/§1402: net×0.9235 → 12.4% OASDI to the $176,100 (2025) Social-Security wage base, coordinated with W-2 box-3 wages, then 2.9% Medicare uncapped) + the §164(f) one-half-SE-tax above-the-line deduction (reduces AGI), and the net flows to Schedule 1 line 3 → 1040 line 8 → AGI. REQUIRES scheduleCIsSingleSolePropFinalNetAffirmed:true AND scheduleCNoAmtAdjustmentAffirmed:true (no Form 6251 AMT preference — depletion 2d, circulation 2o, long-term contracts 2p, mining 2q, R&E 2r, IDCs 2t); a LOSS → schedule_c_loss_needs_review; W-2 wages present without socialSecurityWages → schedule_c_se_needs_social_security_wages; QBI/§199A, depreciation/§179/bonus, multiple Schedule Cs, spouse allocation, SE health-insurance, home-office, farm/clergy/statutory, and §1402 optional methods are out of scope → schedule_c_needs_review. STATE: CA CONFORMS (taxes the net in CA AGI as ordinary income; no CA SE tax / no CA §199A QBI), requiring BOTH caScheduleCSelfEmployedForCaPurposesAffirmed:true (AB5/ABC worker classification) AND caScheduleCNoStateBusinessAdjustmentsAffirmed:true (zero Schedule CA 540 line-3 business-income adjustment). NY ALSO CONFORMS (taxes the net in NY AGI as ordinary income), requiring nyScheduleCNoStateBusinessAdjustmentsAffirmed:true (zero Form IT-225 §168(k)-bonus / 2025-R&E / §179-SUV business-income addition); NY needs NO worker-classification affirmation. A VERIFY flag names the separate NY MCTMT + NYC-UBT, which the engine does not compute.

scheduleCIsSingleSolePropFinalNetAffirmedtrue
§6694 affirmation REQUIRED whenever scheduleCIncome is explicitly supplied, INCLUDING exactly $0:

§6694 affirmation REQUIRED whenever scheduleCIncome is explicitly supplied, INCLUDING exactly $0: attests it is the FINAL Schedule C line-31 net of ONE sole proprietor (the same taxpayer whose socialSecurityWages are supplied), with no depreciation/§179/bonus, no SE health-insurance (§162(l)) or home-office (§280A), not farm/clergy/statutory-employee, not a §1402 optional method, and not two spouses' combined self-employment (the OASDI cap is per-individual). Absent → decline. (The §199A QBI deduction is the separate opt-in scheduleCQbiEligible.)

scheduleCNoAmtAdjustmentAffirmedtrue
§6694 affirmation REQUIRED whenever scheduleCIncome is explicitly supplied, INCLUDING exactly $0 (a $0 REGULAR-tax net can still embed a genuine AMT preference, e.g.

§6694 affirmation REQUIRED whenever scheduleCIncome is explicitly supplied, INCLUDING exactly $0 (a $0 REGULAR-tax net can still embed a genuine AMT preference, e.g. large gross receipts offset by large deductions where one differs for AMT even though the two regular-tax figures net to zero; a confirmed executed under-tax at $0 net motivated this widening). Attests the Schedule C line-31 net contains NO AMT preference or adjustment under Form 6251 lines 2d (depletion), 2o (circulation costs), 2p (long-term contracts), 2q (mining exploration/development costs), 2r (research/experimental costs), or 2t (intangible drilling costs) — this engine's AMT computation otherwise passes otherPreferences:0 for every computed Schedule C return, correct ONLY when none of these differ between regular tax and AMT. Absent → decline (schedule_c_needs_review); a preparer must complete Form 6251 by hand.

scheduleCPersonalServicesCapitalNotMaterialAffirmedtrue
§6694 affirmation REQUIRED with canBeClaimedAsDependent:true and a positive scheduleCIncome:

§6694 affirmation REQUIRED with canBeClaimedAsDependent:true and a positive scheduleCIncome: all of it is from the filer's own personal services and capital is not a material income-producing factor (§911(d)(2)(B)). Absent → declines (dependent_filer_needs_review). Federal only.

scheduleCQbiEligibletrue
§199A QBI opt-in (below-threshold only).

§199A QBI opt-in (below-threshold only). When true (with a positive affirmed scheduleCIncome), computes the 20% QBI deduction = min(20% × (Schedule C net − §164(f) half-SE), 20% × (taxable income − net capital gain)) [Form 8995], reducing taxable income. Attests: (a) a QUALIFIED §162 trade/business; (b) NO self-employed retirement (SEP/SIMPLE/solo-401k), SE health-insurance, or other QBI-reducing deduction beyond the half-SE the engine already subtracts (overstating QBI under-taxes). The engine computes the taxable-income threshold ($197,300 single/HoH/MFS, $394,600 MFJ, 2025) and DECLINES the at/above-threshold case (Form 8995-A wage/UBIA/SSTB, engine-invisible). Absent → no QBI (over-tax-safe). Federal-only (CA does not conform to §199A).

socialSecurityWagesnumber
W-2 box 3 — the SE earner's own Social-Security wages+tips (≥0).

W-2 box 3 — the SE earner's own Social-Security wages+tips (≥0). REQUIRED (fail-closed) when scheduleCIncome is present AND the return has W-2 wages: W-2 SS wages already used part of the combined $176,100 OASDI ceiling (Schedule SE lines 8–9), so the SE OASDI is capped at the REMAINING room. Absent-with-wages → schedule_c_se_needs_social_security_wages (assuming $0 would over-collect OASDI → inflate the §164(f) deduction → under-tax a phase-out). An explicit 0 affirms no W-2 SS wages. Box 5 (medicareWages) is uncapped and cannot substitute. Federal-only.

scheduleEIncomenumber
CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN;

CONTAINER SCALAR - OMITTING THIS FIELD ASSERTS THE SCHEDULE DOES NOT EXIST ON THE RETURN; it does NOT mean $0. A schedule that exists and nets to zero MUST be sent explicitly as 0, because the section 6694 affirmation gates trigger on the schedule's EXISTENCE and omitting a zero-net schedule silently skips them. THE ENGINE CANNOT DETECT A VIOLATION - omission is indistinguishable from absence, so this obligation is enforced by the caller. Schedule E net (SIGNED). A NON-NEGATIVE value COMPUTES a simple passive rental (→ AGI + §1411 NIIT) with scheduleERentalIsPassiveFinalNet:true AND scheduleERentalNotSection162Business:true AND scheduleERentalNoAmtDifferenceAffirmed:true. A NEGATIVE value (rental LOSS) COMPUTES under EITHER of two mutually-exclusive mechanisms: (1) the §469(i) up-to-$25,000 active-participation allowance (allowance = $25,000 − 50% × (modified AGI − $100,000), zero at MAGI ≥ $150k; the allowed portion reduces AGI, the excess SUSPENDS as an advisory Form-8582 carryforward) — ONLY with ALL FOUR loss affirmations below PLUS ALL THREE of the non-negative-route affirmations (scheduleERentalIsPassiveFinalNet + scheduleERentalNotSection162Business + scheduleERentalNoAmtDifferenceAffirmed), filing status ≠ married_filing_separately, and NO Social Security benefits (a §469-MAGI add-back the engine fences out); OR (2) the IRC §469(g)(1)(A) full-disposition PAL RELEASE (routed by asserting ANY ONE of the four disposition affirmations true) — the FULL current-year loss PLUS any prior-year §469-suspended loss from the SAME activity, UNCAPPED (no $25k limit, no MAGI phase-out), when the taxpayer disposed of their ENTIRE interest in a FULLY TAXABLE cash sale to an UNRELATED PARTY. Requires ALL SIX §469(g) affirmations below PLUS the two positive affirmations, filing status ≠ married_filing_separately, and a same-track computed AMT-binding check (belt-and-suspenders only — the actual AMT safety mechanism is the required scheduleERentalNoAmtDifferenceAffirmed attestation, since a computed check at only the pre-/post-release configurations cannot rule out a cross-track AMT divergence Form 6251's own PAL/at-risk worksheet would reveal). NIIT: declines (rather than silently floor) whenever the un-modeled Form 8960 same-activity NII deduction could materially change the §1411 tax owed — computes only when provably immaterial. Any other loss case → schedule_e_needs_review decline. STATE: NY conforms for a POSITIVE net (nyScheduleENoStateBusinessAdjustmentsAffirmed); a rental LOSS (either mechanism) declines for NY. CA rejects it (separate FTB 3801/3885A §469 track — deferred).

scheduleERentalIsPassiveFinalNettrue
§6694 affirmation REQUIRED for a non-negative scheduleEIncome:

§6694 affirmation REQUIRED for a non-negative scheduleEIncome: attests it is the FINAL Schedule E line-26 PASSIVE net — post depreciation/§465 at-risk/absorbed §469 suspended losses, no property disposition (no §1250 recapture), rental real estate only (no royalties/K-1). The AMT-side question is a SEPARATE required affirmation, scheduleERentalNoAmtDifferenceAffirmed. Absent this affirmation → decline.

scheduleERentalNotSection162Businesstrue
§6694 affirmation REQUIRED for a positive scheduleEIncome OR a rental LOSS (either §469(i) or §469(g) mechanism):

§6694 affirmation REQUIRED for a positive scheduleEIncome OR a rental LOSS (either §469(i) or §469(g) mechanism): attests the rental is NOT a §162 trade/business (Notice 2019-07 safe harbor), so no §199A QBI 20% deduction applies. If it IS, a preparer must compute the QBI deduction (omitting it would over-tax). Absent → decline.

scheduleERentalActiveParticipationAffirmedtrue
§469(i)-mechanism-only §6694 affirmation REQUIRED for a rental LOSS routed to the $25,000 allowance:

§469(i)-mechanism-only §6694 affirmation REQUIRED for a rental LOSS routed to the $25,000 allowance: attests §469(i)(6) ACTIVE participation (bona-fide management decisions, ≥10% ownership, not a limited partner) — the lower bar that unlocks the up-to-$25,000 special allowance. Absent → the loss declines. (NOT required for the §469(g) full-disposition release — that mechanism has no active-participation requirement.)

scheduleERentalNoPriorSuspendedPALAffirmedtrue
§469(i)-mechanism-only §6694 affirmation REQUIRED for a rental LOSS routed to the $25,000 allowance:

§469(i)-mechanism-only §6694 affirmation REQUIRED for a rental LOSS routed to the $25,000 allowance: attests NO prior-year §469 suspended passive loss is carried into this activity (Form 8582 carryforward is not tracked by that mechanism). Absent → decline. (The §469(g) full-disposition release is the OPPOSITE case — it exists specifically to release a prior-year suspended PAL — so this affirmation does not apply there; use the four scheduleERental*Disposition*/scheduleERentalUnrelatedPartyAffirmed/scheduleERentalDispositionAtRiskAffirmed fields instead.)

scheduleERentalAtRiskAffirmedtrue
§469(i)-mechanism-only §6694 affirmation REQUIRED for a rental LOSS routed to the $25,000 allowance:

§469(i)-mechanism-only §6694 affirmation REQUIRED for a rental LOSS routed to the $25,000 allowance: attests the loss is fully allowed under the §465 AT-RISK rules (sufficient at-risk basis — not limited on Form 6198). Absent → decline. (The §469(g) full-disposition release uses the SEPARATE scheduleERentalDispositionAtRiskAffirmed field instead — its wording is disposition-specific.)

scheduleERentalNotRealEstateProfessionalAffirmedtrue
§6694 affirmation REQUIRED for a rental LOSS under EITHER mechanism (§469(i) allowance or §469(g) full-disposition release):

§6694 affirmation REQUIRED for a rental LOSS under EITHER mechanism (§469(i) allowance or §469(g) full-disposition release): attests the taxpayer is NOT a §469(c)(7) real-estate professional for this activity — a real-estate professional's rental may not have been passive under the ordinary rules, so its suspension/release mechanics differ and this engine declines rather than guess. Absent → decline.

scheduleERentalEntireInterestDisposedAffirmedtrue
§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release.

§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release. Attests the ENTIRE interest in the passive activity was disposed — not a partial interest, and not one property carved out of a larger activity grouped with other properties under Reg. §1.469-4. A partial/grouped disposition does not trigger the full release. Absent → decline.

scheduleERentalFullyTaxableCashSaleAffirmedtrue
§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release.

§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release. Attests the disposition was a CASH SALE (or economically equivalent fully-taxable transaction) — SPECIFICALLY NOT an installment sale under §453 (§469(g)(3) releases the suspended loss RATABLY as gain is recognized, not all at once), NOT a §1031 like-kind exchange (the loss carries over rather than releasing), and NOT a gift or transfer at death (§469(j)(6)/§469(g)(2) have their own different rules). Absent → decline.

scheduleERentalUnrelatedPartyAffirmedtrue§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release. Attests the buyer is NOT a related party under §267(b)/§707(b). Absent → decline.
scheduleERentalDispositionAtRiskAffirmedtrue
§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release (disposition-specific wording — distinct from scheduleERentalAtRiskAffirmed, which is scoped to the §469(i) allowance).

§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release (disposition-specific wording — distinct from scheduleERentalAtRiskAffirmed, which is scoped to the §469(i) allowance). Attests the taxpayer had SUFFICIENT §465 at-risk basis to support the ENTIRE released amount (this year's operating result plus any prior-year suspended amount), never limited under the at-risk rules (no Form 6198 limitation, this year or in any year the loss was suspended). Absent → decline.

scheduleERentalNoAmtDifferenceAffirmedtrue
§6694 affirmation, one per Schedule E rental activity, REQUIRED on EVERY route that reaches Schedule E — i.e.

§6694 affirmation, one per Schedule E rental activity, REQUIRED on EVERY route that reaches Schedule E — i.e. whenever scheduleEIncome is present at any value, positive, zero or negative: (1) a non-negative scheduleEIncome — attests the post-1986 depreciation AND passive-activity differences are both identical between AMT and regular tax for this activity; or (2) the §469(g) full-disposition PAL release — attests the AMT-side §469 suspended amount (line 2m, Passive activities), the §465 at-risk amount (line 2n, Loss limitations), and the disposition's own gain/loss (line 2k, Disposition of property) are ALL identical between AMT and regular tax. or (3) a NEGATIVE scheduleEIncome limited by the §469(i) up-to-$25,000 active-participation allowance — attests the AMT-refigured amount reported for the activity equals the regular-tax amount (Form 6251 line 2m is the difference between what the activity reports for AMT and what it reports for regular tax, each after its own §469 limitation, so it can run in EITHER direction. The AMT/regular depreciation difference for a rental reverses sign over an asset's life (150%-declining-balance for AMT against 200% for regular gives SMALLER AMT deductions in the early years and LARGER ones later, and post-1998 residential rental real property has no AMT depreciation adjustment at all), and the AMT-refigured activity can be a net GAIN where the regular one is a loss. Where both tracks are losses the allowance applies to each, so line 2m is positive only when the AMT loss falls below BOTH the regular loss and the allowance — and zero when both losses exceed the allowance. A positive line 2m raises AMTI), that there is no AMT-ONLY prior-year unallowed loss for the activity (scheduleERentalNoPriorSuspendedPALAffirmed attests the REGULAR track only), and that the §469(i) allowance is the same on both tracks (AMT modified AGI equals regular modified AGI). Form 6251 runs its own separate passive-activity-loss/at-risk/depreciation worksheet this engine does not model, and the resulting direction is NOT bounded absent this attestation: The engine passes otherPreferences:0 into the AMT and models no line-2m adjustment, so absent this attestation the direction is unbounded and an omitted positive line 2m is a pure UNDER-tax. Supplied with no scheduleEIncome at all → orphan-affirmation decline. Absent/false when a trigger applies → decline.

scheduleERentalDispositionGainReflectedAffirmedtrue
§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release.

§469(g)-mechanism-only §6694 affirmation REQUIRED for the full-disposition PAL release. Attests FIVE things: (a) this disposition's property was held MORE THAN ONE YEAR (one year or less is not §1231 property at all — its entire gain or loss is ordinary, Form 4797 Part II); (b) combined with EVERY OTHER §1231 property transaction this SAME year, the annual §1231 netting (Form 4797 Part I) is a NET GAIN, not a net loss (a net LOSS makes even this disposition's own gain wholly ORDINARY under §1231(a)(2)), AND there is NO unrecaptured net §1231 loss from the preceding 5 years (the §1231(c) lookback) recharacterizing any part of this year's gain as ordinary; (c) only this disposition's own FINAL RESIDUAL long-term-capital-gain amount, after that full Form 4797 determination, is reflected in netLongTermCapGain, not omitted; (d) any unrecaptured §1250 25%-rate portion of that residual (distinct from ordinary depreciation recapture, excluded by (e)) is included WITHIN netLongTermCapGain AND SEPARATELY declared via sec1250UnrecapturedGain — declaring it only within netLongTermCapGain without the separate declaration taxes it at 0/15/20 instead of 25%, an under-tax; AND (e) NO Form 4797/§1231 ordinary gain or loss of ANY kind exists for this disposition — including, without limitation, §1245/§1250 ordinary recapture and any §1231(c) lookback-recharacterized ordinary gain (the YEAR-LEVEL net-§1231-loss case is already excluded by (b)'s net-gain requirement; a DISPOSITION-level loss within a net-gain year is itself a long-term capital loss, not ordinary, and (e) does not exclude it). The engine has no annual §1231-netting algorithm, no five-year-lookback state, and no field capable of representing Form 4797 ordinary gain or loss (NOT wages, which is exclusively W-2 box 1 employment income) — if ANY of (a)/(b)/(e) is not true, this field must not be affirmed true. Absent → decline.

qbiDeductionnumberNot computed by this engine: any value declines (out_of_scope_income). Send REIT dividends as reit199ADividends instead.
pensionDistributionTaxablenumber
1040 lines 4b/5b — the FULLY-TAXABLE portion of a pension/annuity/IRA distribution (1099-R box 2a).

1040 lines 4b/5b — the FULLY-TAXABLE portion of a pension/annuity/IRA distribution (1099-R box 2a). ORDINARY income → AGI + ordinary tax ALWAYS; NOT in the Additional-Medicare base (not wages). §1411 NIIT status depends on pensionDistributionIsNonqualifiedAnnuityNii (see below). A POSITIVE value COMPUTES only with BOTH pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true. Basis/after-tax, QCD, rollover, Roth conversion, NUA, and the early-distribution additional tax (Form 5329 10%/25%, or CA's FTB 3805P) are NOT modeled → pension_needs_review decline (do not affirm). NY EXCLUDES it on the state return (IT-201 line 26 govt / line 29 private $20k@59½); CA CONFORMS and TAXES it for the clean case this engine computes. CA's ONE MODELED exclusion is caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed — uniformed-services retired pay / a DoD Survivor Benefit Plan annuity, up to $20,000, AGI-gated (R&TC §§17132.9/17132.10); that one is COMPUTED, not merely flagged. A VERIFY flag separately names the unmodeled CA divergences enumerated in CA_COMPUTE_CAPABILITY.state_adjustments.pension (served on GET /api/mcp/tax-compute/state), which is the single authoritative list — this text states no count of its own, because a count restated in many places is a claim that must be maintained in many places, and on this surface it was not: Tier-2 railroad retirement (RRB-1099-R), which CA excludes (45 U.S.C. §231m) and whose omission OVER-taxes; and CA's own early-distribution additional tax, 2.5% (R&TC §17085(c)(1)) and 6% where §72(t)(6) applies (§17085(c)(2)), which this engine computes for NEITHER jurisdiction — per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax, and omitting THIS one UNDER-taxes. And an IRA-to-HSA one-time funding distribution under §408(d)(9): federally EXCLUDED under §408(d)(9)(A), but California conforms IRC §223 out entirely (R&TC §17215.4) and the FTB 3805P instructions require it ADDED BACK to CA AGI, and a 2 1/2% additional tax where the distribution is premature under the §72(t) rules. That one runs the OPPOSITE way — omitting it UNDER-taxes California — and the engine has no field for it, so a CA return carrying one is outside the modeled surface.

pensionDistributionFullyTaxableAffirmedtrue
§6694 affirmation REQUIRED for a positive pensionDistributionTaxable (one of TWO required affirmations — see pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed below):

§6694 affirmation REQUIRED for a positive pensionDistributionTaxable (one of TWO required affirmations — see pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed below): attests the amount is the FULLY-TAXABLE 1099-R box 2a distribution (taxable amount DETERMINED — box 2b NOT checked), with NO basis/after-tax contributions, and that it is NOT a QCD, rollover, Roth conversion, or NUA. Absent → the distribution declines (pension_needs_review).

pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmedtrue
§6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed.

§6694 affirmation REQUIRED for a positive pensionDistributionTaxable, alongside pensionDistributionFullyTaxableAffirmed. Attests EITHER the recipient was 59½+ at distribution, OR a full-amount exception applies under §72(t)(2) (qualified plans) — which, like the age-59½ basis above, answers the §72(t)/(q) EARLY-distribution question ONLY and does NOT by itself discharge the outcome condition below: a 50-year-old 5-percent owner with a genuine §72(t)(2)(A)(iii) disability exception and amounts over the plan formula still owes §72(m)(5) or §72(q)(2) (nonqualified annuities) — DIFFERENT, non-identical lists (fed-pension-5b-72q-levy-exception-fix, 2026-08-29 — §72(q)(2) is materially shorter, e.g. no IRS-levy exception), OR the distribution is outside §72(t)/(q) AND outside every OTHER additional-tax regime -- which is the condition that actually matters, and being outside §72(t) alone is NOT sufficient for it. §7702A MODIFIED ENDOWMENT CONTRACT distributions are the worked counterexample: outside §72(t) (which reaches only a 'qualified retirement plan' per §4974(c)) and outside §72(q) (which reaches only 'an annuity contract'), yet §72(v)(1) imposes its own 10% additional tax whose exception list at §72(v)(2) is ONLY age 59½, disability, and substantially-equal-periodic-payments -- NO death exception and NO levy exception, which the Form 5329 instructions state directly at Exception 04 ('doesn't apply to modified endowment contracts'). A MEC reaches this field legitimately as 1099-R box 7 code D. §72(m)(5) (10% on a 5%-owner's qualified-plan amounts exceeding the plan formula) is a further regime this field does not enumerate. This engine models NONE of these additional taxes, so affirm only if NO FEDERAL CHAPTER 1 ADDITIONAL TAX ON THIS DISTRIBUTION, WHICHEVER FORM REPORTS IT (Form 5329 Part I for §72(t)/(q)/(v); Schedule 2 for §72(m)(5)) is owed on this distribution — §72(t), §72(q), §72(v), §72(m)(5) or any like regime; the regimes named here are ILLUSTRATIVE, never a complete list. DELIBERATELY OUT OF SCOPE of this affirmation, because this engine handles them elsewhere and sweeping them in here would make an honest caller unable to affirm: the §1411 net investment income tax, which pensionDistributionIsNonqualifiedAnnuityNii governs, and state analogues such as California's 2.5% FTB 3805P additional tax, which are disclosed on their own surfaces (a governmental §457(b) plan distribution not attributable to a rollover from a qualified retirement plan, IRC §72(t)(9), IS such a case -- this does NOT include §457(f)/§409A nonqualified deferred compensation or a nongovernmental §457(b) plan, which are reported to the recipient on Form W-2 for employee participants, and on other information returns for nonemployees and for beneficiaries of deceased participants — never on the pension information return that feeds this field, so they can never legitimately occupy pensionDistributionTaxable -- certify-leaf round-16 fix, 2026-09-01, correcting an over-broad round-15 addition); not a partial/dollar-capped exception such as first-time-homebuyer $10,000 or birth/adoption $5,000; the qualified-HSA-funding-distribution exception is not available from a SEP or SIMPLE IRA (BOTH plan types, not only SIMPLE): §408(d)(9)(B) defines the term as a distribution from an individual retirement plan 'other than a plan described in subsection (k) or (p)' -- (k) is a SEP, (p) a SIMPLE -- and the 2025 Instructions for Form 5329, Part I say 'from an IRA (other than a SEP or SIMPLE IRA)'. IRS Notice 2008-51 and Pub. 969 narrow that bar to an ONGOING SEP or SIMPLE IRA, 'ongoing' meaning an employer contribution is made for the plan year ending with or within the tax year of the distribution; where you cannot substantiate that a plan is NOT ongoing, treat it as ongoing, which is the over-decline-safe direction. Either way this engine does not model a qualified HSA funding distribution at all: FEDERALLY §408(d)(9)(A) excludes it from gross income, so it is not a fully-taxable 1040 line-5b amount. This text does NOT summarize the rest of §408(d)(9): the §408(d)(9)(C) dollar cap and one-time-transfer rule, and the §408(d)(9)(D) testing-period recapture with its own (ii) death/disability exception. Read §408(d)(9) in full rather than relying on a one-sentence compression of it. CALIFORNIA DOES NOT CONFORM, and carrying the federal treatment across is an UNDER-tax: R&TC §17215.4 conforms IRC §223 out of California entirely, and per the FTB 3805P instructions 'any distribution from an IRA to an HSA must be added to adjusted gross income (AGI) on the taxpayer's California return and would be subject to a 2 1/2% additional tax under the rules for premature distributions under IRC Section 72' — owed even where NO federal §72(t) tax is. This engine models NEITHER the federal exclusion NOR the CA add-back. SIMPLE-IRA timing within the §72(t)(6)(A) 2-year period does NOT by itself disqualify a 59½+ or exception-covered distribution — it only affects the RATE (10% vs 25%, §72(t)(6)) — and note CALIFORNIA DIVERGES: its analogue is 2.5% (R&TC 17085(c)(1)), 6% where 72(t)(6) applies (17085(c)(2)), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions', so a federally-valid exception does not guarantee $0 of CA additional tax; this engine computes NEITHER additional tax for a genuinely early, no-exception distribution. THE 2-YEAR CLOCK IS ANCHORED TO PARTICIPATION IN THE EMPLOYER'S PLAN, NOT THE ACCOUNT'S AGE: §72(t)(6)(A) runs the period from 'the date such individual first participated in any qualified salary reduction arrangement maintained by the individual's employer under section 408(p)(2)', and IRS Notice 98-4 Q&A I-5 gives the operational start — 'the first day on which contributions made by the individual's employer are deposited in the individual's SIMPLE IRA' (the Form 5329 instructions and FTB 3805P agree). It is measured PER EMPLOYER, so a new employer's SIMPLE starts a NEW 2-year period for that employer's own contributions — reading the clock as the ACCOUNT's age can UNDER-tax at 10%/2.5%. A transfer or rollover between SIMPLE IRAs under the SAME employer's arrangement does not restart it. ACROSS EMPLOYERS THE PERIOD FOLLOWS EACH EMPLOYER'S OWN CONTRIBUTIONS — 26 CFR §1.408A-4 A-4(b): 'This 2-year period of section 408(d)(3)(G) applies separately to the contributions of each of an individual's employers maintaining a SIMPLE IRA Plan' — and A-4(b) itself identifies that period as 'the 2-year period described in section 72(t)(6)', so it is THIS period, not a rollover-only clock. The rule it construes is §408(d)(3)(G)'s restriction on conversions; applying the same contribution-tracing to the RATE is this engine's reading of it. It runs BOTH ways. Dollars traceable to a prior employer whose period has EXPIRED keep that expiry and are NOT pulled into the new employer's open window. Dollars traceable to a prior employer whose period is STILL OPEN carry it into the new account and stay at 25%/6% even after the receiving employer's own window closes — until that prior period itself expires, not indefinitely. Where provenance cannot be substantiated, treat the amount as still inside a 2-year period (25%/6%) rather than assuming the lower rate. (§72(t)(6)(B) separately waives the 25% for amounts rolled into a 401(k)/403(b) when the employer terminates the SIMPLE and converts — ignoring it is over-tax-safe.) Whenever this field is true AND pensionDistributionIsNonqualifiedAnnuityNii is not explicitly false, pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed is ALSO required (see below) to confirm the basis is genuinely valid under the shorter §72(q)(2) list, not just borrowed from §72(t)(2). The engine does NOT compute the early-distribution additional tax itself — only gates on whether one could apply. Absent → the distribution declines (pension_needs_review).

pensionDistributionIsNonqualifiedAnnuityNiiboolean
§6694 affirmation, whole-scalar, for the ENTIRE pensionDistributionTaxable amount's §1411 NIIT classification.

§6694 affirmation, whole-scalar, for the ENTIRE pensionDistributionTaxable amount's §1411 NIIT classification. true = a NONQUALIFIED COMMERCIAL ANNUITY — net investment income under §1411(c)(1)(A)(i), included in the §1411 NIIT base. false/absent = a qualified-plan distribution (§401(a)/403(a)/403(b)/408/408A/457(b), IRC §1411(c)(5)) — excluded from NIIT. A MIXED distribution must affirm neither. A §7702A MODIFIED ENDOWMENT CONTRACT HAS NO TRUTHFUL POLE HERE and must be left ABSENT: `true` means a nonqualified commercial ANNUITY and `false` means a QUALIFIED-PLAN distribution, and a MEC is neither — it is life insurance, reaching this engine as a 1099-R box 7 code D. Absent is fail-closed: where the classification would change the §1411 NIIT owed, the return declines rather than computing on a guess. NOT asserted here, either way: whether a MEC distribution belongs in the §1411 NII base. The 2025 Instructions for Form 8960 do not address modified endowment contracts, and their ONE mention of a life insurance contract is 'Gain or loss from the disposition of an annuity or life insurance contract' — a DISPOSITION question, not the question whether the §72 income portion of a MEC DISTRIBUTION is net investment income. So this engine takes no position; a preparer must resolve it. (A superseded version of this sentence asserted a negative universal about how often that phrase appears in those instructions. It was wrong on the facts and wrong in kind: the phrase does occur, in the disposition line quoted just above, and the claim had been taken from a SUMMARY of the document rather than the document. The superseded wording is described rather than reproduced, because a quoted retraction is indistinguishable from a live assertion to any search.) On THIS federal endpoint, required for NIIT-materiality purposes (else pension_needs_review decline) ONLY when this return's MAGI/NII shape makes the classification actually change the NIIT owed (an exact base-invariance test, not a MAGI-threshold proxy) — a SEPARATE, independent trigger requires this field to be affirmatively false (or the sibling early-withdrawal-basis field above to be true) whenever an early-withdrawal exception is claimed, per fed-pension-5b-72q-levy-exception-fix above. See also the /state endpoint below: NY's own $20,000 private-pension exclusion requires this field UNCONDITIONALLY whenever claimed, regardless of federal NIIT materiality. true is flatly inconsistent with nyPensionIsGovernmentPension:true or nyPrivatePensionQualifiesFor20kExclusion:true → decline (pension_exclusion_classification_ambiguous).

pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmedboolean
§6694 affirmation REQUIRED whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true AND pensionDistributionIsNonqualifiedAnnuityNii is NOT explicitly false.

§6694 affirmation REQUIRED whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true AND pensionDistributionIsNonqualifiedAnnuityNii is NOT explicitly false. §72(q)(2) — the exception list for NONQUALIFIED annuity contracts — is materially shorter than §72(t)(2)'s (qualified plans): NO IRS-levy exception, and none of education/homebuyer/birth-adoption/reservist/health-insurance/medical/disaster/domestic-abuse/emergency-expense/terminal-illness either. true attests the claimed basis is one of: age 59½+; death of the contract HOLDER (narrower than an employee's death); disability (§72(m)(7)); substantially-equal-periodic-payments; pre-8/14/1982 investment (allocable portion only); a §130(d) qualified funding asset; an immediate annuity contract (§72(u)(4)); or an employer-held post-termination §401(a)/403(a) plan pending separation. Do NOT affirm on any §72(t)(2)-only basis (levy, education, homebuyer, birth/adoption, reservist, QDRO, medical, disaster, domestic-abuse, emergency-expense, terminal-illness, or qualified-HSA-funding) — none has a §72(q)(2) analogue, at any dollar amount. Do NOT affirm on a §72(e)(5)(D) plan/contract EITHER: §72(e)(5)(D) is itself titled 'Contracts under qualified plans' and covers only §401(a)/403(a)/403(b)/818(a)(3) plans and IRAs — the SAME non-overlap character as the deliberately-omitted §72(q)(2)(H) — if this is the actual basis, the distribution is a qualified plan or IRA and pensionDistributionIsNonqualifiedAnnuityNii was misanswered; correct the classification instead. Absent/false with the trigger condition met → decline (pension_needs_review, fail-closed); the alternative is to affirmatively classify pensionDistributionIsNonqualifiedAnnuityNii:false (round-11 correction, 2026-08-30: this rules OUT the §72(q)(2) list, and where §72(t) reaches the distribution the §72(t)(2) list is what governs — but `false` does NOT by itself establish that §72(t) reaches it at all: a governmental §457(b) distribution NOT attributable to a rollover from a qualified retirement plan truthfully takes `false` and is outside §72(t) entirely (§72(t)(9); 2025 Form 5329 instructions, exception 13). Where §72(t) does reach it, that list is NOT uniform across every plan type — see pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmed, ALSO required).

pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmedboolean
§6694 affirmation REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the…

§6694 affirmation REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — REGARDLESS of which specific basis that field relies on, since the engine cannot see which basis was claimed from that single generic field. Attests the SPECIFIC basis relied upon is actually available for the ACTUAL plan type of this distribution. 26 U.S.C. §72(t)(2)/(3)/(10) contains MANY plan-type-restricted exceptions -- the caller must independently verify plan-type eligibility for WHATEVER basis is claimed. Known illustrative examples (fetched directly from uscode.house.gov; NOT a complete list; further plan-type-restricted bases include, e.g., §404(k) ESOP stock dividends, federal phased-retirement annuities, §408(d)(4) IRA-only withdrawals, §402A(e) pension-linked emergency savings accounts, and §401(a)(39) long-term-care distributions effective for distributions after 2025-12-29): (1) §72(t)(3)(A) -- the separation-after-age-55 exception (§72(t)(2)(A)(v)) and the QDRO alternate-payee exception (§72(t)(2)(C)) do NOT apply to a distribution from an individual retirement plan (IRA); (2) §72(t)(2)(D)/(E)/(F) -- the unemployed-health-insurance-premiums, higher-education, and first-home exceptions are each IRA-ONLY; (3) §72(t)(3)(B) -- the SEPP basis (§72(t)(2)(A)(iv)) from an employer qualified plan is valid ONLY if the payment series begins after separation from service; (4) §72(t)(2)(G)(iii)(I) -- the reservist exception is IRA-or-elective-deferral-only and carries NO dollar cap; (5) §72(t)(2)(H)(vi)(I)/(I)(iv) -- birth/adoption and emergency-personal-expense are NOT available from a defined benefit plan; (6) §72(t)(2)(K)(vi)(I) -- domestic abuse is NOT available from a defined benefit plan or a §§401(a)(11)/417 QJSA plan. THERE IS NO SHORTCUT AROUND THE OUTCOME CONDITION BELOW, WHICH GOVERNS AND IS THE ONLY THING THAT DISCHARGES THIS AFFIRMATION. None of the following discharges it on its own. (a) pensionDistributionIsNonqualifiedAnnuityNii is explicitly true (round-12 correction, 2026-08-30: 'NOT explicitly false' was too broad — it admitted the unaffirmed/undefined case, where the parenthetical justification below is FALSE for an actual §72(t)-governed distribution, since §72(q)(2)(H) is itself an ITEM IN the §72(q)(2) exception list -- that list's chapeau reads 'Paragraph (1) shall not apply to any distribution—' and (H) is 'to which subsection (t) applies (without regard to paragraph (2) thereof)', so its effect is to exempt a §72(t)-governed distribution from §72(q)(1)'s TAX, not to remove it from §72(q)(2). The two regimes are therefore mutually exclusive, which is why only an AFFIRMATIVE nonqualified-annuity classification actually puts the shorter §72(q)(2) list in control) — the shorter §72(q)(2) list governs instead and has none of these plan-type splits. (b) The claimed basis is age-59½+, death, disability, or the IRS-levy exception (§72(t)(2)(A)(vii)) — these are identical regardless of plan type, UNLIKE the generic SEPP basis (divergence (3), which IS plan-type-dependent) — BUT NONE OF THEM DISCHARGES §72(m)(5), which reaches a 5-percent owner's excess-over-plan-formula amounts AT ANY TIME with no age, death, disability or levy carve-out and is reported on Schedule 2 line 17j. (c) Nor does being outside §72(t)/(q): being outside §72(t) alone is NOT sufficient. §7702A MODIFIED ENDOWMENT CONTRACT distributions are the worked counterexample: outside §72(t) (which reaches only a 'qualified retirement plan' per §4974(c)) and outside §72(q) (which reaches only 'an annuity contract'), yet §72(v)(1) imposes its own 10% additional tax whose exception list at §72(v)(2) is ONLY age 59½, disability, and substantially-equal-periodic-payments -- NO death exception and NO levy exception, which the Form 5329 instructions state directly at Exception 04 ('doesn't apply to modified endowment contracts'). A MEC reaches this field legitimately as 1099-R box 7 code D. §72(m)(5) (10% on a 5%-owner's qualified-plan amounts exceeding the plan formula) is a further regime this field does not enumerate. This engine models NONE of these additional taxes, so affirm only if NO FEDERAL CHAPTER 1 ADDITIONAL TAX ON THIS DISTRIBUTION, WHICHEVER FORM REPORTS IT (Form 5329 Part I for §72(t)/(q)/(v); Schedule 2 for §72(m)(5)) is owed on this distribution — §72(t), §72(q), §72(v), §72(m)(5) or any like regime; the regimes named here are ILLUSTRATIVE, never a complete list. DELIBERATELY OUT OF SCOPE of this affirmation, because this engine handles them elsewhere and sweeping them in here would make an honest caller unable to affirm: the §1411 net investment income tax, which pensionDistributionIsNonqualifiedAnnuityNii governs, and state analogues such as California's 2.5% FTB 3805P additional tax, which are disclosed on their own surfaces. This is a non-exhaustive teaching aid, not a completeness claim of any kind, for any §72(t)(2)/(3)/(10) basis not named above. Absent → the distribution declines (pension_needs_review).

pensionDistributionNoSeppModificationRecaptureAffirmedtrue
§6694 affirmation REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the…

§6694 affirmation REQUIRED for EVERY positive pensionDistributionTaxable whenever pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed is true, and for ANY $0 pensionDistributionTaxable (the year a series stops) — REGARDLESS of which specific basis that field relies on, since the engine cannot distinguish age-59½+ from a substantially-equal-periodic-payments (SEPP) basis or any other exception from that single generic field. IF the SEPP basis was ever relied upon (§72(t)(2)(A)(iv) for a qualified plan/IRA, or §72(q)(2)(D) for a nonqualified annuity), §72(t)(4) and §72(q)(3) are PARALLEL rules (IRS Notice 2022-6 §2.07 — IRAs covered via §2.03/§3.02(f)): if that SEPP series was later modified — including a balance addition other than investment experience, a partial transfer to another plan, or a rollover, NOT only a change in payment amount (Notice 2022-6 §3.02(e)) — before the LATER of the close of the 5-year period beginning with the first payment or age 59½, the modification-year tax is increased by the additional tax that would have applied to every prior payment, plus interest. If NO distribution ever relied on a SEPP basis, this affirmation is trivially true. NOT a modification, ONLY on these exact terms: depletion CAUSED BY following the qualifying method itself to its natural end, where the account/contract is an individual account plan or an IRA (Notice 2022-6 §3.03(a) excuses only the resulting reduced final payment and subsequent cessation), OR — a LESS CERTAIN §3.04-inferred reading for the §72(q) side, not a direct textual match — the analogous exhaustion of a nonqualified annuity contract through that same method; NOT depletion from any other act; a modification BY REASON OF death or disability -- the statute reads 'other than by reason of death or disability', so causation is required and a disability that merely EXISTS while the taxpayer independently changes the payment does not qualify; a distribution to which §72(t)(10) applies -- the qualified-public-safety-employee / private-sector-firefighter age-50-or-25-years-of-service exception, available ONLY from a governmental plan (§414(d)) or, for an employee providing firefighting services, a plan described in §402(c)(8)(B)(iii)/(iv)/(vi); NEVER from an IRA, which is §402(c)(8)(B)(i)/(ii) and outside §72(t)(10) entirely; no §72(q) analogue; a one-time switch to the required-minimum-distribution method (§3.03(b)); or — for the REQUIRED MINIMUM DISTRIBUTION method specifically (the most common SEPP method, previously omitted despite that): its required ANNUAL REDETERMINATION (§3.01(a)), a beneficiary/table change REQUIRED by §3.02(b), or (for a series commencing before 2023) substituting the current version of the SAME table for the CORRESPONDING table used under Rev. Rul. 2002-62 — Notice 2022-6 Section 4's own word is 'corresponding', and it does real limiting work: it pairs each current table with ITS OWN predecessor. A CROSS-TYPE swap (e.g. Single Life -> Uniform Lifetime, which lengthens the divisor and LOWERS the payment) IS a modification and the §72(t)(4)/§72(q)(3) recapture on every prior payment plus interest is owed; §3.01(a) otherwise requires that 'the same life expectancy tables continue to be used' (Notice 2022-6 Section 4, naming both §72(t)(4) and §72(q)(3) by number). This engine does NOT let you affirm through a plan-to-plan transfer/rollover (§72(t)(4)(C)) or a §1035 exchange (§72(q)(3)(B)) even though both are real, SECURE-2.0-added safe harbors (Pub. L. 117-328 §323, effective for transfers/exchanges after 2023-12-31) — the engine cannot verify their own precondition (combined distributions across the old and new plan/contract still satisfying the SEPP schedule), so it declines those cases on purpose (over-tax-safe). This engine does not compute the recapture tax or its interest — it only gates on whether the current distribution is a modification-year distribution. Absent → the distribution declines (pension_needs_review). An explicit false is OUT OF CONTRACT on the wire (enum is [true]) but is handled defensively: supplying false asserts that a series WAS modified, so it declines with its own distinct reason REGARDLESS of the distribution amount, including zero — because ceasing a series is itself a modification unless the account was exhausted (Notice 2022-6 §3.03(a)). Do not supply false as a default for an unchecked box; omit the field instead.

qualifyingChildrenForCtcinteger
Number of qualifying children under 17 (valid SSN, dependent) for the Child Tax Credit — Schedule 8812 Part I (nonrefundable) AND Part II (the refundable ACTC — both modeled).

Number of qualifying children under 17 (valid SSN, dependent) for the Child Tax Credit — Schedule 8812 Part I (nonrefundable) AND Part II (the refundable ACTC — both modeled). The year's per-child amount ($2,000; $2,200 from 2025; a 2021 count declines), phased out 5% of AGI over $400k MFJ / $200k others (excess rounded up to the next $1,000), limited to tax liability. REQUIRES childTaxCreditChildrenQualifyAffirmed AND the filer-level ID affirmation (ctcActcFilerAndSpouseValidSsnAffirmed; before 2025 it or odcFilerAndSpouseValidTinAffirmed).

form8962Requiredboolean
Form 8962 (premium tax credit):

Form 8962 (premium tax credit): true when its instructions' Who Must File test is met, including advance payments on someone else's Form 1095-A for a member of this tax family. true computes Form 8962 from premiumTaxCredit (2020 and 2022-2025) and otherwise declines premium_tax_credit_needs_review; false means no Form 8962. Omitted: excess advance premium tax credit repayment is not added (an under-tax).

premiumTaxCreditobject
Form 8962 Parts I-III for one Form 1095-A, 2020 and 2022-2025 only (federal only).

Form 8962 Parts I-III for one Form 1095-A, 2020 and 2022-2025 only (federal only). Each amount is entered as the Form 8962 instructions for the return's tax year direct for its line or column, in whole cents; line 2a is figured from this return (Worksheet 1-1). Requires form8962Required:true, taxExemptInterest, socialSecurityBenefits and noForeignOrTerritoryExclusionAffirmed:true; a dependent filer or medicalExpenses above 0 declines.

childTaxCreditChildrenQualifyAffirmedtrue
§6694 affirmation REQUIRED for a positive qualifyingChildrenForCtc:

§6694 affirmation REQUIRED for a positive qualifyingChildrenForCtc: attests EVERY child is under 17 at year-end, has a valid SSN (valid for employment, issued BEFORE the due date including extensions), is your dependent, a US citizen/national/resident, lived with you > half the year, and did not provide > half their own support. Absent → declines (child_tax_credit_needs_review). Covers the CHILD's own eligibility only — see ctcActcFilerAndSpouseValidSsnAffirmed for the separate filer-level SSN requirement.

ctcActcFilerAndSpouseValidSsnAffirmedtrue
§6694 affirmation REQUIRED for a positive qualifyingChildrenForCtc (from 2025):

§6694 affirmation REQUIRED for a positive qualifyingChildrenForCtc (from 2025): attests the filer (on a joint return, at least one spouse) has a valid SSN (valid for employment, issued BEFORE the due date including extensions), and on a joint return the other spouse has at minimum an SSN or ITIN issued ON OR BEFORE the due date (including extensions). Before 2025 it or odcFilerAndSpouseValidTinAffirmed meets the filer rule, and without either the CTC declines (child_tax_credit_needs_review).

federalPublicBenefitAffirmedboolean
§6694 affirmation: the return does not answer No on Schedule 3-A (Form 1040) line 7 or line 8, and where its line 6 is above zero it answers Yes to both: on the date the first return claiming the…

§6694 affirmation: the return does not answer No on Schedule 3-A (Form 1040) line 7 or line 8, and where its line 6 is above zero it answers Yes to both: on the date the first return claiming the child tax credit or the credit for other dependents for the year is filed, the filer (on a joint return, the filer or the spouse, and on any other return, the filer alone) is a U.S. citizen, U.S. national, or qualified alien (8 U.S.C. 1641(b)) and so declares under penalty of perjury; read only when year >= 2026 and additionalChildTaxCredit > 0: false declines child_tax_credit_needs_review, and omitted computes as if true, flagged VERIFY.

otherDependentsForOdcinteger
Number of other dependents for the $500 Credit for Other Dependents (ODC) — Schedule 8812 Part I.

Number of other dependents for the $500 Credit for Other Dependents (ODC) — Schedule 8812 Part I. Dependents who are NOT CTC-qualifying children. Same MAGI phase-out; a 2021 count declines. REQUIRES otherDependentsQualifyForOdcAffirmed AND odcFilerAndSpouseValidTinAffirmed.

otherDependentsQualifyForOdcAffirmedtrue
§6694 affirmation REQUIRED for a positive otherDependentsForOdc:

§6694 affirmation REQUIRED for a positive otherDependentsForOdc: attests each is your dependent, a US citizen/national/resident with an SSN, ITIN, or ATIN issued ON OR BEFORE the due date (including extensions), and is NOT also a CTC qualifying child. Absent → declines (child_tax_credit_needs_review). Covers the DEPENDENT's own eligibility only — see odcFilerAndSpouseValidTinAffirmed for the separate filer-level TIN requirement.

odcFilerAndSpouseValidTinAffirmedtrue
§6694 affirmation REQUIRED for a positive otherDependentsForOdc:

§6694 affirmation REQUIRED for a positive otherDependentsForOdc: attests the FILER (and spouse, if married_filing_jointly) has an SSN or ITIN issued ON OR BEFORE the due date (including extensions), which before 2025 is also the CTC/ACTC filer rule. false declines any CTC or ODC, and absent declines the ODC (child_tax_credit_needs_review).

socialSecurityBenefitsnumber
SSA-1099 box 5 — net Social Security benefits, box 3 less box 4 (≥0;

SSA-1099 box 5 — net Social Security benefits, box 3 less box 4 (≥0; a negative repayment is schema-rejected). The TAXABLE portion (1040 line 6b) is COMPUTED via the §86 worksheet (0/50/85% tiers by provisional income = other AGI + tax-exempt interest + ½ benefits; base $25k single/$32k MFJ/$0 MFS-lived-with-spouse, adjusted $34k/$44k). ORDINARY income → AGI + ordinary tax ONLY (NOT NIIT, NOT Additional Medicare). REQUIRES socialSecurityStandardCaseAffirmed:true AND taxExemptInterest supplied AND (for MFS) socialSecurityMfsLivedWithSpouse; §86(e) lump-sum / foreign / railroad RRB-1099 → social_security_needs_review decline. CA/NY fully EXCLUDE the taxable SS on the state return (Schedule CA (540) line 6 col B / IT-201 line 27).

taxExemptInterestnumber
1040 line 2a — tax-exempt interest.

1040 line 2a — tax-exempt interest. NOT taxable / NOT in AGI, but ADDED to the §86 Social Security provisional-income calc. REQUIRED whenever socialSecurityBenefits is present (undefined ≠ zero → decline, because omitting it understates provisional income and UNDER-taxes the benefits; an explicit 0 affirms no tax-exempt interest). A POSITIVE value ALSO requires taxExemptInterestNoPrivateActivityBonds:true (line 2a may include private-activity-bond interest — a positive AMT preference the engine does not model, so a positive amount without the no-PAB affirmation declines).

socialSecurityStandardCaseAffirmedtrue
§6694 affirmation REQUIRED for a positive socialSecurityBenefits:

§6694 affirmation REQUIRED for a positive socialSecurityBenefits: attests box 5 is a STANDARD current-year SSA-1099 net, NOT a §86(e) lump-sum election, NOT foreign/totalization benefits, NOT railroad RRB-1099 Tier-1, and no one on the return excludes income under §911, §931 or §933, savings-bond interest under §135 (Form 8815), adoption benefits under §137 or 2020 unemployment compensation under §85(c), which §86(b)(2)(A) adds back. Absent → the benefits decline (social_security_needs_review).

socialSecurityMfsLivedWithSpouseboolean
REQUIRED for a married_filing_separately filer with Social Security:

REQUIRED for a married_filing_separately filer with Social Security: true if the filer lived with their spouse any time during the year (→ §86 base $0, up to 85% taxable from the first dollar), false if lived apart all year (→ treated like single). Absent for MFS+SS → decline (the engine cannot infer it and would under-tax a lived-with-spouse filer).

canBeClaimedAsDependentbooleanrequired
true when another taxpayer can claim this filer as a dependent.

true when another taxpayer can claim this filer as a dependent. The standard deduction is then the greater of the year's floor ($1,350 for 2025-2026) or earned income (wages + Schedule C − half SE tax) plus the year's add-on ($450 for 2024-2026), never above the regular amount (§63(c)(5)). Declines (dependent_filer_needs_review) when the sum of every income line other than wages and Schedule C (losses as $0) and Schedule C net of half SE tax exceeds twice the floor (the kiddie tax, Form 8615, is not computed), with qualifyingChildrenForCtc or otherDependentsForOdc, with a positive scheduleCIncome lacking scheduleCPersonalServicesCapitalNotMaterialAffirmed, or on a joint or head-of-household return. Required: a missing value fails validation.

noForeignOrTerritoryExclusionAffirmedbooleanrequired
§6694 affirmation: no one on the return (the filer, and on a joint return either spouse) files Form 2555 for the year or excludes income under §931 (Form 4563) or §933 (Puerto Rico); false declines…

§6694 affirmation: no one on the return (the filer, and on a joint return either spouse) files Form 2555 for the year or excludes income under §931 (Form 4563) or §933 (Puerto Rico); false declines (out_of_scope_income): excluded income has no input.

filerAge65OrOlderboolean
true when the filer is 65 or older at year end (born before January 2 of year − 64;

true when the filer is 65 or older at year end (born before January 2 of year − 64; a decedent counts only if 65 at death). Adds the year's §63(f) amount ($2,000 single/HoH, $1,600 married, in 2025) to the standard deduction. Absent means false (an over-tax).

filerBlindbooleantrue when the filer is blind under §63(f)(4) at year end. Adds the §63(f) amount, like filerAge65OrOlder.
spouseAge65OrOlderbooleanThe filerAge65OrOlder test, for the spouse. true needs a married status (else a 400); it adds the §63(f) amount on a joint return and is not applied on MFS (flagged).
spouseBlindbooleanAs spouseAge65OrOlder, for a spouse blind under §63(f)(4).
spouseItemizesDeductions"yes" | "no" | "unknown"Required on married_filing_separately (else a 400) and only there. Whether the other spouse itemizes: yes makes the standard deduction $0 (§63(c)(6)(A)); no applies it; unknown declines (itemized_deduction_needs_review).
seniorDeductionEligibilityAffirmedboolean
2025-2028 senior deduction ($6,000 per person 65+ on filerAge65OrOlder / joint spouseAge65OrOlder, less 6% of MAGI over $75,000, $150,000 joint).

2025-2028 senior deduction ($6,000 per person 65+ on filerAge65OrOlder / joint spouseAge65OrOlder, less 6% of MAGI over $75,000, $150,000 joint). Attests each has an SSN valid for employment and was 65 before year end (a decedent only if 65 at death), and that no one on the return (the filer, and on a joint return either spouse, 65 or not) excludes income under §911/931/933. Absent: not taken (flagged, an over-tax). Never on MFS; not for a dependent filer (flagged).

taxExemptInterestNoPrivateActivityBondstrue
§6694 affirmation REQUIRED for a positive taxExemptInterest:

§6694 affirmation REQUIRED for a positive taxExemptInterest: attests NONE of it is specified private-activity-bond interest (Form 6251 line 2g), a positive AMT preference. The engine does not route tax-exempt interest into the AMT computation, so an unaffirmed positive amount could under-state AMT → declines (social_security_needs_review). An explicit taxExemptInterest:0 needs no affirmation.

estateTrustK1NoAmtAdjustmentAffirmedtrue
§6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest.

§6694 affirmation (Form 6251 line 2j), REQUIRED whenever the return carries taxableInterest, ordinaryDividends, qualifiedDividends, scheduleEIncome or any Schedule D input (presence, even $0) or a positive taxExemptInterest. WHAT `true` ATTESTS: no Schedule K-1 (Form 1041) received for this tax year, from any estate or trust, shows a positive amount in box 12 code A (adjustment for minimum tax purposes, Form 6251 line 2j) or any amount, positive or negative, in box 12 codes B through I. Attest true if no such K-1 was received, or if every code A amount is zero or negative and codes B through I are blank on all of them (a negative code A left out over-states the tax). The engine sets line 2j to $0. Absent or false with any of those inputs: the return declines (estate_trust_amt_adjustment_unmodeled); true with none of them: declined as an orphan; false always declines (a preparer completes Form 6251). Never default it. Not detected: a K-1 with a code A or B-I amount but no income boxes, on a return with none of those inputs.

k1sarray of object
Schedule K-1 (Form 1041) from an estate or trust (federal only;

Schedule K-1 (Form 1041) from an estate or trust (federal only; the state endpoint rejects it). Each K-1's boxes add to the matching return line: box 1 → taxableInterest (1040 line 2b), 2a → ordinaryDividends (3b), 2b → qualifiedDividends (3a), 3 → netShortTermCapGain (Schedule D line 5), 4a → netLongTermCapGain (Schedule D line 12). Do NOT also include these amounts in those scalar fields. The return then carries that income, so the attestations its presence requires (e.g. estateTrustK1NoAmtAdjustmentAffirmed; the Schedule D ones for box 3/4a) apply. Partnership and S-corporation K-1s are not accepted.

k1AmountsNotReportedElsewhereAffirmedtrue
§6694 affirmation REQUIRED when k1s is present:

§6694 affirmation REQUIRED when k1s is present: the K-1 amounts are not also included in any other income field (taxableInterest, ordinaryDividends, qualifiedDividends, netShortTermCapGain, netLongTermCapGain, capGainAggregates). A box 3 or 4a gain together with capGainAggregates declines. Absent declines; supplied without k1s declines as an orphan (k1_needs_review).

otherIncomePresentButUnmodeledarray of stringNames of income types on the return that this engine does not model; any entry declines (out_of_scope_income).

Example

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": 85000,
    "medicareWages": 85000,
    "federalWithholding": 9500
  }'
Response 200 · COMPUTED
{
  "computed": true,
  "year": 2025,
  "filingStatus": "single",
  "taxableIncome": 69250,
  "incomeTax": 10155,
  "totalTax": 10155,
  "lines": [
    { "lineId": "1040:15", "label": "Taxable income", "amount": 69250 },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 10155,
      "derivation": "<5 derivation steps — see full response>"
    },
    { "lineId": "1040:24", "label": "Total tax", "amount": 10155 }
  ],
  "flags": [
    "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
  ],
  "owedOrRefund": 655,
  "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": "single",
  "taxableIncome": 69250,
  "incomeTax": 10155,
  "totalTax": 10155,
  "lines": [
    {
      "lineId": "1040:15",
      "label": "Taxable income",
      "amount": 69250,
      "derivation": []
    },
    {
      "lineId": "1040:16",
      "label": "Income tax",
      "amount": 10155,
      "derivation": [
        {
          "lineId": "1040:16",
          "label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
          "inputs": [
            { "name": "taxableIncome", "value": 69250 }
          ],
          "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 $69,250 → Tax Table band midpoint $69,275",
          "result": 0
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 10% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 11925 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2025/single",
              "value": "10% (up to $11,925)",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.1 × $11,925 = $1,192.5",
          "result": 1192.5
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 12% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 36550 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2025/single",
              "value": "12% (up to $48,475)",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.12 × $36,550 = $4,386",
          "result": 4386
        },
        {
          "lineId": "1040:16",
          "label": "Ordinary income tax — 22% bracket",
          "inputs": [
            { "name": "taxableIncomeInBracket", "value": 20800 }
          ],
          "rule": {
            "description": "marginal rate × taxable income falling within this bracket",
            "authority": "IRC §1(j)",
            "constantRef": {
              "table": "BRACKETS_BY_YEAR",
              "key": "2025/single",
              "value": "22% (up to $103,350)",
              "revProc": "Rev. Proc. 2024-40"
            }
          },
          "computation": "0.22 × $20,800 = $4,576",
          "result": 4576
        },
        {
          "lineId": "1040:16",
          "label": "Whole-dollar rounding — ordinary income tax",
          "inputs": [
            { "name": "unroundedOrdinaryTax", "value": 10155 }
          ],
          "rule": {
            "description": "round the ordinary income tax to whole dollars",
            "authority": "Form 1040 instructions — whole-dollar rounding"
          },
          "computation": "$10,155 − $10,154.5 = $0.5",
          "result": 0.5
        }
      ]
    },
    {
      "lineId": "1040:24",
      "label": "Total tax",
      "amount": 10155,
      "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": 655,
  "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."
  }
}

Responses

StatusMeaning
200Computed return (or an honest decline)
400Invalid body / JSON / failed validation
401Missing / unknown / revoked key (no enumeration)
403Account suspended — contact billing (distinct from 401: the key is valid)
409Idempotency-Key reused with a different body (`idempotency_key_reused`), or a concurrent in-flight duplicate (`idempotency_key_in_progress`). Retry; NOT billed.
429
Monthly quota exhausted (account-wide;

Monthly quota exhausted (account-wide; `quota_exceeded`, next_action `upgrade_plan_or_wait_next_period`, retry_safe false) or per-minute rate exceeded (`rate_limit_exceeded`, next_action `retry_after_backoff`, retry_safe true). Not billed.

500Sanitized server error computing the return
503Metering outage — fail-closed (the call is NOT silently served free)

The computed result's fields are listed on Responses & states; decline codes are on Declines & affirmations.

Discovery

GET /api/mcp/tax-compute/federal returns the supported years and an illustrative (not exhaustive) list of common fields. It needs a key and uses no quota. The fields above are the complete list.