API Release Notes for Build 8.61

The enhancements and modifications below are in build 8.61 of the TWS API. For clarification on any of the items listed, refer to the appropriate section in the User's Guide, or contact IB customer service.

Enhancements

Overriding TWS Order Price Percentage Constraints from the API for ActiveX, Socket Library, and Java API Clients, and Discontinued Popup.

Starting with API Version 8.60 (client version 22) and TWS version 850 (server version 22), all socket-based API technologies, including the socket client library, ActiveX, and Java, have the ability to override TWS’s order price percentage constraints, which are applied to orders that TWS sees as deviating too much from the NBBO` of the contract. This is done via a new parameter “overridePercentageConstraints” to the PLACE_ORDER message version 18. The ActiveX control has a new property for this purpose, also called “overridePercentageConstraints.” This functionality was put into place to work in conjunction with the fact that TWS will no longer pop up a confirmation dialog when an API order violates the percentage constraints TWS imposes. If the “overridePercentageConstraints” flag is not set, such orders going forward will be rejected. Keep in mind that orders with prices that severely depart from the contract’s NBBO but would otherwise be filled will be rejected by IB’s servers.

API Market Data Request Rejection Error Message and Discontinued Popup.

Starting with TWS version 850 (server version 22), TWS will no longer generate a popup dialog when an API market data request is rejected due to a lack of a necessary market data permission. In these situations, as has been the case previously, an error message will be sent to the API client with error code=354.

API Market and Historical Data Farm Connection Information Messages.

Starting with TWS version 850 (server version 22), TWS sends error messages to API clients informing them of the status of the various market and historical data connections it knows of. These messages are as follows:

2103 A market data farm is disconnected.

2104 A market data farm is connected.

2105 A historical data farm is disconnected.

2106 A historical data farm is connected.

2107 A historical data farm connection has become inactive but should be available upon demand.

2108 A market data farm connection has become inactive but should be available upon demand.

Note that when a farm is disconnected it may still be available, or shortly become available, as is the case following a temporary Internet disconnect. Also note that TWS itself attempts re-connection when this kind of event occurs, which can be observed in TWS during an Internet disconnect. In addition, these messages all end with a colon (“:”), followed by the name of the market or historical data farm they pertain to. And, the first two characters in any farm name indicate the portion of the world that farm covers, either “us,” “eu,” or “hk.” So, if the Hong Kong (Asia) market data farm is down, market data requests to United States or European farms should still succeed. Finally, double-clicking on TWS’s “Market Data” green light indicator will pop up a dialog informing the user of the status of TWS’s various market and historical data connections.

Improved API Historical Data Query Robustness and Status messages

Starting with TWS version 851 (server version 22), the robustness of API historical queries with regard to Internet or HMDS server disconnects has been improved. Specifically, when an Internet or HMDS disconnect occurs, TWS repeatedly attempts to reconnect. Upon reconnection, queries that were interrupted will be automatically re-requested and, upon success, will receive their entire result set. HMDS connectivity has been implemented this way so that events like 10 second Internet disconnects (which happen frequently) have no impact on TWS charting or API historical data queries ultimately succeeding. If during or after a disconnect, a previous request is re-tried with the same ticker before the initial query completes, TWS will generate a duplicate ticker ID error, as the previous attempt is still being processed. Once the initial query completes or generates an HMDS error, the ticker can be re-used.

In TWS version 851 (server version 22) and earlier, API error code 162 was used to send both historical data query errors and informational messages. Starting with TWS version 852 (server version 23), and going forward, API error code 162 will mean that an HMDS query error occurred, an example being that data was requested in the future and therefore nothing will be returned. HMDS informational messages such as "HMDS server disconnect occurred. Attempting reconnection..." will be moved from error code 162 to new error code 165. This will enable an API client to differentiate between errors and informational messages without it needing to parse the error message text. Note that it is possible for the API client to receive partial HMDS data before an HMDS error message is generated, and that informational messages can happen at any time, and, due to re-querying upon reconnection, never imply that a failure has occurred.

In TWS version 851 (server version 22) and going forward, these are the possible 162 (and future 165) message contents:

ERRORS: (always code=162)

- Messages generated by HMDS itself. TWS does not know ahead of time what their content will be. An example is “No market data permissions for LIFFE FUT.”

- HMDS query returned no data: + description

- TWS exited during processing of HMDS query.

INFORMATIONAL: (TWS 851 and before, code=162. TWS 852 and on, code=165)

- HMDS server connection was successful.

- HMDS server disconnect occurred. Attempting reconnection...

- HMDS connection attempt failed. Connection will be re-attempted...

Complete API Support for Bond Trading.

Starting with API Version 8.60 (client version 22) and TWS version 852 (server version 23), all API technologies, whether socket or DDE-based, completely support BOND trading via the API. This is done via their correctly processing the following messages with the security type = BOND:

PLACE_ORDER

REQ_MKT_DATA

REQ_HISTORICAL_DATA

REQ_CONTRACT_DETAILS

REQ_MKT_DEPTH

In each of those messages, the bond’s CUSIP or ISIN number is sent in the symbol field.

BOND contracts have very different characteristics than those which the API has traditionally covered. Because of this, both socket and DDE-based API technologies have a new message, BOND_CONTRACT_DATA. For Excel/DDE users, the TwsDde.xls spreadsheet included in the API Beta 8.60 download has a new page and corresponding macro for bond contract details requests. For socket-based API technologies, including Java, the socket library .dll, and ActiveX control, there is a new bondContractDetails message. Its contents are:

STRING symbol, STRING secType, STRING cusip, double coupon, STRING maturity, STRING issueDate, STRING ratings, STRING bondType, STRING couponType, long convertible (1 if yes, 0 if no), long callable (1 if yes, 0 if no), long putable (1 if yes, 0 if no), STRING descAppend, STRING exchange, STRING curency, STRING marketName, STRING tradingClass, long conId, double minTick, STRING orderTypes, STRING validExchanges.

Price Magnifier Added to Socket API Contract Details Messages.

Starting with TWS version 852 (server version 23) and API Version 8.60 (client version 22), when API clients request the details of an existing contract, all socket-based API technologies, including the socket client library, ActiveX, and Java, will receive a new version 2 of the CONTRACT_DATA message, it containing the contract’s price magnifier. This integer value is what the price of the contract as expressed in its native currency is multiplied by to get its display price. For example, many British stocks trade in pence. Their price multipliers are 100. The Z FTSE 100 Index futures contract that trades on LIFFE also has a price multiplier of 100. The price multiplier of all US stocks is 1, reflecting the fact that they are quoted in dollars.

Price Magnifier Applied to EXECUTION_DATA Execution Prices.

Starting with TWS version 852 (server version 23) and API Version 8.60 (client version 22), the execution price reported to DDE-based and socket-based API clients (via the EXECUTION_DATA message) has the price multiplier applied to it. This causes execution prices on such contracts as the Z on LIFFE to be reported to the API in index points and not GBP. This is of value because it causes all executions prices to be reported consistently with market data, historical data, and the price at which the order was placed. Note that this adjustment will not be made when sending executions to API socket clients with client version 21 or lower.

Exercising Options from the API for Active X, Socket Library, and Java Clients

Starting with API Version 8.52 (client version 20) and TWS version 849 (server version 21) all socket-based API technologies, including the socket client library, ActiveX, and Java, have the ability to exercise and lapse options via the new exerciseOptions() method. For Java (with the socket client library having an analogous method), the new method signature is:

void exerciseOptions(int tickerId, Contract contract, int exerciseAction, int exerciseQuantity, String account, int override);

For ActiveX, it is this (the significant difference being that the account is a property of the ActiveX control and not a parameter to the method):

void exerciseOptions(long id, BSTR symbol, BSTR secType, BSTR expiry, double strike, BSTR right, BSTR multiplier, BSTR exchange, BSTR curency, long exerciseAction, long exerciseQuantity, long override);

The “exerciseAction” parameter can have two values: 1 for exercise, and 2 for lapse. If no multiplier is specified, a default of 100 is assumed. If the “override” parameter is non-zero, exercise instructions will be processed even if the option is out-of-the-money, and lapse instructions will be processed even if the option is in-the-money. Please note that “SMART” is not an allowed exchange in exerciseOptions() calls, and that TWS does a moneyness request for the position in question whenever any API initiated exercise or lapse is attempted.

Expanded Historical Data Queries

Since its introduction in API version 8.4 and TWS version 843.0 (client version 18 and server version 16, respectively), all socket-based API technologies, including the socket client library, ActiveX, and Java, have had the ability to extract historical data going back 24 hours for any valid contract or combo. This ability has been expanded in API Version 8.51 (client version 20) and TWS version 848 (server version 20) to allow queries of up to one week in duration, which can end at any date and time during the past six months. For this purpose, the reqIntradayData method has been renamed to reqHistoricalData(), which now sends a new version 3 of the message. The messages TWS sends in response to these queries have been renamed HISTORICAL_DATA messages, with their format unchanged. As has always been the case with API historical data queries, data is returned in bars of a nature very similar to the bars in TWS charts, with the final bar returned in response to any reqHistoricalData() request having a start time value of “finished.” This allows an API application to know when its query has completed. Finally, it remains the case that only one request for historical data can be in process at any given time.

The signature of the reqHistoricalData() method is:

reqHistoricalData(long id, String symbol, String secType, String expiry, double strike, String right, String multiplier, String exchange, String curency, String endDateTime, String durationStr, long barSizeSetting, String whatToShow, long useRTH, long formatDate)

The “endDateTime” parameter accepts a string in the form yyyymmdd HH:mm:ss, with a time zone optionally allowed after a space at the end of the string. At the time of this release, “20050701 18:26:44 GMT” is a legal value for this parameter (though it will not be six months later!)

The “durationStr” time span covered by a reqHistoricalData() request is specified via an integer followed by a space, followed by one of these units: S (for seconds), D (for days), or W (for weeks). If no unit is given, seconds is assumed.

The “barSizeSetting” specifies the size of the bars that will be returned (within limits imposed by IB’s servers and TWS). These eleven values are allowed:

Bar Size
Parameter Value
1 sec 1
5 sec 2
15 sec 3
30 sec 4
1 minute 5
2 minutes 6
5 minutes 7
15 minutes 8
30 minutes 9
1 hour 10
1 day 11

The “whatToShow” parameter determines the nature of the data extracted , with allowable values being “TRADES,” “MIDPOINT,” “BID,” “ASK,” or “BID_ASK.” Bars of the first four types contain the start time, open, high, low, close, volume, and weighted average price during the time slice in question. The contents of bars returned in response to a BID_ASK query differ from those returned by the other query types, in that the open and close values are actually the time weighted average bid, and time weighted average offer, respectively. This makes these bars identical in nature to TWS’s “BID_ASK” candlestick chart bars.

Two additional parameters to reqHistoricalData() calls are “useRTH” and “formatDate.” If useRTH is set to 0, all data available during the time span requested is returned, even data bars covering time intervals where the market in question was outside of its “Regular Trading Hours” (RTH). If useRTH has a non-zero value, only data within the “Regular Trading Hours” of the product in question is returned, even if the time span requested falls partially or completely outside of them. If “formatDate” = 1, dates applying to bars are returned in a format “yyyymmdd{space}{space}hh:mm:dd” - the same format already used in EXECUTION_DATA messages. If formatDate = 2, those dates are returned as a long integer specifying the number of seconds since 1/1/1970 GMT.

When TWS connects either to IB via the internet, or an API client application, it creates Java-based sockets of a predetermined size. If an API application intends to make historical data requests that return more than 1000 bars, it is recommended that TWS be configured to increase the sizes of the API socket buffer. This can be done in the “settings.xml” file in the user’s Jts directory. It is important that TWS not be running when its settings.xml file is manually modified. In the <SystemSettings> XML element, the <apiSocketBufferSizes> elements can be used for this purpose. Adding this line to the <SystemSettings> element in settings.xml should suffice:

<apiSocketBufferSizes>500000</apiSocketBufferSizes>
Extended Open Order Messages

API Version 8.51 (client version 20) and TWS version 848 (server version 20), now support a new version 10 open order message which is sent to all API technologies that do direct socket traffic with TWS, including the provided socket client library, and Java test client. That message, when sent to client version 20 API clients, contains two new fields, including the order’s parent ID and trigger method. ActiveX clients using the Tws.ocx ActiveX control provided with API 8.51 will receive those new fields in the OpenOrder4 event, as well as several others that have been added to it. The new OpenOrder4 event signature is:

void openOrder4(long id, BSTR symbol, BSTR secType, BSTR expiry, double strike, BSTR right, BSTR exchange, BSTR curency, BSTR localSymbol, BSTR action, long quantity, BSTR orderType, double lmtPrice, double auxPrice, BSTR tif, BSTR ocaGroup, BSTR account, BSTR openClose, long origin, BSTR orderRef, long clientId, long permId, BSTR sharesAllocation, BSTR faGroup, BSTR faMethod, BSTR faPercentage, BSTR faProfile, BSTR goodAfterTime, BSTR goodTillDate, long ocaType, int rthOnly, BSTR rule80A, BSTR settlingFirm, int allOrNone, long minQty, double percentOffset, int eTradeOnly, int firmQuoteOnly, double nbboPriceCap, long auctionStrategy, double startingPrice, double stockRefPrice, double delta, double stockRangeLower, double stockRangeUpper, int blockOrder, int sweepToFill, int ignoreRth, int hidden, double discretionaryAmt, long displaySize, long parentId, long triggerMethod, long shortSaleSlot, BSTR designatedLocation).

Server Version and Tws Connection Time Provided to the API

When TWS connects to IB, it receives the true time from IB’s servers, which is why TWS’ displayed time will often differ from that set locally on the client host. Upon connection, API Version 8.51 (client version 20) and TWS version 848 (server version 20) now provide the socket-based API application with the server version and TWS-known time of connection. Knowing the true time will be of use to API applications in tasks such as execution filtering by time and specifying precise end-times for historical data queries (see above). The TWS connection time is provided as a string with the format “yyyymmdd{SPACE}HH:mm:ss{SPACE}” followed by the local time zone.

In API technologies that do direct socket traffic with TWS, including the provided socket client library and Java test client, this new data can be extracted via the EClientSocket’s “TwsConnectionTime” and “serverVersion” methods. The ActiveX control makes the new data available to API applications via two new properties of the same name.

Time Zone String Specification in Open Order Messages

Good after time and good till date date-time strings are specified in the local time zone, in the format “yyyymmdd HH:mm:ss{SPACE}” followed by the local time zone. In areas such as Brisbane in Eastern Australia and Beijing in China, where ambiguities can occur regarding time zone strings such as “EST” and “CST,” the time zone is specified via a longer string that is unique to that area.

Support for all TWS extended order attributes when placing orders in all API technologies

Starting with API version 8.5 and TWS version 847.0 (client version 19 and server version 19, respectively), all API technologies and test clients, including DDE/Excel, the socket client library, ActiveX, Visual C++, and Java, allow orders to be placed that specify 16 new extended order attributes. DDE/Excel allows these and all extended order attributes to be specified in the TwsDde.xls spreadsheet’s “Extended Order Attributes” worksheet. The socket-based API technologies allow them to be specified via a new version 17 of the placeOrder method. The tws.ocx ActiveX control allows them to be specified as properties of the ActiveX control.

These newly supported extended order attributes, which are also supported by production TWS, are:

Attribute Possible Values
long ocaType Cancel on Fill with Block =1
Reduce on Fill with Block = 2
Reduce on Fill without Block = 3
int rthOnly (regular trading hours only) yes=1, no=0
String rule80A Individual = 'I'
Agency = 'A',
AgentOtherMember = 'W'
IndividualPTIA = 'J'
AgencyPTIA = 'U'
AgentOtherMemberPTIA = 'M'
IndividualPT = 'K'
AgencyPT = 'Y'
AgentOtherMemberPT = 'N'
String settlingFirm (pertains to institutional only)
int allOrNone yes=1, no=0
long minQty (minimum quantity)
double percentOffset (pertains to relative orders only)
int eTradeOnly (trade with electronic quotes) yes=1, no=0
int firmQuoteOnly (trade with firm quotes) yes=1, no=0
double nbboPriceCap (maximum SMART order distance from the NBBO)  
long auctionStrategy (pertains to BOX exchange only) match = 1
improvement = 2
transparent = 3
double startingPrice (pertains to BOX exchange only)
double stockRefPrice (pertains to BOX exchange only)
double delta (pertains to BOX exchange only)
double stockRangeLower (pertains to BOX exchange only)
double stockRangeUpper (pertains to BOX exchange only)
Extended order attributes and DDE message length limits

Prior to API version 8.5 and TWS version 847.0, if the user desired to leave an extended order attribute field blank, TWS would accept the string “EMPTY” (without the quotes) in its place. DDE imposes a 255 character limit on the item in a DDE message. The 16 new extended order attributes were causing messages to exceed that limit. Because of this, TWS version 847.0 allows the string “{}” (without the quotes) to indicate that the field is empty, and TwsDde.xls from API version 8.5 going forward sends empty fields using that string. This causes the length of an item string for a typical stock limit order to be around 170 characters instead of being around 270, which violated the limit.

Extended order attributes added to all socket-based API OPEN_ORDER messages

Starting with API version 8.5 and TWS version 847.0 (client version 19 and server version 19, respectively), all socket-based API technologies, including the socket client .dll library, ActiveX, and Java, have the 16 extended order attributes listed above added to OPEN_ORDER messages. The client version 19 socket client .dll library and Java test client receive the newly supported attributes directly as a part of the new version 9 of the OPEN_ORDER message. The ActiveX control receives them from the socket client .dll library, and then sends them to an ActiveX API client application via the new openOrder4 event. Its signature is described as follows:

void openOrder4(long id, BSTR symbol, BSTR secType, BSTR expiry, double strike, BSTR right, BSTR exchange, BSTR curency, BSTR localSymbol, BSTR action, long quantity, BSTR orderType, double lmtPrice, double auxPrice, BSTR tif, BSTR ocaGroup, BSTR account, BSTR openClose, long origin, BSTR orderRef, long clientId, long permId, BSTR sharesAllocation, BSTR faGroup, BSTR faMethod, BSTR faPercentage, BSTR faProfile, BSTR goodAfterTime, BSTR goodTillDate, long ocaType, int rthOnly, BSTR rule80A, BSTR settlingFirm, int allOrNone, long minQty, double percentOffset, int eTradeOnly, int firmQuoteOnly, double nbboPriceCap, long auctionStrategy, double startingPrice, double stockRefPrice, double delta, double stockRangeLower, double stockRangeUpper);

Visual Basic 6.0 has a limit on the number of parameters it will accept in an ActiveX event. This limit precluded adding support for the new openOrder4 event to the Visual Basic 6.0 API test client, and was the motivation for porting that test client to Visual Basic.NET, which imposes no such limit. The Visual Basic 6.0 API test client will still receive the previously existing openOrder3 event.

Support for subscribing to a limited number of market depth rows

Starting with API version 8.5 and TWS version 847.0 (client version 19 and server version 19, respectively), all socket-based API technologies, including the socket client library, ActiveX, and Java, have a new version 3 of the reqMktDepth() method. That new method has a new final parameter, it being the number of rows of market depth data that is being subscribed to. This new parameter allows the API client application to limit the number of rows of level 2 market depth data that are subscribed to, so that the CPU utilization of the API application remains manageable. During the trading day in the US, level 2 market depth data on heavily traded securities such as QQQQ can be several dozen rows deep. Prior to API 8.5, an ActiveX-based API client application attempting to subscribe to that volume of data would consume all available CPU, and not respond correctly to GUI events. Via limiting the number of rows subscribed to, as well as optimization work done on all socket-based API test clients, level 2 market depth data can be efficiently subscribed to by ActiveX-based API client applications, even Visual Basic 6.0. Note that the Visual Basic 6.0 test client’s display of that data is limited to seven rows simultaneously to optimize the performance of the test client, as Visual Basic 6.0 is not efficient at displaying real-time updates.

New Visual Basic.NET Test Client

As both Visual Basic.NET source code, and in compiled executable form, API 8.5 contains a Visual Basic.NET test client. This new application was ported from the previously existing and now deprecated Visual Basic 6.0 test client, and communicates with TWS via the API Beta 8.5 ActiveX control. It has two significant advantages over the Visual Basic 6.0 test client, they being more efficient display of level 2 market depth data, and the ability to receive the new openOrder4 event. When consuming 20 rows of level 2 market depth data, Visual Basic.NET has been found to be markedly more efficient than Visual Basic 6.0, even when Visual Basic 6.0 is in compiled form. During that scenario, Visual Basic.NET typically consumed about 1/4 as much CPU to process the same information and display almost three times more of it as real-time updates.

Given this significant gain in efficiency, as well as the ability to receive openOrder4 events, it is strongly recommended that Visual Basic 6.0 API applications be upgraded to Visual Basic.NET. As Microsoft describes on its Microsoft Developers Network website in an article called “Preparing Your Visual Basic 6.0 Applications for the Upgrade to Visual Basic .NET,” Visual Basic.NET has an Upgrade Wizard that will read a Visual Basic 6.0 project and do most of the work necessary to upgrade it to Visual Basic.NET. Once the wizard has completed, only small further modifications should be necessary to complete the upgrade. For more details see:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvb600/html/vb6tovbdotnet.asp

Extraction of intraday historical data for ActiveX, Socket Library, and Java API Clients

Starting with API version 8.4 and TWS version 843.0 (client version 18 and server version 16, respectively), all socket-based API technologies, including the socket client library, ActiveX, and Java, can extract intraday historical data going back 24 hours for any valid contract or combo. For this purpose, the API sends a new message, ReqIntradayData, with TWS responding with INTRADAY_DATA messages containing the requested data. Unlike market data requests, only one request for intraday data can be in process at any given time. The time span covered by the request is specified by an integer number of seconds. Data is returned in bars of a nature very similar to the bars in TWS charts, each bar containing the start time, open, high, low, close, volume, and weighted average price during the time slice in question. The final time slice has a start time value of "finished," allowing an API application to know when its query has completed. The time duration of time slices is determined by the length of time of the entire request, as is shown in this table:

Duration of request Time slice duration
<= 2000 seconds 1 second
2001 to 10000 seconds 5 seconds
10001 to 20000 seconds 10 seconds
20001 to 30000 seconds 15 seconds
30001 to 60000 seconds 30 seconds
60001 to 24 hours (86400 seconds) 60 seconds

The nature of the data extracted is governed by sending a string having a value of "TRADES," "MIDPOINT," "BID," or "ASK." Finally, a ReqIntradayData parameter exists called "useRTH." If it is set to 0, all data available during the time span requested is returned, even data bars covering time intervals where the market in question was illiquid. If useRTH has a non-zero value, only data within the "Regular Trading Hours" of the product in question is returned, even if the time span requested falls partially or completely outside of them.

When TWS connects either to IB via the internet, or an API client application, it creates Java-based sockets of a predetermined size. If an API application intends to make intraday historical data requests that return more than 1000 bars, it is recommended that TWS be configured to increase the sizes of the buffers in both sockets. This can be done in the "settings.xml" file in the user's Jts directory. It is important that TWS not be running when its settings.xml file is manually modified. In the <SystemSettings> XML element, the <ccpSocketBufferSizes> and <apiSocketBufferSizes> elements can be used for this purpose. Adding these two lines to the <SystemSettings> element in settings.xml should suffice:

<ccpSocketBufferSizes>500000</ccpSocketBufferSizes>
<apiSocketBufferSizes>500000</apiSocketBufferSizes>
Addition of "Good Till Date" to Open Order messages for ActiveX, Socket Library, and Java API Clients

Starting with API version 8.4 and TWS version 843.0 (client version 18 and server version 16, respectively), all socket-based API technologies, including the socket client library, ActiveX, and Java, have a "Good Till Date" field added to their open order messages. ActiveX clients will receive this field in their openOrder3 events, which have also had a "Good After Time" value added to them.


© 2001 Interactive Brokers LLC. All rights reserved. Sun, Sun Microsystems, the Sun Logo and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Excel is a trademark or registered trademark of Microsoft Corporation in the United States and/or other countries.