API Release Notes for build 8.85

The enhancements and modifications below are in build 8.85 of the TWS API. For clarification on any of the items listed, refer to the appropriate section in the Users Guide, or send us an email at Beta Support.

Volatility Orders from the API

TWS Version 857 introduced volatility trading of options, and a new order type, "VOL." What happens with VOL orders is that the limit price that is sent to the exchange is computed by TWS as a function of a daily or
annualized option volatility provided by the user. VOL orders can be placed for any US option that trades on the BOX exchange. VOL orders are eligible for dynamic management, a powerful new functionality wherein TWS can manage options orders in response to specifications set by the user.

Starting with API Version 8.80 (client version 24), and TWS Version 857 (server version 26), all socket-based API technologies, including the socket client library, ActiveX, and Java, fully support the volatility trading of options and the VOL order type.

All volatility orders have these parameters:

- Volatility: what the price is computed from via TWS's options analytics. For VOL orders, the limit price sent to an exchange is not editable, as it is the output of a function. Volatility is expressed as a percentage.

- Volatility Type: Set to 1 for Daily, or 2 for Annual.

- Reference Price Type: Set to 1 for Average of National Best Bid or Ask, or set to 2 for National Best Bid when buying a call or selling a put, and National Best Ask when selling a call or buying a put. The reference price is used to compute the limit price sent to an exchange (whether or not Continuous Update is selected), and for stock price range monitoring.

- Continuous Update: Whether TWS is supposed to update the order price as the underlier moves. If continuous Update is selected, the limit price sent to an exchange is modified by TWS if the computed price of the option changes enough to warrant doing so. This is very helpful in keeping the limit price sent to the exchange up to date as the underlier price changes.

- Stock Range Lower: If the underlier's reference price crosses below this price, TWS will cancel the order. Merely touching the stock range lower price does not cancel the order.

- Stock Range Upper: If the underlier's reference price crosses above this price, TWS will cancel the order. Merely touching the stock range upper price does not cancel the order.

TWS versions 857 (server version 26) and 858 (server version 27) also supported the boolean Delta Neutral VOL order parameter, which is deprecated in TWS 859 in favor of the more powerful Hedge Delta Order Type (see below):

- Delta-Neutral: Specifies whether TWS is supposed to do the corresponding delta trade upon full or partial execution of the option order. If delta neutral is selected, market orders in the underlier will be placed in response to executions to maintain delta-neutrality.

All parameters pertaining to VOL orders are also added to the open order messages sent to all socket-based API technologies, including the socket client library, ActiveX, and Java. ActiveX has those parameters added to the OpenOrder4 event. Note as always that the Visual Basic 6.0 test client is incapable of receiving openOrder4. For that and other reasons that include improved CPU performance when subscribed to large volumes of market data, upgrading from Visual Basic 6.0 to Visual Basic.NET continues to be strongly recommended.

Expanded Control of Hedge Delta Order Behavior

Starting with API Version 8.84 (client version 27), and TWS Version 859 (server version 28), VOL orders, whether placed via either DDE or socket-based API technologies such as Java, ActiveX, or the socket .dll,
have an expanded control over hedge delta order behavior. First, where before hedge delta was a boolean parameter that, if set to true, triggered the placement of delta hedging MKT orders upon full or partial execution of a VOL order, TWS 859 (server version 28) introduces the ability to specify the hedge delta order type and hedge delta aux price (if applicable), via these two new parameters:

- Hedge Delta Order Type: Specifies whether TWS is supposed to do the corresponding delta trade upon full or partial execution of the VOL order. If a hedge delta order type is specified, orders of that type in the
underlier will be placed in response to option executions to maintain delta-neutrality. The order types that are allowed depend upon the underlier. If the placement of a VOL order with no hedge delta orders is desired, NONE can be sent as the Hedge Delta Order Type. If LMT is specified, TWS will set the hedge delta order's limit price to be the reference price at the time of execution. This writer suggests REL and MTL as good candidates for delta hedging, as REL often leads to superior executions, while MTL if only partially filled becomes a limit order that can not move away from where the underlier was trading at execution time.

- Hedge Delta Aux Price: If a Hedge Delta Order Type is specified that requires an aux price (such as REL), it is specified in this parameter.

Option Computation Market Data Ticks

Starting with API Version 8.81 (client version 26), and TWS Version 858 (server version 27), three new market data ticks have been introduced, they being option model computations for bid, ask, and last option price ticks. Each of these ticks contain the TWS-computed option implied volatility and delta corresponding to any option market data price tick. These ticks are supported for all API technologies, including DDE and all socket-based API technologies, including the socket client library, ActiveX, and Java.

Note that in TWS versions 857 (server version 26) and 858 (server version 27), these ticks occurred only on initial market data subscription, and when the price of the option changed. TWS version 859 (server version 28) adds to that the re-computation and sending of those ticks whenever the underlier price changes as well. This gives the API application knowledge of the options NBBO implied volatility as well as NBBO prices.

Improvements to the Java Test Client

Starting with API Version 8.80, the following improvements have been made to the Java test client:

- It provides a new object, IBTextPanel, which is an easy-to-use scrolling window-based text display and text editing JPanel. It is used both in the Sample Frame to display tickers, server responses, and errors, and in the Financial Adviser dialog to edit Financial Advisor configuration XML. The SampleFrame.java source file shows its use.

- It provides a second new object, IBGridBagPanel, which is an easy-to-use JPanel for building GUIs. The FinancialAdvisorDlg.java source file shows three IBTextPanels being placed into an IBGridBagPanel in only
three simple lines of code.

- It no longer depends upon or supplies any objects in the com.borland.jbcl.layout package, including XYConstraints and XYLayout. Where those objects were used before, it now uses IBGridBagPanel.

Extensions to Socket-based API Market Scanner Subscription

As was introduced in API Version 8.70 (client version 23) and TWS version 854 (server version 24), all socket-based API technologies, including the socket client library, ActiveX, and Java, have the ability to subscribe to the same data that drives the TWS Market Scanner. API 8.80 (client version 24), and TWS version 856 (server version 25) introduced a version 2 of the reqScannerSubscription() method, which allows the specification of these two new parameters:

- Average Option Volume Above (Can leave empty)

- Scanner Setting Pairs (Such as "Annual,true". Can leave empty)

Scanner setting pairs are delimited by slashes, making this parameter open ended as further developments occur. The "Annual,true" pairing would cause the "Top Option Implied Vol % Gainers" scan to return annualized volatilities.

For Java and socket client library API clients, these two new values are added to the ScannerSubscription object. For ActiveX reqScannerSubscription() calls, which do not use the ScannerSubscription object, two additional parameters have been added for these values.

Further, API Version 8.81 (client version 26), and TWS Version 858 (server version 27) introduce the ability to set the stock type filter in API Market Scanner queries via the new version 3 of the reqScannerSubscription() method. The stock type filter is specified via a new stockTypeFilter parameter in the scanner subscription. At the time API Version 8.81 (client version 26) was released, recognized stock type filter values were the following:

- "ALL" (which excludes nothing)

- "STOCK" (which excludes ETFs)

- "ETF" (which includes ETFs)

Extensions to Socket-based API Historical Data Queries

Starting with TWS Version 858 (server version 27), socket-based API historical data queries can be done going back 1 year, and, new duration units have been added for them. The list of supported duration units is:

- S (seconds)

- D (days)

- W (weeks)

- M (months)

- Y (years)

As has always been the case, the HMDS server enforces restrictions on what bar sizes can be used and how many bars can be extracted for a given period and duration unit.

Socket-based API Historical Data Query End Records Contain Date Range Covered

Starting with TWS Version 858 (server version 27) and API Version 8.81 (client version 26), the final record returned by a socket-based API historical data query will be of this form: finished-{Start Date/Time}-{End
Date/Time}. An example of such a string is this:

finished-20060406 12:19:16-20060406 12:24:16

The addition of the dash-delimited start and end time strings makes it easy for the API application to ascertain and display the start and end times that a query covers.

Expanded Excel TwsDde.xls support for limit and aux prices.

Starting with API version 8.81 and going forward, the TwsDde.xls Excel spreadsheet will send limit and aux prices for a wider variety of order types than was previously supported. The new list of supported order types includes:

Limit prices: "LMT", "STPLMT", "REL", "LIT", "LOC", "PEGMKT", "TRAILLMT"

Aux prices: "STP", "STPLMT", "REL", "LIT", "MIT", "TRAIL", "TRAILLMT"

Redirection of order error popups due to server rejection.

Starting with TWS version 859 (server version 28) and going forward, TWS will have reduced error popups due to API orders being rejected by IB's server processing. Two examples of popups that will be eliminated are:

1) rejections such as an attempt to sell short a US stock when shorting that issue is prohibited by reg SHO.

2) rejections caused by incorrect place order parameters such as a non-existent symbol or exchange.

Instead, these errors will be re-directed to the API in error codes such as 200-203.

Settings file restore interrupts API going forward

Starting with TWS version 858 (server version 27) and going forward, when the user restores a settings file, any API socket connections will be broken, and any API DDE subscriptions will be interrupted. This is because the new settings file may or may not allow API connections, or may have different trusted IP addresses.

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