investsteuer

Deutsche Kapitalertrag- und Investmentbesteuerung als Bibliothek. Keine Abhängigkeiten, TypeScript-Typen inklusive, und an jeder Regel steht die Fundstelle.

English version

npm install investsteuer

Warum es das gibt

Die Regeln sind bekannt, aber sie werden fast überall zu grob umgesetzt. Drei Beispiele, die in fast jedem selbstgebauten Rechner falsch sind:

• Kirchensteuer wird aufgeschlagen statt eingerechnet. Wer kirchensteuerpflichtig ist, zahlt nicht 25 % plus Kirchensteuer, sondern den ermäßigten Tarif nach § 32d Abs. 1 Satz 4 EStG: (e − 4q) / (4 + k). Bei 9 % Kirchensteuer sind das 24,45 % statt 25 % — die naive Rechnung liegt rund 0,6 Prozentpunkte zu hoch.
• Die Vorabpauschale wird ohne ihre beiden Begrenzungen gerechnet. Der Basisertrag ist auf die Wertsteigerung des Jahres gedeckelt (§ 18 Abs. 1 Satz 3 InvStG), und im Erwerbsjahr fällt pro vollem Monat vor dem Kauf ein Zwölftel weg (§ 18 Abs. 4). Ohne beides kommt bei einem Fonds im Minus eine Steuer heraus, die es nicht gibt.
• Verluste landen in einem Topf. Es sind zwei, mit einer asymmetrischen Regel: Aktienverluste dürfen nur Aktiengewinne mindern, übrige Verluste zusätzlich auch Aktiengewinne — nie andersherum (§ 20 Abs. 6 EStG).

Diese Bibliothek macht es richtig und sagt jeweils dazu, warum.

Verwendung

Abgeltungsteuer inklusive Kirchensteuer und Teilfreistellung

import { computeCapitalGainsTax, CHURCH_TAX_RATES } from "investsteuer";

const ergebnis = computeCapitalGainsTax({
  grossIncome: 5_000,      // Bruttoertrag
  fundType: "equity",      // Aktienfonds → 30 % Teilfreistellung
  allowance: 1_000,        // freier Sparer-Pauschbetrag
  churchTaxRate: CHURCH_TAX_RATES.other, // 9 %
});

ergebnis.teilfreistellungAmount; // 1500
ergebnis.taxBase;                // 2500
ergebnis.totalTax;               // 699.88
ergebnis.effectiveRate;          // 0.1400

Die Reihenfolge ist gesetzlich vorgegeben und nicht beliebig: erst Teilfreistellung (§ 20 InvStG), dann Sparer-Pauschbetrag (§ 20 Abs. 9 EStG) auf den bereits gekürzten Betrag, dann der Tarif.

Vorabpauschale

import { computeVorabpauschale } from "investsteuer";

const ergebnis = computeVorabpauschale({
  yearStartValue: 30_000,  // Rücknahmepreis am ersten Handelstag
  yearEndValue: 33_000,    // am letzten Handelstag
  distributions: 0,        // thesaurierend
  fundType: "equity",
  allowance: 1_000,
  churchTaxRate: 0,
  purchaseMonth: 1,        // 1 = ganzjährig gehalten
  basiszins: 0.032,        // 2026
});

ergebnis.vorabpauschale;       // 672
ergebnis.cappedByValueGrowth;  // false
ergebnis.fundLostValue;        // false
ergebnis.tax.totalTax;         // 0 — Pauschbetrag deckt sie ab

Ein Fonds, der im Jahr an Wert verloren hat, liefert vorabpauschale: 0 — nicht weil es so bequem ist, sondern weil § 18 Abs. 3 InvStG es so vorsieht.

Basiszins-Historie

import { BASISZINS_HISTORY, basiszinsFor, LATEST_BASISZINS } from "investsteuer";

LATEST_BASISZINS;        // { year: 2026, rate: 0.032, bmfLetter: "2026-01-13" }
basiszinsFor(2021);      // { year: 2021, rate: -0.0045, noVorabpauschale: true, … }

Lückenlos ab 2018, jeder Jahrgang mit dem BMF-Schreiben, das ihn festgesetzt hat. 2021 und 2022 waren negativ — in beiden Jahren fiel gar keine Vorabpauschale an, weil ein negativer Basisertrag durch Ausschüttungen nicht unterschritten werden kann.

Verlustverrechnungstöpfe

import { computeLossPoolCarryforward } from "investsteuer";

const jahre = computeLossPoolCarryforward([
  { year: 2024, stockGains: 0, stockLosses: 1_000, generalGains: 1_000, generalLosses: 0 },
]);

jahre[0].generalTaxableGain; // 1000 — Aktienverluste helfen hier NICHT
jahre[0].stockCarryOut;      // 1000 — sie werden vorgetragen

Fundstellen

| Regel | Norm | |---|---| | Abgeltungsteuer 25 % | § 32d Abs. 1 Satz 1 EStG | | Ermäßigter Tarif bei Kirchensteuer | § 32d Abs. 1 Satz 4 EStG | | Sparer-Pauschbetrag 1.000 / 2.000 € | § 20 Abs. 9 EStG | | Teilfreistellung 30 / 15 / 60 / 80 % | § 20 InvStG | | Vorabpauschale, Deckelung, Zwölftelung | § 18 InvStG | | Basiszins | § 18 Abs. 4 InvStG, jährliches BMF-Schreiben | | Verlusttöpfe und Vortrag | § 20 Abs. 6 EStG |

Die Basiszins-Werte für 2025 und 2026 wurden direkt aus den BMF-Schreiben ausgelesen, die älteren Jahrgänge gegen die Fachpresse gegengeprüft.

Grenzen

Bewusst nicht abgebildet: anrechenbare ausländische Quellensteuer (das q in der Tarifformel), Betriebsvermögen und Körperschaften (dort gelten höhere Teilfreistellungssätze), Altbestände vor 2009, sowie alles, was eine individuelle Veranlagung betrifft.

Diese Bibliothek rechnet Regeln nach. Sie ist keine Steuerberatung, und sie kennt deinen Einzelfall nicht.

Mitwirken

Fehler in einer Regel oder eine fehlende Fundstelle sind die wertvollsten Meldungen — bitte als Issue mit Norm und, wenn möglich, einer Beispielrechnung.

Herkunft

Herausgelöst aus Planafolio, einem Portfolio-Tracker mit Altersvorsorge-Planung für deutsche Privatanleger. Dieselbe Logik steht dort hinter den Steuerrechnern. Die Basiszins-Reihe gibt es zusätzlich als offenen Datensatz.

MIT-Lizenz.