API Build 9.72 - Release Notes

Show Quote Exchange

Beginning with release 9.72.18, a single data request from the API can receive aggregate quotes from multiple exchanges. With API versions 9.72.18 and TWS 9.62 and higher, the tick types 'bidExch' (tick type 32), 'askExch' (tick type 33), 'lastExch' (tick type 84) are used to identify the source of a quote. To preserve bandwidth, the data returned to these tick types consists of a sequence of capital letters rather than a long list of exchange names for every returned exchange name field. To find the full exchange name corresponding to a single letter code returned in tick types 32, 33, or 84, and API function IBApi::EClient::reqSmartComponents is available.

Different IB contracts have a different exchange map containing the set of exchanges on which they trade. Each exchange map has a different code, such as "a6" or "a9". This exchange mapping code is returned to IBApi::EWrapper::tickReqParams immediately after a market data request is made by a user with market data subscriptions. To find a particular map of single letter codes to full exchange names, the function reqSmartComponents is invoked with the exchange mapping code returned to tickReqParams.

For instance, a market data request for the IBKR US contract may return the exchange mapping identifier "a6" to tickReqParams. Invoking the function reqSmartComponents with the symbol "a9" will reveal the list of exchanges offering market data for the IBKR US contract, and their single letter codes. The code for "ARCA" may be "P". In that case if "P" is returned to the exchange tick types, that would indicate the quote was provided by ARCA.

For samples and more information, see http://interactivebrokers.github.io/tws-api/ smart_components.html

Soft Dollar Tiers

Soft Dollar tiers are supported in version 9.72.18, and require TWS version 959 or above.

For examples go to: http://interactivebrokers.github.io/tws-api/financial_advisor_methods_and_orders.html#soft_dollar_tiers

New EClient Function

Effective with TWS build 956, we have added the reqSecDefOptParams function on the EClient class to obtain the available Futures and Futures Options contracts for an underlying.

The function's parameters include:

reqId: The request's identifier.
underlyingSymbol: Symbol of the FUT/FOP underlying contract.
futFopExchange: FUT/FOP trading exchange.
underlyingSecType: Security type of the underlying (i.e. STK).
underlyingConId: IB's conId of the underlying product.

The delivered information will be returned via the EWrapper's securityDefinitionOptionalParameter as:

reqId: Originating request identifier.
exchange: Delivered contract's exchange.
underlyingConId: IB conid for the underlying.
tradingClass: Contract’s trading class.
multiplier: FOPs multiplier.
expirations: List of available expirations.
strikes: List of available strikes.

Once all the information has been delivered, the EWrapper's securityDefinitionOptionalParameterEnd marker will be triggered.

New Order Types Support in API

Adjustable Stops, Pegged-to-Benchmark and Conditional orders are now supported in the API.

Adjustable Stops: Attach one-time adjustments to stop, stop limit, trailing stop and trailing stop limit order using the following new attributes within the Order class:

triggerPrice: When this price is penetrated, the adjustment will take place.
adjustedOrderType: Parent order will be changed to the given type (i.e. STP, STP LMT, TRAIL, etc).
adjustedStopPrice: Adjusted parent's order stop price.
adjustedStopLimitPrice: Adjusted parent order's stop limit price.
adjustableTrailingUnit: Set to 0 to indicate amount, set to 1 for percentage.
adjustedTrailingAmount: Trailing amount/percent of the adjusted order.

Pegged-to-Benchmark: Peg your order to a reference contract's movement in the market using the following new attributes within the Order class.

startingPrice: When the reference contract reaches this price.
isPeggedChangeAmountDecrease: True if decrementing order's price.
peggedChangeAmount: Amount by which the order price will move.
referenceContractId: The reference contract's conId.
referenceExchange: Exchange on which reference contract needs to be tracked.
stockRefPrice: Starting reference price.
stockRangeLower & stockRangeUpper: Pegged-to-benchmark order will remain active as long as the reference price remains within this threshold.

For examples go to: http://interactivebrokers.github.io/tws-api/basic_orders.html#pegged_benchmark

Conditional: Specify conditions that must be met before the order will trigger. Uses the following classes and new attributes within each class:

Order class

conditionsCancelOrder: set to true to cancel the order when the conditions are met.
conditions: list of conditions to be met.

PriceCondition (new class)

conId: conId of the contract to be used as reference.
exchange: exchange in which to track the reference contract.
isMore: true when condition requires the price to be “higher than”.
price: reference contract's price to be met for the condition to trigger.
isConjunctionConnection: use "AND" or "OR" to concatenate to next condition.

ExecutionCondition (new class)

Symbol: the reference contract's symbol for which the execution is expected.
Exchange: exchange in which to track the reference contract.
SecType: reference contract's security type.
isConjunctionConnection: use "AND" or "OR" to concatenate to next condition.

MarginCondition (new class)

isMore: true if margin has to be greater than the given margin's percent.
percent: margin percent to be checked by the condition.
isConjunctionConnection: use "AND" or "OR" to concatenate to next condition.

PercentageChangeCondition (new class)

isMore: true if the percentage change is greater than what the condition specifies.
changePercent: the percent amount change the condition requires.
conId: conId of the contract to be used as reference.
exchange: exchange in which to track the reference contract.
isConjunctionConnection: use "AND" or "OR" to concatenate to next condition.

TimeCondition (new class)

isMore: before (false) or after (true) a given time.
time: time to trigger the condition
isConjunctionConnection: use "AND" or "OR" to concatenate to next condition.

VolumeCondition (new class)

conId: conId of the contract to be used as reference.
exchange: exchange in which to track the reference contract.
isMore: true if volume has to be greater than what is given.
volume: volume amount to trigger condition.

For examples go to: http://interactivebrokers.github.io/tws-api/order_conditions.html

Model Portfolios Supported in API

EClient Class: Positions and account updates can now be requested for a given account or model via reqPositionsMulti and reqAccountUpdatesMulti methods.

EWrapper Interface: Information is delivered via the new positionMulti/positionMultiEnd and accountUpdateMulti/accountUpdateMultiEnd callbacks.

Fields Renamed from "Expiry" to "LastTradingDay" or “LastTradingDayorContractMonth”

Within TWS, we use the last trading day and not the actual expiration date for futures, options and futures options contracts. To more accurately reflect this data, we have changed all of the “expiry” fields throughout the API to either “LastTradingDay” or “LastTradingDayorContractMonth” as noted below.

For TWS messages being sent to the API client, the values is always Last Trading Day, and so the "Expiry" field has been changed to "LastTradingDay":

OPEN_ORDER = 5;
PORTFOLIO_VALUE = 7;
CONTRACT_DATA = 10;
EXECUTION_DATA = 11;
SCANNER_DATA = 20;
TICK_EFP = 47;
POSITION = 61;

For messages sent from the API to TWS, if the value length is 8, TWS understand it as the Last Trading Day. If the value length is 6, TWS understand it as the Contract Month. For these, the “Expiry” field has been renamed to “LastTradingDayorContractMonth”:

REQ_MKT_DATA = 1;
PLACE_ORDER = 3;
REQ_CONTRACT_DATA = 9;
REQ_MKT_DEPTH = 10;
REQ_HISTORICAL_DATA = 20;
EXERCISE_OPTIONS = 21;
REQ_REAL_TIME_BARS = 50;
REQ_CALC_IMPLIED_VOLAT = 54;
REQ_CALC_OPTION_PRICE = 55;

For the above, the expiry field is wrapped in the Contract class. We have renamed Contract.expiry to Contract.lastTradingDayOrContractMonth.

SSL Support in API

The TWS API library can now communicate with servers when used as a mobile API over a secured SSL protocol. In conjunction with this added support, the EClientSocket, which was previously a combination of client functionality plus socket functionality/transport, was split to isolate socket functionality/transport in an ESocket class implementing an ETransport interface. This refactoring allows us to implement alternative transports, specifically SSL.

New Order Fields for Volatility Orders

Two new attributes are supported for Volatility and Pegged to Volatility orders. These are available in all API platforms

randomizeSize - Boolean
randomizePrice - Boolean

Read-Only Mode for API

Effective in TWS 950 and above, API users have the option to set the API to Read-Only mode. This mode allows viewing of market data and account information, but blocks any type of trading activity Additionally, users can elect to limit access only to connections made from the same computer. To set API parameters, from within TWS Global Configuration select API.

Clients and Sample Applications

Beginning with this release, we have made the following changes to our API clients and sample applications:

The C++ MFC-based client and sample applications have been deprecated.
The ActiveX Control is now written in C#.
PosixClient has been renamed to CppClient, and is located in the source directory of your API installation folder.
In the Java client, the AnyWrapper interface has been removed. Its methods have been incorporated into the EWrapper interface.
The ApiController-specific classes (e.g. NewOrder) have been merged into the main Java client.

Connection Enhancements

We have added the following new connection features:

useV100Plus and connectionOptions - These fields are used together to implement two-way versioning for connections to TWS 947+.

When enabled via setUseV100Plus, the client will report a range of supported API versions to TWS. TWS will respond with highest supported API version in the range specified by the client. From that moment on, both client and server are expected to send messages formatted according to the negotiated version. Currently only version 100 is supported. This version adds 4-byte network-byte-order length prefixes to all messages.

connectionOptions is a field reserved for future extensions. For now, API clients should specify an empty string when connecting to TWS.
startApi: optionalCapabilities - This field is reserved for future extensions. For now, API clients should specify an empty string.

Solicited Flag

We have added a new Order attribute, Solicited to the Order object. Solicited is a boolean attribute with the following values:

True = solicited (orders initiated by a broker through the brokers research and design).
False = unsolicited (those instigated by a broker's customer either through their actions or by the broker at their direction).

New Error Codes

The following new error codes have been added to the Java client:

506 - Unsupported Version
507 - Bad Message Length
508 - Bad Message

primaryExchange Field

Beginning with this release, we have made the following changes to the primaryExchange field:

TWS serverVersion=75 and above supports the new dedicated field primaryExchange.
TWS builds 939, 942 and above (note that this corresponds to a subset of serverVerion=69 and above; not all serverVersion=69 support this) support this new behavior:
The exchange field is formatted as follows:
exchange= SMART:LSEIOB1
In this example, the colon ( : ) is a default separator that is configurable in TWS.
For new builds, you can set primaryExchange either in the new dedicated field or by using the separator, but not both. If primaryExchange is set in both places, the request will be rejected.

API Order End Marker Bug Fixed

We have fixed a bug with API orders that sent an end marker prematurely. Beginning with TWS beta release 948, the end marker will be sent to the API only after all of the orders have been delivered to TWS.