• C#
  • Java
  • VB
  • C++
  • Python
Contact us
Spreads

Spread contracts, also known as combos or combinations, combine two or more instruments. To define a combination contract it is required to know the conId of the IBApi.Contract in question. The conId of an instrument can easily be obtained via the IBApi.EClientSocket.reqContractDetails request.

The spread contract's symbol can be either the symbol of one of the contract legs or, for two-legged combinations the symbols of both legs separated by a comma as shown in the examples below.

Stock Spread

  • Contract contract = new Contract();
    contract.Symbol = "IBKR,MCD";
    contract.SecType = "BAG";
    contract.Currency = "USD";
    contract.Exchange = "SMART";
    ComboLeg leg1 = new ComboLeg();
    leg1.ConId = 43645865;//IBKR STK
    leg1.Ratio = 1;
    leg1.Action = "BUY";
    leg1.Exchange = "SMART";
    ComboLeg leg2 = new ComboLeg();
    leg2.ConId = 9408;//MCD STK
    leg2.Ratio = 1;
    leg2.Action = "SELL";
    leg2.Exchange = "SMART";
    contract.ComboLegs = new List<ComboLeg>();
    contract.ComboLegs.Add(leg1);
    contract.ComboLegs.Add(leg2);
  • Contract contract = new Contract();
    contract.symbol("MCD");
    contract.secType("BAG");
    contract.currency("USD");
    contract.exchange("SMART");
    ComboLeg leg1 = new ComboLeg();
    ComboLeg leg2 = new ComboLeg();
    List<ComboLeg> addAllLegs = new ArrayList<>();
    leg1.conid(43645865);//IBKR STK
    leg1.ratio(1);
    leg1.action("BUY");
    leg1.exchange("SMART");
    leg2.conid(9408);//MCD STK
    leg2.ratio(1);
    leg2.action("SELL");
    leg2.exchange("SMART");
    addAllLegs.add(leg1);
    addAllLegs.add(leg2);
    contract.comboLegs(addAllLegs);
  • Dim contract As Contract = New Contract
    contract.Symbol = "MCD"
    contract.SecType = "BAG"
    contract.Currency = "USD"
    contract.Exchange = "SMART"
    Dim leg1 As ComboLeg = New ComboLeg
    leg1.ConId = 43645865
    leg1.Ratio = 1
    leg1.Action = "BUY"
    leg1.Exchange = "SMART"
    Dim leg2 As ComboLeg = New ComboLeg
    leg2.ConId = 9408
    leg2.Ratio = 1
    leg2.Action = "SELL"
    leg2.Exchange = "SMART"
    contract.ComboLegs = New List(Of ComboLeg)
    contract.ComboLegs.Add(leg1)
    contract.ComboLegs.Add(leg2)
  • Contract contract;
    contract.symbol = "MCD";
    contract.secType = "BAG";
    contract.currency = "USD";
    contract.exchange = "SMART";
    ComboLegSPtr leg1(new ComboLeg);
    leg1->conId = 43645865;
    leg1->action = "BUY";
    leg1->ratio = 1;
    leg1->exchange = "SMART";
    ComboLegSPtr leg2(new ComboLeg);
    leg2->conId = 9408;
    leg2->action = "SELL";
    leg2->ratio = 1;
    leg2->exchange = "SMART";
    contract.comboLegs.reset(new Contract::ComboLegList());
    contract.comboLegs->push_back(leg1);
    contract.comboLegs->push_back(leg2);
  • 1  contract = Contract()
    2  contract.symbol = "IBKR,MCD"
    3  contract.secType = "BAG"
    4  contract.currency = "USD"
    5  contract.exchange = "SMART"
    6 
    7  leg1 = ComboLeg()
    8  leg1.conId = 43645865#IBKR STK
    9  leg1.ratio = 1
    10  leg1.action = "BUY"
    11  leg1.exchange = "SMART"
    12 
    13  leg2 = ComboLeg()
    14  leg2.conId = 9408#MCD STK
    15  leg2.ratio = 1
    16  leg2.action = "SELL"
    17  leg2.exchange = "SMART"
    18 
    19  contract.comboLegs = []
    20  contract.comboLegs.append(leg1)
    21  contract.comboLegs.append(leg2)

Note: EFPs are simply defined as a bag contract of stock and corresponding SSF with a ratio of 100:1.

Options Spread

  • Contract contract = new Contract();
    contract.Symbol = "DBK";
    contract.SecType = "BAG";
    contract.Currency = "EUR";
    contract.Exchange = "DTB";
    ComboLeg leg1 = new ComboLeg();
    leg1.ConId = 197397509;//DBK JUN 15 '18 C
    leg1.Ratio = 1;
    leg1.Action = "BUY";
    leg1.Exchange = "DTB";
    ComboLeg leg2 = new ComboLeg();
    leg2.ConId = 197397584;//DBK JUN 15 '18 P
    leg2.Ratio = 1;
    leg2.Action = "SELL";
    leg2.Exchange = "DTB";
    contract.ComboLegs = new List<ComboLeg>();
    contract.ComboLegs.Add(leg1);
    contract.ComboLegs.Add(leg2);
  • Contract contract = new Contract();
    contract.symbol("DBK");
    contract.secType("BAG");
    contract.currency("EUR");
    contract.exchange("DTB");
    ComboLeg leg1 = new ComboLeg();
    ComboLeg leg2 = new ComboLeg();
    List<ComboLeg> addAllLegs = new ArrayList<>();
    leg1.conid(197397509);//DBK JUN 15 '18 C
    leg1.ratio(1);
    leg1.action("BUY");
    leg1.exchange("DTB");
    leg2.conid(197397584);//DBK JUN 15 '18 P
    leg2.ratio(1);
    leg2.action("SELL");
    leg2.exchange("DTB");
    addAllLegs.add(leg1);
    addAllLegs.add(leg2);
    contract.comboLegs(addAllLegs);
  • Dim contract As Contract = New Contract
    contract.Symbol = "DBK"
    contract.SecType = "BAG"
    contract.Currency = "EUR"
    contract.Exchange = "DTB"
    Dim leg1 As ComboLeg = New ComboLeg
    leg1.ConId = 197397509 'DBK JUN 15 '18 C
    leg1.Ratio = 1
    leg1.Action = "BUY"
    leg1.Exchange = "DTB"
    Dim leg2 As ComboLeg = New ComboLeg
    leg2.ConId = 197397584 'DBK JUN 15 '18 P
    leg2.Ratio = 1
    leg2.Action = "SELL"
    leg2.Exchange = "DTB"
    contract.ComboLegs = New List(Of ComboLeg)
    contract.ComboLegs.Add(leg1)
    contract.ComboLegs.Add(leg2)
  • Contract contract;
    contract.symbol = "DBK";
    contract.secType = "BAG";
    contract.currency = "EUR";
    contract.exchange = "DTB";
    ComboLegSPtr leg1(new ComboLeg);
    leg1->conId = 197397509;
    leg1->action = "BUY";
    leg1->ratio = 1;
    leg1->exchange = "DTB";
    ComboLegSPtr leg2(new ComboLeg);
    leg2->conId = 197397584;
    leg2->action = "SELL";
    leg2->ratio = 1;
    leg2->exchange = "DTB";
    contract.comboLegs.reset(new Contract::ComboLegList());
    contract.comboLegs->push_back(leg1);
    contract.comboLegs->push_back(leg2);
  • 1  contract = Contract()
    2  contract.symbol = "DBK"
    3  contract.secType = "BAG"
    4  contract.currency = "EUR"
    5  contract.exchange = "DTB"
    6 
    7  leg1 = ComboLeg()
    8  leg1.conId = 197397509 #DBK JUN 15 2018 C
    9  leg1.ratio = 1
    10  leg1.action = "BUY"
    11  leg1.exchange = "DTB"
    12 
    13  leg2 = ComboLeg()
    14  leg2.conId = 197397584 #DBK JUN 15 2018 P
    15  leg2.ratio = 1
    16  leg2.action = "SELL"
    17  leg2.exchange = "DTB"
    18 
    19  contract.comboLegs = []
    20  contract.comboLegs.append(leg1)
    21  contract.comboLegs.append(leg2)

Guaranteed Futures Spread

  • Contract contract = new Contract();
    contract.Symbol = "VIX";
    contract.SecType = "BAG";
    contract.Currency = "USD";
    contract.Exchange = "CFE";
    ComboLeg leg1 = new ComboLeg();
    leg1.ConId = 195538625;//VIX FUT 20160217
    leg1.Ratio = 1;
    leg1.Action = "BUY";
    leg1.Exchange = "CFE";
    ComboLeg leg2 = new ComboLeg();
    leg2.ConId = 197436571;//VIX FUT 20160316
    leg2.Ratio = 1;
    leg2.Action = "SELL";
    leg2.Exchange = "CFE";
    contract.ComboLegs = new List<ComboLeg>();
    contract.ComboLegs.Add(leg1);
    contract.ComboLegs.Add(leg2);
  • Contract contract = new Contract();
    contract.symbol("VIX");
    contract.secType("BAG");
    contract.currency("USD");
    contract.exchange("CFE");
    ComboLeg leg1 = new ComboLeg();
    ComboLeg leg2 = new ComboLeg();
    List<ComboLeg> addAllLegs = new ArrayList<>();
    leg1.conid(195538625);//VIX FUT 20160217
    leg1.ratio(1);
    leg1.action("BUY");
    leg1.exchange("CFE");
    leg2.conid(197436571);//VIX FUT 20160316
    leg2.ratio(1);
    leg2.action("SELL");
    leg2.exchange("CFE");
    addAllLegs.add(leg1);
    addAllLegs.add(leg2);
    contract.comboLegs(addAllLegs);
  • Dim contract As Contract = New Contract
    contract.Symbol = "VIX"
    contract.SecType = "BAG"
    contract.Currency = "USD"
    contract.Exchange = "CFE"
    Dim leg1 As ComboLeg = New ComboLeg
    leg1.ConId = 195538625
    leg1.Ratio = 1
    leg1.Action = "BUY"
    leg1.Exchange = "CFE"
    Dim leg2 As ComboLeg = New ComboLeg
    leg2.ConId = 197436571
    leg2.Ratio = 1
    leg2.Action = "SELL"
    leg2.Exchange = "CFE"
    contract.ComboLegs = New List(Of ComboLeg)
    contract.ComboLegs.Add(leg1)
    contract.ComboLegs.Add(leg2)
  • Contract contract;
    contract.symbol = "VIX";
    contract.secType = "BAG";
    contract.currency = "USD";
    contract.exchange = "CFE";
    ComboLegSPtr leg1(new ComboLeg);
    leg1->conId = 195538625;
    leg1->action = "BUY";
    leg1->ratio = 1;
    leg1->exchange = "CFE";
    ComboLegSPtr leg2(new ComboLeg);
    leg2->conId = 197436571;
    leg2->action = "SELL";
    leg2->ratio = 1;
    leg2->exchange = "CFE";
    contract.comboLegs.reset(new Contract::ComboLegList());
    contract.comboLegs->push_back(leg1);
    contract.comboLegs->push_back(leg2);
  • 1  contract = Contract()
    2  contract.symbol = "VIX"
    3  contract.secType = "BAG"
    4  contract.currency = "USD"
    5  contract.exchange = "CFE"
    6 
    7  leg1 = ComboLeg()
    8  leg1.conId = 256038899 # VIX FUT 201708
    9  leg1.ratio = 1
    10  leg1.action = "BUY"
    11  leg1.exchange = "CFE"
    12 
    13  leg2 = ComboLeg()
    14  leg2.conId = 260564703 # VIX FUT 201709
    15  leg2.ratio = 1
    16  leg2.action = "SELL"
    17  leg2.exchange = "CFE"
    18 
    19  contract.comboLegs = []
    20  contract.comboLegs.append(leg1)
    21  contract.comboLegs.append(leg2)

Smart-Routed Futures Spread

Futures spreads can also be defined as Smart-routed (non-guaranteed) combos. When placing an order for a non-guaranteed combo from the API, the non-guaranteed flag must be set to 1. Historical data for smart-routed futures spreads is generally available from the API with the requisite market data subscriptions.

  • Contract contract = new Contract();
    contract.Symbol = "WTI"; // WTI,COIL spread. Symbol can be defined as first leg symbol ("WTI") or currency ("USD").
    contract.SecType = "BAG";
    contract.Currency = "USD";
    contract.Exchange = "SMART";
    ComboLeg leg1 = new ComboLeg();
    leg1.ConId = 55928698;//WTI future June 2017
    leg1.Ratio = 1;
    leg1.Action = "BUY";
    leg1.Exchange = "IPE";
    ComboLeg leg2 = new ComboLeg();
    leg2.ConId = 55850663;//COIL future June 2017
    leg2.Ratio = 1;
    leg2.Action = "SELL";
    leg2.Exchange = "IPE";
    contract.ComboLegs = new List<ComboLeg>();
    contract.ComboLegs.Add(leg1);
    contract.ComboLegs.Add(leg2);
  • Contract contract = new Contract();
    contract.symbol("WTI"); // WTI,COIL spread. Symbol can be defined as first leg symbol ("WTI") or currency ("USD").
    contract.secType("BAG");
    contract.currency("USD");
    contract.exchange("SMART"); // smart-routed rather than direct routed
    ComboLeg leg1 = new ComboLeg();
    ComboLeg leg2 = new ComboLeg();
    List<ComboLeg> addAllLegs = new ArrayList<>();
    leg1.conid(55928698);// WTI future June 2017
    leg1.ratio(1);
    leg1.action("BUY");
    leg1.exchange("IPE");
    leg2.conid(55850663);// COIL future June 2017
    leg2.ratio(1);
    leg2.action("SELL");
    leg2.exchange("IPE");
    addAllLegs.add(leg1);
    addAllLegs.add(leg2);
    contract.comboLegs(addAllLegs);
  • Dim contract As Contract = New Contract
    contract.Symbol = "WTI" ' WTI,COIL spread. Symbol can be defined as first leg symbol ("WTI") or currency ("USD")
    contract.SecType = "BAG"
    contract.Currency = "USD"
    contract.Exchange = "SMART"
    Dim leg1 As ComboLeg = New ComboLeg
    leg1.ConId = 55928698 ' WTI future June 2017
    leg1.Ratio = 1
    leg1.Action = "BUY"
    leg1.Exchange = "IPE"
    Dim leg2 As ComboLeg = New ComboLeg
    leg2.ConId = 55850663 ' COIL future June 2017
    leg2.Ratio = 1
    leg2.Action = "SELL"
    leg2.Exchange = "IPE"
    contract.ComboLegs = New List(Of ComboLeg)
    contract.ComboLegs.Add(leg1)
    contract.ComboLegs.Add(leg2)
  • Contract contract;
    contract.symbol = "WTI"; // WTI,COIL spread. Symbol can be defined as first leg symbol ("WTI") or currency ("USD").
    contract.secType = "BAG";
    contract.currency = "USD";
    contract.exchange = "SMART";
    ComboLegSPtr leg1(new ComboLeg);
    leg1->conId = 55928698; // WTI future June 2017
    leg1->action = "BUY";
    leg1->ratio = 1;
    leg1->exchange = "IPE";
    ComboLegSPtr leg2(new ComboLeg);
    leg2->conId = 55850663; // COIL future June 2017
    leg2->action = "SELL";
    leg2->ratio = 1;
    leg2->exchange = "IPE";
    contract.comboLegs.reset(new Contract::ComboLegList());
    contract.comboLegs->push_back(leg1);
    contract.comboLegs->push_back(leg2);
  • 1  contract = Contract()
    2  contract.symbol = "WTI" # WTI,COIL spread. Symbol can be defined as first leg symbol ("WTI") or currency ("USD")
    3  contract.secType = "BAG"
    4  contract.currency = "USD"
    5  contract.exchange = "SMART"
    6 
    7  leg1 = ComboLeg()
    8  leg1.conId = 55928698 # WTI future June 2017
    9  leg1.ratio = 1
    10  leg1.action = "BUY"
    11  leg1.exchange = "IPE"
    12 
    13  leg2 = ComboLeg()
    14  leg2.conId = 55850663 # COIL future June 2017
    15  leg2.ratio = 1
    16  leg2.action = "SELL"
    17  leg2.exchange = "IPE"
    18 
    19  contract.comboLegs = []
    20  contract.comboLegs.append(leg1)
    21  contract.comboLegs.append(leg2)

Inter-Commodity Futures

For Inter-Commodity futures, the 'Local Symbol' field in TWS is used for the 'Symbol' field in the API contract definition, e.g. "CL.BZ". They are always guaranteed combos, which is the default in the API.

  • Contract contract = new Contract();
    contract.Symbol = "CL.BZ";
    contract.SecType = "BAG";
    contract.Currency = "USD";
    contract.Exchange = "NYMEX";
    ComboLeg leg1 = new ComboLeg();
    leg1.ConId = 47207310; //CL Dec'16 @NYMEX
    leg1.Ratio = 1;
    leg1.Action = "BUY";
    leg1.Exchange = "NYMEX";
    ComboLeg leg2 = new ComboLeg();
    leg2.ConId = 47195961; //BZ Dec'16 @NYMEX
    leg2.Ratio = 1;
    leg2.Action = "SELL";
    leg2.Exchange = "NYMEX";
    contract.ComboLegs = new List<ComboLeg>();
    contract.ComboLegs.Add(leg1);
    contract.ComboLegs.Add(leg2);
  • Contract contract = new Contract();
    contract.symbol("CL.BZ");
    contract.secType("BAG");
    contract.currency("USD");
    contract.exchange("NYMEX");
    ComboLeg leg1 = new ComboLeg();
    ComboLeg leg2 = new ComboLeg();
    List<ComboLeg> addAllLegs = new ArrayList<>();
    leg1.conid(47207310); //CL Dec'16 @NYMEX
    leg1.ratio(1);
    leg1.action("BUY");
    leg1.exchange("NYMEX");
    leg2.conid(47195961); //BZ Dec'16 @NYMEX
    leg2.ratio(1);
    leg2.action("SELL");
    leg2.exchange("NYMEX");
    addAllLegs.add(leg1);
    addAllLegs.add(leg2);
    contract.comboLegs(addAllLegs);
  • Dim contract As Contract = New Contract
    contract.Symbol = "CL.BZ"
    contract.SecType = "BAG"
    contract.Currency = "USD"
    contract.Exchange = "NYMEX"
    Dim leg1 As ComboLeg = New ComboLeg
    leg1.ConId = 47207310 ' CL Dec'16 @NYMEX
    leg1.Ratio = 1
    leg1.Action = "BUY"
    leg1.Exchange = "NYMEX"
    Dim leg2 As ComboLeg = New ComboLeg
    leg2.ConId = 47195961 ' BZ Dec'16 @NYMEX
    leg2.Ratio = 1
    leg2.Action = "SELL"
    leg2.Exchange = "NYMEX"
    contract.ComboLegs = New List(Of ComboLeg)
    contract.ComboLegs.Add(leg1)
    contract.ComboLegs.Add(leg2)
  • Contract contract;
    contract.symbol = "CL.BZ";
    contract.secType = "BAG";
    contract.currency = "USD";
    contract.exchange = "NYMEX";
    ComboLegSPtr leg1(new ComboLeg);
    leg1->conId = 47207310; //CL Dec'16 @NYMEX
    leg1->action = "BUY";
    leg1->ratio = 1;
    leg1->exchange = "NYMEX";
    ComboLegSPtr leg2(new ComboLeg);
    leg2->conId = 47195961; //BZ Dec'16 @NYMEX
    leg2->action = "SELL";
    leg2->ratio = 1;
    leg2->exchange = "NYMEX";
    contract.comboLegs.reset(new Contract::ComboLegList());
    contract.comboLegs->push_back(leg1);
    contract.comboLegs->push_back(leg2);
  • 1  contract = Contract()
    2  contract.symbol = "CL.BZ" #symbol is 'local symbol' of intercommodity spread.
    3  contract.secType = "BAG"
    4  contract.currency = "USD"
    5  contract.exchange = "NYMEX"
    6 
    7  leg1 = ComboLeg()
    8  leg1.conId = 47207310 #CL Dec'16 @NYMEX
    9  leg1.ratio = 1
    10  leg1.action = "BUY"
    11  leg1.exchange = "NYMEX"
    12 
    13  leg2 = ComboLeg()
    14  leg2.conId = 47195961 #BZ Dec'16 @NYMEX
    15  leg2.ratio = 1
    16  leg2.action = "SELL"
    17  leg2.exchange = "NYMEX"
    18 
    19  contract.comboLegs = []
    20  contract.comboLegs.append(leg1)
    21  contract.comboLegs.append(leg2)

Please be mindful of the fact that inter-commodity spreads are offered by the exchange directly, and so they are direct-routed though the legs have different underlyings. Only real time, and not historical, data is offered for inter-commodity spread contracts through the API.

It is also possible in many cases to create a spread of the same future contracts in a inter-commodity spread which is smart-routed and non-guaranteed. Historical data for this spread would generally be available from the API. Also, historical data for expired spread contracts is not available in TWS or the API.