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

Beginning with TWS v971, Stock/Stock combos will have ticker symbols in alphabetical order when they are both used in the symbol field, e.g. "AMD,IBKR".

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 = "EUREX";

ComboLeg leg1 = new ComboLeg();

leg1.ConId = 577164786;//DBK Jun21'24 CALL @EUREX

leg1.Ratio = 1;

leg1.Action = "BUY";

leg1.Exchange = "EUREX";

ComboLeg leg2 = new ComboLeg();

leg2.ConId = 577164767;//DBK Dec15'23 CALL @EUREX

leg2.Ratio = 1;

leg2.Action = "SELL";

leg2.Exchange = "EUREX";

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("EUREX");

ComboLeg leg1 = new ComboLeg();

ComboLeg leg2 = new ComboLeg();

List<ComboLeg> addAllLegs = new ArrayList<>();

leg1.conid(577164786);//DBK Jun21'24 2 CALL @EUREX

leg1.ratio(1);

leg1.action("BUY");

leg1.exchange("EUREX");

leg2.conid(577164767);//DBK Dec15'23 2 CALL @EUREX

leg2.ratio(1);

leg2.action("SELL");

leg2.exchange("EUREX");

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 = "EUREX"

Dim leg1 As ComboLeg = New ComboLeg

leg1.ConId = 577164786 'DBK Jun21'24 CALL @EUREX

leg1.Ratio = 1

leg1.Action = "BUY"

leg1.Exchange = "EUREX"

Dim leg2 As ComboLeg = New ComboLeg

leg2.ConId = 577164767 'DBK Dec15'23 CALL @EUREX

leg2.Ratio = 1

leg2.Action = "SELL"

leg2.Exchange = "EUREX"

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 = "EUREX";

ComboLegSPtr leg1(new ComboLeg);

leg1->conId = 577164786;//DBK Jun21'24 CALL @EUREX

leg1->action = "BUY";

leg1->ratio = 1;

leg1->exchange = "EUREX";

ComboLegSPtr leg2(new ComboLeg);

leg2->conId = 577164767;//DBK Dec15'23 CALL @EUREX

leg2->action = "SELL";

leg2->ratio = 1;

leg2->exchange = "EUREX";

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 = "EUREX"

6

7 leg1 = ComboLeg()

8 leg1.conId = 577164786 #DBK Jun21'24 2 CALL @EUREX

9 leg1.ratio = 1

10 leg1.action = "BUY"

11 leg1.exchange = "EUREX"

12

13 leg2 = ComboLeg()

14 leg2.conId = 577164767 #DBK Dec15'23 2 CALL @EUREX

15 leg2.ratio = 1

16 leg2.action = "SELL"

17 leg2.exchange = "EUREX"

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 = 326501438 # VIX FUT 201903

9 leg1.ratio = 1

10 leg1.action = "BUY"

11 leg1.exchange = "CFE"

12

13 leg2 = ComboLeg()

14 leg2.conId = 323072528 # VIX FUT 2019049

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 = "COIL.WTI";

contract.SecType = "BAG";

contract.Currency = "USD";

contract.Exchange = "IPE";

ComboLeg leg1 = new ComboLeg();

leg1.ConId = 183405603; //WTI Dec'23 @IPE

leg1.Ratio = 1;

leg1.Action = "BUY";

leg1.Exchange = "IPE";

ComboLeg leg2 = new ComboLeg();

leg2.ConId = 254011009; //COIL Dec'23 @IPE

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("COIL.WTI");

contract.secType("BAG");

contract.currency("USD");

contract.exchange("IPE");

ComboLeg leg1 = new ComboLeg();

ComboLeg leg2 = new ComboLeg();

List<ComboLeg> addAllLegs = new ArrayList<>();

leg1.conid(183405603); //WTI�Dec'23�@IPE

leg1.ratio(1);

leg1.action("BUY");

leg1.exchange("IPE");

leg2.conid(254011009); //COIL�Dec'23�@IPE

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 = "COIL.WTI"

contract.SecType = "BAG"

contract.Currency = "USD"

contract.Exchange = "IPE"

Dim leg1 As ComboLeg = New ComboLeg

leg1.ConId = 183405603 ' WTI Dec'23 @IPE

leg1.Ratio = 1

leg1.Action = "BUY"

leg1.Exchange = "IPE"

Dim leg2 As ComboLeg = New ComboLeg

leg2.ConId = 254011009 ' COIL Dec'23 @IPE

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 = "COIL.WTI";

contract.secType = "BAG";

contract.currency = "USD";

contract.exchange = "IPE";

ComboLegSPtr leg1(new ComboLeg);

leg1->conId = 183405603; //WTI Dec'23 @IPE

leg1->action = "BUY";

leg1->ratio = 1;

leg1->exchange = "IPE";

ComboLegSPtr leg2(new ComboLeg);

leg2->conId = 254011009; //COIL Dec'23 @IPE

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 = "COL.WTI" #symbol is 'local symbol' of intercommodity spread.

3 contract.secType = "BAG"

4 contract.currency = "USD"

5 contract.exchange = "IPE"

6

7 leg1 = ComboLeg()

8 leg1.conId = 183405603 #WTI�Dec'23�@IPE

9 leg1.ratio = 1

10 leg1.action = "BUY"

11 leg1.exchange = "IPE"

12

13 leg2 = ComboLeg()

14 leg2.conId = 254011009 #COIL�Dec'23�@IPE

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)

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.