IBKR conId und Kontrakte: Instrumente eindeutig definieren.

Die IBKR conId ist die eindeutige Kontraktnummer, mit der Interactive Brokers jedes handelbare Instrument identifiziert. Wer Aktien, Futures, Optionen oder Devisen per API stabil ansprechen will, ermittelt die conId einmal mit reqContractDetails, prüft das Ergebnis und arbeitet danach mit conId plus Exchange. Das empfiehlt IBKR selbst, und es beugt den beiden typischen Problemen vor: dem Fehler 200 „No security definition has been found“ und, gefährlicher, einer Order auf das falsche Instrument. Dieser Leitfaden zeigt die nötigen Felder je Wertpapierart, die häufigsten Ursachen von Fehler 200, die wichtigen Felder aus ContractDetails wie tradingClass, Multiplier, Tick-Größe und Handelszeiten sowie ein Python-Beispiel mit ib_async, das Kontrakte vor dem ersten Handel prüft und als Stammdatensatz speichert. Stand Oktober 2026, geprüft an der TWS-API-Dokumentation einschließlich der am 08.10.2026 neu eingeführten Contract Reference.

Was ist die IBKR conId und warum ist sie besser als ein Symbol?

Jedes Instrument in der Datenbank von Interactive Brokers hat einen Contract Identifier, kurz conId. Das ist eine ganze Zahl, die genau einen Kontrakt an genau einem Listing beschreibt. Ein Tickersymbol leistet das nicht: „SAP“ gibt es an mehreren Börsen und in mehreren Währungen, „ES“ steht für viele Futures-Verfälle, und dieselbe Optionsserie existiert mit unterschiedlichen Strikes und Rechten. Die TWS API akzeptiert deshalb zwar eine Beschreibung aus Symbol, Wertpapierart (SecType), Börse (Exchange) und Währung (Currency), IBKR rät in der Contract Reference aber ausdrücklich dazu, conId und Exchange zu verwenden. Diese beiden Werte definieren einen Kontrakt vollständig.

Die conId ist laut IBKR statisch und ändert sich nicht. Das Beispiel aus der Doku: Apple an der NASDAQ hat die conId 265598 und behält sie, solange die Aktie nicht delistet wird oder das Unternehmen nicht mehr börsennotiert ist. Für einen Bot heißt das: Die conId eignet sich als Primärschlüssel für Positionen, Orders, Marktdaten und historische Kurse. Ein Symbol eignet sich dafür nicht, weil es sich bei Umbenennungen ändern kann und mehrdeutig ist. Wie man Namen, Ticker und Kennungen über mehrere Datenquellen hinweg zusammenführt, beschreibt der Artikel Entity-Resolution und Ticker-Mapping; hier geht es um den IBKR-spezifischen Teil.

Zwei Sonderfälle sollten Sie kennen. Bei Kryptowährungen hängt die conId vom Listing ab: Bitcoin bei PAXOS hat laut IBKR die conId 479624278, bei Zerohash 541686651. Und wenn ein Wert nicht mehr gelistet ist, kann die Position auf der Börse „VALUE“ geführt werden. Das ist eine reine Haltebörse, über die bestehende Positionen geschlossen, aber keine neuen eröffnet werden können. Ein Bot, der plötzlich VALUE als Exchange sieht, sollte deshalb keine Order senden, sondern einen Menschen informieren.

Welche Felder braucht ein IBKR-Kontrakt je Wertpapierart?

Die Contract Reference vom 08.10.2026 beschreibt die Contract-Struktur je Wertpapierart. Die folgende Tabelle fasst die dort genannten Felder für die häufigsten Fälle zusammen. Für Aktien ist SMART als Exchange zulässig; dann sucht das Smart Routing von IBKR den Ausführungsplatz. Die Primärbörse (in Python primaryExchange, in der Objektreferenz primaryExch) ist die Heimatbörse des Werts und laut IBKR für alle Aktien gute Praxis.

Zwei Formatdetails sorgen besonders oft für Fehler. Erstens lastTradeDateOrContractMonth: Ein Wert im Format YYYYMM wird als Kontraktmonat gelesen, ein Wert im Format YYYYMMDD als letzter Handelstag. Die Futures-Beispiele der Contract Reference arbeiten mit dem Monat; bei Optionen und Futures-Optionen mit mehreren Verfällen im selben Monat verlangt IBKR das exakte Datum. Zweitens die Wertpapiererkennung über Kennnummern: Die API akzeptiert secIdType mit ISIN, CUSIP oder FIGI und secId mit dem Wert, als Exchange dann SMART. Das ist praktisch, wenn Ihre Daten aus einem Depotauszug oder einer Fondsliste kommen, ersetzt aber nicht die Prüfung des Ergebnisses.

Für Futures gibt es zusätzlich die Wertpapierart CONTFUT (Continuous Futures). Sie liefert eine fortlaufende Reihe des jeweils vorderen Kontrakts, ist laut IBKR aber nur für historische Daten zulässig, nicht für Orders, nicht für Live-Daten und nicht in der Web API. Abgelaufene Futures lassen sich mit includeExpired für historische Daten der letzten zwei Jahre abrufen, abgelaufene Optionen dagegen nicht.

IBKR-Fehler 200 „No security definition“ beheben.

Fehler 200 lautet „No security definition has been found for the request“. Laut IBKR passt die Beschreibung dann zu keinem Kontrakt in der Datenbank, meist wegen eines falschen oder fehlenden Parameters. Unter demselben Code meldet die API aber auch den zweiten Fall: Die Beschreibung ist mehrdeutig, weil mehrere Kontrakte passen. Beide Fälle haben unterschiedliche Lösungen, und ein Bot sollte sie unterscheiden.

Häufige Ursachen in der Praxis:

• Falsche Börse oder Währung: Ein deutscher Wert wird mit USD angefragt oder ein US-Future an der falschen Börse. IBKR weist darauf hin, dass eine Anfrage mit Currency USD nur US-Kontrakte liefert, auch wenn es Nicht-US-Instrumente in USD gibt.
• Fehlende Primärbörse: Für manche Aktien mit gleichem Symbol, gleicher Währung und gleicher Exchange verlangt IBKR die Primärbörse, sonst ist die Beschreibung mehrdeutig.
• Fehlender Multiplier: Für Futures mit mehreren Multiplikatoren zum selben Verfall muss das Feld multiplier gesetzt sein.
• Abgelaufener oder falscher Verfall: Ein Datum im falschen Format oder ein Monat, der nicht gelistet ist. Abgelaufene Futures findet die API nur mit includeExpired, handeln lassen sie sich nicht.
• Abweichende Symbolik: Das Symbol bei IBKR muss nicht dem Kürzel entsprechen, das Sie aus anderen Datenquellen kennen. Das Symbol an der Primärbörse steht im Feld localSymbol, bei Optionen ist das das OCC-Symbol.

Die schnellste Diagnose ist manuell: In der TWS (Trader Workstation) den Wert per Rechtsklick über „Financial Instrument Info“ und „Description“ oder „Details“ öffnen. Dort stehen conId, Symbol, Handelsklasse, Multiplier und Börsen so, wie die API sie erwartet. Für Aktien hilft außerdem reqMatchingSymbols, das zu einem Tickeranfang oder Firmennamen bis zu 16 passende Werte liefert; zwischen zwei Aufrufen muss laut IBKR mindestens eine Sekunde liegen. Für die Fehlerbehandlung im Bot gilt: Fehler 200 ist kein Verbindungsproblem und wird durch Wiederholen nicht besser.

Kontrakte mit reqContractDetails in Python prüfen.

reqContractDetails nimmt einen Contract als Vorlage und liefert alle passenden Kontrakte einzeln zurück, abgeschlossen durch contractDetailsEnd. Im Gegensatz zu den meisten API-Funktionen darf die Vorlage also unvollständig sein. Genau das macht die Funktion zum passenden Prüfschritt: Liefert sie keinen Treffer, ist die Beschreibung falsch. Liefert sie mehrere, muss der Bot anhand von Erwartungswerten auswählen oder abbrechen. Liefert sie genau einen, übernimmt der Bot die conId und die Stammdaten.

Für Aktien hat der Schritt einen Nebeneffekt: Laut IBKR cached TWS die Kontraktdaten intern, wenn reqContractDetails für eine Aktie mit Symbol, SecType, Exchange und Currency aufgerufen wird. Spätere Orders mit conId und Exchange nutzen diese Werte und werden schneller übertragen. Bei Derivaten ist Vorsicht geboten: Anfragen zu Optionen, Warrants und Futures-Optionen werden intern gedrosselt und sollten so vollständig wie möglich sein. Ganze Optionsketten fragt man besser über reqSecDefOptParams ab und nicht über unvollständige Vorlagen.

Das folgende Beispiel nutzt ib_async, den Community-Nachfolger von ib_insync, und das Beispiel des E-mini S&P 500 aus der IBKR-Doku mit Multiplier 50. Es löst einen Future auf, prüft Erwartungswerte, baut einen Stammsatz und kontrolliert später den Kontrakt nur über conId und Exchange. Grundlagen zu Verbindung, Client-ID und Event-Loop beschreibt der Artikel IB API mit Python in der Praxis.

# Nur gegen ein Paper-Konto testen; Port laut API-Einstellungen von TWS bzw. IB Gateway (hier 7497)
from ib_async import IB, Future, Contract

ib = IB()
ib.connect("127.0.0.1", 7497, clientId=21)

# 1) Vorlage mit Erwartungswerten (Beispiel E-mini S&P 500 aus der IBKR-Doku)
vorlage = Future(symbol="ES", lastTradeDateOrContractMonth="202612",
                 exchange="CME", currency="USD")
erwartet = {"multiplier": "50", "secType": "FUT"}

details = ib.reqContractDetails(vorlage)   # leere Liste = kein Treffer (Fehler 200)
treffer = [d for d in details
           if d.contract.multiplier == erwartet["multiplier"]
           and d.contract.secType == erwartet["secType"]]
if len(treffer) != 1:
    raise RuntimeError(f"{len(treffer)} Treffer statt 1 - Handel gesperrt")

d = treffer[0]
c = d.contract
stammsatz = {
    "conId": c.conId, "exchange": c.exchange, "currency": c.currency,
    "localSymbol": c.localSymbol, "tradingClass": c.tradingClass,
    "multiplier": c.multiplier, "lastTradeDate": c.lastTradeDateOrContractMonth,
    "minTick": d.minTick, "marketRuleIds": d.marketRuleIds,
    "minSize": str(d.minSize), "sizeIncrement": str(d.sizeIncrement),
    "timeZoneId": d.timeZoneId, "tradingHours": d.tradingHours,
}
print(stammsatz)

# 2) Später im Bot: nur noch conId + Exchange verwenden und gegenprüfen
pruef = Contract(conId=stammsatz["conId"], exchange=stammsatz["exchange"])
ok = ib.qualifyContracts(pruef)   # nicht auflösbar: leere Liste oder None
if not ok or ok[0] is None or pruef.multiplier != stammsatz["multiplier"]:
    raise RuntimeError("Kontrakt weicht vom Stammsatz ab - Handel gesperrt")

ib.disconnect()

Wichtig ist die Haltung dahinter: Der Bot vertraut nicht darauf, dass die Vorlage eindeutig ist, sondern verlangt genau einen Treffer mit den erwarteten Eigenschaften. Weicht etwas ab, wird nicht gehandelt. Mit der offiziellen ibapi funktioniert dasselbe über die Callbacks contractDetails und contractDetailsEnd; der Ablauf bleibt gleich.

Wichtige Felder: tradingClass, Multiplier, Tick-Größe, Handelszeiten.

ContractDetails und der darin enthaltene Contract liefern deutlich mehr als die conId. Für einen Bot sind vor allem diese Felder relevant:

• tradingClass: die Handelsklasse, wie sie auch im Beschreibungsfenster der TWS steht. IBKR nennt als Beispiel „FGBL“ für den Bund-Future. Bei Optionen und Futures-Optionen führt IBKR die Handelsklasse als mögliches Zusatzfeld, wenn die übrigen Angaben einen Kontrakt nicht eindeutig machen.
• multiplier: der Faktor zwischen Preis und Geldwert. Er bestimmt, wie viel ein Punkt Bewegung je Kontrakt wert ist, und ist die Grundlage jeder Positionsgrößenberechnung.
• minTick und marketRuleIds: minTick zeigt nur die kleinste mögliche Tick-Größe. Viele Werte haben preisabhängige Ticks; die vollständige Regel liefert reqMarketRule mit der Market-Rule-ID, die je gültiger Börse in marketRuleIds steht. Preise, die nicht zum Tick passen, lehnt IBKR mit Fehler 110 ab.
• minSize, sizeIncrement, suggestedSizeIncrement: kleinste Ordergröße und erlaubte Schrittweite. Wer Stückzahlen berechnet, muss darauf runden.
• tradingHours, liquidHours, timeZoneId: Handelszeiten des aktuellen und des nächsten Tages, die regulären Handelszeiten und die Zeitzone. IBKR weist darauf hin, dass timeZoneId unverändert aus den Börsenplänen kommt und nicht immer der Anzeige in der TWS entspricht.
• validExchanges und orderTypes: zulässige Börsen und unterstützte Ordertypen für diesen Kontrakt.
• realExpirationDate, contractMonth, underConId, settlementMethod: tatsächlicher Verfall, Kontraktmonat, conId des Basiswerts und ob physisch oder bar abgerechnet wird (die Abrechnungsart laut Changelog ab TWS bzw. IB Gateway 10.49.01).

Ein typisches Beispiel für die Bedeutung des Multipliers: An der Eurex gibt es den DAX-Future in drei Größen, mit 25, 5 und 1 Euro je Indexpunkt. Eine Bewegung von 100 Punkten entspricht damit je Kontrakt 2.500, 500 oder 100 Euro. Wer die Größe verwechselt, hat das Fünf- oder Fünfundzwanzigfache des geplanten Risikos im Markt. Der Bot sollte deshalb nie nur Symbol und Verfall prüfen, sondern immer auch Multiplier und Handelsklasse gegen den eigenen Stammsatz.

Kontrakt-Stammdaten im Bot verwalten.

Ein stabiler Bot trennt die Strategie von der Kontraktauflösung. Die Strategie spricht von „Instrument X“, die Stammdatenschicht übersetzt das in eine geprüfte conId. Sinnvoll ist eine kleine Tabelle, etwa in SQLite oder Postgres, mit einem Datensatz je Kontrakt:

1. Schlüssel: conId und Exchange, dazu Ihre interne Instrument-ID.
2. Beschreibung: SecType, Symbol, localSymbol, tradingClass, Currency, primaryExchange, Verfall.
3. Handelsparameter: Multiplier, minTick, marketRuleIds, minSize, sizeIncrement, validExchanges.
4. Zeitplan: timeZoneId, tradingHours, liquidHours mit dem Datum der Abfrage.
5. Verwaltung: Zeitpunkt der letzten Prüfung, Status (aktiv, auslaufend, gesperrt) und wer den Eintrag freigegeben hat.

Die conId bleibt stabil, die übrigen Felder nicht unbedingt. Handelszeiten gelten laut ContractDetails nur für den aktuellen und den nächsten Tag, Feiertage und Sonderzeiten ändern sie. Deshalb lohnt ein täglicher Abgleich vor Handelsbeginn: Für jede aktive conId einmal reqContractDetails aufrufen, Abweichungen zum Stammsatz protokollieren und bei kritischen Feldern wie Multiplier oder Tick-Regel den Handel für dieses Instrument stoppen, bis ein Mensch geprüft hat. Bei Futures gehört der Rollwechsel dazu: Der neue Verfall bekommt eine neue conId, und der Wechsel sollte ein bewusster, protokollierter Schritt sein, kein stiller Austausch im Code.

Für Positionen gilt dasselbe Prinzip. Der Abgleich zwischen Bot und Broker sollte über die conId laufen, nicht über Symbole. Sonst kann eine Position in einem anderen Verfall oder an einer anderen Börse als „fehlend“ erscheinen, obwohl sie existiert, oder der Bot hält zwei Kontrakte für einen.

Grenzen und Risiken: falsches Instrument, falsche Größe.

Das größte Risiko ist nicht der Fehler 200, sondern sein Gegenteil: Die API findet einen Kontrakt, aber nicht den gemeinten. Eine Order läuft dann fehlerfrei durch, nur auf das falsche Instrument. Typische Verwechslungen sind die falsche Börse oder Währung bei Aktien, Mini statt Standard bei Futures, ein falscher Verfall, vertauschte Währungen bei Devisen und Put statt Call. Die Folgen reichen von unerwünschtem Währungsrisiko bis zu einer Position, die ein Vielfaches des geplanten Risikos trägt. Bei Futures und verkauften Optionen sind Verluste über den Einsatz hinaus möglich.

Weitere Grenzen, die Sie einplanen sollten:

• Stammdaten sind kein Freibrief: Auch eine geprüfte conId schützt nicht vor einem falsch berechneten Preis oder einer falschen Stückzahl. Positionslimits, Ordergrößenlimits und eine Plausibilitätsprüfung des Orderwerts gehören zusätzlich in den Bot.
• Verfall und Lieferung: Wer auslaufende Futures oder Optionen nicht rechtzeitig schließt oder rollt, riskiert Lieferung oder Ausübung. IBKR behält sich in seinen Richtlinien Schutzmaßnahmen bis zur Glattstellung auslaufender Positionen vor. Die Fristen sind produktspezifisch und auf der IBKR-Seite zu Lieferung und Ausübung nachzulesen.
• Doku im Wandel: IBKR hat die Dokumentation im Oktober 2026 umgebaut. Alte Deep-Links können ins Leere führen, und Felder oder Beispiele können sich mit neuen TWS-Versionen ändern. Prüfen Sie deshalb gegen die aktuelle Contract Reference und testen Sie jede Änderung im Paper-Konto.
• Kontoabhängigkeit: Ob Sie einen Kontrakt handeln dürfen, hängt von Kontotyp, Handelsberechtigungen und Region ab. ContractDetails kann dazu Gründe in ineligibilityReasonList liefern; eine gefundene conId heißt nicht, dass eine Order angenommen wird.

Ein automatisiertes System bleibt in Ihrer Verantwortung. Saubere Kontraktdefinitionen reduzieren Bedienfehler, sie machen eine Strategie weder profitabel noch risikofrei.

Was Sie jetzt konkret tun können.

1. Bestand prüfen: Suchen Sie im Code alle Stellen, an denen Kontrakte nur über Symbol und Börse entstehen, und ersetzen Sie sie durch einen Zugriff auf die Stammdatenschicht.
2. Erwartungswerte festlegen: Notieren Sie je Instrument conId, Exchange, Currency, Multiplier und Handelsklasse, abgelesen in der TWS unter „Financial Instrument Info“.
3. Prüfschritt einbauen: Beim Start und täglich vor Handelsbeginn reqContractDetails aufrufen, genau einen Treffer verlangen und Abweichungen als Handelssperre behandeln.
4. Tick- und Größenregeln anwenden: Preise über die Market Rule runden, Stückzahlen über minSize und sizeIncrement.
5. Im Paper-Konto testen: Fehler 200, mehrdeutige Treffer, einen Rollwechsel und einen falschen Multiplier bewusst provozieren und prüfen, ob der Bot korrekt stoppt.

Wenn Sie das nicht selbst bauen wollen: Marcel Gautsche entwickelt Python-Systeme für Interactive Brokers nach Ihren Vorgaben, testet sie mit echten Kosten und richtet auf Wunsch Betrieb und Monitoring auf einem VPS ein. Die Live-Aktivierung auf Ihrem Konto nehmen Sie selbst vor. Details stehen auf der Seite Trading-Automatisierung.

Häufige Fragen.

Wie finde ich die conId eines Wertpapiers bei Interactive Brokers?

Am einfachsten in der Trader Workstation: Rechtsklick auf den Wert, dann „Financial Instrument Info“ und „Description“ oder „Details“. Dort steht die conId zusammen mit Symbol, Börse und Handelsklasse. Per API liefert reqContractDetails die conId im zurückgegebenen Contract, für Aktien hilft zusätzlich reqMatchingSymbols bei der Suche nach Ticker oder Firmenname.

Was bedeutet IBKR Error 200 No security definition has been found?

Die Kontraktbeschreibung passt zu keinem Instrument in der IBKR-Datenbank, meist wegen eines falschen oder fehlenden Feldes wie Börse, Währung oder Verfall. Unter demselben Code meldet die API auch mehrdeutige Beschreibungen. Dann helfen zusätzliche Felder wie primaryExchange bei Aktien oder multiplier und tradingClass bei Futures. Wiederholen ohne Änderung löst das Problem nicht.

Ändert sich die conId bei Interactive Brokers?

Laut IBKR ist die conId statisch und ändert sich nicht, solange das Instrument gelistet bleibt. Apple an der NASDAQ hat zum Beispiel dauerhaft die conId 265598. Bei Futures und Optionen hat aber jeder Verfall eine eigene conId, und bei Kryptowährungen unterscheidet sie sich je Listing-Börse. Nach einem Rollwechsel braucht der Bot also eine neue conId.

Was ist der Unterschied zwischen YYYYMM und YYYYMMDD bei lastTradeDateOrContractMonth?

Ein Wert mit sechs Ziffern im Format YYYYMM wird als Kontraktmonat gelesen, ein Wert mit acht Ziffern im Format YYYYMMDD als letzter Handelstag. Die Futures-Beispiele von IBKR nutzen das Monatsformat. Bei Optionen mit mehreren Verfällen im selben Monat verlangt IBKR das exakte Datum, sonst ist die Beschreibung mehrdeutig oder trifft den falschen Verfall.

Kann ich mit Continuous Futures bei IBKR handeln?

Nein. Der Typ CONTFUT ist laut IBKR-Dokumentation nur für historische Daten in der TWS API gedacht. Für Orders und Live-Daten müssen Sie den konkreten Verfall mit eigener conId verwenden. Auch das Enddatum der historischen Abfrage muss bei Continuous Futures leer bleiben, und in der Web API steht der Typ nicht zur Verfügung.

Quellen und Stand.

• Contract Reference: Introduction (Contract Identifier) — Interactive Brokers, TWS API Documentation
• Contract Reference: Futures (Continuous und Expired Futures) — Interactive Brokers, TWS API Documentation
• Request Contract Details — Interactive Brokers, TWS API Documentation
• Contract Details: Introduction — Interactive Brokers, TWS API Documentation
• Contract (Objektreferenz) — Interactive Brokers, TWS API Documentation
• ContractDetails (Objektreferenz) — Interactive Brokers, TWS API Documentation
• Error Codes — Interactive Brokers, TWS API Documentation
• TWS API Changelog, 08.10.2026 — Interactive Brokers

Stand: 22. Oktober 2026. Produkte, Funktionen und Preise ändern sich schnell; maßgeblich sind die Angaben der Anbieter und Behörden.

Sie wollen Ihren IBKR-Bot mit sauberer Kontraktverwaltung und Prüfschritten bauen lassen? Unverbindlich anfragen — wir klären Instrumente, Stammdaten, Kontrollmechanismen und den Testumfang im Paper-Konto. Mehr zu meinem Angebot: Trading-Systeme entwickeln lassen.