Contracts

Contract Management
Copy Location

Best Practices
Copy Location

Interactive Brokers does maintain the use of creating contracts in both the Trader Workstation and Client Portal APIs. The default structure will allow the individual to typically reference the ticker symbol, security type, exchange, and currency; however, the best practice recommended by Interactive Brokers for both platforms is to use only the contract identifier, or ConId, and the Exchange instead. This will cover a complete contract without the need for additional parameters.

These conids are static for each and every contract and will never change. Values such as 265598 for AAPL will always remain as the AAPL contract identifier for the underlying stock contract.

The Value Exchange
Copy Location

While clients will typically trade a given instrument at a designated exchange, some clients may find their contracts listed as trading on VALUE. The VALUE exchange is a holding exchange used for clients to close positions on a contract that is no longer listed.

A recent example of this is when TWTR / X was recently purchased. In this event, customers would be able to close all existing positions they had on the contract; however, no new positions could be taken. This is a result of the company going private and no longer allowing the stocks to be publicly traded.

Bonds
Copy Location

Symbol: String. The CUSIP of the bond.

SecType: String. Always specify as BOND.

Exchange: String. Smart may be specified. May direct route if interested.

Currency: String. Specify the base currency the BOND is traded with.

symbol= "912828C57"
secType = "BOND"
exchange = "SMART"
currency = "USD"

CFDs
Copy Location

Symbol: String. Specify the symbol of the CFD.

SecType: String. Specify CFD.

Exchange: String. Specify SMART.

Currency: String. Specify the base currency the CFD is traded with.

 symbol = "IBDE30"
 secType = "CFD"
 currency = "EUR"
 exchange = "SMART"

Commodities
Copy Location

Symbol: String. Specify the symbol of the commodity.

SecType: String. Specify CMDTY.

Exchange: String. Specify SMART.

Currency: String. Specify the base currency the commodity is traded with.

symbol = "XAUUSD"
secType = "CMDTY"
exchange = "SMART"
currency = "USD"

Contracts specified by FIGI
Copy Location

SecId: String. Specify the FIGI code of the instrument

SecIdType: String. Specify “FIGI”.

Exchange: String. Specify SMART.

secIdType = "FIGI"
secId = "BBG000B9XRY4"
exchange = "SMART"

Cryptocurrency
Copy Location

Symbol: String. Specify the symbol of the cryptocurrency.

SecType: String. Specify CRYPTO.

Exchange: String. Specify PAXOS.

Currency: String. Only USD is available at this time.

symbol = "ETH"
secType = "CRYPTO"
currency = "USD"
exchange = "PAXOS"

Futures
Copy Location

Symbol: String. Specify the underlying symbol of the future.

SecType: String. Specify FUT.

Exchange: String. Specify the exchange where the future is traded.

Currency: String. Specify the currency which the future is traded.

LastTradeDateOrContractMonth: String. Enter the month the contract expires. In the event there are multiple expiries in the same month, exact date must be specified.

symbol = "ES"
secType = "FUT"
exchange = "CME"
currency = "USD"
lastTradeDateOrContractMonth = "202809"

Futures Options
Copy Location

Symbol: String. Specify the underlying symbol of the futures option.

SecType: String. Specify FOP.

Exchange: String. Specify the exchange where the underlying is traded.

Currency: String. Specify the base currency of the futures option.

LastTradeDateOrContractMonth: String. Enter the month the contract expires. In the event there are multiple expiries in the same month, exact date must be specified.

Strike: float. Enter the strike price of the derivative.

Right: String. Enter the right, “C” for Calls and “P” for Puts.

Multiplier: String. Enter the multiplier of the derivative.

symbol = "GBL"
secType = "FOP"
exchange = "EUREX"
currency = "EUR"
lastTradeDateOrContractMonth = "20230224"
strike = 138
right = "C"
multiplier = "1000"

FX Pairs
Copy Location

Symbol: String. Specify the target currency. For orders, this will dictate the quantity value.

SecType: String. Specify CASH.

Exchange: String. Specify IDEAL for Virtual Forex or IDEALPRO for true forex trading.

Currency: String. Specify the base currency forex pair. This will dictate size with cash quantity trades.

symbol = "EUR"
secType = "CASH"
exchange = "IDEALPRO"
currency = "GBP"

Indices
Copy Location

Symbol: String. Specify the symbol for the index.

SecType: String. Specify IND.

Exchange: String. Specify the host exchange for the index.

Currency: String. Specify the base currency of the index.

symbol = "DAX"
secType = "IND"
exchange = "EUREX"
currency = "EUR"

Mutual Funds
Copy Location

Symbol: String. Specify the symbol for the mutual fund.

SecType: String. Specify FUND.

Exchange: String. Specify the exchange of the fund. FUNDSERV is the most common.

Currency: String. Specify the base currency of the fund.

symbol = "VINIX"
secType = "FUND"
exchange = "FUNDSERV"
currency = "USD"

Note: It is recommended to understand mutual fund orders on TWS UI before implementing via API due to restrictions enforced on trading mutual funds For example to buy ARBIX one requires to use cash quantity ie cashQty while selling ARBIX can be implemented using total quantity ie totalQuantity

Options
Copy Location

Symbol: String. Specify the underlying symbol of the option.

SecType: String. Specify OPT.

Exchange: String. SMART routing may be specified. May use direct routing such as BOX.

Currency: String. Specify the base currency of the option.

LastTradeDateOrContractMonth: String. Enter the month the contract expires. In the event there are multiple expiries in the same month, exact date must be specified.

Strike: float. Enter the strike price of the derivative.

Right: String. Enter the right, “C” for Calls and “P” for Puts.

Multiplier: String. Enter the multiplier of the derivative.

symbol = "GOOG"
secType = "OPT"
exchange = "BOX"
currency = "USD"
lastTradeDateOronth = "20190315"
strike = 1180
right = "C"
multiplier = "100"

Stocks
Copy Location

Symbol: String. Specify the symbol for the Stock or ETF.

SecType: String. Specify STK.

Exchange: String. Smart routing is available. Otherwise, a direct exchange may be specified.

Currency: String. Specify the base currency of the stock.

symbol = "AAPL"
secType = "STK"
exchange = "SMART"
currency = "USD"

For certain smart-routed stock that have the same symbol, currency and exchange, you would also need to specify the primary exchange attribute to uniquely define the This should be defined as the native exchange of a and is good practice to include for all stocks.

For the purpose of requesting market data, the routing exchange and primary exchange can be specified in a single ‘exchange’ field if they are separated by a valid component exchange separator, for instance exchange = “SMART:ARCA” The default separators available are colon “:” and slash “/” Other component exchange separators can be defined using the field defined in TWS Global Configuration under API -> Settings.

Symbol: String. Specify the symbol for the Stock or ETF.

SecType: String. Specify STK.

Exchange: String. Smart routing is available. Otherwise, a direct exchange may be specified.

Currency: String. Specify the base currency of the stock.

PrimaryExchange: Specify the primary listing exchange of the instrument.

symbol = "SPY"
secType = "STK"
currency = "USD"
exchange = "SMART"
primaryExchange = "ARCA"

Stock Contract with IPO price
Copy Location

Symbol: String. Specify the symbol for the Stock or ETF.

SecType: String. Specify STK.

Exchange: String. Smart routing is available. Otherwise, a direct exchange may be specified.

Currency: String. Specify the base currency of the stock.

symbol = "EMCGU"
secType = "STK"
currency = "USD"
exchange = "SMART"

Warrants
Copy Location

Warrants, like options, require an expiration date, a right, a strike and a multiplier. For some warrants it will be necessary to define a localSymbol or conId to uniquely identify the contract.

Dutch Warrants and Structured Products
Copy Location

Symbol: String. Specify the underlying symbol of the warrant.

SecType: String. Specify WAR.

Exchange: String. Specify the holding exchange for the warrant. SWB, FWB, and GETTEX are common holding exchanges.

Currency: String. Specify the base currency of the warrant.

LastTradeDateOrContractMonth: String. Enter the month the contract expires. In the event there are multiple expiries in the same month, exact date must be specified.

Strike: float. Enter the strike price of the derivative.

Right: String. Enter the right, “C” for Calls and “P” for Puts.

Multiplier: String. Enter the multiplier of the derivative.

symbol = "GOOG"
secType = "WAR"
exchange = "FWB"
currency = "EUR"
lastTradeDateOronth = "20201117"
strike = 15000
right = "C"
multiplier = "001"

Standard Warrants
Copy Location

LocalSymbol: String. Specify the exact symbol of the derivative.

SecType: String. Specify IOPT.

Exchange: String. Specify the holding exchange for the warrant. SWB, FWB, and GETTEX are common holding exchanges.

Currency: String. Specify the base currency of the warrant.

localSymbol = "B881G"
secType = "IOPT"
exchange = "SBF"
currency = "EUR"

To unambiguously define a Dutch Warrant or Structured Product (IOPTs) the conId or localSymbol field must be used.

It is important to note that if reqContractDetails is used with an incompletely-defined IOPT contract definition, that thousands of results can be returned and the API connection broken.
IOPT contract definitions will often change and it will be necessary to restart TWS or IB Gateway to download the new contract definition.

Spread Contracts
Copy Location

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 contract in question.

The conId of an instrument can easily be obtained via the EClientSocket.reqContractDetails request or the /iserver/secdef/search endpoint.

Note: Even though a contract can be created with any pair of instruments, not all instruments are as actively traded as others. If you are unsure why data may not be retrieved, or why an order may not be executed, it is considered best practice to confirm data against the Trader Workstation or Client Portal market data.

TWSAPI Spreads
Copy Location

As with standard contracts, you will continue to define the standard values such as symbol, secType, exchange, and currency. However, with combo orders, the “ComboLegs” field must be added and the ComboLeg objects should be attached. The example provided will showcase more detail of behavior; however, these require a conid, exchange, ratio, and an action for every ComboLeg on the order.

Contract()

Symbol: String. Specify the symbol of the CFD.

SecType: String. Specify CFD.

Exchange: String. Specify SMART.

Currency: String. Specify the base currency the CFD is traded with.

ComboLegs: List of ComboLeg objects. Create a list to contain all subsequent legs.

ComboLeg()

ConId: int. The conId, or contract Identifier, should be used to specify the exact contract. Symbols or local symbols can not be used for ComboLegs.

Ratio: int. Specify the ratio for the specific leg. The ratio will be multiplied by the totalQuantity field for of the order object.

Action: String. Specify what to do with the order. Users may choose Buy or Sell for these orders.

Exchange: String. Specify the routing exchange for the contract. SMART may be used.

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)

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

ComboLeg leg1 = new ComboLeg();
ComboLeg leg2 = new ComboLeg();
List 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);

Contract contract;
contract.symbol = "IBKR,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);

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();
contract.ComboLegs.Add(leg1);
contract.ComboLegs.Add(leg2);

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)

CPAPI Spreads
Copy Location

Combo Orders follow the format of: ‘{spread_conid};;;{leg_conid1}/{ratio},{leg_conid2}/{ratio}‘

This example documents the same structure of a long IBKR order against a short MCD order.

"conidex": "28812380;;;43645865/1,9408/-1"

Combination orders or spread orders may also be placed using the same orders endpoint. In the case of combo orders, we must use the ‘conidex’ instead of “conid”. The conidex field is a string representation of our combo order parameters.

The spread_conid is a unique identified used to denote a spread order. For US Stock Combos, only the spread_conid needs to be submitted.. For all other countries, you will need to use the format ‘spread_conid@exchange’.

Available currency spread conids:

Currency	Spread ConID
AUD	61227077
CAD	61227082
CHF	61227087
CNH	136000441
GBP	58666491
HKD	61227072
INR	136000444
JPY	61227069
KRW	136000424
MXN	136000449
SEK	136000429
SGD	426116555
USD	28812380

Following our spread_conid, we will then follow with 4 semicolnons, and then the first leg_coind. This will be the first contract to trade. After the conid, a forward slash, ‘/’, needs to be included followed by your spread ratio.

The ratio indicates two parts. The first is the sign of the ratio, whether it is positive or negative. Positive signs indicate a ‘Buy’ side, while a negative value represents a ‘Sell’ side. This could also be explained as a state of ‘Long’ and ‘Short’ respectively, depending on your current position and intention. After indicating the side, you would indicate the ratio value. This is the multiplier of your quantity value.

Now, you can continue to add legs to the order by separating them with a comma. The number of legs available is based on the exchange’s rules.

Contract Management Copy Location

Copy Location

Best Practices Copy Location

Copy Location

The Value Exchange Copy Location

Copy Location

Bonds Copy Location

Copy Location

CFDs Copy Location

Copy Location

Commodities Copy Location

Copy Location

Contracts specified by FIGI Copy Location

Copy Location

Cryptocurrency Copy Location

Copy Location

Futures Copy Location

Copy Location

Futures Options Copy Location

Copy Location

FX Pairs Copy Location

Copy Location

Indices Copy Location

Copy Location

Mutual Funds Copy Location

Copy Location

Options Copy Location

Copy Location

Stocks Copy Location

Copy Location

Stock Contract with IPO price Copy Location

Copy Location

Warrants Copy Location

Copy Location

Dutch Warrants and Structured Products Copy Location

Copy Location

Standard Warrants Copy Location

Copy Location

Spread Contracts Copy Location

Copy Location

TWSAPI Spreads Copy Location

Copy Location

Contract()

ComboLeg()

CPAPI Spreads Copy Location

Copy Location

Available currency spread conids:

Contract Management
Copy Location

Best Practices
Copy Location

The Value Exchange
Copy Location

Bonds
Copy Location

CFDs
Copy Location

Commodities
Copy Location

Contracts specified by FIGI
Copy Location

Cryptocurrency
Copy Location

Futures
Copy Location

Futures Options
Copy Location

FX Pairs
Copy Location

Indices
Copy Location

Mutual Funds
Copy Location

Options
Copy Location

Stocks
Copy Location

Stock Contract with IPO price
Copy Location

Warrants
Copy Location

Dutch Warrants and Structured Products
Copy Location

Standard Warrants
Copy Location

Spread Contracts
Copy Location

TWSAPI Spreads
Copy Location

CPAPI Spreads
Copy Location