undefined

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 LYNXApi.Contract in question. The conId of an instrument can easily be obtained via the LYNXApi.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".

** Python **

contract = Contract()
contract.symbol = "IBKR,MCD"
contract.secType = "BAG"
contract.currency = "USD"
contract.exchange = "SMART"

leg1 = ComboLeg()
leg1.conId = 43645865#IBKR STK
leg1.ratio = 1
leg1.action = "BUY"
leg1.exchange = "SMART"

leg2 = ComboLeg()
leg2.conId = 9408#MCD STK
leg2.ratio = 1
leg2.action = "SELL"
leg2.exchange = "SMART"

contract.comboLegs = []
contract.comboLegs.append(leg1)
contract.comboLegs.append(leg2)

** Java **

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);

[!NOTE] EFPs are simply defined as a bag contract of stock and corresponding SSF with a ratio of 100:1.

Options Spread

** Python **

contract = Contract()
contract.symbol = "DBK"
contract.secType = "BAG"
contract.currency = "EUR"
contract.exchange = "DTB"

leg1 = ComboLeg()
leg1.conId = 317960956 #DBK JUN 21 2019 C
leg1.ratio = 1
leg1.action = "BUY"
leg1.exchange = "DTB"

leg2 = ComboLeg()
leg2.conId = 334216780  #DBK MAR 15 2019 C
leg2.ratio = 1
leg2.action = "SELL"
leg2.exchange = "DTB"

contract.comboLegs = []
contract.comboLegs.append(leg1)
contract.comboLegs.append(leg2)

** Java **

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);

Guaranteed Futures Spread

** Python **

contract = Contract()
contract.symbol = "VIX"
contract.secType = "BAG"
contract.currency = "USD"
contract.exchange = "CFE"

leg1 = ComboLeg()
leg1.conId = 326501438 # VIX FUT 201903
leg1.ratio = 1
leg1.action = "BUY"
leg1.exchange = "CFE"

leg2 = ComboLeg()
leg2.conId = 323072528 # VIX FUT 2019049
leg2.ratio = 1
leg2.action = "SELL"
leg2.exchange = "CFE"

contract.comboLegs = []
contract.comboLegs.append(leg1)
contract.comboLegs.append(leg2)

** Java **

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);

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.

** Python **

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"

leg1 = ComboLeg()
leg1.conId = 55928698 # WTI future June 2017
leg1.ratio = 1
leg1.action = "BUY"
leg1.exchange = "IPE"

leg2 = ComboLeg()
leg2.conId = 55850663 # COIL future June 2017
leg2.ratio = 1
leg2.action = "SELL"
leg2.exchange = "IPE"

contract.comboLegs = []
contract.comboLegs.append(leg1)
contract.comboLegs.append(leg2)

** Java **

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);

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.

** Python **

contract = Contract()
contract.symbol = "CL.BZ" #symbol is 'local symbol' of intercommodity spread. 
contract.secType = "BAG"
contract.currency = "USD"
contract.exchange = "NYMEX"
leg1 = ComboLeg()
leg1.conId = 47207310 #CL Dec'16 @NYMEX
leg1.ratio = 1
leg1.action = "BUY"
leg1.exchange = "NYMEX"

leg2 = ComboLeg()
leg2.conId = 47195961 #BZ Dec'16 @NYMEX
leg2.ratio = 1
leg2.action = "SELL"
leg2.exchange = "NYMEX"

contract.comboLegs = []
contract.comboLegs.append(leg1)
contract.comboLegs.append(leg2)

** Java **

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);

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.*