IBKR Flex-Import einrichten

WheelTrading liest Ihre Trade-, Dividenden- und Konto-Bewegungs-Historie aus dem IBKR Flex Web Service. Das ist die offizielle End-of-Day- Quelle von Interactive Brokers (mit Commissions, realisiertem G/V, Kostenbasis, Quellensteuer und Spin-Offs).

Sie brauchen genau drei Werte aus Ihrem IBKR-Account, die einmalig in WheelTrading eingetragen werden:

Flex Token (1 Jahr gueltig)
Transactions-Query-ID (eine kombinierte Query - empfohlen)
(optional) zwei Einzel-Query-IDs (Trades + Dividenden) als Fallback

Alle drei Werte werden in WheelTrading verschluesselt gespeichert (Fernet/AES) und sind nur fuer den eigenen Account sichtbar. Anderen Usern (Multi-User-Betrieb) bleiben Ihre IDs verborgen - jeder User pflegt sein eigenes Tripel.

Empfehlung fuer neue User: Nur die Transactions-Query anlegen (Abschnitt 3). Die zwei Einzel-Querys sind seit Mai 2026 nicht mehr noetig - die kombinierte Query liefert alles und halbiert die IBKR-Aufrufe.

1. Flex Web Service in IBKR aktivieren

Loggen Sie sich in Account Management (Lynx-/IBKR-Portal) ein.
Reporting -> Settings -> Flex Web Service oeffnen.
Klick auf "Configure" -> Service aktivieren.
IBKR zeigt Ihnen einen langen alphanumerischen Flex Token an.

Diesen kopieren - er ist nur einmal sichtbar.

In WheelTrading: Einstellungen -> Globals -> API-Keys ->

IBKR Flex Token -> einfuegen und Speichern.

Token-Gueltigkeit: 1 Jahr. WheelTrading warnt 14 Tage vor Ablauf per Banner; einfach in IBKR einen neuen Token erzeugen und in den Globals ersetzen.

2. Transactions-Query in IBKR anlegen

Reporting -> Custom Statements -> Flex Queries -> Create -> Activity Flex Query.

Name: beliebig, z.B. WheelTrading Transactions. Period: Last 365 Calendar Days (empfohlen) oder Year To Date. Format: XML, Version: 3.

Sections (Abschnitte) - bitte alle haken

In der deutschen IBKR-Maske heisst die Auswahl "Abschnitte (Bitte mehrere auswaehlen)". Setzen Sie folgende Haken:

Pflicht:

Trades
Bartransaktionen *(= Cash Transactions: Dividenden, Quellensteuer,

Ein-/Auszahlungen, Zinsen)*

Cash-Bericht (= Cash Report, Salden je Waehrung)
Provisionsdetails (= Commission Details, einzelne Fees)
Transaktionsgebuehren (= Transaction Tax, SEC- / Stempelfees)
Zinsdetails (Staffelung) (= Interest Accruals)
Forex-G&V-Details (= FX Transactions, USD<->EUR-Konvertierungen)

Stark empfohlen (Steuer-Vollstaendigkeit):

Kapitalmassnahmen *(= Corporate Actions, Spin-Offs etc. - Pflicht fuer

korrekte Kostenbasis bei VSNT, WBD, T-Mobile usw.)*

Veraenderung der aufgelaufenen Dividenden
Offene aufgelaufene Dividenden
Umsatzsteuer-Details

Brauchen Sie NICHT (nur Rauschen): Aufgelaufene Zinsen, IBSS, IBG-Notes, FDIC, HK IPO, CFD-Gebuehren, Debit-Card, Leihgebuehren, Fremdwaehrungssalden, Bezugsrechte.

Felder

Pro Section bietet IBKR detaillierte Feld-Listen an. Der einfachste Weg ist, in jeder gehakten Section auf "All" zu klicken (oder das oberste Haken-Symbol). WheelTrading nutzt aktuell folgende Pflichtfelder:

Section	Pflichtfelder
Trades	`tradeID`, `ibExecID`, `assetCategory`, `symbol`, `underlyingSymbol`, `currency`, `buySell`, `quantity`, `tradePrice`, `tradeDate`, `dateTime`, `proceeds`, `ibCommission`, `taxes`, `netCash`, `fxRateToBase`, `accountId`, `conid`, `notes`, `openCloseIndicator`, `multiplier`, `putCall`, `strike`, `expiry`, `settleDateTarget`
Cash Transactions	`transactionID`, `type`, `description`, `amount`, `symbol`, `isin`, `currency`, `fxRateToBase`, `exDate`, `payDate`, `reportDate`, `accountId`, `conid`
Corporate Actions	`transactionID`, `type`, `description`, `symbol`, `underlyingSymbol`, `dateTime`, `quantity`, `proceeds`, `costBasis`, `fifoPnlRealized`, `fxRateToBase`, `assetCategory`, `multiplier`, `currency`
Commission Details	`tradeID`, `commission`, `currency`, `dateTime`

Mit "All" sind Sie auf der sicheren Seite. Fehlt ein Feld, ist das kein offensichtlicher Fehler im UI - aber Cost-Basis oder Steuerwerte koennen unvollstaendig sein.

Webhook-Feld

Das Feld "Webhook" auf der IBKR-Query-Seite leer lassen. WheelTrading nutzt das normale Pull-Verfahren (Polling alle 12 h); Webhooks sind ein Premium-Feature von IBKR und werden nicht unterstuetzt.

Speichern -> Query-ID notieren

Nach dem Speichern zeigt IBKR die Query-ID an (5- bis 7-stellige Zahl, z.B. 1532801).

3. Query-ID in WheelTrading eintragen

Einstellungen -> Globals -> API-Keys -> IBKR Flex Query-ID (Transactions) -> Query-ID einfuegen und Speichern.

Sobald gespeichert:

Der combined-flex-scheduler holt das XML zentral 2x taeglich

(Cron 06:30 + 18:30 UTC) und fuettert daraus parallel:

Trade-Historie + Cost-Basis (Steuer)
Dividenden + Quellensteuer
Corporate Actions (Spin-Off-Override fuer Kostenbasis 0)
Transaktionen / Cash-Bewegungen
Die zwei aelteren Einzel-Schedulers (Trades 06:15/18:15, Dividenden

06:00/18:00) ueberspringen Ihren User automatisch - kein Doppel-Call.

Bei jedem Lauf zeigt das Globals-Panel: Letzter Sync (mit Alter),

Ergebnis-Badge (+3 neu, 12 bekannt gruen / rot bei Fehler).

Tipp: Direkt nach dem ersten Eintragen den manuellen Import-Button (Globals -> IBKR-Datenimport -> "Trade-Historie importieren") druecken, damit Sie nicht auf den naechsten Cron-Tick warten muessen.

4. Multi-User-Hinweise

Jeder User pflegt sein eigenes Tripel (Token + Query-ID).
Ihre IDs werden niemals anderen Usern angezeigt oder geteilt.
Wenn Sie ein Familien-/Joint-Konto mit mehreren Login-Usern haben,

legen Sie pro WheelTrading-User einen eigenen IBKR-Sub-Account an und je Sub-Account eine eigene Query - sonst sehen alle dieselben Trades.

Der combined-flex-scheduler iteriert pro Sync-Tick alle aktiven User

sequentiell mit 2-3 Sekunden Abstand, um IBKRs 15-Minuten-Rate-Limit (Fehler 1018 Too many requests) zu schonen.

Bei 1018 wiederholt der Scheduler den Aufruf automatisch mit

exponentiellem Backoff (max. 3 Versuche).

5. Optional: getrennte Trades- und Dividenden-Querys (Legacy)

Wenn Sie die kombinierte Transactions-Query nicht nutzen wollen (z.B. weil Ihr IBKR-Plan keine grossen Querys erlaubt), koennen Sie wie frueher zwei einzelne Querys anlegen:

`WheelTrading Trades` (Trade Confirmation Flex Query, nur Section

Trades) -> Query-ID in IBKR Flex Query-ID (Trades)

`WheelTrading Dividends` (Activity Flex Query, nur Section

Cash Transactions) -> Query-ID in IBKR Flex Query-ID (Dividenden)

Sobald die Transactions-Query-ID gesetzt ist, ueberschreibt sie diese zwei Felder fuer den Auto-Sync. Die manuellen Import-Buttons nutzen weiter die jeweilige Einzel-Query, falls vorhanden.

6. Was passiert nach dem Import?

Historie: Alle Trades sichtbar unter Trades -> Historie.
Cost-Basis: Automatisch berechnet aus BUY / SELL / Assignment +

Premium-Adjustment der Wheel-Strategie.

Spin-Offs: Aktien aus Corporate Actions vom Typ SO bekommen

automatisch cost_basis = 0 (§ 20 Abs. 4a EStG); voller Erloes beim Verkauf wird als Gewinn ausgewiesen. Marker: "Spin-Off-Lot (Kostenbasis 0)" in der Description.

Steuern: Quellensteuer wird auf 15 % DBA-Satz gekappt und im Tab

Steuern -> Dividenden ausgewiesen.

Transaktionen (in Vorbereitung): Die kombinierte Query liefert

bereits alle Daten; die UI-Seite folgt.

Idempotent: Bekannte Eintraege werden als skipped gezaehlt; den Import koennen Sie beliebig oft wiederholen.

7. Haeufige Fehler

`Code 1001: Statement could not be generated`

IBKR-Server ist gerade beschaeftigt, oder die Query wurde frisch angelegt und muss noch registriert werden (5-15 Minuten). WheelTrading retried das automatisch auf zwei Ebenen:

Flex-Client: 4 Versuche innerhalb von ~100 Sekunden (linearer

Backoff 10 s, 20 s, 30 s, 40 s).

Scheduler: falls der Client aufgibt, wartet der Scheduler

noch bis zu 2x weitere Runden mit 180 s + 360 s Backoff. Zusammen also bis zu ~10 Minuten pro Tick.

Wenn es danach immer noch fehlt: Query in IBKR Account Management oeffnen, Period auf Last 365 Calendar Days setzen, speichern (auch ohne Aenderung) und warten. Der naechste Auto-Tick greift dann. Manuell sofort testen: Button "Jetzt" auf der Performance-Seite oder unter Konto -> Globals.

`Code 1018: Too many requests`

15-Minuten-Rate-Limit getroffen (z.B. weil Sie zusaetzlich manuell importiert haben). Wird automatisch als transient behandelt und vom Scheduler-Retry mit abgefangen. Einfach 15 Min warten oder auf den naechsten Auto-Tick warten.

Token expired

Flex-Tokens sind 1 Jahr gueltig. Neuen Token in IBKR erzeugen, in Globals ersetzen. Wird NICHT retried (kein transientes Problem).

Query liefert 0 Trades

Period falsch (z.B. Today statt Last 365 Days) oder Section Trades nicht angehakt.

Spin-Off-Aktie hat negativen G/V im Steuertab

Section Kapitalmassnahmen fehlt in der Query. Edit in IBKR -> ergaenzen -> in WheelTrading manuellen Import erneut druecken.

`Code 1019: Statement generation in progress`

IBKR ist gerade dabei, die Daten zu erstellen. Scheduler wartet automatisch ab; bei manuellen Imports einfach 30 s spaeter erneut.

8. Automatischer Sync, Retry & Pause

WheelTrading holt Ihre Flex-Daten in mehreren Ebenen ab, damit Sie sich um transiente IBKR-Aussetzer nicht selbst kuemmern muessen.

Zwei feste Auto-Termine pro Tag

Trades: 06:15 + 18:15 UTC
Dividenden: 06:00 + 18:00 UTC
Combined-Query (falls Sie eine gepflegt haben): 06:30 + 18:30 UTC

(halbiert die IBKR-Quota-Last, ersetzt beide Einzel-Querys).

Manuell koennen Sie jederzeit ueber "Jetzt" einen Sofort-Import ausloesen.

Zwei-Ebenen-Retry

Jeder Auto-Tick versucht den Flex-Pull bis zu drei Mal in Reihe. Zwischen den Versuchen liegen 180 s und 360 s Wartezeit -- lang genug, damit IBKR eine kurze Delle typischerweise ueberwunden hat. Retried wird NUR bei transienten Fehler-Codes (1001, 1018, 1019, 1020). Ein abgelaufener Token oder eine geloeschte Query wird sofort gemeldet, da hilft Warten nicht.

Innerhalb jedes Versuchs retried der Flex-Client selbst nochmal 4x mit linearem Backoff (10/20/30/40 s). Insgesamt ergibt das bis zu ~10 Minuten pro Auto-Tick.

Circuit-Breaker: Auto-Pause nach wiederholten Fehlschlaegen

Wenn zwei aufeinanderfolgende Auto-Ticks trotz Retry scheitern, setzt WheelTrading den Sync automatisch fuer 6 Stunden auf Pause und schickt einmalig eine Telegram-Nachricht (sofern Sie das eingerichtet haben):

⏸️ Flex-Sync pausiert Der trades-Import ist nach 2 aufeinanderfolgenden Fehl-Laeufen automatisch pausiert. Naechster Versuch fruehestens: 15.07.2026 22:00 UTC

Zweck: nicht sinnlos gegen ein bekanntes IBKR-Problem laufen und keine Rate-Limits verbraten. Solange die Pause aktiv ist, skippt jeder planmaessige Tick lautlos.

Sie sehen die Pause an zwei Stellen im Frontend:

Performance-Seite (Header): der gelbe Banner zeigt zusaetzlich

"| Auto-Sync pausiert bis HH:MM".

Konto -> Globals -> Auto-Sync: ein oranger Hinweiskasten oberhalb

der Trades/Dividenden-Kacheln erklaert Ursache und naechsten Auto-Zeitpunkt.

Pause manuell aufheben

Ein Klick auf "Jetzt" (Performance-Header oder Globals-Panel) geht immer durch, auch waehrend einer aktiven Pause:

Der manuelle Endpoint startet einen frischen Flex-Pull (mit Retry).
Bei Erfolg werden Failure-Zaehler + Pause automatisch

zurueckgesetzt; der naechste Auto-Tick laeuft dann wieder normal.

Bei Misserfolg bleibt die Pause bestehen, aber Sie sehen die

aktuelle IBKR-Fehlermeldung sofort.