API Reference Guide September 2010 Updated through API Release 9.64 2010 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, Windows and Visual Basic (VB) are trademarks or registered trademarks of the Microsoft Corporation in the United States and/or in other countries. Any symbols displayed within these pages are for illustrative purposes only, and are not intended to portray any recommendation.

Contents
1 Overview .................................................................................. 13
About the APIs ................................................................................................ 14 Run the API through TWS ................................................................................. 15 Run the API through the IB Gateway .................................................................. 16 Recommendations ........................................................................................... 18 API Logging .................................................................................................... 19 Example Log Entry ............................................................................. 20 API Request/Server Response Message Identifiers........................................... 20 Historical Data Limitations ................................................................................ 21 Valid Duration and Bar Size Settings for Historical Data Requests .............. 22 API Orders and TWS Precautionary Settings ........................................................ 23 API Order IDs.................................................................................................. 25 New Order Example ............................................................................. 25 Modified Order Example ....................................................................... 25 Requests for Quotes (RFQs) .............................................................................. 26 Submitting RFQs using the API.............................................................. 26 Delta-Neutral RFQs.............................................................................. 26 RFQ Samples ...................................................................................... 26 Requesting Real-Time Index Premium Data ......................................................... 27 Uninstalling and Re-installing the TWS API Software on Windows ........................... 28

DDE for Excel............................................................................ 29

Getting Started with the DDE for Excel API.......................................................... 30 Download the API Components and Spreadsheet............................................. 30 Configure the Application to Support API Components ..................................... 31 Open the Sample Spreadsheet...................................................................... 33 Using the DDE for Excel Sample Spreadsheet ...................................................... 34 Tickers Page ................................................................................................... 35 Using the Tickers Page ................................................................................ 35 Tickers Page Toolbar Buttons........................................................................ 38 Basic Orders Page............................................................................................ 39 Placing Orders ............................................................................................ 40

API Reference Guide

Contents

Placing a Combination Order ........................................................................ 41 Supported Order Types................................................................................ 43 Order Attributes ......................................................................................... 44 Basic Orders Page Toolbar Buttons ................................................................ 45 Extended Order Attributes Page ......................................................................... 46 Manually Program Extended Order Attributes.................................................. 47 Apply Extended Order Attributes to Individual Orders and Groups of Orders........ 47 Extended Order Attributes............................................................................ 48 Conditional Orders Page ................................................................................... 52 Setting Up Conditional Orders....................................................................... 52 Conditional Order Examples ......................................................................... 53 If-Filled order ..................................................................................... 53 Price-change order .............................................................................. 54 Conditional Orders Page Toolbar Buttons........................................................ 55 Advanced Orders Page ..................................................................................... 56 Placing a Bracket Order ............................................................................... 57 Placing a Volatility Order.............................................................................. 58 Placing a Trailing Stop Limit Order ................................................................ 59 Placing a Scale Order .................................................................................. 60 Placing a Relative Order............................................................................... 61 Advanced Orders Page Toolbar Buttons.......................................................... 62 Open Orders Page............................................................................................ 63 Viewing Open Orders................................................................................... 64 Open Orders Tab Toolbar ............................................................................. 64 Executions Page .............................................................................................. 65 Viewing Executions ..................................................................................... 65 Executions Page Toolbar Buttons .................................................................. 66 Executions Reporting Page ................................................................................ 67 Running Execution Reports .......................................................................... 68 Account Page .................................................................................................. 69 Using the Account Page ............................................................................... 70 Account Page Values ................................................................................... 71 Account Page Toolbar Buttons ...................................................................... 75 ................................................................................................................ 75 Portfolio Page.................................................................................................. 76 Viewing Your Portfolio ................................................................................. 76

API Reference Guide

ii

Contents

Portfolio Page Toolbar Buttons ...................................................................... 77 Historical Data Page ......................................................................................... 78 Viewing Historical Data ................................................................................ 79 Historical Data Page Query Specification Fields ............................................... 81 Historical Data Page Toolbar Buttons ............................................................. 83 Market Scanner Page ....................................................................................... 84 Starting a Market Scanner Subscription ......................................................... 85 Market Scanner Parameters ......................................................................... 85 Available Market Scanners ........................................................................... 87 Market Scanner Page Toolbar Buttons............................................................ 91 Contract Details Page ....................................................................................... 92 Requesting Contract Details ......................................................................... 92 Contract Details Page Toolbar Buttons ........................................................... 93 Bond Contract Details Page ............................................................................... 94 Requesting Bond Contract Details ................................................................. 94 Bond Contract Details Page Toolbar Buttons ................................................... 95 Market Depth Page .......................................................................................... 96 Using the Market Depth Page ....................................................................... 97 Market Depth Page Toolbar Buttons............................................................... 98 Advisors Page ................................................................................................. 99 Allocating Shares to a Single Account .......................................................... 100 Placing an Order using an FA Account Group and Method ............................... 101 Placing an Order using an Allocation Profile .................................................. 102 Advisors Page Toolbar Buttons.................................................................... 103 DDE for Excel API Reference ........................................................................... 104 Viewing the Code...................................................................................... 104 Modules................................................................................................... 105 Named Ranges ......................................................................................... 105 Macros .................................................................................................... 106 DDE Syntax for Excel ................................................................................ 107

ActiveX ................................................................................... 113

Linking to the Application using ActiveX ............................................................ 114 Registering Third-Party ActiveX Controls ........................................................... 115 Running the ActiveX API on 64-bit Windows XP Systems ..................................... 115 Using the Visual Basic Sample Program ............................................................ 116

API Reference Guide

iii

Contents

ActiveX Methods ............................................................................................ 117 connect()................................................................................................. 119 disconnect()............................................................................................. 119 reqMktDataEx() ........................................................................................ 119 reqMktData() ........................................................................................... 120 reqMktData2() ......................................................................................... 121 cancelMktData() ....................................................................................... 122 calculateImpliedVolatility()......................................................................... 122 cancelCalculateImpliedVolatility()................................................................ 122 calculateOptionPrice() ............................................................................... 122 cancelCalculateOptionPrice() ...................................................................... 123 placeOrderEx() ......................................................................................... 123 placeOrder() ............................................................................................ 123 placeOrder2() .......................................................................................... 126 cancelOrder() ........................................................................................... 127 reqOpenOrders() ...................................................................................... 128 reqAllOpenOrders() ................................................................................... 128 reqAutoOpenOrders() ................................................................................ 128 reqExecutionsEx()..................................................................................... 128 reqExecutions() ........................................................................................ 128 reqIds() .................................................................................................. 129 reqContractDetailsEx() .............................................................................. 129 reqContractDetails().................................................................................. 130 reqContractDetails2() ................................................................................ 131 reqMktDepthEx() ...................................................................................... 131 reqMktDepth() ......................................................................................... 132 reqMktDepth2()........................................................................................ 133 cancelMktDepth() ..................................................................................... 133 addComboLeg()........................................................................................ 134 clearComboLegs()..................................................................................... 135 reqNewsBulletins().................................................................................... 135 cancelNewsBulletins() ............................................................................... 135 setServerLogLevel() .................................................................................. 135 reqManagedAccts() ................................................................................... 136 reqAccountUpdates()................................................................................. 136 requestFA() ............................................................................................. 136

API Reference Guide

iv

Contents

replaceFA() .............................................................................................. 137 reqHistoricalDataEx() ................................................................................ 138 reqHistoricalData() ................................................................................... 141 exerciseOptionsEx() .................................................................................. 143 exerciseOptions() ..................................................................................... 144 reqScannerParameters()............................................................................ 144 reqScannerSubscriptionEx() ....................................................................... 145 reqScannerSubscription() .......................................................................... 145 cancelHistoricalData() ............................................................................... 147 cancelScannerSubscription() ...................................................................... 147 reqRealTimeBarsEx()................................................................................. 147 reqRealTimeBars() .................................................................................... 148 cancelRealTimeBars() ................................................................................ 149 reqCurrentTime()...................................................................................... 149 createComboLegList() ............................................................................... 149 createContract() ....................................................................................... 150 createExecutionFilter() .............................................................................. 150 createOrder() ........................................................................................... 150 createScannerSubscription() ...................................................................... 150 createTagValueList.................................................................................... 150 createUnderComp() .................................................................................. 151 reqFundamentalData() .............................................................................. 151 cancelFundamentalData() .......................................................................... 151 ActiveX Events .............................................................................................. 152 tickPrice()................................................................................................ 153 tickSize()................................................................................................. 153 tickOptionComputation()............................................................................ 154 tickGeneric() ............................................................................................ 154 tickString() .............................................................................................. 154 tickEFP() ................................................................................................. 155 tickSnapshotEnd() .................................................................................... 155 orderStatus() ........................................................................................... 157 errMsg() .................................................................................................. 158 connectionClosed() ................................................................................... 158 openOrderEx() ......................................................................................... 159 openOrder1() ........................................................................................... 159

API Reference Guide

Contents

openOrder2() ........................................................................................... 160 openOrder3() ........................................................................................... 161 openOrder4() ........................................................................................... 163 updateAccountValue() ............................................................................... 168 updatePortfolioEx() ................................................................................... 169 updatePortfolio() ...................................................................................... 170 updateAccountTime() ................................................................................ 171 nextValidId()............................................................................................ 171 permId() ................................................................................................. 171 contractDetailsEx() ................................................................................... 172 contractDetails()....................................................................................... 172 contractDetailsEnd() ................................................................................. 173 execDetailsEx() ........................................................................................ 173 execDetails()............................................................................................ 174 execDetailsEnd() ...................................................................................... 175 updateMktDepth() .................................................................................... 175 updateMktDepthL2() ................................................................................. 176 updateNewsBulletin() ................................................................................ 176 managedAccounts() .................................................................................. 177 receiveFA() .............................................................................................. 177 historicalData() ........................................................................................ 177 bondContractDetails() ............................................................................... 179 scannerParameters()................................................................................. 180 scannerDataEx()....................................................................................... 180 scannerData() .......................................................................................... 180 scannerDataEnd() ..................................................................................... 181 realtimeBar() ........................................................................................... 181 currentTime()........................................................................................... 182 fundamentalData() ................................................................................... 182 ActiveX COM Objects...................................................................................... 183 IExecution ............................................................................................... 184 IExecutionFilter ........................................................................................ 184 IContract ................................................................................................. 186 IContractDetails ....................................................................................... 188 IComboLeg .............................................................................................. 189 IComboLegList ......................................................................................... 190

API Reference Guide

vi

Contents

IOrder..................................................................................................... 190 IOrderState ............................................................................................. 196 IScannerSubscription ................................................................................ 197 ITagValueList ........................................................................................... 198 ITagValue ................................................................................................ 198 IUnderComp ............................................................................................ 198 ActiveX Properties.......................................................................................... 199 Placing a Combination Order ........................................................................... 204 Example........................................................................................... 204

C++ ........................................................................................ 207

Linking to TWS using the TwsSocketClient.dll .................................................... 208 Using the C++ TestSocketClient Sample Program .............................................. 213 To run the pre-built sample application ........................................................ 213 To run the TestSocketClient program from Microsoft Visual Studio 2008 ........... 213 Class EClientSocket Functions ......................................................................... 215 EClientSocket() ........................................................................................ 215 eConnect() .............................................................................................. 216 eDisconnect()........................................................................................... 216 isConnected()........................................................................................... 216 reqMktData() ........................................................................................... 217 cancelMktData() ....................................................................................... 217 calculateImpliedVolatility()......................................................................... 217 cancelCalculateImpliedVolatility()................................................................ 218 calculateOptionPrice() ............................................................................... 218 cancelCalculateOptionPrice() ...................................................................... 218 placeOrder() ............................................................................................ 218 cancelOrder() ........................................................................................... 219 checkMessages() ...................................................................................... 219 reqOpenOrders() ...................................................................................... 219 reqAccountUpdates()................................................................................. 219 reqExecutions() ........................................................................................ 220 reqIDs() .................................................................................................. 220 reqContractDetails().................................................................................. 220 reqMktDepth() ......................................................................................... 220 cancelMktDepth() ..................................................................................... 221

API Reference Guide

vii

Contents

reqNewsBulletins().................................................................................... 221 cancelNewsBulletins() ............................................................................... 221 setLogLevel() ........................................................................................... 221 reqAllOpenOrders() ................................................................................... 221 reqAutoOpenOrders() ................................................................................ 222 reqManagedAccts() ................................................................................... 222 requestFA() ............................................................................................. 222 replaceFA() .............................................................................................. 223 reqHistoricalData() ................................................................................... 223 exerciseOptions() ..................................................................................... 225 reqScannerParameters()............................................................................ 225 reqScannerSubscription() .......................................................................... 225 cancelHistoricalData() ............................................................................... 226 cancelScannerSubscription() ...................................................................... 226 reqRealTimeBars() .................................................................................... 226 cancelRealTimeBars() ................................................................................ 227 reqCurrentTime()...................................................................................... 227 serverVersion() ........................................................................................ 227 TwsConnectionTime() ................................................................................ 227 reqFundamentalData() .............................................................................. 227 cancelFundamentalData() .......................................................................... 228 Class EWrapper Functions ............................................................................... 229 tickPrice()................................................................................................ 230 tickSize()................................................................................................. 230 tickOptionComputation()............................................................................ 231 tickGeneric() ............................................................................................ 231 tickString() .............................................................................................. 232 tickEFP() ................................................................................................. 232 tickSnapshotEnd() .................................................................................... 233 orderStatus() ........................................................................................... 234 error() .................................................................................................... 235 winError()................................................................................................ 235 connectionClosed() ................................................................................... 236 managedAccounts() .................................................................................. 236 openOrder()............................................................................................. 236 updateAccountValue() ............................................................................... 237

API Reference Guide

viii

Contents

updatePortfolio() ...................................................................................... 238 updateAccountTime() ................................................................................ 238 nextValidId()............................................................................................ 239 contractDetails()....................................................................................... 239 contractDetailsEnd() ................................................................................. 239 execDetails()............................................................................................ 239 execDetailsEnd() ...................................................................................... 240 updateMktDepth() .................................................................................... 240 updateMktDepthL2() ................................................................................. 240 updateNewsBulletin() ................................................................................ 241 receiveFA() .............................................................................................. 242 bondContractDetails() ............................................................................... 242 historicalData() ........................................................................................ 242 scannerParameters()................................................................................. 243 scannerData() .......................................................................................... 243 scannerDataEnd() ..................................................................................... 243 realtimeBar() ........................................................................................... 244 currentTime()........................................................................................... 244 fundamentalData() ................................................................................... 244 SocketClient Properties................................................................................... 245 Execution ................................................................................................ 246 ExecutionFilter ......................................................................................... 246 Contract .................................................................................................. 248 ContractDetails......................................................................................... 250 ComboLeg ............................................................................................... 251 Order ...................................................................................................... 252 OrderState............................................................................................... 256 ScannerSubscription ................................................................................. 257 UnderComp.............................................................................................. 258 Placing a Combination Order ........................................................................... 259 Example........................................................................................... 259

Java........................................................................................ 261
Linking to TWS using the Java API ................................................................... 262 Running the Java Test Client Sample Program ................................................... 265 Java Test Client Overview ............................................................................... 269

API Reference Guide

ix

Contents

Package ........................................................................................... 269 TestJavaClient Classes............................................................................... 269 Java API Overview ......................................................................................... 271 Java EClientSocket Methods ............................................................................ 272 EClientSocket() ........................................................................................ 273 eConnect() .............................................................................................. 273 eDisconnect()........................................................................................... 273 isConnected()........................................................................................... 273 reqMktData() ........................................................................................... 274 cancelMktData() ....................................................................................... 274 calculateImpliedVolatility()......................................................................... 274 cancelCalculateImpliedVolatility()................................................................ 275 calculateOptionPrice() ............................................................................... 275 cancelCalculateOptionPrice() ...................................................................... 275 placeOrder() ............................................................................................ 275 cancelOrder() ........................................................................................... 275 reqOpenOrders() ...................................................................................... 276 reqAccountUpdates()................................................................................. 276 reqExecutions() ........................................................................................ 276 reqContractDetails().................................................................................. 277 reqMktDepth() ......................................................................................... 277 cancelMktDepth() ..................................................................................... 277 reqNewsBulletins().................................................................................... 277 cancelNewsBulletins() ............................................................................... 278 setServerLogLevel() .................................................................................. 278 reqAllOpenOrders ..................................................................................... 278 reqAutoOpenOrders() ................................................................................ 278 reqManagedAccts() ................................................................................... 279 requestFA() ............................................................................................. 279 replaceFA() .............................................................................................. 279 reqScannerParameters()............................................................................ 280 reqScannerSubscription() .......................................................................... 280 cancelScannerSubscription() ...................................................................... 280 reqHistoricalData() ................................................................................... 281 cancelHistoricalData() ............................................................................... 282 reqRealTimeBars() .................................................................................... 283

API Reference Guide

Contents

cancelRealTimeBars() ................................................................................ 283 exerciseOptions() ..................................................................................... 284 reqCurrentTime()...................................................................................... 284 serverVersion() ........................................................................................ 284 TwsConnectionTime() ................................................................................ 284 reqFundamentalData() .............................................................................. 285 cancelFundamentalData() .......................................................................... 285 Java EWrapper Methods.................................................................................. 286 tickPrice()................................................................................................ 287 tickSize()................................................................................................. 288 tickOptionComputation()............................................................................ 288 tickGeneric() ............................................................................................ 289 tickString() .............................................................................................. 289 tickEFP() ................................................................................................. 289 tickSnapshotEnd() .................................................................................... 290 orderStatus() ........................................................................................... 291 error() .................................................................................................... 292 connectionClosed() ................................................................................... 293 managedAccounts() .................................................................................. 293 openOrder()............................................................................................. 293 updateAccountValue() ............................................................................... 294 updatePortfolio() ...................................................................................... 295 updateAccountTime() ................................................................................ 295 nextValidId()............................................................................................ 295 contractDetails()....................................................................................... 296 contractDetailsEnd() ................................................................................. 296 bondContractDetails() ............................................................................... 296 execDetails()............................................................................................ 296 execDetailsEnd() ...................................................................................... 297 updateMktDepth() .................................................................................... 297 updateMktDepthL2() ................................................................................. 298 updateNewsBulletin() ................................................................................ 298 receiveFA() .............................................................................................. 299 historicalData() ........................................................................................ 299 scannerParameters()................................................................................. 300 scannerData() .......................................................................................... 300

API Reference Guide

xi

Contents

scannerDataEnd() ..................................................................................... 300 realtimeBar() ........................................................................................... 301 currentTime()........................................................................................... 301 fundamentalData() ................................................................................... 301 Java SocketClient Properties ........................................................................... 302 Execution ................................................................................................ 303 ExecutionFilter ......................................................................................... 303 Contract .................................................................................................. 305 ContractDetails......................................................................................... 306 ComboLeg ............................................................................................... 307 Order ...................................................................................................... 309 OrderState............................................................................................... 314 ScannerSubscription ................................................................................. 315 UnderComp.............................................................................................. 316 Placing a Combination Order ........................................................................... 317 Example........................................................................................... 317

Advisors ................................................................................. 321

Financial Advisor Orders and Account Configuration............................................ 322 Excel DDE Support......................................................................................... 322 Support by Other API Technologies .................................................................. 322 Improved Financial Advisor Execution Reporting ................................................ 323 Allocation Methods for Account Groups ............................................................. 324 EqualQuantity Method ........................................................................ 324 NetLiq Method .................................................................................. 324 AvailableEquity Method ...................................................................... 324 PctChange Method............................................................................. 324

ActiveX for Excel .................................................................... 327

Getting Started with the ActiveX for Excel API ................................................... 328 Download the API Components and Spreadsheet........................................... 328 Running the ActiveX for Excel API on 64-bit Windows XP Systems ................... 329 Open the Sample Spreadsheet.................................................................... 329 Using the ActiveX for Excel Sample Spreadsheet ................................................ 330 General Page ................................................................................................ 331 General Page Toolbar Buttons..................................................................... 333

API Reference Guide

xii

Contents

Tickers Page ................................................................................................. 334 Using the Tickers Page .............................................................................. 334 Tickers Page Toolbar Buttons...................................................................... 336 Bulletins Page ............................................................................................... 337 Bulletins Page Toolbar Buttons.................................................................... 337 Market Depth Page ........................................................................................ 338 Using the Market Depth Page ..................................................................... 339 Market Depth Page Toolbar Buttons............................................................. 339 Basic Orders Page.......................................................................................... 340 Placing Orders .......................................................................................... 341 Placing a Combination Order ...................................................................... 342 Supported Order Types.............................................................................. 344 Basic Orders Page Toolbar Buttons .............................................................. 344 Conditional Orders Page ................................................................................. 345 Setting Up Conditional Orders..................................................................... 345 Conditional Order Examples ....................................................................... 346 If-Filled order ................................................................................... 346 Price-change order ............................................................................ 347 Conditional Orders Page Toolbar Buttons...................................................... 348 Advanced Orders Page ................................................................................... 349 Placing a Bracket Order ............................................................................. 351 Placing a Volatility Order............................................................................ 352 Placing a Trailing Stop Limit Order .............................................................. 353 Placing a Scale Order ................................................................................ 354 Placing a Relative Order............................................................................. 355 Advanced Orders Page Toolbar Buttons........................................................ 355 Extended Order Attributes Page ....................................................................... 356 Manually Program Extended Order Attributes................................................ 357 Apply Extended Order Attributes to Individual Orders and Groups of Orders...... 357 Open Orders Page.......................................................................................... 358 Viewing Open Orders................................................................................. 359 Open Orders Tab Toolbar ........................................................................... 359 Account Page ................................................................................................ 360 Using the Account Page ............................................................................. 360 Account Page Toolbar Buttons .................................................................... 362 Portfolio Page................................................................................................ 363

API Reference Guide

xiii

Contents

Viewing Your Portfolio ............................................................................... 363 Exercising Options .................................................................................... 363 Portfolio Page Toolbar Buttons .................................................................... 364 Executions Page ............................................................................................ 365 Viewing Executions ................................................................................... 366 Executions Page Toolbar Buttons ................................................................ 366 Historical Data Page ....................................................................................... 367 Viewing Historical Data .............................................................................. 368 Historical Data Page Query Specification Fields ............................................. 370 Historical Data Page Toolbar Buttons ........................................................... 372 Contract Details Page ..................................................................................... 373 Requesting Contract Details ....................................................................... 373 Contract Details Page Toolbar Buttons ......................................................... 374 Bond Contract Details Page ............................................................................. 375 Requesting Bond Contract Details ............................................................... 375 Bond Contract Details Page Toolbar Buttons ................................................. 376 Real Time Bars Page ...................................................................................... 377 Real Time Bars Page Toolbar Buttons .......................................................... 378 Market Scanner Page ..................................................................................... 379 Starting a Market Scanner Subscription ....................................................... 380 Market Scanner Parameters ....................................................................... 380 Available Market Scanners ......................................................................... 382 Market Scanner Page Toolbar Buttons.......................................................... 386 Fundamentals Page........................................................................................ 387 Fundamentals Page Toolbar Buttons ............................................................ 388 Advisors Page ............................................................................................... 389 Allocating Shares to a Single Account .......................................................... 390 Placing an Order using an FA Account Group and Method ............................... 391 Placing an Order using an Allocation Profile .................................................. 392 Advisors Page Toolbar Buttons.................................................................... 393 Log Page ...................................................................................................... 394

POSIX..................................................................................... 395
Running the POSIX Client on a Windows Machine ............................................... 396

API Reference Guide

xiv

Contents

Reference Tables .................................................................... 397

API Message Codes ........................................................................................ 398 Error Codes ...................................................................................... 398 System Message Codes ...................................................................... 407 Warning Message Codes..................................................................... 407 Tick Types .................................................................................................... 408 Generic Tick Types......................................................................................... 411 Using the SHORTABLE Tick......................................................................... 412 TAG Values for FUNDAMENTAL_RATIOS tickType ............................................... 413 Supported Order Types................................................................................... 419 Extended Order Attributes .............................................................................. 421 Available Market Scanners .............................................................................. 425 IBAlgo Parameters ......................................................................................... 429

API Reference Guide

xv

Contents

API Reference Guide

xvi

Overview

This chapter provides an overview of the APIs (Application Programming Interfaces) available, including the following topics:

About the APIs Run the API through TWS Run the API through the IB Gateway Recommendations API Logging Historical Data Limitations API Orders and TWS Precautionary Settings API Order IDs Requests for Quotes (RFQs) Requesting Real Time Premium Data Uninstalling the API Software

API Reference Guide

13

Overview About the APIs

About the APIs

We provide several APIs which you can use to link to our system and trade your IB account. The API allows you to connect through either the TWS or the IB Gateway. Connecting through the TWS requires that you have the application running, but also allows you to test and confirm that your API orders are working correctly. Connecting through the IB Gateway allows you to use the AIP without a large GUI application running, but does not provide an interface for you to test and confirm API activity. Regardless of the connection method you use, the API allows you to:

Run multiple sessions off the same IB login. View market data. Submit, modify, and cancel basic and advanced orders. View open orders. View updated status of your account balance and portfolio. View historical data and run market scanners.

To view syntax for specific functionality, see the DDE for Excel, ActiveX, C++ or Java topics in this guide. Customers with no programming expertise should begin with the DDE for Excel section, which uses an everyday Excel spreadsheet to link to TWS via the API. The API provides multiple development methods to connect, including:

The DDE component to link through Excel (for Windows platforms only). The ActiveX control to link through a Visual Basic and .NET application (on Windows platforms only). The Windows C++ socket client component to link through a C++ application (for Windows platforms). The Java API to link from a Java application (for all platforms). API topics are written for experienced programmers and provide little guidance for non-technical users.

Note:

To develop and test your API program, we recommend that you use the sample application and connect via TWS. Once you are satisfied that the API works as designed, you can use the GUI-less IB Gateway to connect, if you desire. To use the API components and view sample source code and spreadsheets 1 Install or upgrade the latest API and sample files from the IB website. On the Trading menu, select API Solutions, then click the IB API button. Click Download latest version under the appropriate OS column and install the program on your computer. Configure the application to support the API. Use the sample application to learn how to request market data, submit orders, etc. Customize the sample applications to meet your needs, or create your own application using described syntax and functionality.

2 3 4

API Reference Guide

14

Overview Run the API through TWS

Run the API through TWS

To run the API through TWS, you must always have your system running and it must be configured to use any of the API components. To enable API connection through TWS 1 2 Log into TWS. On the Configure menu, select API then select the check box for either Enable ActiveX and Socket Clients (ActiveX, C++ and Java API connections), and/or Enable DDE Clients (for DDE for Excel API connections only) to configure TWS for the appropriate API connection. You must have these settings enabled to connect to the API through TWS

You can also select Global Configuration from the Configure menu to display the TWS API Configuration window, then make your selections and click OK. Only one API application can access a single instance at a time. With the exception of DDE for Excel, the API application does not need to be running on the same computer on which the application is running.

Note:

API Reference Guide

15

Overview Run the API through the IB Gateway

Run the API through the IB Gateway

The IB Gateway provides a low-resource alternative to TWS for connecting to the IB trading system via the API. The gateway uses approximately 40% fewer system resources than TWS. However, the gateway is GUI-less, which means that you cannot view the API activity as you can when running TWS.

To log into the IB Gateway 1 2 3 4 From the Login menu on the IB web site, select IB Gateway. Select the API radio button. Log in using your IB username and password, just as you would when logging into TWS. Click Login. The Interactive Brokers Gateway box opens, displaying the connection status and gateway activity.

API Reference Guide

16

Overview Run the API through the IB Gateway

You must have the IB Gateway running while connected to the API.

API Reference Guide

17

Overview Recommendations

Recommendations
Before you use our TWS API to create your own customized trading application, you should consider the following important recommendations:

Placing Orders by Conid - When you place an order by conid, you must provide the conid AND the exchange. If you provide extra fields when placing an order by conid, the order may not work. Order IDs - Each order you place must have a unique Order ID. We recommend that you increment your own Order IDs to avoid conflicts between orders placed from your API application. Please test your API application with an IB Paper Trading account to catch and avoid any errors. You can request a Paper Trading account from Account Management.

API Reference Guide

18

Overview API Logging

API Logging
As client requests are processed (both system and API clients) it logs certain information to its 'log.txt' log file, which is located in the installation directory. The purpose of this file is to help resolve problems by providing some insight into the state of the program before the problem occurred. API clients can specify how detailed they want these log entries to be by setting the log level. Log levels are:

1 = SYSTEM (least detailed) 2 = ERROR (default, if no level is specified) 3 = WARNING 4 = INFORMATION 5 = DETAIL (most detailed) Setting the log level to 5 will have a performance overhead, and should only be used when trying to resolve an issue.

Note:

The log entries for API requests have the format: [ClientID:ClientVersion:ServerVersion:ClientType:Request:Response:Versio n:LogEntryType] where:

ClientID is the clientId used when connecting. ClientVersion identifies the client's request stream (for internal use). ServerVersion identifies the server's response stream (for internal use). ClientType is the type of API connection: DDE = 0, Socket = 1. Request: If greater than 0, indicates that the log entry is the result of an API client request. The number shown is the request identifier as listed in the "Outgoing Request Identifiers" section below. Response: If greater than 0, indicates that the log entry is the result of a server response to the API. The number shown is the response identifier as listed in the "Incoming Response Identifiers" section below. Version identifies the version of the request or response message. The version changes when the message format changes. LogEntryLevel identifies the type of log entry (i.e. the log level as listed above)

API Reference Guide

19

Overview API Logging

Example Log Entry [0:9:9:1:1:0:3:DET]Socket request [3;52;IBM;STK;null;0.0;2;SMART;null;null] From this example, we can tell that a socket client with clientId=0 connected and made a request for market data. The version of the market data request, which was 3,implies what data should have been sent.

API Request/Server Response Message Identifiers

Outgoing Request Identifiers 1 = Request Market Data 2 = Cancel Market Data 3 = Place Order 4 = Cancel Order 5 = Request Open Orders 6 = Request Account Data 7 = Request Execution Reports 8 = Request Next Order Id 9 = Request Contract Details 10 = Request Market Depth 11 = Cancel Market Depth 12 = Request News Bulletins 13 = Cancel News Bulletins 14 = Set Server Log Level Note:

Incoming Response Identifiers 1 = Ticker Price 2 = Ticker Size 3 = Order Status 4 = Error Message 5 = Open Order 6 = Account Value 7 = Portfolio Value 8 = Account Update Time 9 = Next Valid Order Id 10 = Contract Details 11 = Execution Report Details 12 = NYSE Open Book Row Entry 13 = Level II Quotes Row Entry 14 = News Bulletin

This information, along with the various request/response message versions, can be found in the EClientSocket implementation file supplied with the API installation.

API Reference Guide

20

Overview Historical Data Limitations

Historical Data Limitations

Historical data requests are subject to the following limitations:

Historical data requests can go back one full calendar year. Each request is restricted to duration and bar size values that return no more than 2000 bars (2000 bars per request).

All of the API technologies support historical data requests. However, requesting the same historical data in a short period of time can cause extra load on the backend and subsequently cause pacing violations. The error code and message that indicates a pacing violation is: 162 - Historical Market Data Service error message: Historical data request pacing violation The following conditions can cause a pacing violation:

Making identical historical data requests within 15 seconds; Making six or more historical data requests for the same Contract, Exchange and Tick Type within two seconds.

Also, observe the following limitation when requesting historical data:

Do not make more than 60 historical data requests in any ten-minute period. For more information about historical data requests, see Viewing Historical Data in the DDE for Excel chapter, reqHistoricalDataEx() in the ActiveX chapter, reqHistoricalData() in the C++ chapter, and reqHistoricalData() in the Java chapter.

Note:

API Reference Guide

21

Overview Historical Data Limitations

Valid Duration and Bar Size Settings for Historical Data Requests The following table lists valid duration and bar size settings for API historical data requests. Please note that these are only guidelines. Duration 1Y 6M 3M 1M 1W 2D 1D 14400 S (4 hrs) 7200 S (2 hrs) 3600 S (1 hr) 1800 S (30 mins) 960 S (15 mins.) 300 S (5 mins) 60 S ( 1 min) Bar Size 1 day 1 day 1 day 1 day, 1 hour 1 day, 1 hour, 30 mins, 15 mins 1 hour, 30 mins, 15 mins, 3 mins, 2 mins, 1 min 1 hour, 30 mins, 15 mins, 5 mins 3 mins, 2 mins, 1 min, 30 secs 1 hour, 30 mins, 15 mins, 5 mins 3 mins, 2 mins, 1 min, 30 secs, 15 secs 1 hour, 30 mins, 15 mins, 5mins 3 mins, 2 mins, 1 min, 30 secs, 15 secs, 5 secs 15 mins, 5 mins 3 mins, 2 mins, 1 min, 30 secs, 15 secs, 5 secs, 15 mins, 5 mins 3 mins, 2 mins, 1 min, 30 secs, 15 secs, 5 secs, 1 secs 5 mins 3 mins, 2 mins, 1 min, 30 secs, 15 secs 5 secs 1 secs 3 mins, 2 mins, 1 min, 30 secs, 15 secs, 5 secs, 1 secs 30 secs, 15 secs, 5 secs, 1 secs

API Reference Guide

22

Overview API Orders and TWS Precautionary Settings

API Orders and TWS Precautionary Settings

By default, Trader Workstation includes precautionary settings as part of its Order Presets on the TWS Configuration page. Precautionary settings are safety checks and include percentage, size limit, total value and number of ticks. They can be modified in TWS for most instrument types (stocks, options, and so on) or for specific tickers.

If your API order violates these settings, you will receive an error message. For example, the default precautionary setting for order size is 500. If you place an order for 1000 shares of stock, you will receive an error message indicating that the size specified violates the constraints specified in the default order settings. TWS precautionary settings apply to API orders placed from ALL API technologies. You can override the precautionary settings by doing one of the following: In TWS:

On the Configure menu, select API then All API Settings. Select the Bypass Order Precautions for API Orders check box, then click OK. All of your API orders will ignore the precautionary settings in TWS. In the Order Presets, enter higher precautionary setting limits for the desired instrument types and or tickers. On the Configure menu, select Order then select Order Presets. Select the instrument type or ticker on the left, enter the desired limits in the Precautionary Settings section of the page, then click OK.

API Reference Guide

23

Overview API Orders and TWS Precautionary Settings

In the IB Gateway:

From the Configure menu, select Settings. Select the Bypass Order Precautions for API Orders checkbox and click OK. All of your API orders will ignore the precautionary settings you had set via a TWS session.

API Reference Guide

24

Overview API Order IDs

API Order IDs

When you place a new order using the API, the order id number must be greater than the previously used numbers. For example, if you place an order with an Order ID of 11, the next order you place should have an Order ID of at least 12. So when you place a new order, the order id must be greater than the previously used order id number. New Order Example In this example, a user is going to place two orders for IBM stock. The first order is a BUY order for 200 shares and set the limit price to $85.25. The second order will be an order to sell 100 shares with the limit price set to $84.25. In this example, the first order is tagged with an Order ID of 1: .placeOrder(1, IBM, BUY, $85.25, 200) Now, user can place a second order. This order is assigned an Order ID of 2: .placeOrder(2, IBM, SELL, $84.25, 100) Modified Order Example To modify an order using the API, resubmit the order you want to modify using the same order id, but with the price or quantity modified as required. Only certain fields such as price or quantity can be altered using this method. If you want to change the order type or action, you will have to cancel the order and submit a new order. In this example, a user initially decides to buy 100 shares and sets the limit price to $85.25. Then, customer wants to modify the same order and change the limit price to $86.25. Note that the first order is assigned an Order ID of 3: .placeOrder(3, IBM, BUY, $85.25, 100) You can now modify the limit price for this order by calling the same .placeOrder method and using the same Order ID of 3, with the limit price modified to $86.25 .placeOrder(3, IBM, BUY, $86.25, 100)

API Reference Guide

25

Overview Requests for Quotes (RFQs)

Requests for Quotes (RFQs)

RFQs from the IB Options Trading Desk allow you to get quotes for large orders from IB affiliate Timber Hill. Quotes are available for US equity and index options, and major European and Asian index options and combinations. For a complete list, please contact the IB Options Trading Desk. RFQs from the IB Options Trading Desk are available only to users who have access to these specific areas. Please contact the IB Options Trading Desk if you are interested in participating. Submitting RFQs using the API Submit an RFQ by submitting an order with an order type of QUOTE. In the response, tickPrice()/tickSize() are called with the tickerId matching the orderId of the RFQ. Use orderId's with a relatively high number to avoid clashes. Additional space is required for non-RFQ tickerIds. Market data for an RFQ is received until the user cancels the RFQ or the RFQ is canceled by the server. The server normally cancels an RFQ when it expires (approximately 1 minute) or if the RFQ request is invalid and/or for an unsupported product. Delta-Neutral RFQs Submit Delta-Neutral RFQs by creating a combo order, even if a single contract must be hedged, and filling up and attaching an UnderComp structure to a contract underComp field. In the UnderComp structure, you must specify the conId of the hedge contract. The price and delta fields can be left empty (0). Upon accepting a Delta-Neutral DN RFQ, the server sends a deltaNeutralValidation() message with the UnderComp structure. If the delta and price fields are empty in the original request, the confirmation will contain the current values from the server. These values are locked when the RFQ is processed and remain locked until the RFQ is canceled. RFQ Samples To learn more about submitting RFQs with the TWS API, look at the RFQ samples included in the 9.6 release of the API software. The samples are located in the samples/rfq folder in your API software installation folder. The SampleRFQ.java sample implements a small-state machine and shows how to submit RFQ's for:

EU Stocks US Futures US Stock Options EU Stock Options Calendar Spread for Index Option (Delta-Neutral) US Stock Option (Delta-Neutral) US Index Option (Delta-Neutral) EU Index Option (Delta-Neutral)

API Reference Guide

26

Overview Requesting Real-Time Index Premium Data

Requesting Real-Time Index Premium Data

You can request real-time Index Premium market data using the following APIs and API sample applications:

ActiveX (including the ActiveX API sample application) C++ (including the C++ API sample application) Java (including the Java API sample application) ActiveX for Excel

To request real-time Index Premium data, you must do the following:

Specify the Symbol, Security Type and Exchange. For example, INDU, IND and NYSE would get you Index Premium data for the Dow Jones Industrial Average.

The exchange must match the index for which you want data. You must use the generic tick type 162 (for Index Future Premium).

API Reference Guide

27

Overview Uninstalling and Re-installing the TWS API Software on Windows

Uninstalling and Re-installing the TWS API Software on Windows

If you encounter problems running the TWS API software on the Windows platform, you can uninstall and re-install the API software. Note: This procedure is usually only necessary when troubleshooting the most extreme API problems.

To uninstall and re-install the TWS API software on Windows 1 2 3 4 5 6 Open the Windows Control Panel, then open Add or Remove Programs. Select TWS Interoperability Components from the list of installed programs, then click Change/Remove. Select Automatic, then click Next to uninstall the TWS API software. In the Windows Explorer, delete the file TwsSocketClient.dll from the Windows\system32 folder. Reboot your computer. Re-install the TWS API software.

API Reference Guide

28

DDE for Excel

This chapter describes the DDE for Excel API, including the following topics:

Getting Started with the DDE for Excel API Using the DDE for Excel Sample Spreadsheet Viewing the Code DDE for Excel API Reference

DDE is an acronym for Dynamic Data Exchange, a Microsoft-created communication method that allows multiple applications that are running simultaneously to exchange data and commands. We use this protocol to link Excel with your running version of TWS or the IB Gateway, allowing you to view real-time market data (including market depth) manage orders and monitor your executions and account information using an Excel spreadsheet. The following figure shows the Tickers page in the Excel DDE API sample spreadsheet.

API Reference Guide

29

DDE for Excel Getting Started with the DDE for Excel API

Getting Started with the DDE for Excel API

We have created a sample DDE-linked Excel spreadsheet, TwsDde.xls, that you can use with your TWS to create a custom Excel application. It's easy to get started with the DDE for Excel API:

Download the API components and sample Excel spreadsheet. Ensure that either: the application server is running and that it is configured to support DDE, or the IB Gateway is running.

Open the spreadsheet and start using the DDE for Excel API.

The sample spreadsheet currently comprises several pages complete with sample data and action buttons that make it easy for you to get market data, send orders and view your activity.

Download the API Components and Spreadsheet

We recommending using the sample Excel spreadsheet that we provide as a starting point toward creating your own DDE for Excel API. Follow the steps below to download the sample spreadsheet. To install the sample DDE Spreadsheet 1 2 From the IB homepage, select API Solutions from the Software menu. Click the IB API icon, and on the API Software page, find the column appropriate to your operating system, click Download latest version. Note: Windows users can download the beta test version of the API by using the Windows Beta column, or revert to the previous production version by selecting Downgrade to Previous Version.

Save the installation program to your computer, and if desired, select a different directory. Click Save. Note that the API installation file is named for the API version; for example, InstallAX_960. Close any versions of TWS, the IB Gateway and Excel that you have running. Locate the API installation program you just saved to your computer, then double-click the file to begin the API installation. Follow the instructions in the installation wizard. By default, the sample DDE spreadsheet is saved to C:\IB_API_X_XX\Excel\TwsDde.xls, where X_XX is the API version number.

4 5 6

Before you can use the spreadsheet, you must have TWS running and configured to support the DDE API. You can also run the sample against the IB Gateway but we recommend you start by running TWS.

API Reference Guide

30

DDE for Excel Getting Started with the DDE for Excel API

Configure the Application to Support API Components

You must have your system running to use any of the API components. To configure the application to support accessing its functionality via the API 1 2 Run the application. On the Configure menu, select API then select the check box for Enable DDE Clients (for DDE for Excel API connections only) to configure TWS.

You can also select Global Configuration from the Configure menu to display the TWS API Configuration window, then make your selections and click OK.

API Reference Guide

31

DDE for Excel Getting Started with the DDE for Excel API

Note:

Note that not more than one API application can simultaneously access a single instance. With the exception of DDE, the API application does not need to be running on the same computer on which the application is running.

API Reference Guide

32

DDE for Excel Getting Started with the DDE for Excel API

Open the Sample Spreadsheet

After you have downloaded the sample spreadsheet and configured the application to allow the DDE for Excel API to link to it, open the spreadsheet and save it as your personal file. To open the sample spreadsheet 1 Go to the API installation folder in which the Excel API sample spreadsheet was installed (typically C:\IB_API_X_XX\Excel, where X_XX is the API version number) and double-click TwsDde.xls. In the macro warning message box, click Enable Macros. If you receive a message asking if you want to link to information in another worksheet, click Yes. Note: To use the spreadsheet macros, your Excel macro security must be set to Medium or Low. If you cannot open the spreadsheet or if the macros don't work, you need to modify your macro security level. In Microsoft Excel 2007, click the Microsoft Office Button, click Excel Options, and then click Trust Center in the Excel Options window. In the Trust Center, click Macro Settings, then change your settings as required. In previous versions of Excel, select Macro from the Tools menu, and then select Security. Set security to Medium or Low. 3 In the User Name field in the Which Trader Workstation? area, type your account user name. Note that you must type your User Name on each page of the worksheet to properly connect.

We recommend using this spreadsheet as the starting point for your API application. This means that when new features are added, you will need to cut and paste your information from your Excel spreadsheet to the newly released sample spreadsheet, and resave the application as your own.

API Reference Guide

33

DDE for Excel Using the DDE for Excel Sample Spreadsheet

Using the DDE for Excel Sample Spreadsheet

The DDE for Excel API sample spreadsheet, TwsDde.xls, includes the following pages (tabs): Page Tickers Description Lets you set up your ticker lines and request market data. You can view market data for all asset types including EFPs and combination orders. Lets you send and modify orders, set up combination orders and EFPs, and request open orders. Used in conjunction with the Basic Orders, Advanced Orders, Conditional Orders and Advisors pages, this page lets you change the time in force, create Hidden or Iceberg orders and apply many other order attributes. Lets you create an order whose submission is contingent on other conditions being met, for example an order based on a prior fill. Shows you all transmitted orders, including those that have been accepted by the IB system, and those that are working at an exchange. Lets you send and modify advanced orders types that require the use of extended order attributes, such as Bracket, Scale and Trailing Stop Limit orders. Lets you view all execution reports, and includes a filtering box so you can limit your results. Linked to the Executions page, this page lets you run four different types of execution reports. Provides up to date account information and displays your portfolio. Displays all your current positions. Request historical data for an instrument based on data you enter in a query. Subscribe to TWS market scanners. Lets you collect contract-specific information you will need for other actions, including the conid and supported order types for a contract Lets you collect bond contract-specific information you will need for other actions, including bond coupon and maturity date. Lets you view market depth for selected quotes. Lets Financial Advisors send and modify FA orders.

Basic Orders Extended Order Attributes Conditional Orders Open Orders Advanced Orders Executions Executions Reporting Account Portfolio Historical Data Market Scanner Contract Details Bond Contract Details Market Depth Advisors Note:

Two additional pages, Old Style Executions and Old Style Account-Portfolio, represent functionality that has been replaced by other pages in the spreadsheet (Executions, Account and Portfolio pages). While these older pages are still included in the TswDde.xls sample spreadsheet, they are no longer documented in this API Users Guide and you should not use them.

API Reference Guide

34

DDE for Excel Tickers Page

Tickers Page
Use the Tickers page to:

Create market data (ticker) lines. Request market data. Create a combination order for options. Create market data line for Exchange for Physical (EFP) combination orders.

Using the Tickers Page

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To create a ticker using the Create Ticker button 1 2 3 4 Click the Tickers tab at the bottom of the spreadsheet. Click the line number to the left of a blank row to select the row. You must have a blank row selected to create a ticker line. Click the Create Ticker button on the toolbar and enter information in the Tickers box. Click OK.

API Reference Guide

35

DDE for Excel Tickers Page

For stocks, you only need to specify the Symbol, Type, Exchange (usually SMART), and Currency.

To create a ticker on the spreadsheet 1 2 Select a blank cell in the Symbol column and enter a symbol. Tab through the all contract description fields and enter data where necessary, for example if you are entering a stock ticker, you don't need values in the Expiry, Strike, P/C and Multiplier fields. Note: The Exchange field accepts the following values: SMART (for smart order routing), and any valid exchange acronym.

To request market data for a ticker 1 2 Select the ticker row for which you want to request market data by clicking the row number. Press Ctrl+R, or click Request Market Data on the toolbar. To get market data for a group of tickers, select multiple ticker rows while holding down the Shift key, then click Request Market Data multiple times until all rows are showing data.

API Reference Guide

36

DDE for Excel Tickers Page

To set the refresh rate The refresh rate determines how often the DDE link to TWS is refreshed. Type the refresh rate value (in milliseconds) in the Refresh Rate field, then click Set Refresh Rate on the toolbar.

TWS market data updates every 300 milliseconds by default, so setting the refresh rate to 250 will get every tick to the spreadsheet. To set the processing rate The server processing rate affects the speed at which the DDE handles requests between TWS and the spreadsheet. Type the processing rate value (in milliseconds) in the Processing Rate field, then click Set Processing Rate on the toolbar.

The allowed range is 100 ms- 200 ms, inclusive. To set the level of detail for logging of API client requests 1 2 In the Log Level field in the Which Trader Workstation? area, enter the desired log level value (1 =SYSTEM, 2=ERROR, 3=WARNING, 4=INFORMATION, 5=DETAIL). Move your cursor out of the Log Level field, then click the Set Log Level button.

To remove all DDE links to TWS The Clear All Links button on the Tickers page lets you remove all DDE links from the TwsDde.xls spreadsheet to TWS that the Visual Basic for Applications (VBA) code provided with the spreadsheet could create. You typically use this button when you are preparing to save the spreadsheet. Clicking this button cancels all market data, historical data, market scanner subscriptions, and other data requests. If you add your own links to existing or new pages, update the clearAllLinks macro to clear those links as well. Each page in the spreadsheet contains its own clearLinks macro; these are all called by the clearAllLinks macro. Note: Clearing all links does NOT cancel orders.

API Reference Guide

37

DDE for Excel Tickers Page

Tickers Page Toolbar Buttons

The toolbar on the Tickers page includes the buttons described below. Button Create Ticker Combo Legs Request Market Data Set Refresh Rate Description Opens the Ticker box. Enter information to create a market data line. Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. Select a line and click to get market data for the selected contract. The Refresh Rate value is in milliseconds, and determines how often the DDE link to TWS is refreshed. The default refresh rate is 1000 (updates every 1 second), and the allowed range is 100ms to 2000ms, inclusive. Note that the TWS market data updates every 300 milliseconds. This means the default "every 1 second" rate will only show 30% of the ticks. A Refresh Rate of 250 will get every tick to the spreadsheet. Set the TWS/DDE server message processing rate (also in milliseconds) to affect the speed at which DDE will handle requests between the spreadsheet and TWS. The allowed range is 100ms to 2000ms, inclusive. This specifies the level of log entry detail used when processing API requests. Valid values include: 1 = SYSTEM 2 = ERROR 3 = WARNING 4 = INFORMATION 5 = DETAIL Jumps to the Error Code field and shows the error code. Opens the News Bulletins message. If you subscribe to bulletins, news will appear in the RED box in the upper right corner of the spreadsheet. Clears all DDE links to the TWS.

Set Processing Rate

Set Log Level

Show Errors Show Bulletins

Clear All Links

API Reference Guide

38

DDE for Excel Basic Orders Page

Basic Orders Page

Use the Basic Orders page to:

Create an order. Create a "basket" of orders. Modify and cancel orders. Create combination orders.

API Reference Guide

39

DDE for Excel Basic Orders Page

Placing Orders
This topic describes how to place the following types of orders on the Orders page:

Simple orders Basket orders Modified orders Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

Note:

To place an order 1 2 3 Click the Basic Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields. You must define the Action (Buy, Sell or Short Sell), Quantity, Order Type, Limit Price (unless it's a market order) and if necessary, the Aux. Price for order types that require it. 4 If desired, apply extended order attributes by clicking the Apply Extended Template button on the toolbar. This applies all attributes you have defined on the Extended Order Attributes page. Click the Place/Modify Order button in the Toolbar section of the page.

To place a "basket" of orders 1 2 3 4 5 Click the Basic Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using fields in the Order Description section. Repeat Steps 1 and 2 for additional orders. Select a group of orders.

To select a group of contiguous orders, highlight the first order, hold down the Shift key, then highlight the last order of the group. To select a group of non-contiguous orders, hold the Ctrl key down as you select each order.

Click the Place/Modify Order button.

API Reference Guide

40

DDE for Excel Basic Orders Page

To modify an order (or group of orders) 1 2 On the Basic Orders page, change any necessary parameters in an order or group of orders. Select the order or a group of orders.

To select a group of contiguous orders, highlight the first order, hold down the Shift key, then highlight the last order of the group. To select a group of non-contiguous orders, hold the Ctrl key down as you select each order.

Click the Place/Modify Order button.

Placing a Combination Order

A combination order is a special type of order that is constructed of many separate legs but executed as a single transaction. To buy a calendar spread, you would:

Buy 1 OPT JUL03 17.5 CALL (100) Sell 1 OPT AUG03 17.5 CALL (100)

To create a calendar spread order The following example walks you through the process of placing a hypothetical calendar spread order for XYZ on ISE.

Use the Contract Details page to get the contract id for both of the leg definitions.

The conid for XYZ option JUL08 17.5 CALL on ISE is "12345678". The conid for XYZ option AUG08 17.5 CALL on ISE is "12345679".

Click the Basic Orders tab to build the combo leg definitions. Click the Combo Legs button on the Basic Orders page toolbar and enter leg information. Your leg information is translated into the format:

API Reference Guide

41

DDE for Excel Basic Orders Page

[CMBLGS]_[NumOfLegs]_[Combo Leg Definitions]_[CMBLGS] where:

[CMBLGS] is the delimiter used to identify the start and end of the leg definitions [NumOfLegs] is the number of leg definitions [Combo Leg Definitions] defines N leg definitions, and each leg definition consists of [conid]_[ratio]_[action]_[exchange]_[openClose], so the resulting combo substring looks as follows: CMBLGS_2_17496957_1_BUY_EMPTY_0_15910089_1_SELL_EMPTY_0_CMBL GS

The combination leg definitions must occur before the extended order attributes. The full place order DDE request string will look like this: =acctName|ord!id12345?place?BUY_1_XYZ_BAG_ISE_LMT_1_CMBLGS_2_1234 5678_1_BUY_EMPTY_0_12345679_1_SELL_EMPTY_0_CMBLGS_DAY_EMPTY_0_O_0 _EMPTY_0_EMPTY_0_0_0EMPTY_0_0 If the order legs do not constitute a valid combination, one of the following errors will be returned:

312 = The combo details are invalid. 313 = The combo details for '<leg number>' are invalid. 314 = Security type 'BAG' requires combo leg details. 315 = Stock combo legs are restricted to SMART exchange.

Notes:

1. The exchange for the leg definition must match that of the combination order. The exception is for a STK leg definition, which must specify the SMART exchange. 2. The openClose leg definition value is always 'SAME' (i.e.0) for retail accounts. For institutional accounts, the value may be any of the following: (SAME, OPEN, CLOSE).

API Reference Guide

42

DDE for Excel Basic Orders Page

Supported Order Types

The order types currently supported through the DDE for Excel API are:

Limit (LMT) Market (MKT) Limit if Touched (LIT) Market if Touched (MIT) Market on Close (MOC) Limit on Close (LOC) Pegged to Market (PEGMKT) Relative (REL) Stop (STP) Stop Limit (STPLMT) Trailing Stop (TRAIL) Trailing Stop Limit (TRAILLIMIT) Volume-Weighted Average Price (VWAP) Volatility orders (VOL)

API Reference Guide

43

DDE for Excel Basic Orders Page

Order Attributes

Field side quantity symbol secType

Valid Values Buy Sell number value (1, 2, 3, etc) any valid underlying symbol STK OPT FUT use the format: YYYYMM number value (120, 65, etc.) P C for put or call Smart any valid exchange/ECN symbol LMT LMTCLS MKT MKTCLS PEGMKT STP STPLMT TRAIL VWAP REL number value number value

exp strike right

exchange orderType

lmtPrice auxPrice

API Reference Guide

44

DDE for Excel Basic Orders Page

Basic Orders Page Toolbar Buttons

The toolbar on the Basic Orders page includes the following buttons: Button Combo Legs Place/Modify Orders Description Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. After you have completed the Order Description fields, and defined any extended attributes, click to create an order for the selected contract. This button cancels the order(s) you have highlighted. Applies the current values on the Extended Order Attributes page to the highlighted order row. Jumps to the Error Code field and shows the error code.

Cancel Order Apply Extended Template Show Errors

API Reference Guide

45

DDE for Excel Extended Order Attributes Page

Extended Order Attributes Page

The Extended Order Attributes page includes all of the optional attributes you can use when you send an order, such as setting a display size to create an iceberg order, adding orders to an OCA group, and setting the transmit date for a Good After Time order. Once you define the attributes on this page, you can apply them to a single order or selected group of orders using the Apply Extended Template button, which occurs on both the Orders page and the Conditional Orders page. The attributes populate the extended order attributes fields that follow the Order Status fields to the far right of the page.

API Reference Guide

46

DDE for Excel Extended Order Attributes Page

Manually Program Extended Order Attributes

Observe the following guidelines when you manually assign an attribute:

When appended to orderDescription, the number and order of attributes cannot be changed. For any attribute that is not defined, use the value 'EMPTY' or {}. Since a string length is limited to 255 characters, we recommend using the open/close curly braces {}. A place order message for a simple stock limit day order looks as follows, with the primary exchange "Supersoes" separating the extended attributes: =psmith12|ord!'id1814454745?place?BUY_1_MSFT_STK_SMART_USD_LMT_26 _{}_DAY_{}_{}_O_0_{}_1_{}_0_0_0_0_0_0_{}_{}_{}_{}_{}_{}_{}_{}_SUP ERSOES_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_1_2_3_4 _5'

Apply Extended Order Attributes to Individual Orders and Groups of Orders

Normally, values that you enter on the Extended Order Attributes page apply to all subsequent orders. However, you also can apply selected attributes to an individual order or a group of orders on the Orders page. Note: You can also use this procedure to apply extended order attributes to orders on the Conditional Orders page.

To apply extended order attributes to individual orders or a group of orders 1 2 3 Enter the value or values on the Extended Order Attributes page that you want to apply to an individual order or group of orders. On the Orders page, select the order or group of orders. Click the Apply Extended Template button. The extended order attributes are applied to the order(s) and the values you entered on the Extended Order Attributes page are added to the corresponding fields in the Extended Order Attributes section of the Orders page. When you place the order or group of orders, the extended order attribute values you entered are applied to the order. For example, you might want to assign a unique Order Ref number to a group or basket of orders. To do this, you would enter the number for the Order Ref attribute on the Extended Order Attributes page, then select all the orders in the group on the Orders page and click Apply Extended Template. 4 Delete the value of the extended order attributes you used for the order from the Extended Order Attributes page. These values will still apply to all subsequent orders that you place from the DDE for Excel API spreadsheet unless you remove the value.

API Reference Guide

47

DDE for Excel Extended Order Attributes Page

Extended Order Attributes

The following table shows the available extended order attributes: Attribute timeInForce Valid Values DAY GTC OPG IOC String String (for institutions) O, C (for institutions) 0, 1 (for institutions) String 0 (don't transmit) 1 (transmit) String (the order ID used for the parent order, use for bracket and auto trailing stop orders) 0 (not a block order) 1 (this is a block order) 0 (not a sweep-to-fill order) 1 (this is a sweep-to-fill order) String (publicly disclosed order size)

ocaGroup account open/close origin orderRef transmit

parentId blockOrder sweepToFill displaySize

API Reference Guide

48

DDE for Excel Extended Order Attributes Page

Attribute triggerMethod

Valid Values Specifies how simulated Stop, Stop-Limit, and Trailing Stop orders are triggered. O - the default value. The "double bid/ask" method will be used for orders for OTC stocks and US options. All other orders will used the "last" method. 1 - use "double bid/ask" method, where stop orders are triggered based on two consecutive bid or ask prices. 2 - "last" method, where stop orders are triggered based on the last price. 3 - "double-last" method, where stop orders are triggered based on last two prices. 4 bid-ask method. For a buy order, a single occurrence of the bid price must be at or above the trigger price. For a sell order, a single occurrence of the ask price must be at or below the trigger price. 7 last-or-bid-ask method. For a buy order, a single bid price or the last price must be at or above the trigger price. For a sell order, a single ask price or the last price must be at or below the trigger price. 8 mid-point method, where the midpoint must be at or above (for a buy) or at or below (for a sell) the trigger price, and the spread between the bid and ask must be less than 0.1% of the midpoint. 0 1 (order not visible when viewing market depth)

hidden

Only valid for orders routed to Island.

Discretionary Amount (SMART Routing) Good After Time Good 'Till Date

Used in conjunction with a limit order to give the order a greater price range over which to execute. Enter the date and time after which the order will become active. Use the format YYYYMMDD hh:mm:ss The order continues working until the close of market on the date you enter. Use the format YYYYMMDD. To specify a time of day to close the order, enter the time using the format HH:MM:SS. Specify the time zone using a valid three-letter acronym. For Advisor accounts only. The name of the Account Group.

FA Group

API Reference Guide

49

DDE for Excel Extended Order Attributes Page

Attribute FA Method

Valid Values For Advisor accounts only. The share allocation method. EqualQuantity NetLiq AvailableEquity PctChange

FA Percentage FA Profile Short Sale Slot

For Advisor accounts only. The share allocation percentage. For Advisor accounts only. The name of the Share Allocation profile. For institutions only. Valid values are: 1 2

Short Sale Location OCA Type

Institutional accounts only. 1 = Cancel on Fill with Block 2 = Reduce on Fill with Block 3 = Reduce on Fill without Block Individual = 'I' Agency = 'A', AgentOtherMember = 'W' IndividualPTIA = 'J' AgencyPTIA = 'U' AgentOtherMemberPTIA = 'M' IndividualPT = 'K' AgencyPT = 'Y' AgentOtherMemberPT = 'N' Institutions only 0 = false 1 = true Identifies the order as a minimum quantity order. The percent offset for relative orders. 0 = false 1 = true 0 = false 1 = true Maximum SMART order distance from the NBBO. match = 1 improvement = 2 transparent = 3 For BOX exchange only. The starting price. For BOX orders only.

Rule 80A

Settling Firm All or None Minimum Qty Percent Offset Electronic Trade Only Firm Quote Only NBBO Price Cap Auction Strategy

Starting Price

API Reference Guide

50

DDE for Excel Extended Order Attributes Page

Attribute Stock Ref Price

Valid Values Used for VOL orders to compute the limit price sent to an exchange (whether or not Continuous Update is used), and for price range monitoring. Also used for price improvement option orders. The stock delta. For BOX orders only. The lower value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. The upper value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. The option price in volatility, as calculated by TWS' Option Analytics. This value is expressed as a percent and is used to calculate the limit price sent to the exchange. 1 = daily 2 = annual 1 = average 2 = BidOrAsk Prior to TWS Release 859, use "1" to send a market order, "0" for no order. After TWS 859, enter an accepted order type such as: MKT, LMT, REL or MTL. 0 = false 1 = true Enter the Aux Price for Hedge Delta order types that require one. Used for Trailing Stop Limit orders only. This is the stop trigger price for TRAILLMT orders. Used for Scale orders only, this value defines the order size of the each order component. Used for Scale orders only, this value is used to calculate the per-unit price of each component in the order. This cannot be a negative number. 0 = false 1 = true

Delta Underlying Range (Low) Underlying Range (High) Volatility

Volatility Type Reference Price Type Hedge Delta Order Type

Continuous Update Hedge Delta Aux Price Trail Stop Price Scale Component Size Scale Price Increment

Outside RTH

API Reference Guide

51

DDE for Excel Conditional Orders Page

Conditional Orders Page

Use the Conditional Orders page to create an order whose submission is contingent on other conditions being met, for example, an order based on a prior fill or a change in the bid or ask price. To see the Conditional Statement fields (in blue), use the scroll bar on the bottom of the page to scroll to the right.

Setting Up Conditional Orders

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To set up a conditional order 1 On the Conditional Orders page, first create the order you want transmitted when a condition is met by defining the contract in the Contract Description fields, and then using the Order Description area to set up the order parameters. In the blue Condition Statements area, use the Statement field to set the criteria which must be met to trigger the order. When the Statement = TRUE, your order will be submitted. The sample spreadsheet includes a pair of orders, with the second orders transmission depending on the first order being completely filled. In this case, the Statement field
API Reference Guide 52

DDE for Excel Conditional Orders Page

trigger is that the value in cell T10 (the Filled field) must be equal to the value in M10 (the order Quantity field). 3 4 Type ADD in the ADD/MOD field because you are creating a one-time order. Define the remaining order parameters just as you did in the Order Description area.

Complete the necessary fields on the Conditional Orders page according to the syntax in the following table. Description An Excel function which returns a true or false. When true, the order will be submitted; when false, nothing happens. Use ADD for a one-time order. Use MOD to continue checking and modifying the order until it is completely filled. This is the field that activates a conditional order, and orders will be activated only with the "ADD" or "MOD" tags. BUY SELL Enter the quantity of the order. Refer to list of supported order types. The limit price for Limit and Stop Limit order types. The stop-election price for Stop and Stop Limit order types, or the offset for relative orders.

Field Statement ADD/MOD

Action Quantity Order Type Lmt Price Aux. Price

All of the fields described above may be variables that depend on other cells, so any type of conditional order may be created.

Conditional Order Examples

If-Filled order An if-filled order is an order that executes if a prior order executes. To create an if-filled order with the condition "If a Buy order fully executes, enter a sell limit order at a price of $50.00": Field Statement ADD/MOD Action Quantity Value Filled cell = 100 ADD SELL 100

API Reference Guide

53

DDE for Excel Conditional Orders Page

Field Order Type Lmt Price Aux. Price Price-change order

Value LMT 50 empty

A price-change order will be triggered if a specific bid or ask price is greater than, less than or equal to a specific price. To create a price change order with the condition "If the bid price drops below 81.20, submit a buy limit order for 200 shares with a limit price of $81.10: Field Statement Value On the Tickers page, put your cursor in the bid price field you want to use, then copy the value that appears in the formula bar (= entry field) at the top of the spreadsheet. This value looks something like this: =username|tik!id4?bid where "4" identifies the bid price for a specific contract. Paste this in the formula bar ("=" entry field) for the Statement, and add your qualifier, "=" ">" or "<" followed by the price. In this example, the formula would be: =username|tik!id4?bid<81.20 ADD BUY 200 LMT 81.10 Not used in this example.

ADD/MOD Action Quantity Order Type Lmt Price Aux. Price

To modify an order (or basket of orders) 1 Select the order or a group of orders.

To select a group of contiguous orders, highlight the first order, hold down the Shift key, then highlight the last order of the group. To select a group of non-contiguous orders, hold the Ctrl key down as you select each order.

2 3

Click the Place/Modify Order button. Change any necessary parameters, then click the Place/Modify Order button.

API Reference Guide

54

DDE for Excel Conditional Orders Page

Conditional Orders Page Toolbar Buttons

The toolbar on the Conditional Orders page includes the following buttons: Button Combo Legs Description Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. After you have completed the Order Description fields, and defined any extended attributes, click to create an order for the selected contract. Applies all attributes on the Extended Order Attributes page to the selected order(s). This button cancels the order(s) you have highlighted. Jumps to the Error Code field and shows the error code.

Place/Modify Order

Apply Extended Template Cancel Order Show Errors

API Reference Guide

55

DDE for Excel Advanced Orders Page

Advanced Orders Page

Use the Advanced Orders page to:

Create complex orders that require the use of extended order attributes, including:

Bracket orders VOL orders Trailing Stop Limit Orders Scale Orders Relative Orders

For more information about using extended order attributes for individual orders or groups of orders, see Apply Extended Order Attributes to Individual Orders and Groups of Orders

API Reference Guide

56

DDE for Excel Advanced Orders Page

Placing a Bracket Order

Bracket orders in the DDE for Excel sample spreadsheet require the use of the extended order attributes Transmit and Parent Order Id. You must turn Transmit off until the order is completely set up, and you must identify the first order in the bracket as the Parent Order. To place a Buy-Limit bracket order 1 2 Click the Advanced Orders tab at the bottom of the spreadsheet. Enter the contract descriptions and order descriptions for all three orders on three contiguous rows:

The first order should be a BUY LMT order. The second order should be a SELL STP order. The third order should be a SELL LMT order.

Click the Extended Order Attributes tab. Change the value for Transmit to 0 (row 13 on the Extended Order Attributes page). This ensures that your orders are not transmitted until you have completed the order setup.

Click the Advanced Orders tab, highlight the first order in the bracket order, then click the Place/Modify Order button. The order is not executed, but the system generates an Order ID.

Copy the Order ID for the first order, omitting the id prefix, then click the Extended Order Attributes tab and paste the Order ID into the Value field for Parent Order Id (row 14). This value will be applied to all subsequent orders until you remove it from the Extended Order Attributes page. The first order of the bracket order is now the primary order.

Click the Advanced Orders tab, highlight the second order, then click the Place/Modify Order button. The order is not executed but is now associated with the primary order by means of the Parent Order Id extended order attribute.

7 8 9

Click the Extended Order Attributes tab and change the value for Transmit back to 1 (row 13). Click the Advanced Orders tab, highlight the third order in the bracket order, then click the Place/Modify Order button. The entire bracket order is transmitted. When you are done placing your bracket order, go to the Extended Order Attributes page and delete the Parent Order Id value you entered. If you do not, this value will be applied to all subsequent orders that you place in the spreadsheet.

API Reference Guide

57

DDE for Excel Advanced Orders Page

Placing a Volatility Order

In the DDE for Excel sample spreadsheet, you place VOL orders by entering values for the following extended order attributes:

Volatility Volatility Type Reference Price Type Continuous Update Underlying Range (Low) - optional Underlying Range (High) - optional Hedge Delta Order Type - optional Hedge Delta Aux Price - optional

To place a VOL order 1 2 3 Click the Advanced Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields.

Enter VOL in the Order Type field.

Click the Extended Order Attributes tab. Enter values in the Value field for the following extended order attributes:

Volatility - This value represents the volatility to use in calculating a limit price for the option. Enter this value as a percentage, not as the market data is displayed. For example, enter 17.12 instead of .1712. Volatility Type - Enter 1 for daily volatility or 2 for annual volatility. Reference Price Type - This value is used to compute the limit price sent to an exchange and for stock range price monitoring. Enter 1 to use the average of the best bid and ask; or 2 to use NBB (bid) when buying a call or selling a put, or the NBO (ask) when selling a call or buying a put. Continuous Update - Enter 1 to automatically update the option price as the underlying stock price (or futures price, for index options) moves. Enter 0 if you do not want to use this feature.

On the Extended Order Attributes page, enter values in the Value field for the following optional extended order attributes:

Underlying Range (Low) - Enter a low-end acceptable stock price relative to the selected option order. If the price of the underlying instrument falls below the lower stock range price, the option order will be canceled.

API Reference Guide

58

DDE for Excel Advanced Orders Page

Underlying Range (High) - Enter a high-end acceptable stock price relative to the selected option order. If the price of the underlying instrument rises above the higher stock range price, the option order will be canceled. Hedge Delta Order Type - Enter LMT, MKT or REL. Enter NONE if you do not want to use delta hedging. Hedge Delta Aux Price - If you have entered LMT or REL as the Hedge Delta Order Type, enter the price as the value for this attribute.

6 7

Click the Advanced Orders tab, then highlight the order row. Click the Apply Extended Template button. The values you entered for the extended order attributes are applied to the order row and displayed in the Extended Order Attributes section of the page. With the order row highlighted, click the Place/Modify Order button. When you are done placing VOL orders, go to the Extended Order Attributes page and delete the VOL order values you entered. If you do not, these values will be applied to all subsequent orders that you place in the spreadsheet.

8 9

Placing a Trailing Stop Limit Order

In TWS, there are four values that make up a trailing stop limit order:

trailing amount stop price limit price limit offset

In the DDE for Excel API spreadsheet, you enter the trailing amount, stop price and limit price. There is no field or extended order attribute for the limit offset value. You must include the limit offset in the stop price (the Trail Stop Price extended order attribute). To create a Trailing Stop Limit Order 1 2 3 Click the Advanced Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields.

Enter BUY or SELL in the Action field. Enter the limit price in the Lmt Price field. Enter TRAILLIMIT in the Order Type field. Enter the trailing amount in the Aux Price field.

API Reference Guide

59

DDE for Excel Advanced Orders Page

Click the Extended Order Attributes tab. Specify the trailing stop price as an extended order attribute. Type this value in the Trail Stop Price Value field.

The Trail Stop Price value must include the limit offset. For a sell order: Trail Stop Price = Limit Price - Trailing Amount - Limit Offset For a buy order: Trail Stop Price = Limit Price + Trailing Amount + Limit Offset

On the Advanced Orders page, select the order row and click the Apply Extended Template button. The Trail Stop Price value is applied to the selected order and displayed in the Trail Stop Price field in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done placing your order, go to the Extended Order Attributes page and delete the Trail Stop Price value you entered. If you do not, this value will be applied to all subsequent orders that you place in the spreadsheet.

6 7

Placing a Scale Order

In the DDE for Excel sample spreadsheet, you place scale orders by entering values for the following extended order attributes:

Scale Component Size Scale Price Increment

To place a scale order 1 2 3 4 Click the Advanced Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields. The order type should be LMT or REL. Click the Extended Order Attributes tab. Enter values in the Value field for the following extended order attributes:

Scale Component Size - Enter the size of the first, or initial, order component. For example, if you submit a 10,000-share order with a Scale Component Size value of 1000, the first component will be fore 1000 shares. Scale Price Increment - Enter the amount used to calculate the per-unit price of each component in the scale ladder. This cannot be a negative number. As of API Release 9.41, the Scale Num Components not supported.

Note:

API Reference Guide

60

DDE for Excel Advanced Orders Page

On the Advanced Orders page, select the order row and click the Apply Extended Template button. The scale order values are applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done placing your order, go to the Extended Order Attributes page and delete the scale order values you entered. If you do not, these values will be applied to all subsequent orders that you place in the spreadsheet.

6 7

Placing a Relative Order

In the DDE for Excel sample spreadsheet, you place relative orders by entering a value for the Percent Offset extended order attribute. To place a relative order 1 2 3 Click the Advanced Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields.

Enter REL as the order type. Enter the price cap in the Lmt Price cell.

4 5

Click the Extended Order Attributes tab. Enter a percentage in decimal form in the Value field for the Percent Offset extended order attribute. On the Advanced Orders page, select the order row and click the Apply Extended Template button. The percent offset value is applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done placing your order, go to the Extended Order Attributes page and delete the Percent Offset value you entered. If you do not, this value will be applied to all subsequent orders that you place in the spreadsheet.

6 7

API Reference Guide

61

DDE for Excel Advanced Orders Page

Advanced Orders Page Toolbar Buttons

The toolbar on the Advanced Orders page includes the following buttons: Button Combo Legs Place/Modify Orders Description Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. After you have completed the Order Description fields, and defined any extended attributes, click to create an order for the selected contract. This button cancels the order(s) you have highlighted. Applies the current values on the Extended Order Attributes page to the highlighted order row. Jumps to the Error Code field and shows the error code.

Cancel Order Apply Extended Template Show Errors

API Reference Guide

62

DDE for Excel Open Orders Page

Open Orders Page

The Open Orders page shows you all transmitted orders, including those that have been accepted by the IB system, and those that are working at an exchange. Once you have subscribed, the page is updated each time you submit a new order, either through the API or in TWS. Once an order executes, it remains on the Open Orders page for 30 seconds, with the Status value changed to FILLED. Then the filled order is cleared and you can see it on the Executions page if you subscribed to real-time executions.

API Reference Guide

63

DDE for Excel Open Orders Page

Viewing Open Orders

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To view open orders: 1 2 Click the Open Orders tab at the bottom of the spreadsheet. Click Subscribe to Open Orders on the toolbar. All of your open orders are displayed on the page, including orders you enter in the Excel API spreadsheet and in TWS. Orders that fill remain on the page for 30 seconds with a value of Fill in the Status field. To remove open orders 1 2 Click the Cancel Open Orders Subscription button on the toolbar. Click the Clear Open Orders button.

Open Orders Tab Toolbar

The toolbar on the Open Orders page includes the following buttons: Button Subscribe to Open Orders Description Once you enter a valid user name, clicking this button queries TWS and returns all open orders. Once you subscribe to open orders, this page updates each time there is a new open order. Cancels the open orders subscription. The page will no longer show your open orders. Removes all open orders from the page. Jumps to the Error Code field and shows the error code.

Cancel Open Orders Subscription Clear Open Orders Show Errors

API Reference Guide

64

DDE for Excel Executions Page

Executions Page
When you subscribe to executions, the Executions page displays information about all completed trades (also called execution reports).

Viewing Executions
Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To view executions 1 2 Click the Executions tab at the bottom of the spreadsheet. Click the Subscribe to Executions button in the toolbar.

To remove execution reports 1 2 Click the Cancel Executions Subscription button on the toolbar. Click the Clear Executions button.

API Reference Guide

65

DDE for Excel Executions Page

Executions Page Toolbar Buttons

The toolbar on the Executions page includes the following buttons: Button Subscribe to Executions Description After you have entered a valid user name, this button queries TWS and returns information about all valid executions. After you subscribe to executions, this page updates each time an order executes. Click to cancel the execution subscription. Removes all execution reports from the page. Jumps to the Error Code field and shows the error code.

Cancel Executions Subscription Clear Executions Show Errors

API Reference Guide

66

DDE for Excel Executions Reporting Page

Executions Reporting Page

Once you have subscribed to executions on the Executions page, you can use the Executions Reporting page to run reports based on an Order ID, Order Reference number, VOL order key, or strategy From a programming point of view, the Executions Reporting page is a practical example of how you can extract array subscription data from the named ranges into which the data is put when it is received, and how such data can be used in your own custom DDE for Excel API applications.

API Reference Guide

67

DDE for Excel Executions Reporting Page

Running Execution Reports

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To run execution reports 1 2 3 On the Executions page, click the Subscribe to Executions button on the toolbar. Click the Executions Reporting tab at the bottom of the worksheet. In the Type field select from:

Order ID - finds all executions resulting from orders with a specified PermID. Order Ref - finds all executions resulting from orders with a given order reference; for example executions from a specific basket order. VOL order - finds all executions resulting from specific volatility order, including any hedge delta executions. Strategy - in the Key field, enter a value to define the Type you selected. For example, if you selected Order ID as the type, enter a specific order ID in the Key field.

API Reference Guide

68

DDE for Excel Account Page

Account Page
Use the Account page to:

View account details including your current Equity with Loan Value and Available funds. View list of advisor-managed account codes. View your current portfolio.

API Reference Guide

69

DDE for Excel Account Page

Using the Account Page

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To view account information 1 2 Click the Account tab at the bottom of the spreadsheet. Click the Subscribe to Account Updates button on the toolbar.

To remove account information 1 2 Click the Cancel Account Subscription button. Click the Clear Account Data button.

To request the list of Financial Advisor (FA) managed account codes 1 2 Click the Account tab at the bottom of the spreadsheet. Click the Request Managed Accounts button.

To request details of a Financial Advisor (FA) managed account 1 2 3 Click the Account tab at the bottom of the spreadsheet. In the Account Code field in the Which Trader Workstation? area, type the account code for which you want details. Click the Request Managed Accounts button.

API Reference Guide

70

DDE for Excel Account Page

Account Page Values

The Account page displays the following values: Field Account Code Account Ready Account Type Accrued Cash Description The account number. For internal use only. Identifies the IB account type. Reflects the current month's accrued debit and credit interest to date, updated daily. At the beginning of each month, the past months accrual is added to the cash balance and this field is zeroed out. Notes

Available Funds

For securities: Equity with Loan Value - Initial margin For commodities: Net Liquidation Value - Initial margin

Buying Power

Cash Account: (Minimum (Equity with Loan Value, Previous Day Equity with Loan Value)-Initial Margin) Standard Margin Account: Available Funds*4

Cash Balance

For securities: Settled cash + sales at the time of trade For commodities: Settled cash + sales at the time of trade + futures PNL

Currency Cushion Day Trades Remaining Day Trades Remaining T+1, T+2, T+3, T+4

Shows the currency types that are listed in the Market Value area. Shows your current margin cushion. Number of day trades left for pattern day trader period. The number of day trades you have left for a 4-day pattern day-trader.

API Reference Guide

71

DDE for Excel Account Page

Field Equity With Loan Value

Description For Securities: Cash Account: Settled Cash Margin Account: Total cash value + stock value + bond value + (non-U.S. & Canada securities options value) For Commodities: Cash Account: Total cash value + commodities option value - futures maintenance margin requirement + minimum (0, futures PNL) Margin Account: Total cash value + commodities option value futures maintenance margin requirement

Notes

Excess Liquidity Exchange Rate Full Available Funds

Equity with Loan Value - Maintenance margin The exchange rate of the currency to your base currency. For securities: Equity with Loan Value - Initial margin For commodities: Net Liquidation Value - Initial margin

Full Excess Liquidity Full Init Margin Req Full Maint Margin Req Future Option Value Futures PNL Gross Position Value Init Margin Req

Equity with Loan Value - Maintenance margin Overnight initial margin requirement in the base currency of the account. Maintenance margin requirement as of next period's margin change in the base currency of the account. Real-time mark-to-market value of futures options. Real-time change in futures value since last settlement. Long Stock Value + Short Stock Value + Long Option Value + Short Option Value. Initial margin requirement in the base currency of the account.

API Reference Guide

72

DDE for Excel Account Page

Field Leverage

Description For Securities: Gross Position value / Net Liquidation value For Commodities: Net Liquidation value - Initial margin

Notes

Look Ahead Available Funds

For Securities: Equity with loan value - look ahead initial margin. For Commodities: Net Liquidation value - look ahead initial margin.

Look Ahead Excess Liquidity Look Ahead Init Margin Req Look Ahead Maint Margin Req Maint Margin Req Net Liquidation

Equity with loan value - look ahead maintenance margin. Initial margin requirement as of next period's margin change in the base currency of the account. Maintenance margin requirement as of next period's margin change in the base currency of the account. Maintenance margin requirement in the base currency of the account. For Securities: Total cash value + stock value + securities options value + bond value For Commodities: Total cash value + commodities options value

Net Liquidation by Currency Option Market Value PNL

Same as above for individual currencies. Real-time mark-to-market value of securities options. The difference between the current market value of your open positions and the average cost, or Value - Average Cost. Marginable Equity with Loan Value as of 16:00 ET the previous day, only applicable to securities.

Previous Day Equity with Loan Value

API Reference Guide

73

DDE for Excel Account Page

Field Realized PnL

Description Shows your profit on closed positions, which is the difference between your entry execution cost and exit execution cost, or (execution price + commissions to open the positions) - (execution price + commissions to close the position). Initial margin requirements calculated under US Regulation T rules. For Securities: Cash Account : Settled Cash Margin Account : Total cash value + stock value + bond value + (non-U.S. & Canada securities options value) Cash Account : Total cash value + commodities option value - futures maintenance margin requirement + minimum (0, futures PNL) Margin Account : Total cash value - futures maintenance margin requirement

Notes

Reg T Equity Reg T Margin

For Commodities:

SMA

Max ((EWL - US initial margin requirements)*, (Prior Day SMA +/change in day's cash +/- US initial margin requirements** for trades made during the day.)) *calculated end of day under US Stock rules, regardless of country of trading. **at the time of the trade Real-time mark-to-market value of stock Cash recognized at the time of trade + futures PNL Total cash value of stock, commodities and securities

Only applicable for securities.

Stock Market Value Total Cash Balance Total Cash Value

API Reference Guide

74

DDE for Excel Account Page

Account Page Toolbar Buttons

The toolbar on the Account page includes the following buttons. Button Subscribe to Account Updates Description Each click gives you data for a specific account value. All blank lines that precede the Account Portfolio section will hold data. Continue to click until all lines are populated. Click this button one time for each position you hold. When you get a line of "0's" you know you have downloaded all current positions. These values continue to update in real-time. Clears all information from the page. You must first cancel your subscription before you can clear the data. For advisor accounts, click this button one time for each account. Jumps to the Error Code field and shows the error code.

Cancel Account Subscription

Clear Account Data

Request Managed Accounts Show Errors

API Reference Guide

75

DDE for Excel Portfolio Page

Portfolio Page
The Portfolio page displays all of your current positions. This page communicates with TWS and updates the values every three minutes, which you can see in the Last Update Time field in the Which Trader Workstation? area of the page.

Viewing Your Portfolio

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To view your portfolio 1 2 Click the Portfolio tab at the bottom of the worksheet. Click the Subscribe to Portfolio Updates button.

To remove portfolio information 1 2 Click the Cancel Portfolio Subscription button. Click the Clear Portfolio Data button.

API Reference Guide

76

DDE for Excel Portfolio Page

Portfolio Page Toolbar Buttons

The toolbar on the Portfolio page includes the following buttons. Button Subscribe to Portfolio Updates Cancel Portfolio Subscription Clear Portfolio Data Description Click to view all current portfolio data. Cancels the connection to TWS that updates your portfolio information. Removes all data from the page. You must cancel your subscription before you can clear all data. Jumps to the Error Code field and shows the error code.

Show Errors

API Reference Guide

77

DDE for Excel Historical Data Page

Historical Data Page

Use the Historical Data page to request historical data for an instrument based on data you enter in query fields. The query results display on a separate worksheet page and creates a new page for the results if the page doesn't currently exist. Note that since the query returns in a named range of cells, you can write VBA macros to perform computations on it, and you can chart and sort the data in Excel.

Note:

For a information about historical data request limitations, see Historical Data Limitations.

API Reference Guide

78

DDE for Excel Historical Data Page

Viewing Historical Data

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To request historical data 1 2 Click the Historical Data tab at the bottom of the spreadsheet. Create a ticker by filling in the fields in the Contract Description section of the page, or by clicking the Create Ticker button on the toolbar and entering the required information in the Ticker box. Enter the parameters of your query in the Query Specification fields. For complete descriptions of the query fields, Historical Data Page Query Specification Fields. Select the line, then click the Request Historical Data button. When the Ctrl field displays "Finished," the results are displayed on the specified page.

3 4

To request historical data for expired contracts 1 On the Historical Data page, create a ticker by filling in the fields in the Contract Description section of the page, or by clicking the Create Ticker button on the toolbar and entering the required information in the Ticker box. Enter the parameters of your query in the Query Specification fields. In the Expired field in the Query Specification section, enter TRUE. Select the line, then click the Request Historical Data button. When the Ctrl field displays "Finished," the results are displayed on the specified page. Note: Historical data queries on expired contracts are limited to the last year of the life of the contract.

2 3 4

API Reference Guide

79

DDE for Excel Historical Data Page

The following figure shows a typical historical data results page.

API Reference Guide

80

DDE for Excel Historical Data Page

Historical Data Page Query Specification Fields

Historical Data queries include the following fields: Parameter End Date/Time Description Use the format yyyymmdd {space}hh:mm:ss{space}tmz where the time zone is allowed (optionally)after a space at the end. This is the time span the request will cover, and is specified using the format integer {space} unit, where valid units are: S (seconds) D (days) W (weeks)

Duration

Y (years) This unit is currently limited to one. If no unit is specified, seconds are used. Bar Size Specifies the size of the bars that will be returned. The following bar sizes may be used, and are specified using the parametric value: Bar Size String Integer Value 1 second 1 5 seconds 2 15 seconds 3 30 seconds 4 1 minutes 5 2 minutes 6 3 minutes 16 5 minutes 7 15 minutes 8 30 minutes 9 1 hour 10 1 day 11 1 week 12 1 month 13 3 months 14 1 year 15 On the query return page, each "bar" is represented by a line in the spreadsheet. If you specify a duration of 300 seconds, and a bar size of "1" (one second) your return will include 300 lines, and the value in each line is equal to one second, or is a one-second bar. Note that you can use either the Integer value of the Bar Size String or the Integer Value to define the bar sizes.

API Reference Guide

81

DDE for Excel Historical Data Page

Parameter What to Show

Description Determines the nature of the data extracted. Valid values include: Trades Midpoint Bid Ask

Bid/Ask All but the Bid/Ask data contain the start time, open, high, low, close, volume and weighted average price during the time slice queried. For the Bid/Ask query, the open and close values are the time-weighted average bid and the time-weighted average offer, respectively. These bars are identical to the TWS charts' candlestick bars. RTH Only Regular Trading Hours only. Valid values include: 0 - all data available during the time span requested is returned, including time intervals when the market in question was outside of regular trading hours. 1 - only data within the regular trading hours for the product requested is returned, even if the time span falls partially or completely outside. 1 - dates that apply to bars are returned in the format yyyymmdd{space}{space}hh:mm:dd (the same format used when reporting executions). 2 - the dates are returned as an integer specifying the number of seconds since 1/1/1970 GMT.

Date Format Style

Valid values include:

Page Name Expired

The name of the results page. This appears in the tab for the results page at the bottom of the worksheet. Valid values: TRUE, FALSE If TRUE, the data query can be done on an expired futures contract, limited to the last year of a contract's life.

For a request with a duration of 300 seconds and a bar of one second, the query return looks like this (the scroll bar on the right side of the page allows you to scroll down and see all 300 bars). Note that the new page is added to the right of the existing tabs on the worksheet.

API Reference Guide

82

DDE for Excel Historical Data Page

Historical Data Page Toolbar Buttons

The toolbar on the Historical Data page includes the following buttons. Button Create Ticker Combo Legs Description Opens the Ticker box. Enter information to create a market data line. Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. Submits your historical data query to TWS and displays the results on a separate worksheet page. Cancels the historical data request. Jumps to the Error Code field and shows the error code.

Request Historical Data

Cancel Historical Data Show Errors

API Reference Guide

83

DDE for Excel Market Scanner Page

Market Scanner Page

Use the Market Scanner page to subscribe to TWS market scanners. These scanners allow you to define criteria and set filters that return the top x number of underlyings which meet all scan criteria. The scan is continually updated in real time.

API Reference Guide

84

DDE for Excel Market Scanner Page

Starting a Market Scanner Subscription

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To start a scanner subscription 1 2 Click the Market Scanner tab at the bottom of the spreadsheet. Highlight an existing scanner row, or enter information for a different market scanner: a b Type the name of the scan results page in the Page Name field. Type TRUE or FALSE in the Activate Page field. Setting these field to TRUE forces the scan results page to pop to the front of your application every time it updates. To stop this behavior, set the value of this field to FALSE. c 3 Type values for the rest of the scan parameters in the lightly shaded section of the page.

Click the Start Scanner Subscription button in the toolbar. A new page for the scanner is created and is displayed after the subscription is processed.

Market Scanner Parameters

The following table describes the market scanner parameters that make up a scanner subscription. Parameter Page name Activate Page? Description The name that will be given to the new page that is created with the scanner data. If set to true, the new scanner page will display on top of the worksheet every time the scan results update. This could be as often as every minute. The type of scan. The instrument type used in the scan. The market used (i.e. US Stocks) for the scan. Allows you to specify just stocks, just ETFs, or both. The number of rows of data to return in the results. Filters out returns with prices below the named price. Can be left empty. Filters out returns with prices above the named price. Can be left empty. Filters out returns with an average volume below the named price. Can be left empty.

Scan Code Instrument Location code Stock type filter Number of rows Price Above Price Below Average volume above

API Reference Guide

85

DDE for Excel Market Scanner Page

Parameter Average Option Volume Above Market Cap Above Market Cap Below Moody Rating Above Moody Rating Below S & P Rating Above S & P Rating Below Maturity Date Above Maturity Date Below Coupon Rate Above Coupon Rate Below Exclude Convertible Scanner Settings Pairs

Description Filters out returns with an average option volume below the named price. Can be left empty. Filters out returns with a market capitalization value below the named price. Can be left empty. Filters out returns with a market capitalization value above the named price. Can be left empty. Filters out returns with a Moody rating below the named price. Can be left empty. Filters out returns with a Moody rating above the named price. Can be left empty. Filters out returns with an S&P rating below the named price. Can be left empty. Filters out returns with an S&P rating above the named price. Can be left empty. Filters out returns with a maturity date below the named price. Can be left empty. Filters out returns with a maturity date above the named price. Can be left empty. Filters out returns with a coupon rate below the named price. Can be left empty. Filters out returns with a coupon rate above the named price. Can be left empty. Filters out convertible bonds. Can be left empty. For example "Annual/True" used on the Top Option Implied Vol% Gainers would instruct the scan to return annualized volatilities. Delimit setting pairs by slashes.

API Reference Guide

86

DDE for Excel Market Scanner Page

Available Market Scanners

The following table shows the available market scanners in the DDE for Excel API spreadsheet. Note: To get more detailed market scan results than are available in the DDE for Excel API spreadsheet, run the Market Scanners in TWS.

Market Scanner (Scan Code)

Low Opt Volume P/C Ratio (LOW_OPT_VOL_PUT_CALL_RATIO)* High Option Imp Vol Over Historical (HIGH_OPT_IMP_VOLAT_OVER_HIST)* Low Option Imp Vol Over Historical (LOW_OPT_IMP_VOLAT_OVER_HIST)* Highest Option Imp Vol (HIGH_OPT_IMP_VOLAT)*

Description Put option volumes are divided by call option volumes and the top underlying symbols with the lowest ratios are displayed. Shows the top underlying contracts (stocks or indices) with the largest divergence between implied and historical volatilities. Shows the top underlying contracts (stocks or indices) with the smallest divergence between implied and historical volatilities. Shows the top underlying contracts (stocks or indices) with the highest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months. Shows the top underlying contracts (stocks or indices) with the largest percent gain between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Shows the top underlying contracts (stocks or indices) with the largest percent loss between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Put option volumes are divided by call option volumes and the top underlying symbols with the highest ratios are displayed. Put option volumes are divided by call option volumes and the top underlying symbols with the lowest ratios are displayed. Displays the most active contracts sorted descending by options volume. Shows the top underlying contracts for highest options volume over a 10-day average. Returns the top 50 contracts with the highest put/call ratio of outstanding option contracts. Returns the top 50 contracts with the lowest put/call ratio of outstanding option contracts.

Top Option Imp Vol % Gainers (TOP_OPT_IMP_VOLAT_GAIN)*

Top Option Imp Vol % Losers (TOP_OPT_IMP_VOLAT_LOSE)*

High Opt Volume P/C Ratio (HIGH_OPT_VOLUME_PUT_CALL_ RATIO) Low Opt Volume P/C Ratio (LOW_OPT_VOLUME_PUT_CALL_ RATIO) Most Active by Opt Volume (OPT_VOLUME_MOST_ACTIVE) Hot by Option Volume (HOT_BY_OPT_VOLUME) High Option Open Interest P/C Ratio (HIGH_OPT_OPEN_INTEREST_PUT_ CALL_RATIO) Low Option Open Interest P/C Ratio (LOW_OPT_OPEN_INTEREST_PUT_ CALL_RATIO)

API Reference Guide

87

DDE for Excel Market Scanner Page

Market Scanner (Scan Code)

Top % Gainers (TOP_PERC_GAIN) Most Active (MOST_ACTIVE)

Description Contracts whose last trade price shows the highest percent increase from the previous night's closing price. Contracts with the highest trading volume today, based on units used by TWS (lots for US stocks; contract for derivatives and non-US stocks). The sample spreadsheet includes two Most Active scans: Most Active List, which displays the most active contracts in the NASDAQ, NYSE and AMEX markets, and Most Active US, which displays the most active stocks in the United States. Contracts whose last trade price shows the lowest percent increase from the previous night's closing price. Contracts where: today's Volume/avgDailyVolume is highest. avgDailyVolume is a 30-day exponential moving average of the contract's daily volume.

Top % Losers (TOP_PERC_LOSE) Hot Contracts by Volume (HOT_BY_VOLUME)

Top % Futures Gainers (TOP_PERC_GAIN) Hot Contracts by Price (HOT_BY_PRICE)

Futures whose last trade price shows the highest percent increase from the previous night's closing price. Contracts where: (lastTradePrice-prevClose)/avgDailyChan ge is highest in absolute value (positive or negative). The avgDailyChange is defined as an exponential moving average of the contract's (dailyClose-dailyOpen)

Top Trade Count (TOP_TRADE_COUNT) Top Trade Rate (TOP_TRADE_RATE) Top Price Range (TOP_PRICE_RANGE) Hot by Price Range (HOT_BY_PRICE_RANGE) Top Volume Rate (TOP_VOLUME_RATE)

The top trade count during the day. Contracts with the highest number of trades in the past 60 seconds (regardless of the sizes of those trades). The largest difference between today's high and low, or yesterday's close if outside of today's range. The largest price range (from Top Price Range calculation) over the volatility. The top volume rate per minute.

API Reference Guide

88

DDE for Excel Market Scanner Page

Market Scanner (Scan Code)

Lowest Option Imp Vol (LOW_OPT_IMP_VOLAT)

Description Shows the top underlying contracts (stocks or indices) with the lowest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months. Returns the top 50 underlying contracts with the (highest number of outstanding call contracts) + (highest number of outstanding put contracts) Contracts that have not traded today. Contracts for which trading has been halted. Shows contracts with the highest percent price INCREASE between the last trade and opening prices. Shows contracts with the highest percent price DECREASE between the last trade and opening prices. Shows contracts with the highest percent price INCREASE between the previous close and today's opening prices. Shows contracts with the highest percent price DECREASE between the previous close and today's opening prices. Shows the top underlying contracts (stocks or indices) with the lowest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months. Shows the top underlying contracts (stocks or indices) with the largest percent gain between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Shows the top underlying contracts (stocks or indices) with the largest percent loss between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. The highest price for the past 13 weeks. The lowest price for the past 13 weeks. The highest price for the past 26 weeks. The lowest price for the past 26 weeks.

Most Active by Opt Open Interest (OPT_OPEN_INTEREST_MOST_ ACTIVE) Not Open (NOT_OPEN) Halted (HALTED)

Top % Gainers Since Open (TOP_OPEN_PERC_GAIN) Top % Losers Since Open (TOP_OPEN_PERC_LOSE) Top Close-to-Open % Gainers (HIGH_OPEN_GAP) Top Close-to-Open % Losers (LOW_OPEN_GAP) Lowest Option Imp Vol (LOW_OPT_IMP_VOLAT)*

Top Option Imp Vol % Gainers (TOP_OPT_IMP_VOLAT_GAIN)*

Top Option Imp Vol % Losers (TOP_OPT_IMP_VOLAT_LOSE)*

13-Week High (HIGH_VS_13W_HL) 13-Week Low (LOW_VS_13W_HL) 26-Week High (HIGH_VS_26W_HL) 26-Week Low (LOW_VS_26W_HL)

API Reference Guide

89

DDE for Excel Market Scanner Page

Market Scanner (Scan Code) 52-Week High (HIGH_VS_52W_HL) 52-Week Low (LOW_VS_52W_HL) EFP - High Synth Bid Rev Yield (HIGH_SYNTH_BID_REV_NAT_ YIELD)

Description The highest price for the past 52 weeks. The lowest price for the past 52 weeks. Highlights the highest synthetic EFP interest rates available. These rates are computed by taking the price differential between the SSF and the underlying stock and netting dividends to calculate an annualized synthetic implied interest rate over the period of the SSF. The High rates may present an investment opportunity. Highlights the lowest synthetic EFP interest rates available. These rates are computed by taking the price differential between the SSF and the underlying stock and netting dividends to calculate an annualized synthetic implied interest rate over the period of the SSF. The Low rates may present a borrowing opportunity.

EFP - Low Synth Bid Rev Yield (LOW_SYNTH_BID_REV_NAT_ YIELD)

*30-day (V30) Implied Volatilities: Implied volatility is calculated using a 100-step binary tree for American style options, and a Black-Scholes model for European style options. Interest rates are calculated using the settlement prices from the day's Eurodollar futures contracts, and dividends are based on historical payouts. The IB 30-day volatility is the at-market volatility estimated for a maturity thirty calendar days forward of the current trading day. It is based on option prices from two consecutive expiration months. The first expiration month is that which has at least eight calendar days to run. The implied volatility is estimated for the eight options on the four closest to market strikes in each expiry. The implied volatilities are fit to a parabola as a function of the strike price for each expiry. The at-the-market implied volatility for an expiry is then taken to be the value of the fit parabola at the expected future price for the expiry. A linear interpolation (or extrapolation, as required) of the 30-day variance based on the squares of the at-market volatilities is performed. V30 is then the square root of the estimated variance. If there is no first expiration month with less than sixty calendar days to run, we do not calculate a V30.

API Reference Guide

90

DDE for Excel Market Scanner Page

Market Scanner Page Toolbar Buttons

The toolbar on the Market Scanner page includes the following buttons. Button Start Scanner Subscription Cancel Scanner Subscription Show Errors Description Creates and displays a new page for results of the selected market scanner. Cancels the market scanner. Jumps to the Error Code field and shows the error code.

API Reference Guide

91

DDE for Excel Contract Details Page

Contract Details Page

Use the Contract Details page to request contract-specific information such as supported order types, valid exchanges, the contract ID, and so on.

Requesting Contract Details

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To request details for a contract 1 2 3 4 Click the Contract Details tab at the bottom of the spreadsheet to open the Contract Details page. Select or enter the ticker symbol for which you want to request contract details. To request contract details for an expired contract, type TRUE in the Expired field. Click the Request Contract Details button on the toolbar.

API Reference Guide

92

DDE for Excel Contract Details Page

Contract Details Page Toolbar Buttons

The toolbar on the Contract Details page includes the following buttons: Button Request Contract Details Show Errors Description Returns information on the selected contract. Jumps to the Error Code field and shows the error code.

API Reference Guide

93

DDE for Excel Bond Contract Details Page

Bond Contract Details Page

Use the Bond Contract Details page to request contract-specific information for bonds, including the coupon, ratings, bond type, maturity date, and so on.

Requesting Bond Contract Details

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To request details for a bond contract 1 2 3 Click the Bond Contract Details tab at the bottom of the spreadsheet. Enter the ticker symbol for which you want to request contract details. Click the Request Bond Contract Details button on the toolbar.

API Reference Guide

94

DDE for Excel Bond Contract Details Page

Bond Contract Details Page Toolbar Buttons

The toolbar on the Bond Contract Details page includes the following buttons: Button Request Bond Contract Details Show Errors Description Gets bond information data for the selected contract. Jumps to the Error Code field and shows the error code.

API Reference Guide

95

DDE for Excel Market Depth Page

Market Depth Page

Use the Market Depth page to view market depth for selected contracts. You can also view market depth for NYSE-listed products through the Open Book Market Data Subscription, and NASDAQ-listed products through the TotalView Market Data Subscriptions, if you have signed up for those subscriptions.

API Reference Guide

96

DDE for Excel Market Depth Page

Using the Market Depth Page

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To request market depth for a contract 1 2 3 Click the Market Depth tab at the bottom of the spreadsheet to open the Market Depth page. Select the ticker symbol for which you want to request the market depth, or enter a new ticker on a blank line. Click the Request Market Depth button on the toolbar.

To reset the market data refresh rate for tickers and market depth 1 2 3 4 Click the Tickers or Market Depth tab at the bottom of the spreadsheet. Type the desired market data refresh rate in milliseconds in the Refresh Rate field in the Which Trader Workstation? area. Move your cursor out of the Refresh Rate field. Click the Set Refresh Rate button on the toolbar.

To display more lines of market depth You can edit the Request Market Depth macro to show more than the default 10 lines. 1 From the Market Depth page, press Alt+F11. The Visual Basic Editor (VBE) opens and displays the code for the Market Depth page. 2 In the Declarations section at the top of the code window for the page, change the number value in numDisplayRows = 10 to a higher/lower value, then click the Save button on the VBE toolbar. Close the Visual Basic Editor.

API Reference Guide

97

DDE for Excel Market Depth Page

Market Depth Page Toolbar Buttons

The toolbar on the Market Depth page includes the following buttons: Button Request Market Depth Cancel Market Depth Set Refresh Rate Show Errors Description View bid/ask depth prices for the selected contract. Cancel market depth for the selected contract. Resets the refresh rate (in milliseconds) for market data. Jumps to the Error Code field and shows the error code.

API Reference Guide

98

DDE for Excel Advisors Page

Advisors Page
If you are a Financial Advisor and manage multiple accounts, use the Advisors page to create FA orders that:

allocate shares to a single managed account use FA account groups and methods use allocation profiles

Note:

You must set up your managed accounts, account groups, methods and allocation profiles in TWS before you can place FA orders in the DDE for Excel API sample spreadsheet.

API Reference Guide

99

DDE for Excel Advisors Page

Allocating Shares to a Single Account

You can use the Advisors page to set up an order and allocate all shares in the order to a single account. To allocate shares to a single account: 1 2 3 4 5 6 Create an account group in TWS. Click the Advisors tab at the bottom of the spreadsheet. Enter the contract information in the Contract Description cells, then enter the order information in the Order Description cells. Click the Extended Order Attributes tab. Enter the account code in the Value cell for the Account (Institutional only) extended order attribute. Click the Advisors tab. Highlight the order row, then click the Apply Extended button to apply the Account order attribute value to the order. The Account value is applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done allocating shares to the account, delete the Account value from the Extended Order Attributes page. If you do not delete this value, it will be applied to all subsequent orders placed from the DDE for Excel API spreadsheet.

7 8

API Reference Guide

100

DDE for Excel Advisors Page

Placing an Order using an FA Account Group and Method

You can also use the Advisors page to set up an order using an FA account group and FA method. To place an order using an FA account group and FA method: 1 2 3 4 Create the FA account group(s) and FA method(s) in TWS. Click the Advisors tab at the bottom of the spreadsheet. Enter the contract information in the Contract Description cells, then enter the order information in the Order Description cells. Click the Extended Order Attributes tab. Enter values for the following extended order attributes:

FA Group - Enter the name of the account group. FA Method - Enter the name of the allocation method to use for this order. FA Percentage - Enter the percentage used by the PctChange allocation method to use for this order. This attribute applies only to FA groups that use this method.

5 6

Click the Advisors tab. Highlight the order row, then click the Apply Extended button to apply the extended order attribute values to the order. The values for FA Group, FA Method and FA Percentage are applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done allocating shares to the account, delete the values you entered on the Extended Order Attributes page. If you do not delete these values, they will be applied to all subsequent orders placed from the DDE for Excel API spreadsheet.

7 8

API Reference Guide

101

DDE for Excel Advisors Page

Placing an Order using an Allocation Profile

You can also use the Advisors page to set up an order using an FA allocation profile. To place an order using an FA allocation profile: 1 2 3 4 5 6 Create the FA allocation profile in TWS. Click the Advisors tab at the bottom of the spreadsheet. Enter the contract information in the Contract Description cells, then enter the order information in the Order Description cells. Click the Extended Order Attributes tab. Enter the name of the allocation profile in the Value field for the FA Profile extended order attribute. Click the Advisors tab. Highlight the order row, then click the Apply Extended button to apply the extended order attribute value to the order. The value for FA Profile is applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done allocating shares to the account, delete the FA Profile value you entered on the Extended Order Attributes page. If you do not delete this value, it will be applied to all subsequent orders placed from the DDE for Excel API spreadsheet.

7 8

API Reference Guide

102

DDE for Excel Advisors Page

Advisors Page Toolbar Buttons

The toolbar on the Basic Orders page includes the following buttons: Button Combo Legs Place/Modify Orders Description Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. After you have completed the Order Description fields, and defined any extended attributes, click to create an order for the selected contract. This button cancels the order(s) you have highlighted. Applies the current values on the Extended Order Attributes page to the highlighted order row. Jumps to the Error Code field and shows the error code.

Cancel Order Apply Extended Show Errors

API Reference Guide

103

DDE for Excel DDE for Excel API Reference

DDE for Excel API Reference

This section provides a variety of reference information about the DDE for Excel API, including the following topics:

Viewing the Code Modules Named Ranges Macros DDE Syntax for Excel

Viewing the Code

To view the Visual Basic code behind the DDE for Excel API spreadsheet, press Alt+F11 from any page. The Visual Basic Editor opens:

The Visual Basic Editor contains three main components:

Project Explorer Properties Window Code Window

API Reference Guide

104

DDE for Excel DDE for Excel API Reference

The Project Explorer contains a list of objects used in the spreadsheet. These object correspond to the pages in the spreadsheet; to view the code for a particular page, double-click the pages corresponding object in the Project Explorer.

Modules
The Visual Basic code includes the following modules (visible in the VBE Project Explorer):

ArrayQueries ErrorDisplay Orders util

The util module contains many pre-defined constants that you can use when you program your own DDE API application. Using these constants instead of hard-coded values will make your application more robust and easier to maintain. Specifically, the following util functions are particularly useful in building new Visual Basic functionality:

composeLink put together a link that receives data, such as a market data bid size, option model volatility, or execution id. composeControlLink put together a link that causes operations to occur, such as subscribing to market data, placing orders, or subscribing to the market scanner. composeContractReq Read a contract description out of a page like Tickers or Orders, and build the DDE string representing it.

Named Ranges
Named ranges are a Microsoft Excel feature that lets you assign meaningful names to a single cell or a range of cells in Microsoft Excel. The TwsDde.xls sample spreadsheet used named ranges extensively. Named ranges help you to move data around on worksheets without breaking existing logic. It also makes important data available to your own custom macros and worksheets. You can view all the named ranges used in the spreadsheet by doing the following, depending on which version of Excel you are using:

In Excel 2007, you can see a complete list of all named ranges used in the spreadsheet by clicking Formulas then clicking Name Manager. The Name Manager displays every named range used in the spreadsheet, the value of the range, and the page and range of cells covered by the range. In earlier versions of Excel, you can view the named ranges by selecting Name > Define from the Tools menu. You can also download a free Name Manager from Microsoft that has additional functionality for these earlier versions of Excel.

API Reference Guide

105

DDE for Excel DDE for Excel API Reference

The following screen shows the Name Manager for the DDE for Excel API sample spreadsheet:

Macros
The DDE API sample spreadsheet uses Microsoft Excel macros extensively. Each toolbar button on every page in the spreadsheet runs a macro when you click it. For example, when you click the Request Market Data button on the Tickers page, you are actually running a macro called requestMarketData. You can see all the macros used in the sample spreadsheet by opening the Excel Macro dialog. From there you can choose to edit the macro, which opens macro code in the Visual Basic Editor.

Note:

You must enable macros when you open Excel or none of the macros in the spreadsheet will function.

For information about recording, editing and viewing macros, refer to your Microsoft Excel documentation.

API Reference Guide

106

DDE for Excel DDE for Excel API Reference

DDE Syntax for Excel

The table below defines possible cell values for DDE-supported functionality. The basic syntax, which appears in the Excel formula bar (the "=" enterable field at the top of the spreadsheet) when you put your cursor in a cell, is: =server|topic!id?reqType?field2 or =server|error!error (for an optional tag that will display errors) where:

server = the username topic = the function category, such as orders (ord) or tickers (tik) id = idn, where n is some integer. For orders, n must always increase, even from session to session. reqType = the request type, such as place or cancel field2 = additional information as noted below
Server server server server server server server server server server server server server server server server Topic ord ord ord ord ord ord ord ord ord ord ord ord ord ord ord id idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn reqType place modify cancel status open executed sharesFilled sharesRemaining price symbol secType expiry strike right multiplier Refer to Note 6 Refer to Note 7 Refer to Note 8 Refer to Note 8 Refer to Note 8 field2 orderDescription orderModification

Description Place an order Modify an order Cancel an order Check order status Request open orders Request executions Check shares filled in order Check shares remaining in order Execution (average) price Underlying Security type Expiry Strike Right Specify contract multiplier for options and futures Order destination Currency Order side Order quantity Order type

server server server server server

ord ord ord ord ord

idn idn idn idn idn

exchange currency side size orderType

API Reference Guide

107

DDE for Excel DDE for Excel API Reference

Description Limit price Auxiliary price Local symbol Last fill price Create ticker Bid implied volatility Bid delta Request bid size Request bid price Request ask price Request ask size Ask implied volatility Ask delta Request last price Request last size Last implied volatility Last delta Request today's high price Request today's low price Request today's volume size Request last close price Request implied volatility calculated by the TWS option modeler Request option delta calculated by the TWS option modeler Request the model price Request present value of dividends expected on the options underlier Request number of hold days until the expiry of the EFP Request expiration date of the single stock future

Server server server server server server server server server server server server server server server server server server server server server server server

Topic ord ord ord ord tik tik tik tik tik tik tik tik tik tik tik tik tik tik tik tik tik tik

id idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn

reqType limitPrice auxPrice localSymbol lastFillPrice req bidImpliedVol bidDelta bidSize bid ask askSize askImpliedVol askDelta last lastSize lastImpliedVol lastDelta high low volume close modelVolatility

field2

server

tik

idn

modelDelta

server server

tik tik

idn idn

modelPrice pvDividend

server

tik

idn

holdDays

server

tik

idn

futureExpiry

API Reference Guide

108

DDE for Excel DDE for Excel API Reference

Description Request dividends expected until the expiration of the single stock future Request annualized basis points Request annualized basis points in percentage form Request implied futures price Request the dividend impact on the annualized basis points interest rate Account statement control key Request one account value string Account value Account currency Account portfolio control key Account portfolio underlying symbol Account portfolio security type Account portfolio expiry Account portfolio strike price Account portfolio right Account portfolio currency Account portfolio local symbol Account portfolio market price Account portfolio market value Account portfolio average cost Account portfolio realized PNL

Server server

Topic tik

id idn

reqType dividendsToExpiry

field2

server server

tik tik

idn idn

basisPoints formattedBasis Points impliedFuture dividendImpact

server server

tik tik

idn idn

server

acct

idn

acctv

Account code (for Advisor-managed accounts only)

server server server server

acct acct acct acct

idn idn idn idn

key value keyCurrency acctp Account code (for Advisor-managed accounts only)

server server server server server server server server server server server

acct acct acct acct acct acct acct acct acct acct acct

idn idn idn idn idn idn idn idn idn idn idn

symbol secType expiry strike right currency localSymbol marketPrice marketValue avgCost realizedPNL

API Reference Guide

109

DDE for Excel DDE for Excel API Reference

Description Account portfolio unrealized PNL Request contract details Valid order types Valid exchanges Contract identifier Minimum tick Order multiplier Market name Trading class Execution order id Underlying Security type Expiry Strike Right Order destination Currency Local symbol Execution id Execution time Account number Exchange where executed Side Number of shares filled in order Execution (average) price Order ID Identifies position as one to be liquidated last Request execution details Request list of Advisor-managed accounts List of Advisor-managed accounts

Server server server server server server server server server server server server server server server server server server server server server server server server server server server server

Topic acct contract contract contract contract contract contract contract contract exec exec exec exec exec exec exec exec exec exec exec exec exec exec exec exec exec exec

id idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn idn

reqType unrealizedPNL req orderTypes validExchanges conid minTick multiplier marketName tradingClass orderId symbol secType expiry strike right exchange currency localSymbol execId time acctnNumber eExchange side shares price permId liquidation

field2

contractDescription

server server

exec FAaccts

idn idn

Req Req

executionFilter

server

FAaccts

idn

Value

API Reference Guide

110

DDE for Excel DDE for Excel API Reference

Description Request market depth

Server server

Topic mktDepth

id idn

reqType req

field2 contractDescripton? num_display_rows Refer to note (1) below. rowId_side Refer to note (2) below. rowId_side Refer to note (2) below. rowId_side Refer to note (2) below. Number of milliseconds Refer to note 3 below

Market maker

server

mktDepth

idn

mktMaker

Order price

server

mktDepth

idn

price

Order size

server

mktDepth

idn

size

Market data refresh rate Subscribe to news bulletins News bulletin message ID News bulletin message type News bulletin message text Exchange from which news bulletins originated Set the server log level

server server server server server server

refreshRate news news news news news

idn sub newsID newsType msg exchange

millisec 0

Refer to note 4 below

server

logLevel

<log_level>

Refer to note 5 below.

Where: orderDescription = side_quantity_symbol_secType_exp_strike_right_exchange_orderType_lmtPrice_auxPrice {_timeInForce_ocaGroup_account_open/close_origin_orderRef_transmit_parentId_blockOr der _sweepToFill_displaySize_triggerMethod_ignoreRth_hidden_clientId_accountCode_goodAft erTime_ goodTillDate_faGroup_faMethod_faPercentage_faProfile_shortSaleSlot_ PRIMARYEXCHANGE _shortSaleLocation_ocaType_rthOnly_rule80A_settlingFirm_allOrNone_minimumQty_perce ntOffset_ electronicTradeOnly_firmQuoteOnly_nbboPriceCap_auctionStrategy_startingPrice_stockRef Price_ delta_stockRangeLower_stockRangeUpper_volatility_volatilityType_referencePriceType_hed geDelta_ continuousUpdate} Attributes in brackets are extended order attributes and are described in the topic Extended Order Attributes.

Note:

API Reference Guide

111

DDE for Excel DDE for Excel API Reference

contractDescription - symbol_secType_exp_strike_right_exchange tickerDescription = symbol_secType_exp_strike_right_exchange ExecutionFilter = clientId_accountCode_date_time_symbol_secType_exchange_side When requesting market depth you can specify the number of rows to display. If not supplied, the default number of rows is five (5) rows. This parameter can be used to optimize performance, as a low number of display rows requires less CPU overhead. For example: =edemo|mktDepth!id0?req?MSFT_STK_SMART?10 will request 10 rows of market depth orders. Field 2 of the market depth 'price' and 'size' reqTypes contain additional information to specify the order row and side that the data applies to. Market depth orders are divided into two sides, BID and ASK, and order entries start from the offset 0. For example: =edemo|mktDepth!id0?price?0_ASK will request the ASK price for the order entry 0. =edemo|mktDepth!id0?size?2_BID will request the BID size for the order entry 2.

Note 1:

Note 2:

Note 3:

When subscribing to news bulletins, the request should look like this: =edemo|news!sub?0 where the request type is a zero. To unsubscribe simply clear the subscription cell.

Note 4:

The valid news bulletin types are: 1 = Regular news bulletin 2 = Exchange no longer available for trading 3 = Exchange available for trading

Note 5:

The valid log levels are: 1 2 3 4 5 = = = = = SYSTEM (least detailed) ERROR (default, if no level is specified) WARNING INFORMATION DETAIL (most detailed)

Note 6:

If the order is a combo, combo legs are inserted after the aux price. Here is a three-legged IBM combo description: CMBLGS_3_8314_100_BUY_SMART_0_36930759_1_BUY_SMART_0_36930816_1_SELL_SMA RT_0_CMBLGS. Each leg contains : contract ID, number of contracts, side, exchange, and open/close (0 or 1). Retail can always specify 0, institutional need to specify a 1 if the order being executed would close a position.

Note 7: Note 8:

If the order is an option or a future, the expiry is inserted after the sec type. If the order is an option, the strike and right (put or call) are inserted after the expiry. If the multiplier is specified, it follows the strike and right.

API Reference Guide

112

ActiveX
This chapter describes the ActiveX API, including the following topics:

3
Linking to the Application using ActiveX Registering Third-Party ActiveX Controls Running the ActiveX API on 64-bit Windows XP Systems Using the Visual Basic Sample Program ActiveX Methods ActiveX Events ActiveX COM Objects ActiveX Properties Placing a Combination Order The API software also includes an ActiveX for Excel sample spreadsheet, which duplicates most of the functionality of the DDE for Excel sample spreadsheet but is based on the ActiveX control, Tws.ocx. See ActiveX for Excel for details.

Note:

API Reference Guide

113

ActiveX Linking to the Application using ActiveX

Linking to the Application using ActiveX

Before you can use third-party ActiveX controls, you must register them with Visual Basic. To link using the ActiveX control and VB, VBA or C++ 1 2 Drop the application control onto a form or dialog box. Call the following methods:

Call the connect() method to connect to the running application. Call the methods you need to perform whatever operations you require, such as the reqMktData() method to request market data.

3 4

Call the placeOrder() method to place an order. Orders using extended attributes require that ActiveX properties representing them be set first. Handle the following events:

Handle the nextValidId() event to receive the next available valid order ID. Increment the ID by one for successive orders. Handle the tickPrice() and tickSize() events to receive the market data. Handle the orderStatus() event to receive status information about orders. Handle the error() event to receive error information. Handle the connectionClosed() event to be notified in case the application stops communicating with the ActiveX control.

API Reference Guide

114

ActiveX Registering Third-Party ActiveX Controls

Registering Third-Party ActiveX Controls

To use a third-party ActiveX control in Visual Basic it must be registered first. To register the ActiveX control with Visual Basic, follow these instructions: 1 2 3 From the Components menu in your VB project, select the TWS ActiveX control (Tws.ocx). Click Apply. Verify that the TWS control appears in the toolbar with all standard controls.

Running the ActiveX API on 64-bit Windows XP Systems

To run the ActiveX API on 64-bit Windows XP systems, do the following: 1 2 3 Install Microsoft Visual C++ 2005 SP1 Redistributable Package (x86). Install Microsoft Visual J# 2.0 Redistributable Package. Download and install the API software.

API Reference Guide

115

ActiveX Using the Visual Basic Sample Program

Using the Visual Basic Sample Program

You can access the server through the ActiveX interface using the Visual Basic sample application. To run the sample you must:

Install the API sample programs Configure the application to support the API components Have MS Visual Studio (Visual Basic 6.0 or higher) installed on your PC.

The Visual Basic program is a sample program that demonstrates use of the TWS ActiveX control to connect to the server from a Visual Basic application. To open the VB_API_sample program: 1 2 From the MS Visual Basic file menu, select Open Project. Navigate to the \TestActiveXClient_VB directory in your API installation folder, and select VB_API_sample.vbp. X_XX represents the API version number; for example, 9.60. If you are using Visual Studio 2008, you will have to upgrade your project before it can be opened. Visual Basic presents an Upgrade Wizard to walk you through this simple process. 3 4 5 Note: On the Projects menu, select Components. In the Components dialog box, select the TWS ActiveXControl module and click OK. Press Ctrl+F5 to compile and run the project. If you have trouble getting the sample program to run, try re-registering the TWS ActiveX component, Tws.ocx.

API Reference Guide

116

ActiveX ActiveX Methods

ActiveX Methods
ActiveX methods allow your application to call functions and request information from TWS. Note: Please note that methods in red have been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods. The new "Ex" methods have been

API Reference Guide

117

ActiveX ActiveX Methods

grouped with their deprecated counterparts for easy identification. Connection and Server
connect() disconnect() reqCurrentTime() setServerLogLevel()

Account
reqAccountUpdates()

News Bulletins
reqNewsBulletins() cancelNewsBulletins()

Market Data
reqMktDataEx() reqMktData() reqMktData2() cancelMktData()

Financial Advisors
reqManagedAccts() requestFA() replaceFA()

calculateImpliedVolatility() cancelCalculateImpliedVolatility() calculateOptionPrice() cancelCalculateOptionPrice() Orders

placeOrderEx() placeOrder() placeOrder2() cancelOrder() reqOpenOrders() reqAllOpenOrders() reqAutoOpenOrders() reqIds() exerciseOptionsEx() exerciseOptions() addComboLeg() clearComboLegs()

Historical Data
reqHistoricalDataEx() requestHistoricalData() cancelHistoricalData()

Market Scanners
reqScannerParameters() reqScannerSubscriptionEx() reqScannerSubscription() cancelScannerSubscription()

Real Time Bars

reqRealTimeBarsEx() reqRealTimeBars() cancelRealTimeBars()

Factory Methods
createComboLegList() createContract() createExecutionFilter() createOrder() createScannerSubscription() createTagValueList() createUnderComp()

Executions
reqExecutionsEx() reqExecutions()

Contract Details
reqContractDetailsEx() reqContractDetails() reqContractDetails2()

Fundamental Data
reqFundamentalData() cancelFundamentalData()

Market Depth
reqMktDepthEx() reqMktDepth() reqMktDepth2() cancelMktDepth()

API Reference Guide

118

ActiveX ActiveX Methods

connect()
Call this method to connect to the host application. Public Overridable Sub connect(ByVal host as String, ByVal port as Integer, ByVal clientID as Integer Parameter host port clientID Description The host name or IP address of the machine where TWS is running. Leave blank to connect to the local host. Must match the port specified in TWS on the Configure>API>Socket Port field. A number used to identify this client connection. All orders placed/modified from this client will be associated with this client identifier. Note: Each client MUST connect with a unique clientId.

disconnect()
Call this method to terminate the connections the host application. Calling this method does not cancel orders that have already been sent. Public Overridable Sub disconnect()

reqMktDataEx()
Call this method to request market data. The market data will be returned by the tickPrice(), tickSize(), tickOptionComputation(), tickGeneric(), tickString() and tickEFP() events in dispinterface_DTwsEvents. Public Overridable Sub reqMktDataEx(ByVal tickerId As Integer, ByVal contract As TWSLib.IContract, ByVal genericTicks As String, ByVal snapshot As Integer) Parameter tickerId Description The ticker id. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. This object contains a description of the contract for which market data is being requested. A comma delimited list of generic tick types. For more information about tick types, seeGeneric Tick Types. Check to return a single snapshot of market data and have the market data subscription cancel. Do not enter any genericTicklist values if you use snapshot.

contract genericTicks snapshot

API Reference Guide

119

ActiveX ActiveX Methods

reqMktData()
Call this method to request market data. The market data will be returned by the tickPrice() and tickSize() events. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub reqMktData(ByVal id As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal multiplier As String, ByVal exchange As String, ByVal primaryExchange As String, ByVal currency As String, ByVal genericTicks As String, ByVal snapshot As Integer) Parameter id Description The ticker id. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. The symbol of the underlying for which you are requesting market data. The security type. Valid values are: expiry strike right multiplier exchange primaryExchange STK OPT FUT IND FOP CASH

symbol secType

The expiration data. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. - allows you to specify a futures or options multiplier in cases where multiple possibilities exist. The order destination, such as Smart. The primary exchange on which the product trades, used to definitively identify a product. To clarify any ambiguity for Smart-routed contracts, include the primary exchange, along with the Smart designation, for the destination. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. Check to return a single snapshot of market data and have the market data subscription cancel. Do not enter any genericTicklist values if you use snapshot.

currency

snapshot

API Reference Guide

120

ActiveX ActiveX Methods

reqMktData2()
Call this method to request market data using the exchange symbol. The market data will be returned by the tickPrice() and tickSize() events. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub reqMktData2(ByVal id As Integer, ByVal localSymbol As String, ByVal secType As String, ByVal exchange As String, ByVal primaryExchange As String, ByVal currency As String, ByVal genericTicks As String, ByVal snapshot As Integer) Parameter id Description The ticker id. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. The local exchange symbol of the underlying for which you are requesting market data. The security type. Valid values are: exchange primaryExchange currency STK OPT FUT IND FOP CASH

localSymbol secType

The order destination, such as SMART. The primary exchange on which the product trades, used to definitively identify a product. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. A comma delimited list of generic tick types. Tick types can be found in the Generic Tick Types page. Check to return a single snapshot of market data and have the market data subscription cancel. Do not enter any genericTicklist values if you use snapshot.

genericTicklist snapshot

API Reference Guide

121

ActiveX ActiveX Methods

cancelMktData()
After calling this method, market data for the specified id will stop flowing. Public Overridable Sub cancelMktData(ByVal id As Integer) Parameter id Description The ID that was specified in the call to reqMktData().

calculateImpliedVolatility()
Call this function to calculate volatility for a supplied option price and underlying price. Public Overridable Sub calculateImpliedVolatility(ByVal reqId As Integer, ByVal contract As TWSLib.IContract, ByVal optionPrice As Double, ByVal underPrice As Double) Parameter reqId contract optionPrice underPrice Description The ticker ID. Describes the contract. The price of the option. Price of the underlying.

cancelCalculateImpliedVolatility()
Call this function to cancel a request to calculate volatility for a supplied option price and underlying price. Public Overridable Sub calculateImpliedVolatility(ByVal reqId As Integer) Parameter reqId Description The ticker id.

calculateOptionPrice()
Call this function to calculate option price and greek values for a supplied volatility and underlying price. Public Overridable Sub calculateOptionPrice(ByVal reqId As Integer, ByVal contract As TWSLib.IContract, ByVal volatility As Double, ByVal underPrice As Double) Parameter reqId contract volatility underPrice Description The ticker ID. Describes the contract. The volatility. Price of the underlying.

API Reference Guide

122

ActiveX ActiveX Methods

cancelCalculateOptionPrice()
Call this function to cancel a request to calculate option price and greek values for a supplied volatility and underlying price. Public Overridable Sub calculateOptionPrice(ByVal reqId As Integer) Parameter reqId Description The ticker id.

placeOrderEx()
Call this method to place an order. The order status will be returned by the orderStatus() event in dispinterface_DTwsEvents. Public Overridable Sub placeOrderEx(ByVal orderId As Integer, ByVal contract As TWSLib.IContract, ByVal order As TWSLib.IOrder) Parameter orderId Description The order Id. You must specify a unique value. When the order status returns, it will be identified by this tag. This tag is also used when canceling the order. This object contains attributes used to describe the contract. This object contains the details of the order. Note: Each client MUST connect with a unique clientId.

contract order

placeOrder()
Call this method to place an order. The order status will be returned by the orderStatus() event. For more details see Active X Properties. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub placeOrder(ByVal id As Integer, ByVal action As String, ByVal quantity As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal multiplier As String, ByVal exchange As String, ByVal primaryExchange As String, ByVal curency As String, ByVal orderType As String, ByVal price As Double, ByVal auxPrice As Double, ByVal goodAfterTime As String, ByVal group As String, ByVal faMethod As String, ByVal faPercentage As String, ByVal faProfile As String, ByVal goodTillDate As String) Parameter id Description The order id. You must specify a unique value. When the order status returns, it will be identified by this tag. This tag is also used when canceling the order.

API Reference Guide

123

ActiveX ActiveX Methods

Parameter action

Description Identifies the side. Valid values are: BUY SELL SSHORT

quantity symbol secType

The order quantity. The symbol of the underlying asset. The security type. Valid values are: STK OPT FUT FOP CASH

expiry strike right multiplier exchange primaryExchange curency

The expiration date. Use the format YYYYMM. The strike price Specifies a Put or Call. Valid values are: P, PUT, C, CALL. Allows you to specify a futures or options multiplier in cases where multiple possibilities exist. The order destination, such as Smart. The primary exchange on which the product trades, used to definitively identify a product. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. Identifies the order type. Valid values are: MKT MKTCLS LMT LMTCLS PEGMKT SCALE STP STPLMT TRAIL REL VWAP

orderType

API Reference Guide

124

ActiveX ActiveX Methods

Parameter lmtPrice

Description The LIMIT price, used for limit, stop-limit and relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero. Identifies the STOP price for stop-limit orders, and the offset amount for relative orders. In all other cases, specify zero. Specifies that the order becomes active after the time set. Send an empty string if not applicable. Specifies the order's "Financial Advisor Group." Send an empty string if not an FA. Specifies the order's "Financial Advisor Allocation Method." Send an empty string if not an FA. Specifies the order's "Financial Advisor Percentage." Send an empty string if not an FA. Specifies the order's "Financial Advisor Profile." Send an empty string if not an FA. Specifies the order's "Good Till Date." Send an empty string if not applicable.

lmtPrice goodAfterTime group faMethod faPercentage faProfile goodTillDate

API Reference Guide

125

ActiveX ActiveX Methods

placeOrder2()
Call this method to place an order using the exchange symbol. The order status will be returned by the orderStatus() event. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub placeOrder2(ByVal id As Integer, ByVal action As String, ByVal quantity As Integer, ByVal localSymbol As String, ByVal secType As String, ByVal exchange As String, ByVal primaryExchange As String, ByVal curency As String, ByVal orderType As String, ByVal lmtPrice As Double, ByVal auxPrice As Double, ByVal goodAfterTime As String, ByVal group As String, ByVal faMethod As String, ByVal faPercentage As String, ByVal faProfile As String, ByVal goodTillDate As String) Parameter id Description The order id. You must specify a unique value. When the order status returns, it will be identified by this tag. This tag is also used when canceling the order. Identifies the side. Valid values are: quantity localSymbol secType BUY SELL SSHORT

action

The order quantity. The local exchange symbol of the underlying asset. The security type. Valid values are: STK OPT FUT FOP CASH

exchange primaryExchange curency

The order destination, such as Smart. The primary exchange on which the product trades, used to definitively identify a product. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency.

API Reference Guide

126

ActiveX ActiveX Methods

Parameter orderType

Description Identifies the order type. Valid values are: MKT MKTCLS LMT LMTCLS PEGMKT SCALE STP STPLMT TRAIL REL VWAP

lmtPrice

The LIMIT price, used for limit, stop-limit and relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero. Identifies the STOP price for stop-limit orders, and the offset amount for relative orders. In all other cases, specify zero. Specifies that the order becomes active after the time set. Send an empty string if not applicable. Specifies the order's "Financial Advisor Group." Send an empty string if not an FA. Specifies the order's "Financial Advisor Allocation Method." Send an empty string if not an FA. Specifies the order's "Financial Advisor Percentage." Send an empty string if not an FA. Specifies the order's "Financial Advisor Profile." Send an empty string if not an FA. Specifies the order's "Good Till Date." Send an empty string if not applicable.

auxPrice goodAfterTime group faMethod faPercentage faProfile goodTillDate

cancelOrder()
Call this method to cancel an order. Public Overridable Sub cancelOrder(ByVal id As Integer) Parameter id Description The order ID that was specified previously in the call to placeOrder()

API Reference Guide

127

ActiveX ActiveX Methods

reqOpenOrders()
Call this method to request the open orders that were placed from this client. Each open order will be fed back through the openOrder1, openOrder2, openOrder3, openOrder4 or openOrderEx() events. Note: The client with a clientId of 0 will also receive the application-owned open orders. These orders will be associated with the client and a new orderId will be generated. This association will persist over multiple API and application sessions.

Public Overridable Sub reqOpenOrders()

reqAllOpenOrders()
Call this method to request the open orders that were placed from all clients and also from the application.Each open order will be fed back through the orderStatus() event. Note: No association is made between the returned orders and the requesting client

Public Overridable Sub reqAllOpenOrders()

reqAutoOpenOrders()
Call this method to request that newly created application orders be implicitly associated with the client. When a new application order is created, the order will be associated with the client, and fed back through the orderStatus() event. Note: This request can only be made from a client with a clientId of 0.

Public Overridable Sub reqAutoOpenOrders(ByVal bAutoBind As Integer) Parameter bAutoBind Description If set to TRUE, newly created application orders will be implicitly associated with the client. If set to FALSE, no association will be made.

reqExecutionsEx()
When this method is called, the execution reports that meet the filter criteria are downloaded to the client via the execDetailsEx() event in dispinterface_DTwsEvents. Public Overridable Sub reqExecutionsEx(ByVal reqId As Integer, ByVal filter As TWSLib.IExecutionFilter) Parameter filter Description The filter criteria used to determine which execution reports are returned.

reqExecutions()
When this method is called, all execution reports are downloaded to the client via the execDetails() event. Public Overridable Sub reqExecutions()
API Reference Guide 128

ActiveX ActiveX Methods

reqIds()
Call this function to request the next valid ID that can be used when placing an order. After calling this method, the nextValidId() event will be triggered, and the id returned is that next valid ID. That ID will reflect any autobinding that has occurred (which generates new IDs and increments the next valid ID therein). Public Overridable Sub reqIds(ByVal numIds As Integer) Parameter numIds Description Set to 1.

reqContractDetailsEx()
Call this method to download all details for a particular contract. The contract details will be received via the contractDetailsEx() callback in dispinterface_DTwsEvents. Public Overridable Sub reqContractDetailsEx(ByVal reqId As Integer, ByVal contract As TWSLib.IContract) Parameter reqId contract Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. This object contains a description of the contract for which market data is being requested.

API Reference Guide

129

ActiveX ActiveX Methods

reqContractDetails()
Call this method to request details for a particular underlying or security. The contract details data will be returned by the contractDetails() event. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub reqContractDetails(ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal multiplier As String, ByVal exchange As String, ByVal curency As String, ByVal includeExpired As Integer) Parameter symbol secType Description The symbol of the underlying for which you are requesting market data. The security type. Valid values are: expiry strike right multiplier exchange curency STK OPT FUT IND FOP CASH

The expiration data. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. Allows you to specify a futures or options multiplier in cases where multiple possibilities exist. The order destination, such as SMART. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency.

API Reference Guide

130

ActiveX ActiveX Methods

reqContractDetails2()
Call this method to request details for a particular security using the exchange symbol. The contract details data will be returned by the contractDetails() event. Public Overridable Sub reqContractDetails2(ByVal localSymbol As String, ByVal secType As String, ByVal exchange As String, ByVal curency As String, ByVal includeExpired As Integer) Parameter localSymbol secType Description The local exchange symbol of the underlying for which you are requesting market data. The security type. Valid values are: exchange curency STK OPT FUT IND FOP CASH

The order destination, such as SMART. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency.

reqMktDepthEx()
Call this method to request market depth for a specific contract. The market depth will be returned by the updateMktDepth() and updateMktDepthL2() events. Public Overridable Sub reqMktDepthEx(ByVal tickerId As Integer, ByVal contract As TWSLib.IContract, ByVal numRows As Integer) Parameter tickerId Description The ticker Id. Must be a unique value. When the market depth data returns, it will be identified by this tag. This is also used when canceling the market depth. This object contains a description of the contract for which market data is being requested. Specifies the number of market depth rows to return.

contract numRows

API Reference Guide

131

ActiveX ActiveX Methods

reqMktDepth()
Call this method to request market depth details for a particular underlying or security. The market depth data will be returned by the updateMktDepth() and updateMktDepthL2() events. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub reqMktDepth(ByVal id As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal multiplier As String, ByVal exchange As String, ByVal curency As String, ByVal numRows As Integer) Parameter id Description The ticker id. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. The symbol of the underlying for which you are requesting market data. The security type. Valid values are: expiry strike right multiplier exchange curency STK OPT FUT IND FOP CASH

symbol secType

The expiration data. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. Allows you to specify a futures or options multiplier in cases where multiple possibilities exist. The order destination, such as SMART. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. Specifies the number of market depth rows you want to display.

numRows

API Reference Guide

132

ActiveX ActiveX Methods

reqMktDepth2()
Call this method to request market depth details for a particular underlying or security. The market depth data will be returned by the updateMktDepth() and updateMktDepthL2() events. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub reqMktDepth2(ByVal id As Integer, ByVal localSymbol As String, ByVal secType As String, ByVal exchange As String, ByVal curency As String, ByVal numRows As Integer) Parameter id Description The ticker id. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. The local exchange symbol of the underlying for which you are requesting market data. The security type. Valid values are: exchange curency STK OPT FUT IND FOP CASH

localSymbol secType

The order destination, such as SMART. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. Specifies the number of market depth rows you want to display.

numRows

cancelMktDepth()
After calling this method, market depth for the specified id will stop flowing. Public Overridable Sub cancelMktDepth(ByVal id As Integer) Parameter id Description The ID that was specified in the call to reqMktDepth() or reqMktDepth2().

API Reference Guide

133

ActiveX ActiveX Methods

addComboLeg()
This method adds a leg definition to an order and must be called for each leg before the combination order can be placed. Combination orders must have a secType of 'BAG." Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed.

Public Overridable Sub addComboLeg(ByVal conId As Integer, ByVal action As String, ByVal ratio As Integer, ByVal exchange As String, ByVal openClose As Integer, ByVal shortSaleSlot As Integer, ByVal designatedLocation As String) Parameter conid action ratio Description The unique contract identifier specifying the security. Select the side (buy or sell) for the leg you are constructing. Select the relative number of contracts for the leg you are constructing. To help determine the ratio for a specific combination order, use Interactive Analytics (see Interactive Analytics in the User's Guide). The exchange to which the complete combination order will be routed. Specifies whether the order is an open or close order. Valid values are: shortSaleSlot Same - (0) same as the parent security. This is the only option for retail customers. Open - (1) This option is for Institutional Customers only. Close - (2) This option is for Institutional Customers only. 0 - inapplicable (i.e. retail customer or not short leg) 1 - clearing broker 2 - third party. If this value is used, you must enter a designated location.

exchange openClose

For institutional customers only.

designatedLocation

If shortSaleSlot == 2, the designatedLocation must be specified. Otherwise leave blank or orders will be rejected.

API Reference Guide

134

ActiveX ActiveX Methods

clearComboLegs()
This method must be called to remove all leg definitions from a combination order before constructing a new combination order. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed.

Public Overridable Sub clearComboLegs()

reqNewsBulletins()
Call this method to start receiving news bulletins. Each bulletin will be returned by the updateNewsBulletin() event. Public Overridable Sub reqNewsBulletins(ByVal allDaysMsgs As Integer) Parameter allDaysMsgs Description If set to TRUE, returns all the existing bulletins for the current day and any new ones. If set to FALSE, will only return new bulletins.

cancelNewsBulletins()
Call this method to stop receiving news bulletins. Public Overridable Sub cancelNewsBulletins()

setServerLogLevel()
The default level is ERROR. See API Logging for more details. Public Overridable Sub setServerLogLevel(ByVal logLevel As Integer) Parameter logLevel Description Specifies the level of log entry detail used by the server when processing API requests. Valid values include: 1 = SYSTEM 2 = ERROR 3 = WARNING 4 = INFORMATION 5 = DETAIL

API Reference Guide

135

ActiveX ActiveX Methods

reqManagedAccts()
Call this method to request the list of managed accounts. The list will be returned by the managedAccounts() event. Note: This request can only be made when connected to a Financial Advisor account.

Public Overridable Sub reqManagedAccts()

reqAccountUpdates()
Call this method to request account updates. The account data will be fed back through the updateAccountTime(), updateAccountValue() and updatePortfolio() events. Public Overridable Sub reqAccountUpdates(ByVal subscribe As Integer, ByVal acctCode As String) Parameter subscribe Description If set to 1, the client will start receiving account and portfolio updates. If set to 2, the client will stop receiving this information. The account code for which to receive account and portfolio updates.

acctCode

requestFA()
Call this method to request FA configuration information from the server. The data returns in an XML string via the receiveFA() event. Public Overridable Sub requestFA(ByVal faDataType As Integer) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being requested. Valid values include: 1 = GROUPS 2 = PROFILE 3 =ACCOUNT ALIASES

API Reference Guide

136

ActiveX ActiveX Methods

replaceFA()
Call this method to modify FA configuration information from the API. Note that this can also be done manually. Public Overridable Sub replaceFA(ByVal faDataType As Integer, ByVal cxml As String) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being modified via the API. Valid values include: cxml 1 = GROUPS 2 = PROFILE 3 =ACCOUNT ALIASES

The XML string containing the new FA configuration information.

API Reference Guide

137

ActiveX ActiveX Methods

reqHistoricalDataEx()
Call this method to start receiving historical data results through the historicalData() event. Note: For a information about historical data request limitations, see Historical Data Limitations.

Public Overridable Sub reqHistoricalDataEx(ByVal tickerId As Integer, ByVal contract As TWSLib.IContract, ByVal endDateTime As String, ByVal duration As String, ByVal barSize As String, ByVal whatToShow As String, ByVal useRTH As Integer, ByVal formatDate As Integer) Parameter tickerId Description The Id for the request. Must be a unique value. When the data is received, it will be identified by this Id. This is also used when canceling the historical data request. This structure contains a description of the contract for which market data is being requested. Use the format yyyymmdd hh:mm:ss tmz, where the time zone is allowed (optionally) after a space at the end. This is the time span the request will cover, and is specified using the format: <integer> <unit>, i.e., 1 D, where valid units are: S (seconds) D (days) W (weeks) M (months)

contract endDateTime durationStr

Y (years) Note: If no unit is specified, seconds are used. Also, note "years" is currently limited to one.

API Reference Guide

138

ActiveX ActiveX Methods

Parameter barSize

Description The size of the bars that will be returned (within IB/TWS limits). Valid values include: Bar Size 1 sec 5 secs 15 secs 30 secs 1 min 2 mins 3 mins 5 mins 15 mins 30 mins 1 hour 1 day 1 week 1 month 3 months 1 year Determines the nature of data being extracted. Valid values include: TRADES MIDPOINT BID ASK BID_ASK HISTORICAL_VOLATILITY OPTION_IMPLIED_VOLATILITY OPTION_VOLUME

whatToShow

useRTH

Determines whether to return all data available during the requested time span, or only data that falls within regular trading hours. Valid values include: 0 - all data is returned even where the market in question was outside of its regular trading hours. 1 - only data within the regular trading hours is returned, even if the requested time span falls partially or completely outside of the RTH.

API Reference Guide

139

ActiveX ActiveX Methods

Parameter formatDate

Description Determines the date format applied to returned bars. Valid values include: 1 - dates applying to bars returned in the format: yyyymmdd{space}{space}hh:mm:dd 2 - dates are returned as a long integer specifying the number of seconds since 1/1/1970 GMT.

API Reference Guide

140

ActiveX ActiveX Methods

reqHistoricalData()
This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods. Public Overridable Sub reqHistoricalData(ByVal id As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal multiplier As String, ByVal exchange As String, ByVal curency As String, ByVal isExpired As Integer, ByVal endDateTime As String, ByVal durationStr As String, ByVal barSizeSetting As String, ByVal whatToShow As String, ByVal useRTH As Integer, ByVal formatDate As Integer) Parameter id Description The ticker id. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. The symbol of the underlying for which you are requesting market data. The security type. Valid values are: expiry strike right multiplier exchange curency STK OPT FUT IND FOP CASH

symbol secType

The expiration data. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. Allows you to specify a futures or options multiplier in cases where multiple possibilities exist. The order destination, such as Smart. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. Defines a query end date and time at any point during the past 6 mos. Valid values include any date/time within the past six months in the format: yyyymmdd HH:mm:ss zzz where "zzz" is the optional time zone. Set the query duration up to one week, using a time unit of seconds, days or weeks. Valid values include any integer followed by a space and then S (seconds), D (days) or W (week). If no unit is specified, seconds is used.

endDateTime

durationStr

API Reference Guide

141

ActiveX ActiveX Methods

Parameter barSizeSetting

Description Specifies the size of the bars that will be returned (within IB/TWS limits). Valid values include: Specifies the size of the bars that will be returned (within IB/TWS limits). Valid values include: Bar Size Parametric Value 1 sec 1 5 secs 2 15 secs 3 30 secs 4 1 min. 5 2 mins 6 5 mins 7 15 mins 8 30 mins 9 1 hour 10 1 day 11 1 week 12 1 month 13 3 months 14 1 year 15 Determines the nature of data being extracted. Valid values include: TRADES MIDPOINT BID ASK BID_ASK

whatToShow

useRTH

Determines whether to return all data available during the requested time span, or only data that falls within regular trading hours. Valid values include: 0 - all data is returned even where the market in question was outside of its regular trading hours. 1 - only data within the regular trading hours is returned, even if the requested time span falls partially or completely outside of the RTH.

formatDate

Determines the date format applied to returned bars. Valid values include: 1 - dates applying to bars returned in the format: yyyymmdd{space}{space}hh:mm:dd 2 - dates are returned as a long integer specifying the number of seconds since 1/1/1970 GMT.

API Reference Guide

142

ActiveX ActiveX Methods

exerciseOptionsEx()
Call this method to exercise options. Note: Please note that SMART is not an allowed exchange in exerciseOptionsEx() calls, and that TWS does a request for the position in question whenever any API initiated exercise or lapse is attempted.

Public Overridable Sub exerciseOptionsEx(ByVal tickerId As Integer, ByVal contract As TWSLib.IContract, ByVal exerciseAction As Integer, ByVal exerciseQuantity As Integer, ByVal account As String, ByVal override As Integer) Parameter tickerId contract exerciseAction Description The Id for the exercise request This structure contains a description of the contract for which market data is being requested. This can have two values: exerciseQuantity account override 1 = exercise 2 = lapse

The number of contracts to be exercised For institutional orders. Specifies the IB account. Specifies whether your setting will override the system's natural action. For example, if your action is "exercise" and the option is not in-the-money, by natural action the option would not exercise. If you have override set to "yes" the natural action would be overridden and the out-of-the money option would be exercised. Values are: 0 = do not override 1 = override

API Reference Guide

143

ActiveX ActiveX Methods

exerciseOptions()
Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub exerciseOptions(ByVal id As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal multiplier As String, ByVal exchange As String, ByVal curency As String, ByVal exerciseAction As Integer, ByVal exerciseQuantity As Integer, ByVal override As Integer) Parameter id symbol secType expiry strike right multiplier Description The ticker id. Must be a unique value. The symbol of the underlying The option type. Values include: OPT, FOP, WAR The expiration date. Use the format YYYYMM The strike price The option right, use values P, PUT, C, or CALL Allows you to specify a futures or option multiplier in cases where more than one possibility exists. If no multiplier is specified, a default value of "100" is assumed. The order destination. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. Specifies whether you want the option to lapse or be exercised. Values are 1 = exercise, 2 = lapse. The quantity you want to exercise. Specifies whether your setting will override the system's natural action. For example, if your action is "exercise" and the option is not in-the-money, by natural action the option would not exercise. If you have override set to "yes" the natural action would be overridden and the out-of-the money option would be exercised. Values are: 0 = no, 1 = yes.

exchange curency

exerciseAction exerciseQuantity override

reqScannerParameters()
Requests an XML string that describes all possible scanner queries. Public Overridable Sub reqScannerParameters()

API Reference Guide

144

ActiveX ActiveX Methods

reqScannerSubscriptionEx()
Call the reqScannerSubscriptionEX() method to start receiving market scanner results through the scannerDataEx() event. Public Overridable Sub reqScannerSubscriptionEx(ByVal tickerId As Integer, ByVal subscription As TWSLib.IScannerSubscription) Parameter tickerId Description The Id for the subscription. Must be a unique value. When the subscription data is received, it will be identified by this Id. This is also used when canceling the scanner. Summary of the scanner subscription parameters including filters.

subscription

reqScannerSubscription()
Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub reqScannerSubscription(ByVal tickerId As Integer, ByVal numberOfRows As Integer, ByVal instrument As String, ByVal locationCode As String, ByVal scanCode As String, ByVal abovePrice As Double, ByVal belowPrice As Double, ByVal aboveVolume As Integer, ByVal marketCapAbove As Double, ByVal marketCapBelow As Double, ByVal moodyRatingAbove As String, ByVal moodyRatingBelow As String, ByVal spRatingAbove As String, ByVal spRatingBelow As String, ByVal maturityDateAbove As String, ByVal maturityDateBelow As String, ByVal couponRateAbove As Double, ByVal couponRateBelow As Double, ByVal excludeConvertible As Integer, ByVal averageOptionVolumeAbove As Integer, ByVal scannerSettingPairs As String, ByVal stockTypeFilter As String) Parameter tickerId numberOfRows instrument locationCode Description The ticker ID. Must be a unique value. Defines the number or rows to display. Defines the instrument type used in the scan. Values include STK, Currently limited to US Stocks, with NYSE, AMEX, NASDAQ, and OTCBB being sub-types. STK.US is a legal value for this parameter. Available values are listed in the scanner parameters XML document. The type of the scan, such as HIGH_OPT_VOLUME_PUT_CALL_RATIO. Available values are listed in the scanner parameters XML document. Filter out contracts with a price lower than this value. Can be left blank. Filter out contracts with a price above than this value. Can be left blank.
145

scanCode

abovePrice belowPrice

API Reference Guide

ActiveX ActiveX Methods

Parameter aboveVolume marketCapAbove marketCapBelow moodyRatingAbove moodyRatingBelow spRatingAbove spRatingBelow maturityDateAbove maturityDateBelow couponRateAbove couponRateBelow excludeConvertible scannerSettingPairs

Description Filter out contracts with a volume below this value. Can be left blank. Filter out contracts with a volume above this value. Can be left blank. Filter out contracts with a market cap above this value. Can be left blank. Filter out contracts with a moody rating below this value. Can be left blank. Filter out contracts with a moody rating above this value. Can be left blank. Filter out contracts with an S&P rating lower than this value. Can be left blank. Filter out contracts with an S&P rating higher than this value. Can be left blank. Filter out contracts with a maturity date later than this value. Can be left blank. Filter out contracts with a maturity date earlier than this value. Can be left blank. Filter out contracts with a coupon rate lower than this value. Can be left blank. Filter out contracts with a coupon rate higher than this value. Can be left blank. Filter out convertible bonds. Can be left blank. Used with the scanCode to help further narrow your query return. Scanner Setting Pairs are delimited by slashes, making this parameter open ended. A pair example is "Annual,true" which when used with Top Option Implied Vol % Gainers scan would return annualized volatilities. defines the stock type to be returned with respect to stocks and ETFs. Valid values include: ALL - excludes nothing STOCK - which excludes ETFs ETF - which includes ETFs

stockTypeFilter

averageOptionVolume Above

Filter out contracts with an average volume lower than this value.

API Reference Guide

146

ActiveX ActiveX Methods

cancelHistoricalData()
Used if an internet disconnect has occurred or the results of a query are otherwise delayed and the application is no longer interested in receiving the data. Public Overridable Sub cancelHistoricalData(ByVal tickerId As Integer) Parameter tickerId Description The ticker ID. Must be a unique value.

cancelScannerSubscription()
Public Overridable Sub cancelScannerSubscription(ByVal tickerId As Integer) Parameter tickerId Description The ticker ID. Must be a unique value.

reqRealTimeBarsEx()
Call the reqRealTimeBarsEx() method to start receiving real time bar results through the realtimeBar() event. Public Overridable Sub reqRealTimeBarsEx(ByVal tickerId As Integer, ByVal contract As TWSLib.IContract, ByVal barSize As Integer, ByVal whatToShow As String, ByVal useRTH As Integer) Parameter tickerId Description The Id for the request. Must be a unique value. When the data is received, it will be identified by this Id. This is also used when canceling the historical data request. This structure contains a description of the contract for which market data is being requested. Currently only 5 second bars are supported, if any other value is used, an exception will be thrown. Determines the nature of the data extracted. Valid values include: useRTH TRADES BID ASK MIDPOINT 0 = all data available during the time span requested is returned, including time intervals when the market in question was outside of regular trading hours. 1 = only data within the regular trading hours for the product requested is returned, even if the time span falls partially or completely outside.

contract barSize whatToShow

Regular Trading Hours only. Valid values include:

API Reference Guide

147

ActiveX ActiveX Methods

reqRealTimeBars()
Call the reqRealTimeBars() method to start receiving real time bar results through the realtimeBar() event. Note: This method has been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated methods.

Public Overridable Sub reqRealTimeBars(ByVal tickerId As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal multiplier As String, ByVal exchange As String, ByVal primaryExchange As String, ByVal currency As String, ByVal isExpired As Integer, ByVal barSize As Integer, ByVal whatToShow As String, ByVal useRTH As Integer) Parameter tickerId Description The Id for the request. Must be a unique value. When the data is received, it will be identified by this Id. This is also used when canceling the historical data request. This is the symbol of the underlying asset. This is the security type. Valid values are: expiry strike right multiplier exchange primaryExchange currency STK OPT FUT IND FOP CASH BAG

symbol secType

The expiration date. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. Allows you to specify a future or option contract multiplier. This is only necessary when multiple possibilities exist. The order destination, such as Smart. Identifies the listing exchange for the contract (do not list SMART). Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. Specifies that the contract has expired. Currently only 5 second bars are supported, if any other value is used, an exception will be thrown.

isExpired barSize

API Reference Guide

148

ActiveX ActiveX Methods

Parameter whatToShow

Description Determines the nature of the data extracted. Valid values include: TRADES BID ASK MIDPOINT 0 = all data available during the time span requested is returned, including time intervals when the market in question was outside of regular trading hours. 1 = only data within the regular trading hours for the product requested is returned, even if the time span falls partially or completely outside.

useRTH

Regular Trading Hours only. Valid values include:

cancelRealTimeBars()
Used if an internet disconnect has occurred or the results of a query are otherwise delayed and the application is no longer interested in receiving the data. Public Overridable Sub cancelRealTimeBars(ByVal tickerId As Integer) Parameter tickerId Description The ticker ID. Must be a unique value.

reqCurrentTime()
Returns the current system time on the server side. Public Overridable Sub reqCurrentTime()

createComboLegList()
This factory method is used to create an IComboLegList COM object. Public Overridable Sub createComboLegList() As TWSLib.IComboLegList You must use the factory create methods to create the COM objects in this section. For example, the createComboLegList() method creates an IComboLeg object. The IComboLeg object contains the definition of the leg list.

API Reference Guide

149

ActiveX ActiveX Methods

createContract()
This factory method is used to create an IContract COM object. Public Overridable Sub createContract() As TWSLib.IContract You must use the factory create methods to create the COM objects described in this chapter. The createContract() method creates an IContract object, which contains a description of the contract for which market data is being requested.

createExecutionFilter()
This factory method is used to create an IExecutionFilter COM object. Public Overridable Sub createExecutionFilter() As TWSLib.IExecutionFilter You must use the factory create methods to create the COM objects described in this chapter. The createExecutionFilter() method creates an IExecutionFilter object, which contains the filter criteria used to determine which execution reports are returned.

createOrder()
This factory method is used to create an IOrder COM object. Public Overridable Sub createOrder() As TWSLib.IOrder You must use the factory create methods to create the COM objects described in this chapter. The createOrder() method creates an IOrder object, which contains the details of an order.

createScannerSubscription()
This factory method is used to create an IScannerSubscription COM object. Public Overridable Sub createScannerSubscription() As TWSLib.IScannerSubscription You must use the factory create methods to create the COM objects described in this chapter. The createScannerSubscripion() method creates an IScannerSubscription object, which contains a summary of the scanner subscription parameters.

createTagValueList
This factory method is used to create ITagValueList and ITagValue objects. Public Overridable Function createTagValueList() As TWSLib.ITagValueList You must use the factory create methods to create the COM objects described in this chapter.

API Reference Guide

150

ActiveX ActiveX Methods

createUnderComp()
This factory method is used to create an IUnderComp COM object. Public Overridable Sub createUnderComp() As TWSLib.IScannerSubscription You must use the factory create methods to create the COM objects described in this chapter. The createUnderComp() method creates an IUnderComp object, which is used to define a Delta-Neutral Combo contract.

reqFundamentalData()
Call this method to receive Reuters global fundamental data. There must be a subscription to Reuters Fundamental set up in Account Management before you can receive this data. Public Overridable Sub reqFundamentalData(ByVal reqId As Integer, ByVal contract As TWSLib.IContract, ByVal reportType As String) Parameter reqId contract reportType Description The ID of the data request. This structure contains a description of the contract for which Reuters Fundamental data is being requested. Identifies the report type, which is one of the following: Estimates Financial Statements Summary

cancelFundamentalData()
Call this method to stop receiving Reuters global fundamental data. Public Overridable Sub cancelFundamentalData(ByVal reqId As Integer) Parameter reqId Description The ID of the data request.

API Reference Guide

151

ActiveX ActiveX Events

ActiveX Events
ActiveX events receive information from the system and make it available to an application. This section defines the ActiveX events you can receive via the DTwsEvents interface. Note: Please note that events in red have been deprecated as of API release 9.4 (December 2007) and will soon be removed. Please update your software to use the "Ex" counterparts to these deprecated events. The new "Ex" events have been grouped with their deprecated counterparts for easy identification. Contract Details contractDetailsEx() contractDetails() contractDetailsEnd() bondContractDetails() Executions execDetailsEx() execDetails() execDetailsEnd() Market Depth updateMktDepth() updateMktDepthL2() Financial Advisors managedAccounts() receiveFA() Historical Data historicalData() Market Scanners scannerParameters() scannerDataEx() scannerData() scannerDataEnd() Real Time Bars realtimebar() Fundamental Data fundamentalData()

Connection and Server connectionClosed() currentTime() errMsg() Market Data tickPrice() tickSize() tickOptionComputation() tickGeneric() tickString() tickEFP() tickSnapshotEnd() Orders orderStatus() openOrderEx() openOrder1() openOrder2() openOrder3() openOrder4() nextValidId() permId() Account and Portfolio updateAccountValue() updatePortfolioEx() updatePortfolio() updateAccountTime() News Bulletins updateNewsBulletin()

API Reference Guide

152

ActiveX ActiveX Events

tickPrice()
This function is called when the market data changes. Prices are updated immediately with no delay. Sub tickPrice(ByVal id As Integer, ByVal tickType As Integer, ByVal price As Double, ByVal canAutoExecute As Integer) Parameter id tickType Description The ticker ID that was specified previously in the call to reqMktData() Specifies the type of price. Possible values are: price canAutoExecute 1 = bid 2 = ask 4 = last 6 = high 7 = low 9 = close

The bid, ask or last price, the daily high, daily low or last day close, depending on tickType value. Specifies whether the price tick is available for automatic execution. Possible values are: 0 = not eligible for automatic execution 1 = eligible for automatic execution

tickSize()
This function is called when the market data changes. Sizes are updated immediately with no delay. Sub tickSize(ByVal id As Integer, ByVal tickType As Integer, ByVal size As Integer) Parameter id tickType Description The ticker ID that was specified previously in the call to reqMktData() Specifies the type of price. Possible values are: size 0 = bid size 3 = ask size 5 = last size 8 = volume

The bid size, ask size, last size or trading volume, depending on the tickType value.

API Reference Guide

153

ActiveX ActiveX Events

tickOptionComputation()
Sub tickOptionComputation(ByVal id As Integer, ByVal tickType As Integer, ByVal impliedVol As Double, ByVal delta As Double, ByVal optPrice As Double, ByVal pvDividend As Double, ByVal gamma As Double, ByVal vega As Double, ByVal theta As Double, ByVal undPrice As Double) Parameter id tickType Description The ticker ID that was specified previously in the call to reqMktData() Specifies the type of tick. Possible values are: ImpliedVol delta optPrice pvDivdend gamma vega theta undPrice 10 = Bid 11 = Ask 12 = Last

The implied volatility calculated by the TWS option modeler, using the specified ticktype value. The option delta calculated by the TWS option modeler. The option price. The present value of dividends expected on the options underlier. The option gamma value. The option vega value. The option theta value. The price of the underlying.

tickGeneric()
This method is called when the market data changes. Values are updated immediately with no delay. Sub tickGeneric(ByVal id As Integer, ByVal tickType As Integer, ByVal value As Double) Parameter tickerId tickType Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of tick. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 46 will map to shortable, etc. The value of the specified field.

value

tickString()
This method is called when the market data changes. Values are updated immediately with no delay.

API Reference Guide

154

ActiveX ActiveX Events

Sub tickString(ByVal id As Integer, ByVal tickType As Integer, ByVal value As String) Parameter tickerId tickType Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of tick. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 45 will map to lastTimestamp, etc. The value of the specified field.

value

tickEFP()
This method is called when the market data changes. Values are updated immediately with no delay. Sub tickEFP(ByVal tickerId As Integer, ByVal field As Integer, ByVal basisPoints As Double, ByVal formattedBasisPoints As String, ByVal totalDividends As Double, ByVal holdDays As Integer, ByVal futureExpiry As String, ByVal dividendImpact As Double, ByVal dividendsToExpiry As Double)) Parameter tickerId field Description The ticker Id that was specified previously in the call to reqMktData(). Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 38 will map to bidEFP, etc. Annualized basis points, which is representative of the financing rate that can be directly compared to broker rates. Annualized basis points as a formatted string that depicts them in percentage form. The total expected dividends. The number of hold days until the expiry of the EFP. The expiration date of the single stock future. The dividend impact upon the annualized basis points interest rate. The dividends expected until the expiration of the single stock future.

basisPoints formattedBasis Points totalDividends holdDays futureExpiry dividendImpact dividendsToExpiry

tickSnapshotEnd()
This is called when a snapshot market data subscription has been fully handled and there is nothing more to wait for. This also covers the timeout case.

API Reference Guide

155

ActiveX ActiveX Events

Sub tickSnapshotEnd(ByVal reqId As Integer) Parameter reqID Description Id of the data request.

API Reference Guide

156

ActiveX ActiveX Events

orderStatus()
This event is called whenever the status of an order changes. It is also fired after reconnecting if the client has any open orders. Sub orderStatus(ByVal id As Integer, ByVal status As String, ByVal filled As Integer, ByVal remaining As Integer, ByVal avgFillPrice As Double, ByVal permId As Integer, ByVal parentId As Integer, ByVal lastFillPrice As Double, ByVal clientId As Integer, ByVal whyHeld As String) Parameter id status Description The order ID that was specified previously in the call to placeOrder() The order status. Possible values include: PendingSubmit - indicates that you have transmitted the order, but have not yet received confirmation that it has been accepted by the order destination. PendingCancel - indicates that you have sent a request to cancel the order but have not yet received cancel confirmation from the order destination. At this point, your order is not confirmed canceled. You may still receive an execution while your cancellation request is pending. Note: PendingSubmit and PendingCancel order statuses are not sent by the system and should be explicitly set by the API developer when an order is canceled. PreSubmitted - indicates that a simulated order type has been accepted by the system and that this order has yet to be elected. The order is held in the system until the election criteria are met. At that time the order is transmitted to the order destination as specified. Submitted - indicates that your order has been accepted at the order destination and is working. Cancelled - indicates that the balance of your order has been confirmed canceled by the system. This could occur unexpectedly when the destination has rejected your order. Filled - indicates that he order has been completely filled. Inactive - indicates that the order has been accepted by the system (simulated orders) or an exchange (native orders) but that currently the order is inactive due to system, exchange or other issues.

API Reference Guide

157

ActiveX ActiveX Events

Parameter filled remaining avgFillPrice

Description Specifies the number of shares that have been executed. Specifies the number of shares still outstanding. The average price of the shares that have been executed. This parameter is valid only if the filled parameter value is greater than zero. Otherwise, the price parameter will be zero. The id used to identify orders. Remains the same over sessions. The order ID of the parent order, used for bracket and auto trailing stop orders. The last price of the shares that have been executed. Valid only if the filled parameter value is greater than zero. Otherwise, the price parameter will be zero. - The ID of the client who placed the order. Note that application orders have a fixed clientId and orderId of 0 that distinguishes them from API orders.

permId parentId lastFilledPrice

clientId

errMsg()
This event is called when there is an error with the communication or when TWS wants to send a message to the client. Sub errMsg(ByVal id As Integer, ByVal errorCode As Integer, ByVal errorMsg As String) Parameter id errorCode errorString Description This is the orderId or tickerId of the request that generated the error Error codes are documented in the Error Codes topic. This is the textual description of the error, also documented in the Error Codes topic.

connectionClosed()
This event is triggered when TWS closes the sockets connection with the ActiveX control, or when TWS is shut down. Sub connectionClosed()

API Reference Guide

158

ActiveX ActiveX Events

openOrderEx()
This method is called to feed in open orders. Sub openOrderEx(ByVal orderId As Integer, ByVal contract As TWSLib.IContract, ByVal order As TWSLib.IOrder, ByVal orderState As TWSLib.IOrderState) Parameter orderId contract order orderState Description The order Id assigned by TWS. Used to cancel or update the order. The Contract class attributes describe the contract. The Order class attributes define the details of the order. The orderState attributes include margin and commissions fields for both pre and post trade data.

openOrder1()
This event sends the contract description of the open order. Note: This event has been deprecated as of API release 9,4 (December 2007) and will soon be removed. Please update your software to use the Ex counterparts to these deprecated events.

Sub openOrder1(ByVal id As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal exchange As String, ByVal curency As String, ByVal localSymbol As String) Parameter id symbol secType Description The assigned order id. Use this id to cancel or modify the order. The underlying symbol. The security type. Valid values are: expiry strike right exchange currency STK OPT FUT IND FOP CASH

The expiration date. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. The order destination, such as Smart. Specifies the currency. This field is only required when the secType = CASH. Otherwise it is ignored.

API Reference Guide

159

ActiveX ActiveX Events

Parameter local symbol

Description The local exchange symbol for the underlying asset.

openOrder2()
This event sends the order description of the open order. Note: This event has been deprecated as of API release 9,4 (December 2007) and will soon be removed. Please update your software to use the Ex counterparts to these deprecated events.

Sub openOrder2(ByVal id As Integer, ByVal action As String, ByVal quantity As Integer, ByVal orderType As String, ByVal lmtPrice As Double, ByVal auxPrice As Double, ByVal tif As String, ByVal ocaGroup As String, ByVal account As String, ByVal openClose As String, ByVal origin As Integer, ByVal orderRef As String, ByVal clientId As Integer) Parameter id action quantity orderType Description The order id. This is the same value that was passed in openOrder1. Identifies the side. Valid values are: BUY, SELL, SSHORT The order quantity. Identifies the order type. Valid values are: lmtPrice MKT MKTCLS LMT LMTCLS PEGMKT STP STPLMT TRAIL REL VWAP

This is the limit price, used for Limit, Stop Limit and Relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero. This is the STOP price for stop limit orders and the offset amount for relative orders. In all other cases, specify 0. The time in force. Valid values are DAY, GTC, IOC Identifies a one-cancels-all group. The account. For institutional customers only. Specifies whether the order is an open or close order. For institutional customers only.

auxPrice tif ocaGroup account openClose

API Reference Guide

160

ActiveX ActiveX Events

Parameter origin orderRef clientId

Description The order origin. For institutional customers only. Valid values are: 0 = Customer, 1 = Firm. The order reference. For institutional customers only. The ID of the requesting client (or TWS) that placed the order. Note that TWS orders have a fixed clientId and orderId of 0 that distinguishes them from API orders.

openOrder3()
This event sends the contract description of the open order. Note: This event has been deprecated as of API release 9,4 (December 2007) and will soon be removed. Please update your software to use the Ex counterparts to these deprecated events.

Sub openOrder3(ByVal id As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal exchange As String, ByVal curency As String, ByVal localSymbol As String, ByVal action As String, ByVal quantity As Integer, ByVal orderType As String, ByVal lmtPrice As Double, ByVal auxPrice As Double, ByVal tif As String, ByVal ocaGroup As String, ByVal account As String, ByVal openClose As String, ByVal origin As Integer, ByVal orderRef As String, ByVal clientId As Integer, ByVal permId As Integer, ByVal sharesAllocation As String, ByVal faGroup As String, ByVal faMethod As String, ByVal faPercentage As String, ByVal faProfile As String, ByVal goodAfterTime As String, ByVal goodTillDate As String) Parameter id symbol secType Description The assigned order id. Use this id to cancel or modify the order. The underlying symbol. The security type. Valid values are: expiry strike right exchange currency local symbol STK OPT FUT IND FOP CASH

The expiration date. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. The order destination, such as Smart. Specifies the currency. This field is only required when the secType = CASH. Otherwise it is ignored. The local exchange symbol for the underlying asset.

API Reference Guide

161

ActiveX ActiveX Events

Parameter action quantity orderType

Description Identifies the side. Valid values are: BUY, SELL, SSHORT The size of the order. Identifies the order type. Valid values are: MKT MKTCLS LMT LMTCLS PEGMKT STP STPLMT TRAIL REL VWAP

lmtPrice

This is the limit price, used for Limit, Stop Limit and Relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero. This is the STOP price for stop limit orders, and the offset amount for relative orders. In all other cases, specify zero.

AuxPrice

API Reference Guide

162

ActiveX ActiveX Events

openOrder4()
This event sends the contract description of the open order. Note: This event has been deprecated as of API release 9,4 (December 2007) and will soon be removed. Please update your software to use the Ex counterparts to these deprecated events.

Sub openOrder4(ByVal id As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal exchange As String, ByVal curency As String, ByVal localSymbol As String, ByVal action As String, ByVal quantity As Integer, ByVal orderType As String, ByVal lmtPrice As Double, ByVal auxPrice As Double, ByVal tif As String, ByVal ocaGroup As String, ByVal account As String, ByVal openClose As String, ByVal origin As Integer, ByVal orderRef As String, ByVal clientId As Integer, ByVal permId As Integer, ByVal sharesAllocation As String, ByVal faGroup As String, ByVal faMethod As String, ByVal faPercentage As String, ByVal faProfile As String, ByVal goodAfterTime As String, ByVal goodTillDate As String, ByVal ocaType As Integer, ByVal rule80A As String, ByVal settlingFirm As String, ByVal allOrNone As Integer, ByVal minQty As Integer, ByVal percentOffset As Double, ByVal eTradeOnly As Integer, ByVal firmQuoteOnly As Integer, ByVal nbboPriceCap As Double, ByVal auctionStrategy As Integer, ByVal startingPrice As Double, ByVal stockRefPrice As Double, ByVal delta As Double, ByVal stockRangeLower As Double, ByVal stockRangeUpper As Double, ByVal blockOrder As Integer, ByVal sweepToFill As Integer, ByVal ignoreRth As Integer, ByVal hidden As Integer, ByVal discretionaryAmt As Double, ByVal displaySize As Integer, ByVal parentId As Integer, ByVal triggerMethod As Integer, ByVal shortSaleSlot As Integer, ByVal designatedLocation As String, ByVal volatility As Double, ByVal volatilityType As Integer, ByVal deltaNeutralOrderType As String, ByVal deltaNeutralAuxPrice As Double, ByVal continuousUpdate As Integer, ByVal referencePriceType As Integer, ByVal trailStopPrice As Double, ByVal basisPoints As Double, ByVal basisPointsType As Integer, ByVal legsStr As String, ByVal scaleInitLevelSize As Integer, ByVal scaleSubsLevelSize As Integer, ByVal scalePriceIncrement As Double) Parameter id symbol secType Description The assigned order id. Use this id to cancel or modify the order. The underlying symbol. The security type. Valid values are: STK OPT FUT IND FOP CASH

API Reference Guide

163

ActiveX ActiveX Events

Parameter expiry strike right exchange curency local symbol action quantity orderType

Description The expiration date. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. The order destination, such as Smart. Specifies the currency. This field is only required when the secType = CASH. Otherwise it is ignored. The local exchange symbol for the underlying asset. Identifies the side. Valid values are: BUY, SELL, SSHORT The size of the order. Identifies the order type. Valid values are: MKT MKTCLS LMT LMTCLS PEGMKT STP STPLMT TRAIL REL VWAP

lmtPrice

This is the limit price, used for Limit, Stop Limit and Relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero. This is the STOP price for stop limit orders, and the offset amount for relative orders. In all other cases, specify zero. The time in force. Identifies the order as part of a one-cancels-all group. Cancel on Fill with Block = 1 Reduce on Fill with Block = 2 Reduce on Fill without Block = 3 The account to which the order is allocated. For institutional customers only. Specifies whether the order is to open or close a position. For institutional customers only. The order origin. Valid values are: 0 = customer; 1 = firm. For institutional customers only. The order reference. For institutional customers only. The ID of the client who placed the order. NOTE: TWS orders have a fixed client ID of "0."

AuxPrice tif ocaGroup ocaType

account openClose origin orderRef clientId

API Reference Guide

164

ActiveX ActiveX Events

Parameter permId sharesAllocation faGroup faMethod faPercentage faProfile goodAfterTime

Description The TWS ID used to identify orders. This value remains the same over TWS sessions. Deprecated. Upgrade to new FA functionality must be done. The advisor group to which the trade will be allocated. Use an empty string if not applicable. Valid values include: The advisor method which will be used to allocate the trade. Use an empty string if not applicable. The percentage of the order for trade allocation. The advisor profile which will be used to allocate the trade. Use an empty string if not applicable. Valid values include: The trade's "Good After Time," format "YYYYMMDD hh:mm:ss (optional time zone)" Use an empty String if not applicable. You must enter GTD as the time in force to use this string. The trade's "Good Till Date," format "YYYYMMDD hh:mm:ss (optional time zone)" Use an empty String if not applicable. 1 = yes, 2 = no Values are: Individual = 'I' Agency = 'A', AgentOtherMember = 'W' IndividualPTIA = 'J' AgencyPTIA = 'U' AgentOtherMemberPTIA = 'M' IndividualPT = 'K' AgencyPT = 'Y' AgentOtherMemberPT = 'N'

goodTillDate

rthOnly rule80A

settlingFirm allOrNone

Institution only. Identifies the order as having the all or none attribute, which means the entire quantity must execute or the order will be cancelled. Values are: 0 = no, 1 = yes Identifies a minimum quantity order type. The percent offset amount for relative orders. Trade with electronic quotes. Values are: 0 = no, 1 = yes Trade with firm quotes. Values are: 0 = no, 1 = yes Maximum smart order distance from the NBBO.

minQty percentOffset eTradeOnly firmQuoteOnly nbboPriceCap

API Reference Guide

165

ActiveX ActiveX Events

Parameter auctionStrategy

Description Values are: match = 1 improvement = 2

transparent = 3 For orders on BOX only. startingPrice stockRefPrice The auction starting price. For orders on BOX only. The stock reference price. The reference price is used for VOL orders to compute the limit price sent to an exchange (whether or not Continuous Update is selected), and for price range monitoring. The stock delta. For orders on BOX only. The lower value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. The upper value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. If set to true, specifies that the order is an ISE Block order. If set to true, specifies that the order is a Sweep-to-Fill order. If set to true, allows triggering of orders outside of regular trading hours. If set to true, the order will not be visible when viewing the market depth. This option only applies to orders routed to the ISLAND exchange. The amount off the limit price allowed for discretionary orders. The publicly disclosed order size, used when placing Iceberg orders. The order ID of the parent order, used for bracket and auto trailing stop orders. Specifies how Simulated Stop, Stop-Limit and Trailing Stop orders are triggered. Valid values are: O - The default value. The "double bid/ask" method will be used for orders for OTC stocks and US options. All other orders will used the "last" method. 1 - use "double bid/ask" method, where stop orders are triggered based on two consecutive bid or ask prices. 2 - "last" method, where stop orders are triggered based on the last price.

delta stockRangeLower

stockRangeUpper

blockOrder sweepToFill ignoreRth hidden

discretionaryAmt displaySize parentId triggerMethod

shortSaleSlot designatedLocation

Valid values are 1 or 2. Use only when shortSaleSlot value = 2.

API Reference Guide

166

ActiveX ActiveX Events

Parameter volatility

Description The option price in volatility, as calculated by TWS' Option Analytics. This value is expressed as a percent and is used to calculate the limit price sent to the exchange. Values are: 1 = Daily volatility 2 = Annual volatility

volatilityType

deltaNeutralOrder Type deltaNeutralAux Price continuousUpdate

VOL orders only. Enter an order type to instruct TWS to submit a delta neutral trade on full or partial execution of the VOL order. For no hedge delta order to be sent, specify NONE. VOL orders only. Use this field to enter a value if the value in the deltaNeutralOrderType field is an order type that requires an Aux price, such as a REL order. VOL orders only. Specifies whether TWS will automatically update the limit price of the order as the underlying price moves. VOL orders only. Specifies how you want TWS to calculate the limit price for options, and for stock range price monitoring. Valid values include: 1 = Average of NBBO 2 = NBB or the NBO depending on the action and right.

referencePriceType

API Reference Guide

167

ActiveX ActiveX Events

updateAccountValue()
This event updates a single account value. Sub updateAccountValue(ByVal key As String, ByVal value As String, ByVal curency As String, ByVal accountName As String) Parameter key Description A string that indicates one type of account value. Below are some of the keys sent by TWS. Account Type Account Code Available Funds Buying Power CashBalance - Account cash balance Currency - Currency string DayTradesRemaining - Number of day trades left EquityWithLoanValue - Equity with Loan Value Excess Liquidity Full Available Funds Full Excess Liquidity Full Init Margin Req Full Maint Margin Req Future Option Value Futures PNL Gross Position Value InitMarginReq - Current initial margin requirement Leverage Look Ahead Available Funds Look Ahead Next Change Look Ahead Excess Liquidity Look Ahead Margin Req Look Ahead Maint Margin Req LongOptionValue - Long option value

API Reference Guide

168

ActiveX ActiveX Events

Parameter key

Description Values, continued: MaintMarginReq - Current maintenance margin NetLiquidation - Net liquidation value OptionMarketValue - Option market value Realized PNL Settled Cash ShortOptionValue - Short option value StockMarketValue - Stock market value Total Cash Balance Total Cash Value UnalteredInitMarginReq - Overnight initial margin requirement UnalteredMaintMarginReq - Overnight maintenance margin requirement Unrealized PNL

value curency account

The value associated with the key. Defines the currency of the value, if the value is a monetary amount. states the account the message applies to. Useful for Financial Advisor sub-account messages.

updatePortfolioEx()
This callback is made in response to the reqAccountUpdates() method. Sub updatePortfolioEx(ByVal contract As TWSLib.IContract, ByVal position As Integer, ByVal marketPrice As Double, ByVal marketValue As Double, ByVal averageCost As Double, ByVal unrealizedPNL As Double, ByVal realizedPNL As Double, ByVal accountName As String) Parameter contract Description This object contains a description of the contract which is being traded. The exchange field in a contract is not set for portfolio update. This integer indicates the position on the contract. If the position is 0, it means the position has just cleared. The unit price of the instrument. The total market value of the instrument. The average cost per share is calculated by dividing your cost (execution price + commission) by the quantity of your position.

position marketPrice marketValue averageCost

API Reference Guide

169

ActiveX ActiveX Events

Parameter unrealizedPNL realizedPNL

Description The difference between the current market value of your open positions and the average cost, or Value - Average Cost. Shows your profit on closed positions, which is the difference between your entry execution cost (execution price + commissions to open the position) and exit execution cost ((execution price + commissions to close the position) The name of the account the message applies to. Useful for Financial Advisor sub-account messages.

accountName

updatePortfolio()
This event updates a single holding in your portfolio. Note: This event has been deprecated as of API release 9,4 (December 2007) and will soon be removed. Please update your software to use the Ex counterparts to these deprecated events.

Sub updatePortfolio(ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal curency As String, ByVal localSymbol As String, ByVal position As Integer, ByVal marketPrice As Double, ByVal marketValue As Double, ByVal averageCost As Double, ByVal unrealizedPNL As Double, ByVal realizedPNL As Double, ByVal accountName As String) Parameter symbol secType Description The symbol of the underlying asset. The security type. Valid values are: expiry strike right curency localSymbol position marketPrice marketValue
API Reference Guide

STK OPT FUT IND FOP CASH BAG

The expiration date. Use the format YYYYMM. The strike price. Specifies a put or call. Valid values are: P, PUT, C, CALL Specifies the currency. This field is only required when the secType = CASH. Otherwise it is ignored. The local exchange symbol of the asset. Indicates the position on the contract. If the value is 0, it means the position has just cleared. The unit price of the instrument. The total market value of the instrument.
170

ActiveX ActiveX Events

Parameter averageCost

Description The average cost per share is calculated by dividing your cost (execution price + commission) by the quantity of your position. The difference between the current market value of your open positions and the average cost, or (Value - Average Cost). Shows your profit on closed positions, which is the difference between your entry execution cost (execution price + commissions to open the position) and exit execution costs (execution price + commissions to close the position). States the account the message applies to. Useful for Financial Advisor sub-account messages.

unrealizedPNL realizedPNL

account

updateAccountTime()
This event sends the time at which the account values and portfolio market prices were calculated. Sub updateAccountTime(ByVal timeStamp As String) Parameter timeStamp Description This indicates the last update time of the account information.

nextValidId()
This event is called after a successful connection to TWS. Sub nextValidId(ByVal id As Integer) Parameter id Description The next available order ID received from TWS upon connection. Increment all successive orders by one based on this ID.

permId()
This event is always received after an order Status event. It gives the permId for the specified order id. The permId will remain the same from session to session. Sub permId(ByVal id As Integer, ByVal permId As Integer) Parameter id Description The next available order ID received from TWS upon connection. Increment all successive orders by one based on this ID. This id will remain the same from session to session

permId

API Reference Guide

171

ActiveX ActiveX Events

contractDetailsEx()
This event is called only in response to the reqContractDetailsEx() method having been called. Sub contractDetailsEx(ByVal reqId As Integer, ByVal contractDetails As TWSLib.IContractDetails) Parameter reqId contractDetails Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. This object contains a full description of the contract being looked up.

contractDetails()
This event is fired when the reqContractDetails() or reqContractDetails2() methods are invoked. Note: This event has been deprecated as of API release 9,4 (December 2007) and will soon be removed. Please update your software to use the Ex counterparts to these deprecated events.

Sub contractDetails(ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal exchange As String, ByVal curency As String, ByVal localSymbol As String, ByVal marketName As String, ByVal tradingClass As String, ByVal conId As Integer, ByVal minTick As Double, ByVal priceMagnifier As Integer, ByVal multiplier As String, ByVal orderTypes As String, ByVal validExchanges As String) Parameter symbol secType Description The underlying symbol. The security type. Valid values are: expiry strike right exchange curency localSymbol STK OPT FUT IND FOP CASH

The expiration date. Use the format YYYYMM. The strike price. Specifies a put or call. Valid values are: P, PUT, C, CALL The order destination, such as Smart. Specifies the currency. This field is only required when the secType = CASH. Otherwise it is ignored. The local exchange symbol of the asset.

API Reference Guide

172

ActiveX ActiveX Events

Parameter marketName tradingClass conId minTick priceMagnifier

Description The market name for this contract. The trading class name for this contract. The unique contract identifier. The minimum price tick. Allows execution and strike prices to be reported consistently with market data, historical data and the order price, i.e. Z on LIFFE is reported in index points and not GBP. The order size multiplier. The list of valid order types for this contract. The list of exchanges on which this contract is traded.

multiplier orderTypes validExchanges

contractDetailsEnd()
This method is called once all contract details for a given request are received. This helps to define the end of an option chain.

Sub contractDetailsEnd(ByVal reqId As Integer) Parameter reqID Description Id of the data request.

execDetailsEx()
This method is called when the reqExecutionsEx() method is invoked, or when an order is filled. Sub execDetailsEx(ByVal reqId As Integer, ByVal contract As TWSLib.IContract, ByVal execution As TWSLib.IExecution) Parameter orderId contract execution Description The order Id that was specified previously in the call to placeOrderEx(). This object contains a full description of the contract that was executed. This structure contains addition order execution details.

API Reference Guide

173

ActiveX ActiveX Events

execDetails()
This event is fired when the reqExecutions() methods is invoked, or when an API order is filled or partially filled. Note: This event has been deprecated as of API release 9,4 (December 2007) and will soon be removed. Please update your software to use the Ex counterparts to these deprecated events.

Sub execDetails(ByVal id As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal cExchange As String, ByVal curency As String, ByVal localSymbol As String, ByVal execId As String, ByVal time As String, ByVal acctNumber As String, ByVal eExchange As String, ByVal side As String, ByVal shares As Integer, ByVal price As Double, ByVal permId As Integer, ByVal clientId As Integer, ByVal isLiquidation As Integer) Parameter id Description The order id. This is the same value that was passed in openOrder1. Note: TWS orders have a fixed orderId of 0, which distinguishes them from API client orders. The underlying symbol. The security type. Valid values are: expiry strike right cExchange curency localSymbol execId time acctNumber eExchange side STK OPT FUT IND FOP CASH

symbol secType

The expiration date. Use the format YYYYMM. The strike price. Specifies a put or call. Valid values are: P, PUT, C, CALL The order destination, such as Smart. Specifies the currency. This field is only required when the secType = CASH. Otherwise it is ignored. The local exchange symbol for the underlying asset. The order execution id. The time of order execution. The customer account number. -Specifies if the transaction was a purchase or a sale. Valid values are: BOT SLD

API Reference Guide

174

ActiveX ActiveX Events

Parameter shares price permId permId isliquidation

Description The number of shares filled. The order execution price. The TWS id used to identify orders, remains the same over TWS sessions. The ID of the client that placed the order. Note that TWS orders have a fixed ID of 0. Specifies whether an execution is the result of a liquidation. Possible values are: 0 = execution is not the result of liquidation 1 = execution is the result of a liquidation

execDetailsEnd()
This method is called once all executions have been sent to a client in response to reqExecutionsEx()

Sub execDetailsEnd(ByVal reqId As Integer) Parameter reqID Description Id of the data request.

updateMktDepth()
This function is called when the market depth changes. Sub updateMktDepth(ByVal id As Integer, ByVal position As Integer, ByVal operation As Integer, ByVal side As Integer, ByVal price As Double, ByVal size As Integer) Parameter id position operation Description The ticker ID that was specified previously in the call to reqMktDepth() Specifies the row ID of this market depth entry. Identifies how this order should be applied to the market depth. Valid values are: side 0 = insert (insert this new order into the row identified by 'position') 1 = update (update the existing order in the row identified by 'position') 2 = delete (delete the existing order at the row identified by 'position')

The side of the book to which this order belongs. Valid values are: 0 = ask 1 = bid

API Reference Guide

175

ActiveX ActiveX Events

Parameter price size

Description The order price. The order size.

updateMktDepthL2()
This function is called when the Level II market depth changes. Sub updateMktDepthL2(ByVal id As Integer, ByVal position As Integer, ByVal marketMaker As String, ByVal operation As Integer, ByVal side As Integer, ByVal price As Double, ByVal size As Integer) Parameter id position marketMaker operation Description The ticker ID that was specified previously in the call to reqMktDepth() Specifies the row id of this market depth entry. Specifies the exchange hosting this order. Identifies the how this order should be applied to the market depth. Valid values are: side 0 = insert (insert this new order into the row identified by 'position') 1 = update (update the existing order in the row identified by 'position') 2 = delete (delete the existing order at the row identified by 'position')

Identifies the side of the book that this order belongs to. Valid values are: 0 = ask 1 = bid

price size

The order price. The order size.

updateNewsBulletin()
This event is triggered for each new bulletin if the client has subscribed (i.e. by calling the reqNewsBulletins() method). Sub updateNewsBulletin(ByVal msgId As Short, ByVal msgType As Short, ByVal message As String, ByVal origExchange As String) Parameter msgId Description The bulletin ID, increments for each new bulletin.

API Reference Guide

176

ActiveX ActiveX Events

Parameter msgType

Description Specifies the type of bulletin. Valid values include: 1 = Regular IB news bulletin 2 = Exchange no longer available for trading. 3 = Exchange is available for trading.

message origExchange

The bulletins message text. The exchange from which this message originated.

managedAccounts()
This event id is fired when a successful connection is made to a Financial Advisor account. It is also fired when the reqManagedAccts() method is invoked. Sub managedAccounts(ByVal accountsList As String) Parameter accountsList Description The comma delimited list of FA-managed accounts.

receiveFA()
This event receives previously requested FA configuration information from TWS. Sub receiveFA(ByVal faDataType As Integer, ByVal cxml As String) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being received from TWS. Valid values include: cxml 1 = GROUPS 2 = PROFILE 3 =ACCOUNT ALIASES

The XML string containing the previously requested FA configuration information.

historicalData()
This event receives requested historical data from TWS. Sub historicalData(ByVal reqId As Integer, ByVal date As String, ByVal open As Double, ByVal high As Double, ByVal low As Double, ByVal close As Double, ByVal volume As Integer, ByVal barCount As Integer, ByVal WAP As Double, ByVal hasGaps As Integer) Parameter reqId date Description The ticker ID of the request to which this bar is responding. The date-time stamp of the start of the bar. The format is determined by the reqHistoricalData() formatDate parameter.

API Reference Guide

177

ActiveX ActiveX Events

Parameter open high low close volume WAP hasGaps

Description The bar opening price. The high price during the time covered by the bar. The low price during the time covered by the bar. The bar closing price. The volume during the time covered by the bar. The weighted average price during the time covered by the bar. Identifies whether or not there are gaps in the data.

API Reference Guide

178

ActiveX ActiveX Events

bondContractDetails()
Sub bondContractDetails(ByVal symbol As String, ByVal secType As String, ByVal cusip As String, ByVal coupon As Double, ByVal maturity As String, ByVal issueDate As String, ByVal ratings As String, ByVal bondType As String, ByVal couponType As String, ByVal convertible As Integer, ByVal callable As Integer, ByVal putable As Integer, ByVal descAppend As String, ByVal exchange As String, ByVal curency As String, ByVal marketName As String, ByVal tradingClass As String, ByVal conId As Integer, ByVal minTick As Double, ByVal orderTypes As String, ByVal validExchanges As String, ByVal nextOptionDate As String, ByVal nextOptionType As String, ByVal nextOptionPartial As Integer, ByVal notes As String) Parameter symbol secType cusip coupon maturity issueDate ratings Description The bond symbol. BOND The nine-character bond CUSIP, or 12 character SEDOL. The interest rate used to calculate the amount you will receive in interest payments over the course of the year. The date on which the issuer must repay the face value of the bond. he date on which the bond was issued. Identifies the credit rating of the issuer. A higher credit rating generally indicates a less risky investment. Bond ratings are from Moody's and S&P respectively. The type of the bond, such as "Corp" for corporate. The type of the coupon, such as "FIXED." Values are: True or False. If true, the bond can be converted to stock under certain conditions. Values are: True or False. If true, the bond can be called by the issuer under certain conditions. Values are: True or False. If true, the bond can be sold back to the issuer under certain conditions. Description string containing further descriptive information about the bond. The exchange on which the BOND trades. The currency in which the bond trades. The market name for this contract. The trading class name for this contract. The IB contract ID of the bond. The minimum price increment of the bond. The order types that apply to this bond. A comma-delimited string of exchanges on which this bond trades.

bondType couponType convertible callable putable descAppend exchange curency marketName tradingClass conId minTick orderTypes validExchanges

API Reference Guide

179

ActiveX ActiveX Events

Parameter nextOptionDate nextOptionType nextOptionPartial notes

Description Next option date. Applies only to bonds with embedded options. Next option type. Applies only to bonds with embedded options. Next option partial. Applies only to bonds with embedded options (is the next option full or partial?). Bond notes, if populated for the bond in IBs database.

scannerParameters()
Sub scannerParameters(ByVal xml As String) Parameter xml Description An XML document that describes the valid parameters that a scanner parameter can have.

scannerDataEx()
This event receives the requested market scanner data results. Sub scannerDataEx(ByVal reqId As Integer, ByVal rank As Integer, ByVal contractDetails As TWSLib.IContractDetails, ByVal distance As String, ByVal benchmark As String, ByVal projection As String, ByVal legsStr As String) Parameter reqId rank contractDetails distance benchmark projection legsStr Description The ID of the request to which this row is responding. The ranking within the response of this bar. This object contains a full description of the contract. Varies based on query. Varies based on query. Varies based on query. Describes combo legs when scan is returning EFP.

scannerData()
Note: This event has been deprecated as of API release 9,4 (December 2007) and will soon be removed. Please update your software to use the Ex counterparts to these deprecated events.

Sub scannerData(ByVal reqId As Integer, ByVal rank As Integer, ByVal symbol As String, ByVal secType As String, ByVal expiry As String, ByVal strike As Double, ByVal right As String, ByVal exchange As String, ByVal curency As String, ByVal localSymbol As String, ByVal marketName As

API Reference Guide

180

ActiveX ActiveX Events

String, ByVal tradingClass As String, ByVal distance As String, ByVal benchmark As String, ByVal projection As String, ByVal legsStr As String) Parameter reqId rank symbol secType expiry strike right exchange currency localSymbol marketName tradingClass distance benchmark projection Description The ticker ID of the request to which this row is responding. The ranking within the response of this particular bar. The symbol to which this bar pertains. The security type of that symbol. If a derivative, the expiration date. If an option, it's strike price. If an option, call or put. The exchange on which the symbol trades. The currency the symbol trades in on the exchange. Identifier assigned to derivatives that uniquely identifies them on an exchange. The market name of the contract. The trading class name of the contract. Varies based on the query. Varies based on the query. Varies based on the query.

scannerDataEnd()
This function is called when the snapshot is received and marks the end of one scan.

Sub scannerDataEnd(ByVal reqId As Integer) Parameter reqId Description The ID of the market data snapshot request being closed by this parameter.

realtimeBar()
This method receives the real-time bars data results. Sub realtimeBar(ByVal tickerId As Integer, ByVal time As Integer, ByVal open As Double, ByVal high As Double, ByVal low As Double, ByVal close As Double, ByVal volume As Integer, ByVal WAP As Double, ByVal Count As Integer) Parameter reqId time open Description The ticker Id of the request to which this bar is responding. The date-time stamp of the start of the bar. The format is determined by the reqHistoricalData() formatDate parameter. The bar opening price.

API Reference Guide

181

ActiveX ActiveX Events

Parameter high low close volume wap count

Description The high price during the time covered by the bar. The low price during the time covered by the bar. The bar closing price. The volume during the time covered by the bar. The weighted average price during the time covered by the bar. When TRADES historical data is returned, represents the number of trades that occurred during the time period the bar covers.

currentTime()
This method receives the current system time on the server side. Sub currentTime(ByVal time As Integer) Parameter time Description The current system time on the server side.,

fundamentalData()
This method is called to receive Reuters global fundamental market data. There must be a subscription to Reuters Fundamental set up in Account Management before you can receive this data. Sub fundamentalData(ByVal reqId As Integer, ByVal data As String) Parameter reqId data Description The ID of the data request. One of three XML reports: Estimates (estimates) Financial statements (finstat) Summary (snapshot)

API Reference Guide

182

ActiveX ActiveX COM Objects

ActiveX COM Objects

The tables below define properties for the following objects:

IExecution IExecutionFilter IContract IContractDetails IComboLeg IComboLegList IOrder IOrderState IScannerSubscription ITagValueList ITagValue IUnderComp

You must use the factory create methods to create the COM objects in this section. Once a COM object has been created by a factory method, the COM object is tied to a corresponding TWS COM object (an instance of the COM object). Do not try to pass a COM object to another instance of a TWS COM object.

API Reference Guide

183

ActiveX ActiveX COM Objects

IExecution

Property orderId() As Integer clientId() As Integer execId() As String time() As String acctNumber() As String exchange() As String side() As String

Description The order id. Note: TWS orders have a fixed order id of "0." The id of the client that placed the order. Note: TWS orders have a fixed client id of "0." Unique order execution id. The order execution time. The customer account number. Exchange that executed the order. Specifies if the transaction was a sale or a purchase. Valid values are: BOT SLD

shares() As Integer price() As Double permId() As Integer liquidation() As Integer cumQty() As Integer avgPrice() As Double

The number of shares filled. The order execution price. The TWS id used to identify orders, remains the same over TWS sessions. Identifies the position as one to be liquidated last should the need arise. Cumulative quantity. Used in regular trades, combo trades and legs of the combo. Average price. Used in regular trades, combo trades and legs of the combo.

IExecutionFilter

Property clientId() As Integer acctCode() As String

Description Filter the results of the reqExecutionsEx() method based on the clientId. Filter the results of the reqExecutionsEx() method based on an account code. Note: this is only relevant for Financial Advisor (FA) accounts. Filter the results of the reqExecutionsEx() method based on execution reports received after the specified time. The format for timeFilter is "yyyymmdd-hh:mm:ss" Filter the results of the reqExecutionsEx() method based on the order symbol.

time() As String

symbol() As String

API Reference Guide

184

ActiveX ActiveX COM Objects

Property secType() String

Description Filter the results of the reqExecutionsEx() method based on the order security type. Note: Refer to the Contract object for the list of valid security types. Filter the results of the reqExecutionsEx() method based on the order exchange. Filter the results of the reqExecutionsEx() method based on the order action. Note: Refer to the Order object for the list of valid order actions.

exchange() As String side() As String

API Reference Guide

185

ActiveX ActiveX COM Objects

IContract

Property symbol() As String secType() As String

Description This is the symbol of the underlying asset. This is the security type. Valid values are: STK OPT FUT IND FOP CASH BAG

expiry() As String strike() As Double right() As String multiplier() As String

The expiration date. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. Allows you to specify a future or option contract multiplier. This is only necessary when multiple possibilities exist. The order destination, such as Smart. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. This is the local exchange symbol of the underlying asset. Identifies the listing exchange for the contract (do not list SMART). If set to true, contract details requests and historical data queries can be performed pertaining to expired contracts. Note: Historical data queries on expired contracts are limited to the last year of the contracts life, and are initially only supported for expired futures contracts, Description for combo legs Dynamic memory structure used to store the leg definitions for this contract. The unique contract identifier.

exchange() As String currency() As String

localSymbol() As String primaryExch() As String includeExpired() As Integer

comboLegsDescrip() As String comboLegs() As Object conId() As Integer

API Reference Guide

186

ActiveX ActiveX COM Objects

Property secIdType As String

Description Security identifier, when querying contract details or when placing orders. Supported identifiers are: ISIN (Example: Apple: US0378331005) CUSIP (Example: Apple: 037833100) SEDOL (Consists of 6-AN + check digit. Example: BAE: 0263494) RIC (Consists of exchange-independent RIC Root and a suffix identifying the exchange. Example: AAPL.O for Apple on NASDAQ.)

secId as String

Unique identifier for the secIdType.

API Reference Guide

187

ActiveX ActiveX COM Objects

IContractDetails

Property summary() As Object marketName() String tradingClass() As String minTick() As Double priceMagnifier() Integer

Description A contract summary. The market name for this contract. The trading class name for this contract. The minimum price tick. Allows execution and strike prices to be reported consistently with market data, historical data and the order price, i.e. Z on LIFFE is reported in index points and not GBP. The list of valid order types for this contract. The list of exchanges this contract is traded on. The underlying contract ID. The descriptive name of the asset. For Bonds. The nine-character bond CUSIP or the 12-character SEDOL. For Bonds. Identifies the credit rating of the issuer. A higher credit rating generally indicates a less risky investment. Bond ratings are from Moody's and S&P respectively. For Bonds. A description string containing further descriptive information about the bond. For Bonds. The type of bond, such as "CORP." For Bonds.The type of bond coupon, such as "FIXED." For Bonds. Values are True or False. If true, the bond can be called by the issuer under certain conditions. For Bonds. Values are True or False. If true, the bond can be sold back to the issuer under certain conditions. For Bonds. The interest rate used to calculate the amount you will receive in interest payments over the course of the year. For Bonds. Values are True or False. If true, the bond can be converted to stock under certain conditions. For Bonds. The date on which the issuer must repay the face value of the bond. For Bonds. The date the bond was issued. For Bonds, applies to bonds with embedded options. For Bonds, applies to bonds with embedded options. For Bonds, applies to bonds with embedded options. For Bonds, if populated for the bond in IB's database

orderTypes() As String validExchanges() As String underConId() As String longName() As String cusip() As String ratings() As String

descAppend() As String bondType() As String couponType() As String callable() As Integer putable() As Integer coupon() As Double

convertible() As Integer maturity() As String issueDate() As String nextOptionDate)_ As String nextOptionType() As String nextOptionPartial() As Integer notes() As String

API Reference Guide

188

ActiveX ActiveX COM Objects

Property contractMonth() As String industry() As String category() As String subcategory() As String timeZoneId() As String tradingHours() As String liquidHours() As String

Description The contract month. Typically the contract month of the underlying for a futures contract. The industry classification of the underlying/product. For example, Financial. The industry category of the underlying. For example, InvestmentSvc. The industry subcategory of the underlying. For example, Brokerage. The ID of the time zone for the trading hours of the product. For example, EST. The trading hours of the product. For example, 20090507:0700-1830,1830-2330;20090508:CLOSED. The liquid trading hours of the product. For example, 20090507:0930-1600;20090508:CLOSED.

IComboLeg

Property conId() As Integer action() As String ratio() As Integer

Description The unique contract identifier specifying the security. The side (buy or sell) for the leg you are constructing. Select the relative number of contracts for the leg you are constructing. To help determine the ratio for a specific combination order, refer to the Interactive Analytics section of the User's Guide. The exchange to which the complete combination order will be routed. Specifies whether the order is an open or close order. Valid values are: 0 - Same as the parent security. This is the only option for retail customers. 1 - Open. This value is only valid for institutional customers. 2 - Close. This value is only valid for institutional customers. Unknown - (3) 0 - inapplicable (i.e. retail customer or not short leg) 1 - clearing broker 2 - third party. If this value is used, you must enter a designated location.

exchange() As String openClose() As Integer

shortSaleSlot() Integer

For institutional customers only.

API Reference Guide

189

ActiveX ActiveX COM Objects

Property designatedLocation() As String

Description If shortSaleSlot == 2, the designatedLocation must be specified. Otherwise leave blank or orders will be rejected.

IComboLegList

Property Add() As Object Count() As Integer Item(Integer) As Object

Description Adds combo legs to a combo leg list. Leg count. Get leg by index.

IOrder

Property orderId() As Integer clientId() As Integer permid() As Integer action() As String totalQuantity() As Integer orderType() As String

Description The id for this order. The id of the client that placed this order. The TWS id used to identify orders, remains the same over TWS sessions. Identifies the side. Valid values are: BUY, SELL, SSHORT The order quantity. Identifies the order type. Valid values are: MKT MKTCLS LMT LMTCLS PEGMKT SCALE STP STPLMT TRAIL REL VWAP TRAILLIMIT

API Reference Guide

190

ActiveX ActiveX COM Objects

Property lmtPrice() As Double

Description This is the LIMIT price, used for limit, stop-limit and relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero. This is the STOP price for stop-limit orders, and the offset amount for relative orders. In all other cases, specify zero. The time in force. Valid values are: DAY, GTC, IOC, GTD. Identifies an OCA (one cancels all) group. Tells how to handle remaining orders in an OCA group when one order or part of an order executes. Valid values include: 1 = Cancel all remaining orders with block 2 = Remaining orders are proportionately reduced in size with block

auxPrice() As Double

timeInForce() As String ocaGroup() As String ocaType() As Integer

3 = Remaining orders are proportionately reduced in size with no block If you use a value "with block" gives your order has overfill protection. This means that only one order in the group will be routed at a time to remove the possibility of an overfill. account() As String openClose() As String The account. For institutional customers only. Specifies whether the order is an open or close order. For institutional customers only. Valid values are O, C. The order origin. For institutional customers only. Valid values are 0 = customer, 1 = firm The order reference. For institutional customers only. Specifies whether the order will be transmitted by TWS. If set to false, the order will be created at TWS but will not be sent. The order ID of the parent order, used for bracket and auto trailing stop orders. If set to true, specifies that the order is an ISE Block order. If set to true, specifies that the order is a Sweep-to-Fill order. The publicly disclosed order size, used when placing Iceberg orders.

origin() As Integer orderRef() String transmit() As Integer

parentId() As Integer blockOrder() As Integer sweepToFill() As Integer displaySize() As Integer

API Reference Guide

191

ActiveX ActiveX COM Objects

Property triggerMethod() As Integer

Description Specifies how Simulated Stop, Stop-Limit and Trailing Stop orders are triggered. Valid values are: 0 - The default value. The "double bid/ask" method will be used for orders for OTC stocks and US options. All other orders will used the "last" method. 1 - use "double bid/ask" method, where stop orders are triggered based on two consecutive bid or ask prices. 2 - "last" method, where stop orders are triggered based on the last price. 3 double last method. 4 bid/ask method. 7 last or bid/ask method. 8 mid-point method.

outsideRth() As Integer hidden() As Integer

If set to true, allows orders to also trigger or fill outside of regular trading hours. If set to true, the order will not be visible when viewing the market depth. This option only applies to orders routed to the ISLAND exchange. The amount off the limit price allowed for discretionary orders. The trade's "Good After Time," format "YYYYMMDD hh:mm:ss (optional time zone)" Use an empty String if not applicable. You must enter a tif value of GTD. The trade's "Good Till Date," format is: YYYYMMDD hh:mm:ss (optional time zone) Use an empty String if not applicable. The Financial Advisor group the trade will be allocated to -- use an empty String if not applicable. The Financial Advisor allocation profile the trade will be allocated to -- use an empty String if not applicable. The Financial Advisor allocation method the trade will be allocated with -- use an empty String if not applicable. The Financial Advisor percentage concerning the trade's allocation -- use an empty String if not applicable. Values are 1 or 2.

discretionaryAmt() As Double goodAfterTime() As String

goodTillDate() As String

faGroup() As String

faProfile() As String

faMethod() As String

faPercentage() As String

shortSaleSlot() As Integer

API Reference Guide

192

ActiveX ActiveX COM Objects

Property designatedLocation() As String ocaType() As Integer

Description Use only when shortSaleSlot value = 2. Cancel on Fill with Block = 1 Reduce on Fill with Block = 2 Reduce on Fill without Block = 3 Precautionary constraints are defined on the TWS Presets page, and help ensure tha tyour price and size order values are reasonable. Orders sent from the API are also validated against these safety constraints, and may be rejected if any constraint is violated. To override validation, set this parameters value to True. Valid values include: 0 = False 1 = True Individual = 'I' Agency = 'A', AgentOtherMember = 'W' IndividualPTIA = 'J' AgencyPTIA = 'U' AgentOtherMemberPTIA = 'M' IndividualPT = 'K' AgencyPT = 'Y' AgentOtherMemberPT = 'N'

overridePercentageConstraints( ) As Integer

rule80A() As String

Valid values are:

settlingFirm() As String clearingAccount() As String

Institutional only. For IBExecution customers: Specifies the true beneficiary of the order. This value is required for FUT/FOP orders for reporting to the exchange. For IBExecution customers: Valid values are: IB, Away, and PTA (post trade allocation). yes=1, no=0 Identifies a minimum quantity order type. The percent offset amount for relative orders. Trade with electronic quotes. yes = 1, no = 0 Trade with firm quotes. yes = 1, no = 0 The maximum Smart order distance from the NBBO.

clearingIntent() As String allOrNone() As Integer minQty() As Integer percentOffset() As Double eTradeOnly() As Integer

firmQuoteOnly() As Integer

nbboPriceCap() As Double

API Reference Guide

193

ActiveX ActiveX COM Objects

Property auctionStrategy() As Integer

Description Valid values are: match = 1 improvement = 2

transparent = 3 For BOX exchange only. startingPrice() As Double stockRefPrice() As Double The starting price. Valid on BOX orders only. The stock reference price. The reference price is used for VOL orders to compute the limit price sent to an exchange (whether or not Continuous Update is selected), and for price range monitoring. The stock delta. Valid on BOX orders only. The lower value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. The upper value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. What the price is, computed via TWSs 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. How the volatility is calculated. deltaNeutralOrderType() As String Daily = 1 Annual = 2

delta() As Double stockRangeLower() As Double

stockRangeUpper() As Double

volatility() Double

volatilityType() Integer

VOL orders only. Enter an order type to instruct TWS to submit a delta neutral trade on full or partial execution of the VOL order. For no hedge delta order to be sent, specify NONE. VOL orders only. Use this field to enter a value if the value in the deltaNeutralOrderType field is an order type that requires an Aux price, such as a REL order.

deltaNeutralAuxPrice() As Double

API Reference Guide

194

ActiveX ActiveX COM Objects

Property continuousUpdate() As Integer

Description Used for dynamic management of volatility orders. Determines whether TWS is supposed to update the order price as the underlying moves. If 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 underlying price changes. Used for dynamic management of volatility orders. Set to 1 = Average of National Best Bid or Ask, or set to 2 = National Best Bid when buying a call or selling a put; and National Best Ask when selling a call or buying a put.

ireferencePriceType() As Integer

trailStopPrice() As Double scaleInitLevelSize() As Integer scaleSubsLevelSize() As Integer scalePriceIncrement() As Double basisPoints() As Integer basisPointsType() As Double whatIf() As Integer

For TRAILLIMIT orders only For Scale orders: Defines the size of the first, or initial, order component. For Scale orders: Defines the order size of the subsequent scale order components. Used in conjunction with scaleInitLevelSize(). For Scale orders: Defines the price increment between scale components. This field is required. For EFP orders only For EFP orders only Use to request pre-trade commissions and margin information. If set to true, margin and commissions data is received back via the IOrderState() object for the openOrder() callback.

API Reference Guide

195

ActiveX ActiveX COM Objects

IOrderState

Property status() As String initMargin() As String maintMargin() As String equityWithLoan() As String commission() As Double minCommission() As Double

Description Displays the order status. Shows the impact the order would have on your initial margin. Shows the impact the order would have on your maintenance margin. Shows the impact the order would have on your equity with loan value. Shows the commission amount on the order. Used in conjunction with the maxCommission field, this defines the lowest end of the possible range into which the actual order commission will fall. Used in conjunction with the minCommission field, this defines the highest end of the possible range into which the actual order commission will fall. Shows the currency of the commission value. Displays a warning message if warranted.

maxCommission() As Double

commissionCurrency() As String warningText() As String

API Reference Guide

196

ActiveX ActiveX COM Objects

IScannerSubscription

Property numberOfRows() As Integer instrument() As String locations() As String scanCode() As String priceAbove() As Double priceBelow() As Double volumeAbove() As Integer marketCapAbove() As Double marketCapBelow() As Double moodyRatingAbove() As String moodyRatingBelow() As String spRatingAbove() As String spRatingBelow() As String maturityDateAbove() As String maturityDateBelow() As String couponRateAbove() As String couponRateBelow() As String excludeConvertible() As Integer scannerSettingPairs() As String

Description Defines the number of rows of data to return for a query. Defines the instrument type for the scan. The location. Can be left blank. Filter out contracts with a price lower than this value. Can be left blank. Filter out contracts with a price higher than this value. Can be left blank. Filter out contracts with a volume lower than this value. Can be left blank. Filter out contracts with a market cap lower than this value. Can be left blank. Filter out contracts with a market cap above this value. Can be left blank. Filter out contracts with a Moody rating below this value. Can be left blank. Filter out contracts with a Moody rating above this value. Can be left blank. Filter out contracts with an S&P rating below this value. Can be left blank. Filter out contracts with an S&P rating above this value. Can be left blank. Filter out contracts with a maturity date earlier than this value. Can be left blank. Filter out contracts with a maturity date later than this value. Can be left blank. Filter out contracts with a coupon rate lower than this value. Can be left blank. Filter out contracts with a coupon rate higher than this value. Can be left blank. Filter out convertible bonds. Can be left blank. Can leave empty. For example, a pairing "Annual, true" used on the "top Option Implied Vol % Gainers" scan would return annualized volatilities. Can leave empty.

averageOptionVolumeAbove () As Integer

API Reference Guide

197

ActiveX ActiveX COM Objects

Property stockTypeFilter() As String

Description Values are: ALL (excludes nothing) STOCK (excludes ETFs) ETF (includes ETFs)

ITagValueList

Property Count() As Integer Item(Integer) As Object

Description The number of tag-value pairs (IBAlgo parameters). A tag-value pair (IBAlgo parameter). For more information, see IBAlgo Parameters.

ITagValue

Property tag() As String value() As String

Description An IBAlgo order parameter. For more information, see IBAlgo Parameters. The value of the IBAlgo parameter.

IUnderComp

Property conId() As Integer delta() As Double price() As Double

Description The unique contract identifier specifying the security. Used for Delta-Neutral Combo contracts. The underlying stock or future delta. Used for Delta-Neutral Combo contracts. The price of the underlying. Used for Delta-Neutral Combo contracts.

API Reference Guide

198

ActiveX ActiveX Properties

ActiveX Properties
The table below defines properties you can use when connecting to a server using ActiveX. Note: All of these properties have been deprecated as of API release 9.4 (December 2007), except string TwsConnectionTime and long serverVersion) and will soon be removed. Please update your software to use the properties in the ActiveX IOrder COM object (except where otherwise noted) instead of these deprecated properties. Description Connection time. Server Version.

Property String TwsConnectionTime long serverVersion

The following properties have been deprecated. They have all been replaced by properties in the IOrder COM object except where otherwise noted. String tif boolean transmit The time in force. Valid values are: DAY, GTC, IOC, GTD Specifies whether the order will be transmitted by the server. If set to false, the order will be created but will not be sent. Identifies an OCA (one cancels all) group. Identifies the account. For institutional customers only. Customer-defined order identification field. Enter a reference string to help identify orders. Identifies the order origin. For institutional customers only. Valid values are: String openClose long parentId boolean blockOrder boolean sweepToFill long displaySize 0 = customer 1 = firm

String oca String account String orderRef long origin

Specifies whether the order is an open or close. For institutional customers only. Valid values are O, C. The order ID of the parent order, used for bracket and auto trailing stop orders. If set to true, specifies that the order is an ISE Block order. If set to true, specifies that the order is a Sweep-to-Fill order. The publicly disclosed order size, used when placing Iceberg orders.

API Reference Guide

199

ActiveX ActiveX Properties

Property long triggerMethod

Description Specifies how Simulated Stop, Stop-Limit and Trailing Stop orders are triggered. Valid values are: O - The default value. The "double bid/ask" method will be used for orders for OTC stocks and US options. All other orders will used the "last" method. 1 - use "double bid/ask" method, where stop orders are triggered based on two consecutive bid or ask prices. 2 - "last" method, where stop orders are triggered based on the last price.

boolean ignoreRth boolean hidden

If set to true, allows triggering of orders outside of regular trading hours. If set to true, the order will not be visible when viewing the market depth. this option only works with orders routed to the ISLAND exchange. Filter the results of the reqExecutions() method based on the clientId. Note: This property has been deprecated. Use the corresponding property in IExecutionFilter. Filter the results of the reqExecutions() method based on an account code. This is only relevant for FA managed accounts. Note: This property has been deprecated. Use the corresponding property in IExecutionFilter. Filter the results of the reqExecutions() method based on execution reports received after the specified time. Note: This property has been deprecated. Use the corresponding property in IExecutionFilter. Filter the results of the reqExecutions() method based on the order symbol. Note: This property has been deprecated. Use the corresponding property in IExecutionFilter. Filter the results of the reqExecutions() method based on the order security type. Refer to the ActiveX methods section for the list of valid security types. Note: This property has been deprecated. Use the corresponding property in IExecutionFilter. Filter the results of the reqExecutions() method based on the order exchange. Note: This property has been deprecated. Use the corresponding property in IExecutionFilter.

long clientIdFilter

String acctCodeFilter

String timeFilter

String symbolFilter

String secTypeFilter

String exchangeFilter

API Reference Guide

200

ActiveX ActiveX Properties

Property String sideFilter

Description Filter the results of the reqExecutions() method based on the order action. Refer to the ActiveX methods sections for the list of valid order actions. Note: This property has been deprecated. Use the corresponding property in IExecutionFilter. Set an order's discretionary amount. For institutional customers only. 0 - inapplicable (i.e. retail customer or not short leg) 1 - clearing broker

double discretionaryAmt long shortSaleSlot

2 - third party. If this value is used, you must enter a designated location. Note: This property has been deprecated. Use the corresponding property in IComboLeg. String designatedLocation String goodAfterTime Only valid when shortSaleSlot value = 2. Otherwise leave blank or orders will be rejected. The trade's "Good After Time," format "YYYYMMDD hh:mm:ss (optional time zone)" Use an empty String if not applicable. This property has been deprecated. Use the corresponding property in IExecutionFilter. You must enter a tif value of GTD. The trade's "Good Till Date," format "YYYYMMDD hh:mm:ss (optional time zone)" Use an empty String if not applicable. Cancel on Fill with Block = 1 Reduce on Fill with Block = 2 Reduce on Fill without Block = 3 Regular trading hours only. 0 = no 1 = yes. Individual = 'I' Agency = 'A', AgentOtherMember = 'W' IndividualPTIA = 'J' AgencyPTIA = 'U' AgentOtherMemberPTIA = 'M' IndividualPT = 'K' AgencyPT = 'Y' AgentOtherMemberPT = 'N' Institutional only. long minQty 0 = no 1 = yes

String goodTillDate

long ocaType

boolean rthOnly String rule80A

String settlingFirm boolean allOrNone

Identifies a minimum quantity order type.

API Reference Guide

201

ActiveX ActiveX Properties

Property double percentOffset boolean eTradeOnly

Description The percent offset for relative orders. Trade with electronic quotes. 0 = no 1 = yes 0 = no 1 = yes

boolean firmquoteOnly

Trade with firm quotes.

double nbboPriceCap long auctionStrategy

Maximum Smart order distance from the NBBO. Valid values are: match = 1 improvement = 2

transparent = 3 For orders on BOX only. double startingPrice double stockRefPrice Starting price. For BOX orders only. Used for VOL orders to compute the limit price sent to an exchange (whether or not Continuous Update is used), and for price range monitoring. Also used for price improvement option orders. The stock delta. For BOX orders only. The lower value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. The upper value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. If set, allows you to override TWS order price percentage constraints set to reject orders that deviate too far from the NBBO. This was created to avoid transmitting orders with an incorrect price. The option price in volatility, as calculated by TWS' Option Analytics. This value is expressed as a percent and is used to calculate the limit price sent to the exchange. Select: string deltaNeutralOrderType 1 = Daily volatility 2 = Annual volatility

double delta double stockRangeLower

double stockRangeUpper

bool overridePercentageConstrai nts double volatility

long volatilityType

VOL orders only. Enter an order type to instruct TWS to submit a delta neutral trade on full or partial execution of the VOL order. For no hedge delta order to be sent, specify NONE. VOL orders only. Use this field to enter a value if the value in the deltaNeutralOrderType field is an order type that requires an Aux price, such as a REL order.
202

int deltaNeutralAuxPrice

API Reference Guide

ActiveX ActiveX Properties

Property bool continuousUpdate

Description VOL orders only. Specifies whether TWS will automatically update the limit price of the order as the underlying price moves. VOL orders only. Specifies how you want TWS to calculate the limit price for options, and for stock range price monitoring. Valid values include: 1 = Average of NBBO 2 = NBB or the NBO depending on the action and right.

long referencePriceType

int scaleNumComponents

For Scale orders: Defines the number of component orders into which the parent order will be split, thereby backing into the number of units within each component. For Scale orders: Defines the number of units per component, backing into the number of components into which the parent order is split. For Scale orders: Defines the price increment per scale component. For EFP orders. For EFP orders.

int scaleComponentSize

double scalePriceIncrement double basisPoints int basisPointsType

API Reference Guide

203

ActiveX Placing a Combination Order

Placing a Combination Order

A combination order is a special type of order that is constructed of many separate legs but executed as a single transaction. Submit combo orders such as calendar spreads, conversions and straddles using the BAG security type (defined in the Contract object). The key to implementing a successful API combination order using the API is to knowing how to place the same order using Trader Workstation. If you are familiar with placing combination orders in TWS, then it will be easier to place the same order using the API, because the API only imitates the behavior of TWS. Example In this example, a customer places a BUY order on a calendar spread for GOOG. To buy one calendar spread means: Leg 1: Sell 1 GOOG OPT SEP 18 '09 150.0 CALL (100) Leg 2: Buy 1 GOOG OPT JAN 21 '11 150.0 CALL (100) Here is a summary of the steps required to place a combo order using the API:

Obtain the contract id (conId) for each leg. Get this number by invoking the reqContractDetailsEx() method. Include each leg on the IComboLeg COM object by populating the related fields. Implement the placeOrderEx() method with the IContract and IOrder COM objects.

To place this combo order 1 Get the Contract IDs for both leg definitions: 'First Leg Dim con1 As TWSLib.IContract con1 = Tws1.createContract con1.symbol = "GOOG" con1.secType = "OPT" con1.expiry = "200909" con1.strike = 150.0 con1.right = "C" con1.multiplier = "100" con1.exchange = "SMART" con1.currency = "USD" Tws1.reqContractDetailsEx(1, con1) 'Second Leg Dim con2 As TWSLib.IContract con2 = Tws1.createContract con2.symbol = "GOOG" con2.secType = "OPT"
API Reference Guide 204

ActiveX Placing a Combination Order

con2.expiry = "201101" con2.strike = 150.0 con2.right = "C" con2.multiplier = "100" con2.exchange = "SMART" con2.currency = "USD" Tws1.reqContractDetailsEx(2, con2) 'All conId numbers are delivered by the ContractDetail() Private Sub Tws1_contractDetailsEx(ByVal sender As Object, ByVal e As AxTWSLib._DTwsEvents_contractDetailsExEvent) Handles Tws1.contractDetailsEx Dim contractDetails As TWSLib.IContractDetails contractDetails = e.contractDetails Dim contract As TWSLib.IContract contract = contractDetails.summary 'reqId = 1 is corresponding to the first request or first leg 'reqId = 2 is corresponding to the second request or second leg If e.reqId = 1 Then leg1 = contract.conId 'to obtain conId for the first leg End If If e.reqId = 2 Then leg2 = contract.conId 'to obtain conId for the second leg End If End Sub 2 Once the program has acquired the conId value for each leg, include it in the ComboLeg object: TWSLib.IComboLegList addAllLegs = Tws1.createComboLegList 'First Combo leg Dim Leg1 As TWSLib.IComboLeg Leg1 = addAllLegs.Add() Leg1.conId = leg1_conId Leg1.ratio = 1 Leg1.action = "SELL" Leg1.exchange = "SMART" Leg1.openClose = 0 Leg1.shortSaleSlot = 0 Leg1.designatedLocation = "" ' Second Combo leg Dim Leg2 As TWSLib.IComboLeg

API Reference Guide

205

ActiveX Placing a Combination Order

Leg2 = addAllLegs.Add() Leg1.conId = leg2_conId Leg1.ratio = 1 Leg1.action = "BUY" Leg1.exchange = "SMART" Leg1.openClose = 0 Leg1.shortSaleSlot = 0 Leg1.designatedLocation = "" 3 Invoke the placeOrder() method with the appropriate contract and order objects: Dim contract As TWSLib.IContract contract = Tws1.createContract contract.symbol = "USD" contract.secType = "BAG" contract.exchange = "SMART" contract.currency = "USD" contract.comboLegs = addAllLegs Dim order As TWSLib.IOrder order = Tws1.createOrder order.action = "BUY" order.totalQuantity = 1 order.orderType = "MKT" Tws1.placeOrderEx(OrderId, contract, order) Note: For more information on combination orders, see the TWS Users Guide topics About Combination Orders and Notes on Combination Orders.

API Reference Guide

206

C++
This chapter describes the C++ API, including the following topics:

4
Linking to TWS using the TwsSocketClient.dll Using the C++ TestSocketClient Sample Program Class EClientSocket Functions Class EWrapper Functions SocketClient Properties Placing a Combination Order

API Reference Guide

207

C++ Linking to TWS using the TwsSocketClient.dll

Linking to TWS using the TwsSocketClient.dll

To link to TWS using the TwsSocketClient.dll 1 2 Create a Windows application using MS Visual Studio (version 5.0 or higher). Add the full path to the \SocketClient\include directory in your API installation folder to your project's include path. This should be done for any individual project that accesses the TwsSocketClient library's header files. Add the full path to the \SocketClient\lib\TwsSocketclient.lib file in your API installation directory to your project's libraries path. This should be done for any individual project that accesses the TwsSocketClient library. Include EWrapper.h and EClientSocket.h in any Visual C++ source code that accesses their functionality and data structures. Subclass the EWrapper class. Override the following functions: Ewrapper Function tickPrice() tickSize() tickOptionComputation() tickGeneric() tickString() tickEFP() orderStatus() openOrder() error() connectionClosed() updateAccountValue() updateAccountTime() updatePortfolio() nextValidId() contractDetails() contractDetailsEnd() bondContractDetails() exectDetails() updateMktDepth() Receives order status. Receives open orders. Receives error information. Notifies when TWS terminates the connection. Receives current account values. Receives the last time account information was updated. Receives current portfolio information. Receives the next valid order ID upon connection. Receives contract information. Identifies the end of a given contract details request. Receives bond contract information. Receives execution report information. Receives market depth information. Description Handles market data.

4 5 6

API Reference Guide

208

C++ Linking to TWS using the TwsSocketClient.dll

Ewrapper Function updateMktDepthL2() updateNewsBulletin() managedAccounts() receiveFA() historicalData() scannerParameters()

Description Receives Level II market depth information. Receives IB news bulletins. Receives a list of Financial Advisor (FA) managed accounts. Receives FA configuration information. Receives historical data results. Receives an XML document that describes the valid parameters of a scanner subscription. Receives market scanner results. Receives real-time bars. Receives the current system time on the server. Receives Reuters global fundamental market data.

scannerData() realTimeBar() currentTime() fundamentalData()

7 8

Instantiate the EClientSocket class. Call the following functions: a b Import com.ib.client.* into your source code file. Implement the EWrapper interface. This class will receive messages from the socket.

API Reference Guide

209

C++ Linking to TWS using the TwsSocketClient.dll

Override the following functions: Ewrapper Functions tickPrice() tickSize() tickOptionComputation() tickGeneric() tickString() tickEFP() orderStatus() openOrder() error() connectionClosed() updateAccountValue() updateAccountTime() updatePortfolio() nextValidId() contractDetails() contractDetailsEnd() bondContractDetails() exectDetails() updateMktDepth() updateMktDepthL2() updateNewsBulletin() managedAccounts() receiveFA() historicalData() scannerParameters() Receives order status. Receives open orders. Receives error information. Notifies when TWS terminates the connection. Receives current account values. Receives the last time account information was updated. Receives current portfolio information. Receives the next valid order ID upon connection. Receives contract information. Identifies the end of a given contract details request. Receives bond contract information. Receives execution report information. Receives market depth information. Receives Level II market depth information. Receives IB news bulletins. Receives a list of Financial Advisor (FA) managed accounts. Receives FA configuration information. Receives historical data results. Receives an XML document that describes the valid parameters of a scanner subscription. Receives market scanner results. Receives real-time bars. Receives the current system time on the server. Receives Reuters global fundamental market data.
210

Description Handles market data.

scannerData() realTimeBar() currentTime() fundamentalData()

API Reference Guide

C++ Linking to TWS using the TwsSocketClient.dll

d e

Instantiate the EClientSocket class. This object will be used to send messages to TWS. Call the following functions: EClientSocket Functions eConnect() eDisconnect() reqMktData() cancelMktData() reqMktDepth() cancelMktDepth() reqContractDetails() placeOrder() cancelOrder() reqAccountUpdates() reqExecutions() reqOpenOrders() Description Connects to TWS. Disconnects from TWS. Requests market data. Cancels market data. Requests market depth. Cancels market depth. Requests contract details. Places an order. Cancels an order. Requests account values, portfolio, and account update time information. Requests a list of the days execution reports. Requests a list of current open orders for the requesting client and associates TWS open orders with the client. The association only occurs if the requesting client has a Client ID of 0. Requests a list of all open orders. Automatically associates a new TWS with the client. The association only occurs if the requesting client has a Client ID of 0. Requests IB news bulletins. Cancels IB news bulletins. Sets the level of API request and processing logging. Requests a list of Financial Advisor (FA) managed account codes. Requests FA configuration information from TWS. Modifies FA configuration information from the API. Requests an XML document that describes the valid parameters of a scanner subscription. Requests market scanner results. Cancels a scanner subscription.

reqAllOpenOrders() reqAutoOpenOrders()

reqNewsBulletin() cancelNewsBulletins() setServerLogLevel() reqManagedAccts() requestFA() replaceFA() reqScannerParameters()

reqScannerSubscription() cancelScannerSubscription()

API Reference Guide

211

C++ Linking to TWS using the TwsSocketClient.dll

EClientSocket Functions reqHistoricalData() cancelHistoricalData() reqRealTimeBars() cancelRealTimeBars() exerciseOptions() reqCurrentTime() serverVersion()

Description Requests historical data. Cancels historical data. Requests real-time bars. Cancels real-time bars. Exercises options. Requests the current server time. Returns the version of the TWS instance to which the API application is connected. Returns the time the API application made a connection to TWS. Requests Reuters global fundamental data. There must be a subscription to Reuters Fundamental set up in Account Management before you can receive this data. Cancels Reuters global fundamental data.

TwsConnectionTime() reqFundamentalData()

cancelFundamentalData()

To run the program, ensure that the TwsSocketClient.dll is in the same directory as your executable, or in your path. By default, the TwsSocketClient.dll file installs into your C:\Windows\system or C:\WINNT\system32 directory.

API Reference Guide

212

C++ Using the C++ TestSocketClient Sample Program

Using the C++ TestSocketClient Sample Program

You can access the IB trading system via TWS or the IB Gateway through a Microsoft Windows-based C++ application using the TWSSocketClient.dll component. Before you can connect to TWS using the SocketClient component, you must:

Install the socket client component and sample programs If you are using TWS, configure it to support the API components Have Microsoft Visual Studio (Visual C++ 5.0 or higher) installed on your PC.

The TestSocketClient program is a sample program that shows you how to use sockets to connect to TWS from a Microsoft Windows-based C++ application.

To run the pre-built sample application

Weve included a complete C++ client with our API software. To run this sample application, go to your TWS API installation folder, then open the \TestSocketClient\Release folder. Run the file named client2.exe.

To run the TestSocketClient program from Microsoft Visual Studio 2008

To create the project file and compile the TestSocketClient application (client2.exe): 1 2 3 4 5 6 Download and install the latest version of the API software. Create the folder where all project related files will be located. For example, C:\SampleSocketClient. Copy the folders TestSocketClient, Shared and SocketClient into the folder you created in Step 2. (For example, C:\SampleSocketClient.) In Visual Studio, select New > Project From Existing Code from the File menu. Select Visual C++ as the project type. In the Create New Project from Existing Code Files dialog: a b c For the Project File location, select the folder you created in Step 2. (For example, C:\SampleSocketClient.) For the Project Name, type SampleSocketClient. Click Finish.

API Reference Guide

213

C++ Using the C++ TestSocketClient Sample Program

Right-click the project in the Solution Explorer and select Properties. In the Property Pages dialog: a On left side of the dialog, select Configuration Parameters > C/C++ > General. In the Additional Include Directories field on the right side of the dialog, type: ./Shared;./SocketClient/src b On left side of the dialog, select Configuration Parameters > C/C++ > Code Generation. In the Runtime Library field on the right side of the dialog, select Multi-threaded (/MT).

8 9

Click OK to save your changes to the project properties. Build the project.

API Reference Guide

214

C++ Class EClientSocket Functions

Class EClientSocket Functions

The list below define the class EClientSocket functions you can use when connecting to TWS. The list of functions includes: Connection and Server EClientSocket() eConnect() eDisconnect() isConnected() reqCurrentTime() serverVersion() TwsConnectionTime() setLogLevel() checkMessages() Market Data reqMktData() cancelMktData() calculateImpliedVolatility() cancelCalculateImpliedVolatility() calculateOptionPrice() cancelCalculateOptionPrice() Orders placeOrder() cancelOrder() reqOpenOrders() reqAllOpenOrders() reqAutoOpenOrders() reqIDs() exerciseOptions() Account reqAccountUpdates() Executions reqExecutions() Contract Details reqContractDetails() Market Depth reqMktDepth() cancelMktDepth() News Bulletins reqNewsBulletins() cancelNewsBulletins() Financial Advisors reqManagedAccts() requestFA() replaceFA() Historical Data reqHistoricalData() cancelHistoricalData() Market Scanners reqScannerParameters() reqScannerSubscription() cancelScannerSubscription() Real Time Bars reqRealTimeBars() cancelRealTimeBars() Fundamental Data reqFundamentalData() cancelFundamentalData()

EClientSocket()
This is the constructor. EClientSocket( EWrapper *ptr) Parameter ptr Description The pointer to an object that was derived from the EWrapper base class.
215

API Reference Guide

C++ Class EClientSocket Functions

eConnect()
This function must be called before any other. There is no feedback for a successful connection, but a subsequent attempt to connect will return the message "Already connected." bool eConnect( const char *host, UINT port, int clientId=0) Parameter host port clientId Description The host name or IP address of the machine where TWS is running. Leave blank to connect to the local host. Must match the port specified in TWS on the Configure>API>Socket Port field. A number used to identify this client connection. All orders placed/modified from this client will be associated with this client identifier. Note: Each client MUST connect with a unique clientId.

eDisconnect()
Call this function to terminate the connections with TWS. Calling this function does not cancel orders that have already been sent.

void eDisconnect() Parameter ptr Description The pointer to an object that was derived from the EWrapper base class.

isConnected()
Call this function to check if there is a connection with TWS

void isConnected()

API Reference Guide

216

C++ Class EClientSocket Functions

reqMktData()
Call this function to request market data. The market data will be returned by the tickPrice and tickSize events.

void reqMktData(TickerID id, const Contract &contract, CString genericTicklist, bool snapshot) Parameter id Description The ticker id. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. This structure contains a description of the contract for which market data is being requested. A comma delimited list of generic tick types. Tick types can be found in the Generic Tick Types page. Check to return a single snapshot of market data and have the market data subscription cancel. Do not enter any genericTicklist values if you use snapshot.

contract genericTicklist snapshot

cancelMktData()
After calling this function, market data for the specified id will stop flowing.

void cancelMktData(TickerID id) Parameter id Description The ID that was specified in the call to reqMktData().

calculateImpliedVolatility()
Call this function to calculate volatility for a supplied option price and underlying price. void calculateImpliedVolatility(TickerID reqId, Contract &contract, double optionPrice, double underPrice) Parameter reqId contract optionPrice underPrice Description The ticker id. Describes the contract. The price of the option. Price of the underlying.

API Reference Guide

217

C++ Class EClientSocket Functions

cancelCalculateImpliedVolatility()
Call this function to cancel a request to calculate volatility for a supplied option price and underlying price. calculateImpliedVolatility(TickerId reqId) Parameter reqId Description The ticker id.

calculateOptionPrice()
Call this function to calculate option price and greek values for a supplied volatility and underlying price. void calculateOptionPrice(TickerId reqId, const Contract &contract, double volatility, double underPrice) Parameter reqId contract volatility underPrice Description The ticker ID. Describes the contract. The volatility. Price of the underlying.

cancelCalculateOptionPrice()
Call this function to cancel a request to calculate the option price and greek values for a supplied volatility and underlying price. cancelCalculateOptionPrice(TickerId reqId) Parameter reqId Description The ticker id.

placeOrder()
Parameter id Description The order id. You must specify a unique value. When the order status returns, it will be identified by this tag. This tag is also used when canceling the order. This structure contains a description of the contract which is being traded. This structure contains the details of the order. Note: Each client MUST connect with a unique clientId.

contract order

Call this function to place an order. The order status will be returned by the orderStatus event.

API Reference Guide

218

C++ Class EClientSocket Functions

void placeOrder( OrderID id, const Contract &contract, const Order &order) Parameter id Description The order id. You must specify a unique value. When the order status returns, it will be identified by this tag. This tag is also used when canceling the order. This structure contains a description of the contract which is being traded. This structure contains the details of the order. Note: Each client MUST connect with a unique clientId.

contract order

cancelOrder()
Call this function to cancel an order.

void cancelOrder(OrderID id) Parameter id Description The order ID that was specified previously in the call to placeOrder()

checkMessages()
This function should be called frequently (every 1 second) to check for messages received from TWS.

void checkMessages()

reqOpenOrders()
Call this function to request the open orders that were placed from this client. Each open order will be fed back through the openOrder() and orderStatus() functions on the EWrapper. Note: The client with a clientId of 0 will also receive the TWS-owned open orders. These orders will be associated with the client and a new orderId will be generated. This association will persist over multiple API and TWS sessions.

void reqOpenOrders()

reqAccountUpdates()
Call this function to start getting account values, portfolio, and last update time information.

void reqAccountUpdates(bool subscribe, const CString& acctCode) Parameter subscribe Description If set to TRUE, the client will start receiving account and portfolio updates. If set to FALSE, the client will stop receiving this information. The account code for which to receive account and portfolio updates.

acctCode

API Reference Guide

219

C++ Class EClientSocket Functions

reqExecutions()
When this function is called, the execution reports that meet the filter criteria are downloaded to the client via the execDetails() function.

void reqExecutions(int reqID, const ExecutionFilter& filter) Parameter reqId filter Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. This object contains attributes that describe the filter criteria used to determine which execution reports are returned.

reqIDs()
Call this function to request from TWS the next valid ID that can be used when placing an order. After calling this function, the nextValidId() event will be triggered, and the id returned is that next valid ID. That ID will reflect any autobinding that has occurred (which generates new IDs and increments the next valid ID therein).

void reqIds(int numIds) Parameter numIds Description The number of ids you want to reserve.

reqContractDetails()
Call this function to download all details for a particular underlying. The contract details will be received via the contractDetails() function on the EWrapper.

void reqContractDetails (const Contract &contract) Parameter reqId Contract Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. The summary description of the contract being looked up.

reqMktDepth()
Call this function to request market depth for a specific contract. The market depth will be returned by the updateMktDepth() and updateMktDepthL2() events.

void reqMktDepth (TickerID id, const Contract &contract, long numRows) Parameter id Description The ticker id. Must be a unique value. When the market depth data returns, it will be identified by this tag. This is also used when canceling the market depth This structure contains a description of the contract for which market depth data is being requested. - specified the number of market depth rows to display.

contract numRows

API Reference Guide

220

C++ Class EClientSocket Functions

cancelMktDepth()
After calling this function, market depth data for the specified id will stop flowing.

void cancelMktDepth (TickerID id) Parameter id Description The ID that was specified in the call to reqMktDepth().

reqNewsBulletins()
Call this function to start receiving news bulletins. Each bulletin will be returned by the updatedNewsBulletin() event.

void reqNewsBulletins(bool allMsgs) Parameter allMsgs Description If set to TRUE, returns all the existing bulletins for the current day and any new ones. If set to FALSE, will only return new bulletins.

cancelNewsBulletins()
Call this function to stop receiving news bulletins.

void cancelNewsBulletins()

setLogLevel()
The default detail level is ERROR. For more details, see API Logging on page -19.

void setLogLevel(int logLevel) Parameter logLevel Description Specifies the level of log entry detail used by the server (TWS) when processing API requests. Valid values include: 1 = SYSTEM 2 = ERROR 3 = WARNING 4 = INFORMATION 5 = DETAIL

reqAllOpenOrders()
Call this function to request the open orders placed from all clients and also from TWS. Each open order will be fed back through the openOrder() and orderStatus() functions on the EWrapper. Note: No association is made between the returned orders and the requesting client.

void reqAllOpenOrders()
API Reference Guide 221

C++ Class EClientSocket Functions

reqAutoOpenOrders()
Call this function to request that newly created TWS orders be implicitly associated with the client. When a new TWS order is created, the order will be associated with the client, and fed back through the openOrder() and orderStatus() functions on the EWrapper. Note: This request can only be made from a client with clientId of 0.

reqAutoOpenOrders (bool bAutoBind) Parameter bAutoBind Description If set to TRUE, newly created TWS orders will be implicitly associated with the client. If set to FALSE, no association will be made.

reqManagedAccts()
Call this function to request the list of managed accounts. The list will be returned by the managedAccounts() function on the EWrapper. Note: This request can only be made when connected to a FA managed account.

void reqManagedAccts()

requestFA()
Call this function to request FA configuration information from TWS. The data returns in an XML string via a "receiveFA" ActiveX event.

requestFA(long faDataType) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being requested. Valid values include: 1 = GROUPS 2 = PROFILE 3 = ACCOUNT ALIASES

API Reference Guide

222

C++ Class EClientSocket Functions

replaceFA()
Call this function to modify FA configuration information from the API. Note that this can also be done manually in TWS itself.

replaceFA(long faDataType, string XML) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being modified via the API. Valid values include: XML 1 = GROUPS 2 = PROFILE 3 =ACCOUNT ALIASES

The XML string containing the new FA configuration information.

reqHistoricalData()
void reqHistoricalData (TickerID id, const Contract &contract, String endDateTime, String durationStr, long barSizeSetting String whatToShow, int useRTH, int formatDate) Parameter id Description The id of the request. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. This object contains a description of the contract for which market data is being requested. Defines a query end date and time at any point during the past 6 mos. Valid values include any date/time within the past six months in the format: yyyymmdd HH:mm:ss ttt where "ttt" is the optional time zone. Set the query duration up to one week, using a time unit of seconds, days or weeks. Valid values include any integer followed by a space and then S (seconds), D (days) or W (week). If no unit is specified, seconds is used.

contract endDateTime

durationStr

API Reference Guide

223

C++ Class EClientSocket Functions

Parameter barSizeSetting

Description Specifies the size of the bars that will be returned (within IB/TWS limits). Valid values include: Bar Size 1 sec 5 secs 15 secs 30 secs 1 min 2 mins 3 mins 5 mins 15 mins 30 mins 1 hour 1 day 1 week 1 month 3 months 1 year Determines the nature of data being extracted. Valid values include: TRADES MIDPOINT BID ASK BID_ASK HISTORICAL_VOLATILITY OPTION_IMPLIED_VOLATILITY OPTION_VOLUME

whatToShow

useRTH

Determines whether to return all data available during the requested time span, or only data that falls within regular trading hours. Valid values include: 0 - all data is returned even where the market in question was outside of its regular trading hours. 1 - only data within the regular trading hours is returned, even if the requested time span falls partially or completely outside of the RTH.

API Reference Guide

224

C++ Class EClientSocket Functions

Parameter formatDate

Description Determines the date format applied to returned bars. Valid values include: 1 - dates applying to bars returned in the format: yyyymmdd{space}{space}hh:mm:dd 2 - dates are returned as a long integer specifying the number of seconds since 1/1/1970 GMT.

Note:

For a information about historical data request limitations, see Historical Data Limitations.

exerciseOptions()
void exerciseOptions(long id, const Contract &contract, int exerciseAction, int exerciseQuantity, const CString &account, int override) Parameter id contract exerciseAction exerciseQuantity override Description The ticker id. Must be a unique value. This structure contains a description of the contract for which market depth data is being requested. Specifies whether you want the option to lapse or be exercised. Values are 1 = exercise, 2 = lapse. The quantity you want to exercise. Specifies whether your setting will override the system's natural action. For example, if your action is "exercise" and the option is not in-the-money, by natural action the option would not exercise. If you have override set to "yes" the natural action would be overridden and the out-of-the money option would be exercised. Values are: 0 = no, 1 = yes.

reqScannerParameters()
Requests an XML string that describes all possible scanner queries.

void reqScannerParameters()

reqScannerSubscription()
void reqScannerSubscription(int tickerId, const ScannerSubscription&subscription) Parameter tickerId ScannerSubscription Description The ticker ID. Must be a unique value. This structure contains possible parameters used to filter results.

API Reference Guide

225

C++ Class EClientSocket Functions

cancelHistoricalData()
Used if an internet disconnect has occurred or the results of a query are otherwise delayed and the application is no longer interested in receiving the data.

void cancelHistoricalData (int tickerId) Parameter tickerId Description The ticker ID. Must be a unique value.

cancelScannerSubscription()
void cancelScannerSubscription(int tickerId) Parameter tickerId Description The ticker ID. Must be a unique value.

reqRealTimeBars()
Call the reqRealTimeBars() function to start receiving real time bar results through the realtimeBar() EWrapper function. void reqRealTimeBars(int tickerId, Contract contract, int barSize, String whatToShow, boolean useRTH) Parameter tickerId Description The Id for the request. Must be a unique value. When the data is received, it will be identified by this Id. This is also used when canceling the request. This object contains a description of the contract for which real time bars are being requested Currently only 5 second bars are supported, if any other value is used, an exception will be thrown. Determines the nature of the data extracted. Valid values include: useRTH TRADES BID ASK MIDPOINT 0 = all data available during the time span requested is returned, including time intervals when the market in question was outside of regular trading hours. 1 = only data within the regular trading hours for the product requested is returned, even if the time time span falls partially or completely outside.

contract barSize whatToShow

Regular Trading Hours only. Valid values include:

API Reference Guide

226

C++ Class EClientSocket Functions

cancelRealTimeBars()
Call the cancelRealTimeBars() function to stop receiving real time bar results.

void cancelRealTimeBars (int tickerId) Parameter tickerId Description The Id that was specified in the call to reqRealTimeBars().

reqCurrentTime()
Returns the current system time on the server side.

void reqCurrentTime()

serverVersion()
Returns the version of the TWS instance to which the API application is connected.

serverVersion()

TwsConnectionTime()
Returns the time the API application made a connection to TWS.

TwsConnectionTime()

reqFundamentalData()
Call this function to receive Reuters global fundamental data. There must be a subscription to Reuters Fundamental set up in Account Management before you can receive this data. void reqFundamentalData(int reqId, const Contract &contract, String reportType) Parameter reqId contract reportType Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. This structure contains a description of the contract for which Reuters Fundamental data is being requested. Identifies the report type, which is one of the following: Estimates Financial Statements Summary

API Reference Guide

227

C++ Class EClientSocket Functions

cancelFundamentalData()
Call this function to stop receiving Reuters global fundamental data. void cancelFundamentalData(int reqId) Parameter reqId Description The ID of the data request.

API Reference Guide

228

C++ Class EWrapper Functions

Class EWrapper Functions

The tables below define the class EWrapper functions you can use when connecting to TWS. These functions receive events from TWS. The list of functions includes: Connection and Server winError() error() connectionClosed() currentTime() Market Data tickPrice() tickSize() tickOptionComputation() tickGeneric() tickString() tickEFP() tickSnapshotEnd() Orders orderStatus() openOrder() nextValidId() Account and Portfolio updateAccountValue() updatePortfolio() updateAccountTime() News Bulletins updateNewsBulletin() Contract Details contractDetails() contractDetailsEnd() bondContractDetails() Executions execDetails() execDetailsEnd() Market Depth updateMktDepth() updateMktDepthL2() Financial Advisors managedAccounts() receiveFA() Historical Data historicalData() Market Scanners scannerParameters() scannerData() scannerDataEnd() Real Time Bars realtimeBar() Fundamental Data fundamentalData()

API Reference Guide

229

C++ Class EWrapper Functions

tickPrice()
This function is called when the market data changes. Prices are updated immediately with no delay. virtual void tickPrice(TickerID id, TickType field, double price, int canAutoExecute) Parameter id tickType Description The ticker ID that was specified previously in the call to reqMktData() Specifies the type of price. Possible values are: price canAutoExecute 1 = bid 2 = ask 4 = last 6 = high 7 = low 9 = close

- could be the bid, ask, last price, daily high, daily low or last day close, depending on tickType value. Specifies whether the price tick is available for automatic execution. Possible values are: 0 = not eligible for automatic execution 1 = eligible for automatic execution

tickSize()
This function is called when the market data changes. Sizes are updated immediately with no delay.

virtual void tickSize(TickerID id, TickType field, int size) Parameter id tickType Description The ticker ID that was specified previously in the call to reqMktData() Specifies the type of size. Possible values are: size 0 = bid size 3 = ask size 5 = last size 8 = volume

Could be the bid size, ask size, last size or trading volume, depending on the tickType value.

API Reference Guide

230

C++ Class EWrapper Functions

tickOptionComputation()
This function is called when the market in an option or its underlier moves. TWSs option model volatilities, prices, and deltas, along with the present value of dividends expected on that options underlier are received. virtual void tickOptionComputation(TickerID tickerId, TickType tickType, double impliedVol, double delta, double modelPrice, double pvDividend, double gamma, double vega, double theta, double undPrice) Parameter id tickType Description The ticker ID that was specified previously in the call to reqMktData() Specifies the type of tick. Possible values are: impliedVol delta optPrice pvDividend gamma vega theta undPrice 10 = Bid 11 = Ask 12 = Last

The implied volatility calculated by the TWS option modeler, using the specified ticktype value. The option delta value. The option price. The present value of dividends expected on the options underlying instrument. The option gamma value. The option vega value. The option theta value. The price of the underlying.

tickGeneric()
This function is called when the market data changes. Values are updated immediately with no delay.

virtual void tickGeneric(TickerId tickerId, TickType tickType, double value) Parameter tickerId tickType Description The ticker Id that was specified previously in the call to reqMktData(). Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 46 will map to shortable, etc. The value of the specified field.

value

API Reference Guide

231

C++ Class EWrapper Functions

tickString()
This function is called when the market data changes. Values are updated immediately with no delay. virtual void tickString(TickerId tickerId, TickType tickType, const CString& value) Parameter tickerId field Description The ticker Id that was specified previously in the call to reqMktData(). Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 45 will map to lastTimestamp, etc. The value of the specified field.

value

tickEFP()
This function is called when the market data changes. Values are updated immediately with no delay. virtual void tickEFP(TickerId tickerId, TickType tickType, double basisPoints, const CString& formattedBasisPoints, double totalDividends, int holdDays, const CString& futureExpiry, double dividendImpact, double dividendsToExpiry) Parameter tickerId field Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 38 will map to bidEFP, etc. Annualized basis points, which is representative of the financing rate that can be directly compared to broker rates. Annualized basis points as a formatted string that depicts them in percentage form. Implied futures price. Number of hold days until the expiry of the EFP. Expiration date of the single stock future. The dividend impact upon the annualized basis points interest rate. The dividends expected until the expiration of the single stock future.

basisPoints formattedBasisPoint s impliedFuture holdDays futureExpiry dividendImpact dividendsToExpiry

API Reference Guide

232

C++ Class EWrapper Functions

tickSnapshotEnd()
This is called when a snapshot market data subscription has been fully handled and there is nothing more to wait for. This also covers the timeout case. virtual void tickSnapshotEnd(int reqId) Parameter reqID Description Id of the data request.

API Reference Guide

233

C++ Class EWrapper Functions

orderStatus()
This event is called whenever the status of an order changes. It is also fired after reconnecting to TWS if the client has any open orders.

virtual void orderStatus(OrderId id, const CString &status, int filled, int remaining, double avgFillPrice, int permId, int parentId, double lastFillPrice, int clientId, const CString& whyHeld) Parameter id status Description The order ID that was specified previously in the call to placeOrder() The order status. Possible values include: PendingSubmit - indicates that you have transmitted the order, but have not yet received confirmation that it has been accepted by the order destination. NOTE: This order status is not sent by TWS and should be explicitly set by the API developer when an order is submitted. PendingCancel - indicates that you have sent a request to cancel the order but have not yet received cancel confirmation from the order destination. At this point, your order is not confirmed canceled. You may still receive an execution while your cancellation request is pending. NOTE: This order status is not sent by TWS and should be explicitly set by the API developer when an order is canceled. PreSubmitted - indicates that a simulated order type has been accepted by the IB system and that this order has yet to be elected. The order is held in the IB system until the election criteria are met. At that time the order is transmitted to the order destination as specified. Submitted - indicates that your order has been accepted at the order destination and is working. Cancelled - indicates that the balance of your order has been confirmed canceled by the IB system. This could occur unexpectedly when IB or the destination has rejected your order. Filled - indicates that the order has been completely filled. Inactive - indicates that the order has been accepted by the system (simulated orders) or an exchange (native orders) but that currently the order is inactive due to system, exchange or other issues.

filled remaining

Specifies the number of shares that have been executed. Specifies the number of shares still outstanding.

API Reference Guide

234

C++ Class EWrapper Functions

Parameter avgFillPrice

Description The average price of the shares that have been executed. This parameter is valid only if the filled parameter value is greater than zero. Otherwise, the price parameter will be zero. The TWS id used to identify orders. Remains the same over TWS sessions. The order ID of the parent order, used for bracket and auto trailing stop orders. The last price of the shares that have been executed. This parameter is valid only if the filled parameter value is greater than zero. Otherwise, the price parameter will be zero. The ID of the client (or TWS) that placed the order. Note that TWS orders have a fixed clientId and orderId of 0 that distinguishes them from API orders. This field is used to identify an order held when TWS is trying to locate shares for a short sell. The value used to indicate this is 'locate'.

permId parentId lastFilledPrice

clientId

whyHeld

error()
This event is called when there is an error with the communication or when TWS wants to send a message to the client. virtual void error(const int id, const int errorCode, const CString errorString) Parameter id errorCode errorString Description This is the orderId or tickerId of the request that generated the error. Error codes are documented in the API Message Codes topic. This is the textual description of the error, also documented in the Error Codes topic.

winError()
This event is called when there is an error on the client side.

virtual void winError(const CString &str, int lastError) Parameter str lastError Description This is the error message text. The error code returned by GetLastError().

API Reference Guide

235

C++ Class EWrapper Functions

connectionClosed()
This function is called when TWS closes the sockets connection with the ActiveX control, or when TWS is shut down.

virtual void connectionClosed()

managedAccounts()
This function is called when a successful connection is made to a Financial Advisor account. It is also called when the reqManagedAccts() function is invoked.

virtual void managedAccounts(const CString& accountsList) Parameter accountsList Description The comma delimited list of FA managed accounts.

openOrder()
This function is called to feed in open orders. virtual void openOrder(OrderId orderId, const Contract &contract, const Order &order, const OrderState &orderState) For more information, see Extended Order Attributes. Parameter orderID contract order orderState Description The order ID assigned by TWS. Use to cancel or update the order. The Contract class attributes describe the contract. The Order class gives the details of the open order. The orderState class includes attributes used for both pre and post trade margin and commission data.

API Reference Guide

236

C++ Class EWrapper Functions

updateAccountValue()
This function is called only when ReqAccountUpdates on EClientSocket object has been called.

virtual void updateAccountValue(const CString& key, const CString& value, const CString& currency, const CString& accountName) Parameter key Description - A string that indicates one type of account value. Below is a set of keys sent by TWS. value currency account CashBalance - Account cash balance Currency - Currency string DayTradesRemaining - Number of day trades left EquityWithLoanValue - Equity with Loan Value InitMarginReq - Current initial margin requirement LongOptionValue - Long option value MaintMarginReq - Current maintenance margin NetLiquidation - Net liquidation value OptionMarketValue - Option market value ShortOptionValue - Short option value StockMarketValue - Stock market value UnalteredInitMarginReq - Overnight initial margin requirement UnalteredMaintMarginReq - Overnight maintenance margin requirement

The value associated with the key. Defines the currency type, in case the value is a currency type. States the account to which the message applies. Useful for Financial Advisor sub-account messages.

API Reference Guide

237

C++ Class EWrapper Functions

updatePortfolio()
This function is called only when reqAccountUpdates on EClientSocket object has been called. virtual void updatePortfolio(const Contract& contract, int position, double marketPrice, double marketValue, double averageCost, double unrealizedPNL, double realizedPNL, const CString& accountName) Parameter contract Description This structure contains a description of the contract which is being traded. The exchange field in a contract is not set for portfolio update. This integer indicates the position on the contract. If the position is 0, it means the position has just cleared. Unit price of the instrument. The total market value of the instrument. The average cost per share is calculated by dividing your cost (execution price + commission) by the quantity of your position. The difference between the current market value of your open positions and the average cost, or Value - Average Cost. Shows your profit on closed positions, which is the difference between your entry execution cost (execution price + commissions to open the position) and exit execution cost ((execution price + commissions to close the position) States the account to which the message applies. Useful for Financial Advisor sub-account messages.

position marketPrice marketValue averageCost

unrealizedPNL realizedPNL

accountName

updateAccountTime()
This function is called only when reqAccountUpdates on EClientSocket object has been called. virtual void updateAccountTime(const CString& timeStamp) Parameter timeStamp Description This indicates the last update time of the account information.

API Reference Guide

238

C++ Class EWrapper Functions

nextValidId()
This function is called after a successful connection to TWS.

virtual void nextValidId(OrderID orderId) Parameter orderId Description The next available order ID received from TWS upon connection. Increment all successive orders by one based on this ID.

contractDetails()
This function is called only when reqContractDetails function on the EClientSocket object has been called.

virtual void contractDetails(const ContractDetails &contractDetails) Parameter reqId contractDetails Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. This structure contains a full description of the contract being looked up.

contractDetailsEnd()
This function is called once all contract details for a given request are received. This helps to define the end of an option chain.

void contractDetailsEnd(int reqId) Parameter reqID Description The ID of the data request.

execDetails()
This event is fired when the reqExecutions() functions is invoked, or when an order is filled.

virtual void execDetails( OrderId orderId, const Contract& contract, const Execution& execution, long liquidation) Parameter id contract execution Description The order ID that was specified previously in the call to placeOrder(). This structure contains a full description of the contract that was executed. This structure contains addition order execution details.

API Reference Guide

239

C++ Class EWrapper Functions

execDetailsEnd()
This function is called once all executions have been sent to a client in response to reqExecutions().

virtual void execDetailsEnd(int reqId) Parameter reqID Description The Id of the data request.

updateMktDepth()
This function is called when the market depth changes. virtual void updateMktDepth(TickerId id, int position, int operation, int side, double price, int size) Parameter id position operation Description The ticker ID that was specified previously in the call to reqMktDepth() Specifies the row id of this market depth entry. Identifies the how this order should be applied to the market depth. Valid values are: side 0 = insert (insert this new order into the row identified by 'position') 1 = update (update the existing order in the row identified by 'position') 2 = delete (delete the existing order at the row identified by 'position')

Identifies the side of the book that this order belongs to. Valid values are: 0 = ask 1 = bid

price size

The order price. The order size.

updateMktDepthL2()
This function is called when the Level II market depth changes. virtual void updateMktDepthL2(TickerId id, int position, CString marketMaker, int operation, int side, double price, int size) Parameter id position marketMaker Description The ticker ID that was specified previously in the call to reqMktDepth() Specifies the row id of this market depth entry. Specifies the exchange hosting this order.

API Reference Guide

240

C++ Class EWrapper Functions

Parameter operation

Description Identifies the how this order should be applied to the market depth. Valid values are: 0 = insert (insert this new order into the row identified by 'position') 1 = update (update the existing order in the row identified by 'position') 2 = delete (delete the existing order at the row identified by 'position')

side

Identifies the side of the book that this order belongs to. Valid values are: 0 = ask 1 = bid

price size

The order price. The order size.

updateNewsBulletin()
This event is triggered for each new bulletin if the client has subscribed (i.e. by calling the reqNewsBulletins() function.

virtual void updateNewsBulletin(int msgId, int msgType, const CString& message, const CString& origExchange Parameter msgId msgType Description The bulletin ID, incrementing for each new bulletin. Specifies the type of bulletin. Valid values include: message origExchange 1 = Regular news bulletin 2 = Exchange no longer available for trading 3 = Exchange is available for trading

The bulletin's message text. The exchange from which this message originated.

API Reference Guide

241

C++ Class EWrapper Functions

receiveFA()
This event receives previously requested FA configuration information from TWS.

virtual receiveFA(long faDataType, string XML) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being received from TWS. Valid values include: XML 1 = GROUPS 2 = PROFILE 3 =ACCOUNT ALIASES

The XML string containing the previously requested FA configuration information.

bondContractDetails()
This function is called only when reqContractDetails function on the EClientSocket object has been called for bonds.

virtual void bondContractDetails(const contractDetails&contractDetails) Parameter reqId contractDetails Description The ID of the data request. This structure contains a description of the contract which is being traded. The exchange field in a contract is not set for portfolio update.

historicalData()
This function receives the requested historical data results. virtual void historicalData(TickerId reqId, const CString& date, double open, double high, double low, double close, int volume, double WAP, int hasGaps) Parameter reqId date open high low close volume WAP Description The ticker ID of the request to which this bar is responding. The date-time stamp of the start of the bar. The format is determined by the reqHistoricalData() formatDate parameter. The bar opening price. The high price during the time covered by the bar. The low price during the time covered by the bar. The bar closing price. The volume during the time covered by the bar. The weighted average price during the time covered by the bar.

API Reference Guide

242

C++ Class EWrapper Functions

Parameter count

Description When TRADES historical data is returned, represents the number of trades that occurred during the time period the bar covers. Reports whether or not there are gaps in the data.

hasGaps

scannerParameters()
This function receives an XML document that describes the valid parameters that a scanner subscription can have.

virtual void scannerParameters(String xml) Parameter

xml

Description
An XML document that describes the valid parameters for queries.

scannerData()
This function receives the requested market scanner data results.

virtual void scannerData(int reqId, int rank, const ContractDetails &contractDetails, String distance, String benchmark, String projection) Parameter reqId rank contractDetails distance benchmark projection legsStr Description The ticker ID of the request to which this row is responding. The ranking within the response of this bar. This object contains a full description of the contract. Varies based on query. Varies based on query. Varies based on query. Describes combo legs when scan is returning EFP.

scannerDataEnd()
This function is called when the snapshot is received and marks the end of one scan.

virtual void scannerDataEnd(int reqId) Parameter reqId Description The ID of the market scanner request being closed by this parameter.

API Reference Guide

243

C++ Class EWrapper Functions

realtimeBar()
This function receives the real-time bars data results.

virtual void realtimeBar(TickerId reqId, long time, double open, double high, double low, double close, long volume, double wap, int count) Parameter reqId time open high low close volume wap count Description The ticker Id of the request to which this bar is responding. The date-time stamp of the start of the bar. The format is determined by the reqHistoricalData() formatDate parameter. The bar opening price. The high price during the time covered by the bar. The low price during the time covered by the bar. The bar closing price. The volume during the time covered by the bar. The weighted average price during the time covered by the bar. When TRADES historical data is returned, represents the number of trades that occurred during the time period the bar covers.

currentTime()
This function receives the current system time on the server side.

virtual void currentTime(long time) Parameter time Description The current system time on the server side.

fundamentalData()
This function is called to receive Reuters global fundamental market data. There must be a subscription to Reuters Fundamental set up in Account Management before you can receive this data. virtual void fundamentalData(int reqId, string data) Parameter reqId data Description The ID of the data request. One of three XML reports: Estimates (estimates) Financial statements (finstat) Summary (snapshot)

API Reference Guide

244

C++ SocketClient Properties

SocketClient Properties
The tables below define properties for the Execution, Contract and Order classes, and classes that are closely related to them.

Execution ExecutionFilter Contract ContractDetails ComboLeg Order OrderState ScannerSubscription UnderComp

API Reference Guide

245

C++ SocketClient Properties

Execution

Property CString execId CString time CString acctNumber CString exchange CString side

Description Unique order execution id. The order execution time. The customer account number. Exchange that executed the order. Specifies if the transaction was a sale or a purchase. Valid values are: BOT SLD

int shares double price int permId long clientId long orderId int liquidation int cumQty double avgPrice

The number of shares filled. The order execution price. The TWS id used to identify orders, remains the same over TWS sessions. The id of the client that placed the order. Note: TWS orders have a fixed client id of 0. The order id. Note: TWS orders have a fixed order id of 0. Identifies the position as one to be liquidated last should the need arise. Cumulative quantity. Used in regular trades, combo trades and legs of the combo. Average price. Used in regular trades, combo trades and legs of the combo.

ExecutionFilter

Property long clientId CString acctCode

Description Filter the results of the reqExecutions() function based on the clientId. Filter the results of the reqExecutions() function based on an account code. Note: this is only relevant for FA managed accounts. Filter the results of the reqExecutions() function based on execution reports received after the specified time. The format for timeFilter is "yyyymmdd-hh:mm:ss" Filter the results of the reqExecutions() function based on the order symbol.

CString time

CString symbol

API Reference Guide

246

C++ SocketClient Properties

Property CString secType

Description Filter the results of the reqExecutions() function based on the order security type. Note: Refer to the Contract struct for the list of valid security types. Filter the results of the reqExecutions() function based on the order exchange. Filter the results of the reqExecutions() function based on the order action. Note: Refer to the Order struct for the list of valid order actions.

CString exchange CString side

API Reference Guide

247

C++ SocketClient Properties

Contract

Property CString symbol CString secType

Description This is the symbol of the underlying asset. This is the security type. Valid values are STK OPT FUT IND FOP CASH BAG

CString expiry double strike CString right CString multiplier CString exchange CString currency

The expiration date. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. Allows you to specify a futures or options multiplier. This is only necessary when multiple possibilities exist.; The order destination, such as Smart. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. This is the local exchange symbol of the underlying asset. Dynamic memory structure used to store the leg definitions for this contract. Description for combo legs. To clarify any ambiguity for Smart-routed contracts, include the primary exchange, along with the Smart designation, for the destination. If set to true, contract details requests and historical data queries can be performed pertaining to expired contracts. Note: Historical data queries on expired contracts are limited to the last year of the contracts life, and are initially only supported for expired futures contracts.

CString localSymbol vector<ComboLeg*>* comboLegs; CString comboLegsDescrip CString primaryExchange bool includeExpired

int conId

The unique contract identifier.

API Reference Guide

248

C++ SocketClient Properties

Property CString secIdType

Description Security identifier, when querying contract details or when placing orders. Supported identifiers are: ISIN (Example: Apple: US0378331005) CUSIP (Example: Apple: 037833100) SEDOL (Consists of 6-AN + check digit. Example: BAE: 0263494) RIC (Consists of exchange-independent RIC Root and a suffix identifying the exchange. Example: AAPL.O for Apple on NASDAQ.)

CString secId

Unique identifier for the secIdType.

API Reference Guide

249

C++ SocketClient Properties

ContractDetails

Property Contract summary CString marketName CString tradingClass double minTick CString orderTypes CString validExchanges CString underConId CString longName CString cusip CString ratings

Description A contract structure. The market name for this contract. The trading class name for this contract. The minimum price tick. The list of valid order type for this contract The list of exchanges on which this contract is traded. The underlying contract ID. The descriptive name of the asset. For Bonds. The nine-character bond CUSIP or the 12-character SEDOL. For Bonds. Identifies the credit rating of the issuer. A higher credit rating generally indicates a less risky investment. Bond ratings are from Moody's and S&P respectively. For Bonds. A description string containing further descriptive information about the bond. For Bonds. The type of bond, such as "CORP." For Bonds. The type of bond coupon, such as "FIXED." For Bonds. Values are True or False. If true, the bond can be called by the issuer under certain conditions. For Bonds. Values are True or False. If true, the bond can be sold back to the issuer under certain conditions. For Bonds. The interest rate used to calculate the amount you will receive in interest payments over the course of the year. For Bonds. Values are True or False. If true, the bond can be converted to stock under certain conditions. For Bonds. The date on which the issuer must repay the face value of the bond. For Bonds. The date the bond was issued. For Bonds, relevant if the bond has embedded options. For Bonds, relevant if the bond has embedded options. For Bonds, relevant if the bond has embedded options, i.e., is the next option full or partial? For Bonds, if populated for the bond in IB's database Allows execution and strike prices to be reported consistently with market data, historical data and the order price, i.e. Z on LIFFE is reported in index points and not GBP. The contract month. Typically the contract month of the underlying for a futures contract.

CString descAppend CString bondType CString couponType bool callable bool putable double coupon bool convertible CString maturity CString issueDate CString nextOptionDate CString nextOptionType Bool nextOptionPartial CString notes long priceMagnifier

CString contractMonth

API Reference Guide

250

C++ SocketClient Properties

Property CString industry CString category CString subcategory CString timeZoneId CString tradingHours CString liquidHours

Description The industry classification of the underlying/product. For example, Financial. The industry category of the underlying. For example, InvestmentSvc. The industry subcategory of the underlying. For example, Brokerage. The ID of the time zone for the trading hours of the product. For example, EST. The trading hours of the product. For example, 20090507:0700-1830,1830-2330;20090508:CLOSED. The liquid trading hours of the product. For example, 20090507:0930-1600;20090508:CLOSED.

ComboLeg

Property long conId long ratio

Description The unique contract identifier specifying the security. Select the relative number of contracts for the leg you are constructing. To help determine the ratio for a specific combination order, refer to the Interactive Analytics section of the User's Guide. The side (buy or sell) for the leg you are constructing. The exchange to which the complete combination order will be routed. Specifies whether the order is an open or close order. Valid values are: Same - (0) same as the parent security. This is the only option for retail customers. Open - (1) only valid for institutional customers. Close - (2) only valid for institutional customers. Unknown 0 - inapplicable (i.e. retail customer or not short leg) 1 - clearing broker 2 - third party. If this value is used, you must enter a designated location.

CString action CString exchange long openClose

int shortSaleSlot

For institutional customers only.

CString designatedLocation

If shortSaleSlot == 2, the designatedLocation must be specified. Otherwise leave blank or orders will be rejected.

API Reference Guide

251

C++ SocketClient Properties

Order

Property long orderId long clientId long permId CString action long totalQuantity CString orderType

Description The id for this order. The id of the client that placed this order. The TWS id used to identify orders, remains the same over TWS sessions. Identifies the side. Valid values are: BUY, SELL, SSHORT The order quantity. Identifies the order type. Valid values are: MKT MKTCLS LMT LMTCLS PEGMKT SCALE STP STPLMT TRAIL REL VWAP TRAILLIMIT

double lmtPrice

This is the LIMIT price, used for limit, stop-limit and relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero. This is the STOP price for stop-limit orders, and the offset amount for relative orders. In all other cases, specify zero. The time in force. Valid values are: DAY, GTC, IOC, GTD. Identifies an OCA (one cancels all) group. Tells how to handle remaining orders in an OCA group when one order or part of an order executes. Valid values include: 1 = Cancel all remaining orders with block 2 = Remaining orders are proportionately reduced in size with block

double auxPrice CString tif CString ocaGroup int ocaType

3 = Remaining orders are proportionately reduced in size with no block If you use a value "with block" gives your order has overfill protection. This means that only one order in the group will be routed at a time to remove the possibility of an overfill.

API Reference Guide

252

C++ SocketClient Properties

Property CString account CString openClose int origin CString orderRef bool transmit long parentId bool blockOrder bool sweepToFill int displaySize int triggerfunction

Description The account. For institutional customers only. For institutional customers only. Valid values are O, C. The order origin. For institutional customers only. Valid values are 0 = customer, 1 = firm The order reference. For institutional customers only. Specifies whether the order will be transmitted by TWS. If set to false, the order will be created at TWS but will not be sent. The order ID of the parent order, used for bracket and auto trailing stop orders. If set to true, specifies that the order is an ISE Block order. If set to true, specifies that the order is a Sweep-to-Fill order. The publicly disclosed order size, used when placing Iceberg orders. Specifies how Simulated Stop, Stop-Limit and Trailing Stop orders are triggered. Valid values are: 0 - The default value. The "double bid/ask" function will be used for orders for OTC stocks and US options. All other orders will used the "last" function. 1 - use "double bid/ask" function, where stop orders are triggered based on two consecutive bid or ask prices. 2 - "last" function, where stop orders are triggered based on the last price. 3 double last function. 4 bid/ask function. 7 last or bid/ask function. 8 mid-point function.

boolean outsideRth() boolean hidden

If set to true, allows orders to also trigger or fill outside of regular trading hours. If set to true, the order will not be visible when viewing the market depth. This option only applies to orders routed to the ISLAND exchange. The amount off the limit price allowed for discretionary orders. Valid values are 1 or 2. Used only when shortSaleSlot = 2. The trade's "Good After Time," format "YYYYMMDD hh:mm:ss (optional time zone)" Use an empty String if not applicable.

double discretionaryAmt int shortSaleSlot CString designatedLocation CString goodAfterTime

API Reference Guide

253

C++ SocketClient Properties

Property CString goodTillDate

Description You must enter GTD as the time in force to use this string. The trade's "Good Till Date," format "YYYYMMDD hh:mm:ss (optional time zone)" Use an empty String if not applicable. Values include: Individual = 'I' Agency = 'A', AgentOtherMember = 'W' IndividualPTIA = 'J' AgencyPTIA = 'U' AgentOtherMemberPTIA = 'M' IndividualPT = 'K' AgencyPT = 'Y' AgentOtherMemberPT = 'N'

CString rule80A

CString settlingFirm CString clearingIntent CString clearingAccount

Institutional only. For IBExecution customers: Valid values are: IB, Away, and PTA (post trade allocation). For IBExecution customers: Specifies the true beneficiary of the order. This value is required for FUT/FOP orders for reporting to the exchange. 0 = no, 1 = yes Identifies a minimum quantity order type. The percent offset amount for relative orders. Trade with electronic quotes. 0 = no, 1 = yes Trade with firm quotes. 0 = no, 1 = yes Maximum smart order distance from the NBBO. Values include: match = 1 improvement = 2

bool allOrNone int minQty double percentOffset bool eTradeOnly bool firmQuoteOnly double nbboPriceCap int auctionStrategy

transparent = 3 For orders on BOX only. double startingPrice double stockRefPrice The auction starting price. For orders on BOX only. The stock reference price. The reference price is used for VOL orders to compute the limit price sent to an exchange (whether or not Continuous Update is selected), and for price range monitoring. The stock delta. For orders on BOX only.

double delta

API Reference Guide

254

C++ SocketClient Properties

Property double stockRangeLower double stockRangeUpper CString faGroup CString faProfile CString fafunction CString faPercentage bool overridePercentageCon straints

Description The lower value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. The upper value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. The Financial Advisor group the trade will be allocated to -- use an empty String if not applicable. The Financial Advisor allocation profile the trade will be allocated to -- use an empty String if not applicable. The Financial Advisor allocation function the trade will be allocated with -- use an empty String if not applicable. The Financial Advisor percentage concerning the trade's allocation -- use an empty String if not applicable. Precautionary constraints are defined on the TWS Presets page, and help ensure tha tyour price and size order values are reasonable. Orders sent from the API are also validated against these safety constraints, and may be rejected if any constraint is violated. To override validation, set this parameters value to True. Valid values include: 0 = False 1 = True

double volatility

The option price in volatility, as calculated by TWS' Option Analytics. This value is expressed as a percent and is used to calculate the limit price sent to the exchange. Values include: 1 = Daily volatility 2 = Annual volatility

int volatilityType

CString deltaNeutralOrderType int deltaNeutralAuxPrice bool continuousUpdate

VOL orders only. Enter an order type to instruct TWS to submit a delta neutral trade on full or partial execution of the VOL order. For no hedge delta order to be sent, specify NONE. VOL orders only. Use this field to enter a value if the value in the deltaNeutralOrderType field is an order type that requires an Aux price, such as a REL order. VOL orders only. Specifies whether TWS will automatically update the limit price of the order as the underlying price moves. VOL orders only. Specifies how you want TWS to calculate the limit price for options, and for stock range price monitoring. Valid values include: 1 = Average of NBBO 2 = NBB or the NBO depending on the action and right.
255

int referencePriceType

API Reference Guide

C++ SocketClient Properties

Property double trailStopPrice int scaleInitLevelSize int scaleSubsLevelSize

Description For TRAILLIMIT orders only For Scale orders: Defines the size of the first, or initial, order component. For Scale orders: Defines the order size of the subsequent scale order components. Used in conjunction with scaleInitLevelSize(). For Scale orders: Defines the price increment between scale components. This field is required. For EFP orders only For EFP orders only Use to request pre-trade commissions and margin information. If set to true, margin and commissions data is received back via the OrderState() object for the openOrder() callback.

double scalePriceIncrement double basisPoints int basisPointsType bool whatIf

OrderState

Property CString status CString initMargin CString maintMargin CString equityWithLoan double commission double minCommission

Description Displays the order status. Shows the impact the order would have on your initial margin. Shows the impact the order would have on your maintenance margin. Shows the impact the order would have on your equity with loan value. Shows the commission amount on the order. Used in conjunction with the maxCommission field, this defines the lowest end of the possible range into which the actual order commission will fall. Used in conjunction with the minCommission field, this defines the highest end of the possible range into which the actual order commission will fall. Shows the currency of the commission value. Displays a warning message if warranted.

double maxCommission

CString commissionCurrency CString warningText

API Reference Guide

256

C++ SocketClient Properties

ScannerSubscription

Property int numberOfRows CString instrument CString locationCode CString scanCode double abovePrice double belowPrice int aboveVolume double marketCapAbove double marketCapBelow CString moodyRatingAbove CString moodyRatingBelow CString spRatingAbove CString spRatingBelow CString maturityDateAbove CString maturityDateBelow double couponRateAbove double couponRateBelow CString excludeConvertible CString scannerSettingPairs int averageOptionVolumeA bove

Description Defines the number of rows of data to return for a query. Defines the instrument type for the scan. The location. Can be left blank. Filter out contracts with a price lower than this value. Can be left blank. Filter out contracts with a price higher than this value. Can be left blank. Filter out contracts with a volume lower than this value. Can be left blank. Filter out contracts with a market cap lower than this value. Can be left blank. Filter out contracts with a market cap above this value. Can be left blank. Filter out contracts with a Moody rating below this value. Can be left blank. Filter out contracts with a Moody rating above this value. Can be left blank. Filter out contracts with an S&P rating below this value. Can be left blank. Filter out contracts with an S&P rating above this value. Can be left blank. Filter out contracts with a maturity date earlier than this value. Can be left blank. Filter out contracts with a maturity date later than this value. Can be left blank. Filter out contracts with a coupon rate lower than this value. Can be left blank. Filter out contracts with a coupon rate higher than this value. Can be left blank. Filter out convertible bonds. Can be left blank. Can leave empty. For example, a pairing "Annual, true" used on the "top Option Implied Vol % Gainers" scan would return annualized volatilities. Can leave empty.

API Reference Guide

257

C++ SocketClient Properties

Property CString stockTypeFilter

Description Values include: ALL (excludes nothing) STOCK (excludes ETFs) ETF (includes ETFs)

UnderComp

Attribute int conId double delta double price

Description The unique contract identifier specifying the security. Used for Delta-Neutral Combo contracts. The underlying stock or future delta. Used for Delta-Neutral Combo contracts. The price of the underlying. Used for Delta-Neutral Combo contracts.

API Reference Guide

258

C++ Placing a Combination Order

Placing a Combination Order

A combination order is a special type of order that is constructed of many separate legs but executed as a single transaction. Submit combo orders such as calendar spreads, conversions and straddles using the BAG security type (defined in the Contract object). The key to implementing a successful API combination order using the API is to knowing how to place the same order using Trader Workstation. If you are familiar with placing combination orders in TWS, then it will be easier to place the same order using the API, because the API only imitates the behavior of TWS. Example In this example, a customer places a BUY order for a CLK9 futures contract and a SELL order for a CLM9 futures contract. In this procedure, the customer must invoke reqContractDetails() to obtain the conId for both CLK9 and CLM9 contracts. Leg 1: Buy 1 CLK9 futures contract Leg 2: Sell 1 CLM9 futures contract Here is a summary of the steps required to place a combo order using the API:

Obtain the contract id (conId) for each leg. Get this number by invoking the reqContractDetails() method. Include each leg on the ComboLeg object by populating the related fields. Implement the placeOrder() method with the Contract and Order socket client properties.

To place this combo order 1 Get the Contract IDs for both leg definitions. Request 1 is assigned to CLK9 and Request 2 is assigned to CLM9. con1.localSymbol = "CLK9"; con1.secType = "FUT"; con1.exchange = "NYMEX"; con1.currency = "USD"; m_client->reqContractDetails(1, con1->getContract()); // request 1 con2.m_localSymbol = "CLM9"; con2.m_secType = "FUT"; con2.m_exchange = "NYMEX"; con2.m_currency = "USD"; m_client->reqContractDetails(2, con2->getContract()); // request 2 The conId values are delivered by the following event. If reqId is equal to 1, then the conid is for the CLK9 contract. If reqId is equal to 2, then the conId is for CLM9.

API Reference Guide

259

C++ Placing a Combination Order

::contractDetails( int reqId, const ContractDetails &contractDetails) { // to obtain conId for CLK9 if (reqId == 1) // to obtain conid for CLM9 if (reqId == 2) ... } 2 Assign all the related values for combo orders and combine them: leg1.conId = Leg1_conId; leg1.ratio = 1; leg1.action = "BUY"; leg1.exchange = "NYMEX"; leg1.openClose = 0; leg1.shortSaleSlot = 0; leg1.designatedLocation = ""; leg2.conId = Leg2_conId; leg2.ratio = 1; leg2.action = "SELL"; leg2.exchange = "NYMEX"; leg2.openClose = 0; leg2.shortSaleSlot = 0; leg2.designatedLocation = ""; 3 Invoke the placeOrder() method with the appropriate contract and order objects. As shown below, it includes the addAllLegs declaration in the contract object. contract.symbol = "USD"; // abitrary value only combo orders contract.secType = "BAG"; // BAG is the security type for COMBO order contract.exchange = "NYMEX"; contract.currency = "USD"; contract.comboLegs = addAllLegs; //including combo order in contract object order.m_action = "BUY"; order.m_totalQuantity = 1; order.m_orderType = "MKT"; m_client->placeOrder(Orderid, contract->getContract(), order->getOrder()); Note: For more information on combination orders, see the TWS Users Guide topics About Combination Orders and Notes on Combination Orders.

API Reference Guide

260

Java
This chapter describes the Java API, including the following topics:

5
Linking to TWS using the Java API Running the Java Test Client Sample Program Java Test Client Overview Java API Overview Java EClientSocket Methods Java EWrapper Methods Java SocketClient Properties Placing a Combination Order

API Reference Guide

261

Java Linking to TWS using the Java API

Linking to TWS using the Java API

To link to TWS using the Java API 1 2 3 Import com.ib.client.* into your source code file. Implement the EWrapper interface. This class will receive messages from the socket. Override the following methods: Ewrapper Method tickPrice() tickSize() tickOptionComputation() tickGeneric() tickString() tickEFP() orderStatus() openOrder() error() connectionClosed() updateAccountValue() updateAccountTime() updatePortfolio() nextValidId() contractDetails() contractDetailsEnd() bondContractDetails() exectDetails() updateMktDepth() updateMktDepthL2() updateNewsBulletin() managedAccounts() receiveFA() historicalData() Receives order status. Receives open orders. Receives error information. Notifies when TWS terminates the connection. Receives current account values. Receives the last time account information was updated. Receives current portfolio information. Receives the next valid order ID upon connection. Receives contract information. Identifies the end of a given contract details request. Receives bond contract information. Receives execution report information. Receives market depth information. Receives Level II market depth information. Receives IB news bulletins. Receives a list of Financial Advisor (FA) managed accounts. Receives FA configuration information. Receives historical data results. Description Handles market data.

API Reference Guide

262

Java Linking to TWS using the Java API

Ewrapper Method scannerParameters()

Description Receives an XML document that describes the valid parameters of a scanner subscription. Receives market scanner results. Receives real-time bars. Receives the current system time on the server. Receives Reuters global fundamental market data.

scannerData() realTimeBar() currentTime() fundamentalData()

4 5

Instantiate the EClientSocket class. This object will be used to send messages to TWS. Call the following methods: EClientSocket Method eConnect() eDisconnect() reqMktData() cancelMktData() reqMktDepth() cancelMktDepth() reqContractDetails() placeOrder() cancelOrder() reqAccountUpdates() reqExecutions() reqOpenOrders() Description Connects to TWS. Disconnects from TWS. Requests market data. Cancels market data. Requests market depth. Cancels market depth. Requests contract details. Places an order. Cancels an order. Requests account values, portfolio, and account update time information. Requests a list of the days execution reports. Requests a list of current open orders for the requesting client and associates TWS open orders with the client. The association only occurs if the requesting client has a Client ID of 0. Requests a list of all open orders. Automatically associates a new TWS with the client. The association only occurs if the requesting client has a Client ID of 0. Requests IB news bulletins. Cancels IB news bulletins. Sets the level of API request and processing logging. Requests a list of Financial Advisor (FA) managed account codes.
263

reqAllOpenOrders() reqAutoOpenOrders()

reqNewsBulletin() cancelNewsBulletins() setServerLogLevel() reqManagedAccts()

API Reference Guide

Java Linking to TWS using the Java API

EClientSocket Method requestFA() replaceFA() reqScannerParameters()

Description Requests FA configuration information from TWS. Modifies FA configuration information from the API. Requests an XML document that describes the valid parameters of a scanner subscription. Requests market scanner results. Cancels a scanner subscription. Requests historical data. Cancels historical data. Requests real-time bars. Cancels real-time bars. Exercises options. Requests the current server time. Returns the version of the TWS instance to which the API application is connected. Returns the time the API application made a connection to TWS. Requests Reuters global fundamental data. There must be a subscription to Reuters Fundamental set up in Account Management before you can receive this data. Cancels Reuters global fundamental data.

reqScannerSubscription() cancelScannerSubscription() reqHistoricalData() cancelHistoricalData() reqRealTimeBars() cancelRealTimeBars() exerciseOptions() reqCurrentTime() serverVersion()

TwsConnectionTime() reqFundamentalData()

cancelFundamentalData()

API Reference Guide

264

Java Running the Java Test Client Sample Program

Running the Java Test Client Sample Program

You can access the IB trading system via TWS or the IB Gateway through a Java application using the socket client component. Before you can connect to TWS, you must:

Install the socket client component and sample programs. If you are using TWS, configure it to support the API components. Have NetBeans with the J2SE development kit installed on your PC. You can download the bundle at the Sun Website, or NetBeans at netbeans.org.

To run the Java Test Client sample program on Windows 1 2 From Windows Explorer, navigate to the Jts:\Java folder. Run the file run.bat.

To run the Java Test Client sample program from a new project in NetBeans 1 2 3 4 Open NetBeans and click New Project to start the wizard. In the Projects area, select Java Application and click Next. In the New Java Application window, name your project, choose a location, and uncheck the check box for Create Main Class. Click Finish.

API Reference Guide

265

Java Running the Java Test Client Sample Program

To set up Java to use the API, right-click SampleJavacode and select Properties.

6 7

From the source category click Add Folder. Navigate to the folder where the TWS API is installed. The folders you want to add are called Java\com and Java\TestJavaClient. Click OK.

API Reference Guide

266

Java Running the Java Test Client Sample Program

Press F6 to run the sample java project. When the message says "Project Samplejavacode does not have main class set" select TestJavaclient.Main and click OK.

API Reference Guide

267

Java Running the Java Test Client Sample Program

The Java Test Clients sample application window is pictured below.

API Reference Guide

268

Java Java Test Client Overview

Java Test Client Overview

This section describes the package, classes and methods used in the Java Test Client, the sample Java program included in the TWS API. Note: The classes and methods used in the Java Test Client were developed for the sample program and are not part of the TWS Java API.

Package The Java Test Client includes the package TestJavaClient. This package includes all the classes and methods required by the Java Test Client sample program.

TestJavaClient Classes
TestJavaClient includes the following classes: Class AccountDlg Description Defines the Account/Portfolio dialog, which the Java Test Client sample program uses to display a customers account and portfolio information. Defines the Account Updates dialog, which the Java Test Client sample program uses to let FA customers subscribe to account updates. Defines the Combination Legs dialog, which the Java Test Client sample program uses to let customers add and remove combo legs. Defines the Connect dialog, which the Java Test Client sample program uses to let customers connect to TWS Defines the Execution Report Filter dialog, which the Java Test Client sample program uses to let customers enter filter criteria for execution reports. Defines the Extended Order Info dialog, which the Java Test Client sample program uses to let customers enter values for extended order attributes. Defines the FA Allocation Info dialog, which the Java Test Client sample program uses to let Financial Advisor customers enter information about allocation profiles and account groups. Defines the Financial Advisor dialog, which Financial Advisor customers use in the Java Test Client sample program. Defines the Log Configuration dialog, which the Java Test Client sample program uses to let customers specify the level of log entries in the log file.

AcctUpdatesDlg

ComboLegDlg

ConnectDlg

ExecFilterDlg

ExtOrdDlg

FAAllocationInfoDlg

FinancialAdvisorDlg

LogConfigDlg

API Reference Guide

269

Java Java Test Client Overview

Class MktDepthDlg

Description Defines the Market Depth dialog, which the Java Test Client sample program uses to let customers view market depth for a specified contracts. Defines the IB News Bulletin Subscription dialog, which the Java Test Client sample program uses to let customers subscribe and unsubscribe to news bulletins. Defines the Sample dialog, which the Java Test Client sample program uses to let customers enter contract and order information for orders and requests for contract data, market depth, market data, options exercise, and historical data queries. Defines the Java Test Client sample program main window. All of the text panels and buttons on the main window are defined in this class. Defines the Market Scanner dialog (also called the Sample dialog in the test client), which the Java Test Client sample program uses to let customers subscribe and unsubscribe to markets scans, as well as request market scan parameters.

NewsBulletinDlg

OrderDlg

SampleFrame

ScannerDlg

Note:

For more information about the Java code in the Java Test Client sample program, see the Getting Started with the TWS Java API guide.

API Reference Guide

270

Java Java API Overview

Java API Overview

The TWS Java API contains the package com.ib.client, which contains the following classes: Class EWrapper ComboLeg Contract ContractDetails EClientSocket Execution ExecutionFilter Order OrderState ScannerSubscription TickType Description This interface is responsible for receiving messages from TWS. This class contains attributes used to describe combo legs. This class contains attributes used to describe a contract. This class contains attributes used to describe contract details, including bond information. This class is responsible for sending messages to TWS. This class contains attributes used to describe a trade. This class contains attributes used to describe execution filter criteria. This class contains attributes used to describe an order. This class contains attributes used to describe the status of an order. This class contains attributes used to describe the elements of a market scan. This class defines the generic tick types and their tick values.

The methods and attributes of these classes are described in the rest of this chapter.

API Reference Guide

271

Java Java EClientSocket Methods

Java EClientSocket Methods

This section describes the class EClientSocket methods you can use when connecting to TWS. The list of methods includes: Connection and Server EClientSocket() eConnect() eDisconnect() isConnected() setServerLogLevel() reqCurrentTime() serverVersion() TwsConnectionTime() Market Data reqMktData() cancelMktData() calculateImpliedVolatility() cancelCalculateImpliedVolatility() calculateOptionPrice() cancelCalculateOptionPrice() Orders placeOrder() cancelOrder() reqOpenOrders() reqAllOpenOrders() reqAutoOpenOrders() exerciseOptions() Account reqAccountUpdates() Executions reqExecutions() Contract Details reqContractDetails() Market Depth reqMktDepth() cancelMktDepth() News Bulletins reqNewsBulletins() cancelNewsBulletins() Financial Advisors reqManagedAccts() requestFA() replaceFa() Market Scanners reqScannerParameters() reqScannerSubscription() cancelScannerSubscription() Historical Data reqHistoricalData() cancelHistoricalData() Real Time Bars reqRealTimeBars() cancelRealTimeBars() Fundamental Data reqFundamentalData() cancelFundamentalData()

API Reference Guide

272

Java Java EClientSocket Methods

EClientSocket()
This is the constructor. EClientSocket(AnyWrapper anyWrapper) Parameter anyWrapper Description The reference to an object that was derived from the AnyWrapper base interface. Note EWrapper extends AnyWrapper.

eConnect()
This function must be called before any other. There is no feedback for a successful connection, but a subsequent attempt to connect will return the message "Already connected." void eConnect( String host, int port, int clientId) Parameter host port clientId Description The host name or IP address of the machine where TWS is running. Leave blank to connect to the local host. Must match the port specified in TWS on the Configure>API>Socket Port field. A number used to identify this client connection. All orders placed/modified from this client will be associated with this client identifier. Note: Each client MUST connect with a unique clientId.

eDisconnect()
Call this method to terminate the connections with TWS. Calling this method does not cancel orders that have already been sent. void eDisconnect()

isConnected()
Call this method to check if there is a connection with TWS. void isConnected()

API Reference Guide

273

Java Java EClientSocket Methods

reqMktData()
Call this method to request market data. The market data will be returned by the tickPrice(), tickSize(), tickOptionComputation(), tickGeneric(), tickString() and tickEFP() methods. void reqMktData(int tickerId, Contract contract, String genericTicklist, boolean snapshot) Parameter tickerId Description The ticker id. Must be a unique value. When the market data returns, it will be identified by this tag. This is also used when canceling the market data. This class contains attributes used to describe the contract. A comma delimited list of generic tick types. Tick types can be found in the Generic Tick Types page. Check to return a single snapshot of market data and have the market data subscription cancel. Do not enter any genericTicklist values if you use snapshot.

contract genericTicklist snapshot

cancelMktData()
After calling this method, market data for the specified Id will stop flowing. void cancelMktData(int tickerId) Parameter tickerId Description The Id that was specified in the call to reqMktData().

calculateImpliedVolatility()
Call this function to calculate volatility for a supplied option price and underlying price. calculateImpliedVolatility(int reqId, Contract optionContract, double optionPrice, double underPrice) Parameter reqId optionContract optionPrice underPrice Description The ticker id. Describes the contract. The price of the option. Price of the underlying.

API Reference Guide

274

Java Java EClientSocket Methods

cancelCalculateImpliedVolatility()
Call this function to cancel a request to calculate volatility for a supplied option price and underlying price. calculateImpliedVolatility(int reqId) Parameter reqId Description The ticker id.

calculateOptionPrice()
Call this function to calculate option price and greek values for a supplied volatility and underlying price. void calculateOptionPrice(int reqId, Contract contract, double volatility, double underPrice) Parameter conid contract volatility underPrice Description The ticker ID. Describes the contract. The volatility. Price of the underlying.

cancelCalculateOptionPrice()
Call this function to cancel a request to calculate the option price and greek values for a supplied volatility and underlying price. cancelCalculateOptionPrice(int reqId) Parameter reqId Description The ticker id.

placeOrder()
void placeOrder( int id, Contract contract, Order order) Parameter id Description The order Id. You must specify a unique value. When the order status returns, it will be identified by this tag. This tag is also used when canceling the order. This class contains attributes used to describe the contract. This structure contains the details of the order. Note: Each client MUST connect with a unique clientId.

contract order

cancelOrder()
Call this method to cancel an order.

API Reference Guide

275

Java Java EClientSocket Methods

void cancelOrder(int id) Parameter id Description The order Id that was specified previously in the call to placeOrder()

reqOpenOrders()
Call this method to request any open orders that were placed from this API client. Each open order will be fed back through the openOrder() and orderStatus() methods on the EWrapper. Note: The client with a clientId of "0" will also receive the TWS-owned open orders. These orders will be associated with the client and a new orderId will be generated. This association will persist over multiple API and TWS sessions.

void reqOpenOrders()

reqAccountUpdates()
Call this function to start getting account values, portfolio, and last update time information. The account data will be fed back through the updateAccountTime(), updateAccountValue() and updatePortfolio() EWrapper methods. void reqAccountUpdates (boolean subscribe, String acctCode) Parameter subscribe Description If set to TRUE, the client will start receiving account and portfolio updates. If set to FALSE, the client will stop receiving this information. The account code for which to receive account and portfolio updates.

acctCode

reqExecutions()
When this method is called, the execution reports that meet the filter criteria are downloaded to the client via the execDetails() method. void reqExecutions(ExecutionFilter filter) Parameter
filter

Description The filter criteria used to determine which execution reports are returned.

API Reference Guide

276

Java Java EClientSocket Methods

reqContractDetails()
Call this method to download all details for a particular contract. The contract details will be received via the contractDetails() method on the EWrapper. void reqContractDetails (int reqId, Contract contract) Parameter reqId contract Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. This class contains attributes used to describe the contract.

reqMktDepth()
Call this method to request market depth for a specific contract. The market depth will be returned by the updateMktDepth() and updateMktDepthL2() methods. void reqMktDepth(int tickerId, Contract contract, int numRows) Parameter tickerId Description The ticker Id. Must be a unique value. When the market depth data returns, it will be identified by this tag. This is also used when canceling the market depth. This class contains attributes used to describe the contract. Specifies the number of market depth rows to return.

contract numRows

cancelMktDepth()
After calling this method, market depth data for the specified Id will stop flowing. void cancelMktDepth(int id) Parameter tickerId Description The Id that was specified in the call to reqMktDepth().

reqNewsBulletins()
Call this method to start receiving news bulletins. Each bulletin will be returned by the updateNewsBulletin() method. void reqNewsBulletins(boolean allMsgs) Parameter allMsgs Description If set to TRUE, returns all the existing bulletins for the current day and any new ones. IF set to FALSE, will only return new bulletins.

API Reference Guide

277

Java Java EClientSocket Methods

cancelNewsBulletins()
Call this method to stop receiving news bulletins. void cancelNewsBulletins()

setServerLogLevel()
The default level is ERROR. Refer to the API logging page for more details. void setServerLogLevel(int logLevel) Parameter logLevel Description Specifies the level of log entry detail used by the server (TWS) when processing API requests. Valid values include: 1 = SYSTEM 2 = ERROR 3 = WARNING 4 = INFORMATION 5 = DETAIL

reqAllOpenOrders
Call this method to request all open orders that were placed from all API clients linked to one TWS, and also from the TWS. Note that you can run up to 8 API clients from a single TWS. Each open order will be fed back through the openOrder() and orderStatus() methods on the EWrapper. Note: No association is made between the returned orders and the requesting client.

void reqAllOpenOrders()

reqAutoOpenOrders()
Call this method to request that newly created TWS orders be implicitly associated with the client. When a new TWS order is created, the order will be associated with the client and automatically fed back through the openOrder() and orderStatus() methods on the EWrapper. Note: TWS orders can only be bound to clients with a clientId of 0.

void reqAutoOpenOrders(boolean bAutoBind) Parameter bAutoBind Description If set to TRUE, newly created TWS orders will be implicitly associated with the client. If set to FALSE, no association will be made.

API Reference Guide

278

Java Java EClientSocket Methods

reqManagedAccts()
Call this method to request the list of managed accounts. The list will be returned by the managedAccounts() method on the EWrapper. Note: This request can only be made when connected to a Financial Advisor (FA) account

void reqManagedAccts()

requestFA()
Call this method to request FA configuration information from TWS. The data returns in an XML string via the receiveFA() method. void requestFA(long faDataType) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being requested. Valid values include: 1 = GROUPS 2 = PROFILE 3 = ACCOUNT ALIASES

replaceFA()
Call this method to request new FA configuration information from TWS. The data returns in an XML string via a "receiveFA" method. void replaceFA(long faDataType, string xml) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being requested. Valid values include: 1 = GROUPS 2 = PROFILE 3 = ACCOUNT ALIASES The XML string containing the new FA configuration information.

xml

API Reference Guide

279

Java Java EClientSocket Methods

reqScannerParameters()
Call the reqScannerParameters() method to receive an XML document that describes the valid parameters that a scanner subscription can have. void reqScannerParameters()

reqScannerSubscription()
Call the reqScannerSubscription() method to start receiving market scanner results through the scannerData() EWrapper method. void reqScannerSubscription(int tickerId, ScannerSubscription subscription) Parameter tickerId Description The Id for the subscription. Must be a unique value. When the subscription data is received, it will be identified by this Id. This is also used when canceling the scanner. Summary of the scanner subscription parameters including filters.

subscription

cancelScannerSubscription()
Call the cancelScannerSubscription() method to stop receiving market scanner results. void cancelScannerSubscription(int tickerId) Parameter tickerId Description The Id that was specified in the call to reqScannerSubscription().

API Reference Guide

280

Java Java EClientSocket Methods

reqHistoricalData()
Call the reqHistoricalData() method to start receiving historical data results through the historicalData() EWrapper method. void reqHistoricalData (int id, Contract contract, String endDateTime, String durationStr, String barSizeSetting, String whatToShow, int useRTH, int formatDate) Parameter tickerId Description The Id for the request. Must be a unique value. When the data is received, it will be identified by this Id. This is also used when canceling the historical data request. This class contains attributes used to describe the contract. Use the format yyyymmdd hh:mm:ss tmz, where the time zone is allowed (optionally) after a space at the end. This is the time span the request will cover, and is specified using the format: <integer> <unit>, i.e., 1 D, where valid units are: " S (seconds) " D (days) " W (weeks) " M (months)

contract endDateTime durationStr

" Y (years) If no unit is specified, seconds are used. Also, note "years" is currently limited to one. barSizeSetting Specifies the size of the bars that will be returned (within IB/TWS limits). Valid values include: Bar Size 1 sec 5 secs 15 secs 30 secs 1 min 2 mins 3 mins 5 mins 15 mins 30 mins 1 hour 1 day 1 week 1 month 3 months 1 year

API Reference Guide

281

Java Java EClientSocket Methods

Parameter whatToShow

Description Determines the nature of data being extracted. Valid values include: TRADES MIDPOINT BID ASK BID_ASK HISTORICAL_VOLATILITY OPTION_IMPLIED_VOLATILITY OPTION_VOLUME

useRTH

Determines whether to return all data available during the requested time span, or only data that falls within regular trading hours. Valid values include: 0 - all data is returned even where the market in question was outside of its regular trading hours. 1 - only data within the regular trading hours is returned, even if the requested time span falls partially or completely outside of the RTH.

formatDate

Determines the date format applied to returned bars. Valid values include: 1 - dates applying to bars returned in the format: yyyymmdd{space}{space}hh:mm:dd 2 - dates are returned as a long integer specifying the number of seconds since 1/1/1970 GMT.

Note:

For a information about historical data request limitations, see Historical Data Limitations.

cancelHistoricalData()
Call the cancelHistoricalData() method to stop receiving historical data results. void cancelHistoricalData (int tickerId) Parameter tickerId Description The Id that was specified in the call to reqHistoricalData().

API Reference Guide

282

Java Java EClientSocket Methods

reqRealTimeBars()
Call the reqRealTimeBars() method to start receiving real time bar results through the realtimeBar() EWrapper method. void reqRealTimeBars(int tickerId, Contract contract, int barSize, String whatToShow, boolean useRTH) Parameter tickerId Description The Id for the request. Must be a unique value. When the data is received, it will be identified by this Id. This is also used when canceling the historical data request. This class contains attributes used to describe the contract. Currently only 5 second bars are supported, if any other value is used, an exception will be thrown. Determines the nature of the data extracted. Valid values include: useRTH - TRADES - BID - ASK - MIDPOINT 0 = all data available during the time span requested is returned, including time intervals when the market in question was outside of regular trading hours. 1 = only data within the regular trading hours for the product requested is returned, even if the time time span falls partially or completely outside.

contract barSize whatToShow

Regular Trading Hours only. Valid values include:

cancelRealTimeBars()
Call this method to stop receiving real time bar results. void cancelRealTimeBars (int tickerId) Parameter tickerId Description The Id that was specified in the call to reqRealTimeBars().

API Reference Guide

283

Java Java EClientSocket Methods

exerciseOptions()
Call the exerciseOptions() method to exercise options. Note: SMART is not an allowed exchange in exerciseOptions() calls, and TWS does a request for the position in question whenever any API initiated exercise or lapse is attempted.

void exerciseOptions(int tickerId, Contract contract, int exerciseAction, int exerciseQuantity, String account, int override) Parameter tickerId contract exerciseAction Description The Id for the exercise request This class contains attributes used to describe the contract. this can have two values: exerciseQuantity account override 1 = exercise 2 = lapse

The number of contracts to be exercised For institutional orders. Specifies the IB account. Specifies whether your setting will override the system's natural action. For example, if your action is "exercise" and the option is not in-the-money, by natural action the option would not exercise. If you have override set to "yes" the natural action would be overridden and the out-of-the money option would be exercised. Values are: 0 = do not override 1 = override

reqCurrentTime()
Returns the current system time on the server side via the currentTime() EWrapper method.

void reqCurrentTime()

serverVersion()
Returns the version of the TWS instance to which the API application is connected. void serverVersion()

TwsConnectionTime()
Returns the time the API application made a connection to TWS. void TwsConnectionTime ()

API Reference Guide

284

Java Java EClientSocket Methods

reqFundamentalData()
Call this method to receive Reuters global fundamental data. There must be a subscription to Reuters Fundamental set up in Account Management before you can receive this data. void reqFundamentalData(int reqId, Contract contract, string reportType) Parameter reqId contract reportType Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. This structure contains a description of the contract for which Reuters Fundamental data is being requested. Identifies the report type, which is one of the following: Estimates Financial Statements Summary

cancelFundamentalData()
Call this method to stop receiving Reuters global fundamental data. void cancelFundamentalData(int reqId) Parameter reqId Description The ID of the data request.

API Reference Guide

285

Java Java EWrapper Methods

Java EWrapper Methods

This section describes the class EWrapper methods you can use when connecting to TWS. The list of methods includes: Connection and Server currentTime() error() connectionClosed() Market Data tickPrice() tickSize() tickOptionComputation() tickGeneric() tickString() tickEFP() tickSnapshotEnd() Orders orderStatus() openOrder() nextValidId() Account and Portfolio updateAccountValue() updatePortfolio() updateAccountTime() Contract Details contractDetails() contractDetailsEnd() bondContractDetails() Executions execDetails() execDetailsEnd() Market Depth updateMktDepth() updateMktDepthL2() News Bulletins updateNewsBulletin() Financial Advisors managedAccounts() receiveFA() Historical Data historicalData() Market Scanners scannerParameters() scannerData() scannerDataEnd() Real Time Bars realtimeBar() Fundamental Data fundamentalData()

API Reference Guide

286

Java Java EWrapper Methods

tickPrice()
This method is called when the market data changes. Prices are updated immediately with no delay. void tickPrice(int tickerId, int field, double price, int canAutoExecute) Parameter tickerId field Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 1 will map to bidPrice, a field value of 2 will map to askPrice, etc. price canAutoExecute 1 = bid 2 = ask 4 = last 6 = high 7 = low 9 = close

Specifies the price for the specified field Specifies whether the price tick is available for automatic execution. Possible values are: 0 = not eligible for automatic execution 1 = eligible for automatic execution

API Reference Guide

287

Java Java EWrapper Methods

tickSize()
This method is called when the market data changes. Sizes are updated immediately with no delay. void tickSize(int tickerId, int field, int size) Parameter tickerId field Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 0 will map to bidSize, a field value of 3 will map to askSize, etc. size 0 = bid size 3 = ask size 5 = last size 8 = volume

Specifies the size for the specified field

tickOptionComputation()
This method is called when the market in an option or its underlier moves. TWSs option model volatilities, prices, and deltas, along with the present value of dividends expected on that options underlier are received. void tickOptionComputation(int tickerId, int field, double impliedVol, double delta, double optPrice, double pvDividend, double gamma, double vega, double theta, double undPrice) Parameter tickerId field Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of option computation. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 13 will map to modelOptComp, etc. impliedVol delta optPrice pvDividend gamma
API Reference Guide

10 = Bid 11 = Ask 12 = Last

The implied volatility calculated by the TWS option modeler, using the specified ticktype value. The option delta value. The option price. The present value of dividends expected on the options underlier The option gamma value.
288

Java Java EWrapper Methods

Parameter vega theta undPrice

Description The option vega value. The option theta value. The price of the underlying.

tickGeneric()
This method is called when the market data changes. Values are updated immediately with no delay. void tickGeneric(int tickerId, int tickType, double value) Parameter tickerId tickType Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 46 will map to shortable, etc. The value of the specified field

value

tickString()
This method is called when the market data changes. Values are updated immediately with no delay. void tickString(int tickerId, int tickType, String value) Parameter tickerId field Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 45 will map to lastTimestamp, etc. The value of the specified field

value

tickEFP()
This method is called when the market data changes. Values are updated immediately with no delay.

API Reference Guide

289

Java Java EWrapper Methods

void tickEFP(int tickerId, int tickType, double basisPoints, String formattedBasisPoints, double impliedFuture, int holdDays, String futureExpiry, double dividendImpact, double dividendsToExpiry) Parameter tickerId field Description The ticker Id that was specified previously in the call to reqMktData() Specifies the type of price. Pass the field value into TickType.getField(int tickType) to retrieve the field description. For example, a field value of 38 will map to bidEFP, etc. Annualized basis points, which is representative of the financing rate that can be directly compared to broker rates Annualized basis points as a formatted string that depicts them in percentage form Implied futures price The number of hold days until the expiry of the EFP The expiration date of the single stock future The dividend impact upon the annualized basis points interest rate The dividends expected until the expiration of the single stock future

basisPoints formattedBasisPoint s impliedFuture holdDays futureExpiry dividendImpact dividendsToExpiry

tickSnapshotEnd()
This is called when a snapshot market data subscription has been fully handled and there is nothing more to wait for. This also covers the timeout case. void tickSnapshotEnd(int reqId) Parameter reqID Description Id of the data request.

API Reference Guide

290

Java Java EWrapper Methods

orderStatus()
This method is called whenever the status of an order changes. It is also fired after reconnecting to TWS if the client has any open orders. void orderStatus(int orderId, String status, int filled, int remaining, double avgFillPrice, int permId, int parentId, double lastFillPrice, int clientId, String whyHeld) Parameter id status Description The order Id that was specified previously in the call to placeOrder() The order status. Possible values include: PendingSubmit - indicates that you have transmitted the order, but have not yet received confirmation that it has been accepted by the order destination. NOTE: This order status is not sent by TWS and should be explicitly set by the API developer when an order is submitted. PendingCancel - indicates that you have sent a request to cancel the order but have not yet received cancel confirmation from the order destination. At this point, your order is not confirmed canceled. You may still receive an execution while your cancellation request is pending. NOTE: This order status is not sent by TWS and should be explicitly set by the API developer when an order is canceled. PreSubmitted - indicates that a simulated order type has been accepted by the IB system and that this order has yet to be elected. The order is held in the IB system until the election criteria are met. At that time the order is transmitted to the order destination as specified . Submitted - indicates that your order has been accepted at the order destination and is working. Cancelled - indicates that the balance of your order has been confirmed canceled by the IB system. This could occur unexpectedly when IB or the destination has rejected your order. Filled - indicates that the order has been completely filled. Inactive - indicates that the order has been accepted by the system (simulated orders) or an exchange (native orders) but that currently the order is inactive due to system, exchange or other issues.

filled remaining

Specifies the number of shares that have been executed. Specifies the number of shares still outstanding.

API Reference Guide

291

Java Java EWrapper Methods

Parameter avgFillPrice

Description The average price of the shares that have been executed. This parameter is valid only if the filled parameter value is greater than zero. Otherwise, the price parameter will be zero. The TWS id used to identify orders. Remains the same over TWS sessions. The order ID of the parent order, used for bracket and auto trailing stop orders. The last price of the shares that have been executed. This parameter is valid only if the filled parameter value is greater than zero. Otherwise, the price parameter will be zero. The ID of the client (or TWS) that placed the order. Note that TWS orders have a fixed clientId and orderId of 0 that distinguishes them from API orders. This field is used to identify an order held when TWS is trying to locate shares for a short sell. The value used to indicate this is 'locate'.

permId parentId lastFilledPrice

clientId

whyHeld

error()
This method is called when there is an error with the communication or when TWS wants to send a message to the client. void error(int id, int errorCode, String errorString) Parameter id errorCode errorString Description This is the orderId or tickerId of the request that generated the error. For information on error codes, see Error Codes. The textual description of the error.

This method is called when exception occurs while handling a request.

void error(Exception e) Parameter e Description The exception that occurred

This method is called when TWS wants to send an error message to the client. (V1). void error(String str) Parameter str Description This is the textual description of the error

API Reference Guide

292

Java Java EWrapper Methods

connectionClosed()
This method is called when TWS closes the sockets connection, or when TWS is shut down. void connectionClosed()

managedAccounts()
This method is called when a successful connection is made to a Financial Advisor account. It is also called when the reqManagedAccts() method is invoked. void managedAccounts(String accountsList) Parameter accountsList Description The comma delimited list of FA managed accounts.

openOrder()
This method is called to feed in open orders. void openOrder(int orderId, Contract contract, Order order, OrderState orderState ) Parameter orderId contract order orderState Description The order Id assigned by TWS. Used to cancel or update the order. The Contract class attributes describe the contract. The Order class attributes define the details of the order. The orderState attributes include margin and commissions fields for both pre and post trade data.

API Reference Guide

293

Java Java EWrapper Methods

updateAccountValue()
This method is called only when reqAccountUpdates() method on the EClientSocket object has been called. void updateAccountValue(String key, String value, String currency, String accountName) Parameter key Description A string that indicates one type of account value. There is a long list of possible keys that can be sent, here are just a few examples: value currency account CashBalance - account cash balance DayTradesRemaining - number of day trades left EquityWithLoanValue - equity with Loan Value InitMarginReq - current initial margin requirement MaintMarginReq - current maintenance margin NetLiquidation - net liquidation value

The value associated with the key. Defines the currency type, in case the value is a currency type. States the account the message applies to. Useful for Financial Advisor sub-account messages.

API Reference Guide

294

Java Java EWrapper Methods

updatePortfolio()
This method is called only when reqAccountUpdates() method on the EClientSocket object has been called. void updatePortfolio(Contract contract, int position, double marketPrice, double marketValue, double averageCost, double unrealizedPNL, double realizedPNL, String accountName) Parameter contract Description This structure contains a description of the contract which is being traded. The exchange field in a contract is not set for portfolio update. This integer indicates the position on the contract. If the position is 0, it means the position has just cleared. The unit price of the instrument. The total market value of the instrument. The average cost per share is calculated by dividing your cost (execution price + commission) by the quantity of your position. The difference between the current market value of your open positions and the average cost, or Value - Average Cost. Shows your profit on closed positions, which is the difference between your entry execution cost (execution price + commissions to open the position) and exit execution cost ((execution price + commissions to close the position) The name of the account the message applies to. Useful for Financial Advisor sub-account messages.

position marketPrice marketValue averageCost

unrealizedPNL realizedPNL

accountName

updateAccountTime()
This method is called only when reqAccountUpdates() method on the EClientSocket object has been called. void updateAccountTime(String timeStamp) Parameter timeStamp Description This indicates the last update time of the account information

nextValidId()
This method is called after a successful connection to TWS. void nextValidId(int orderId) Parameter orderId Description The next available order Id received from TWS upon connection. Increment all successive orders by one based on this Id.

API Reference Guide

295

Java Java EWrapper Methods

contractDetails()
This method is called only when reqContractDetails method on the EClientSocket object has been called. void contractDetails(int ReqId, ContractDetails contractDetails) Parameter reqID contractDetails Description The ID of the data request. Ensures that responses are matched to requests if several requests are in process. This structure contains a full description of the contract being looked up.

contractDetailsEnd()
This method is called once all contract details for a given request are received. This helps to define the end of an option chain. void contractDetailsEnd(int reqId) Parameter reqID Description The Id of the data request.

bondContractDetails()
This method is called only when reqContractDetails method on the EClientSocket object has been called for bonds. void bondContractDetails(int reqId, ContractDetails contractDetails) Parameter reqId contractDetails Description The ID of the data request. This structure contains a full description of the bond contract being looked up.

execDetails()
This method is called when the reqExecutions() method is invoked, or when an order is filled. void execDetails(int reqId, Contract contract, Execution execution) Parameter reqId contract Description The reqID that was specified previously in the call to reqExecution(). This structure contains a full description of the contract that was executed. Note: Refer to the Java SocketClient Properties page for more information.

API Reference Guide

296

Java Java EWrapper Methods

Parameter execution

Description This structure contains addition order execution details. Note: Refer to the Java SocketClient Properties page for more information.

execDetailsEnd()
This method is called once all executions have been sent to a client in response to reqExecutions(). void execDetailsEnd(int reqId) Parameter reqID Description The Id of the data request.

updateMktDepth()
This method is called when the market depth changes. void updateMktDepth(int tickerId, int position, int operation, int side, double price, int size) Parameter tickerId position operation Description The ticker Id that was specified previously in the call to reqMktDepth() Specifies the row Id of this market depth entry. Identifies how this order should be applied to the market depth. Valid values are: side 0 = insert (insert this new order into the row identified by 'position') 1 = update (update the existing order in the row identified by 'position') 2 = delete (delete the existing order at the row identified by 'position')

identifies the side of the book that this order belongs to. Valid values are: 0 = ask 1 = bid

price size

The order price. The order size.

API Reference Guide

297

Java Java EWrapper Methods

updateMktDepthL2()
This method is called when the Level II market depth changes. void updateMktDepthL2(int tickerId, int position, String marketMaker, int operation, int side, double price, int size) Parameter tickerId position marketMaker operation Description The ticker Id that was specified previously in the call to reqMktDepth() Specifies the row id of this market depth entry. Specifies the exchange hosting this order. identifies the how this order should be applied to the market depth. Valid values are: side 0 = insert (insert this new order into the row identified by 'position') 1 = update (update the existing order in the row identified by 'position') 2 = delete (delete the existing order at the row identified by 'position')

Identifies the side of the book that this order belongs to. Valid values are: 0 = ask 1 = bid

price size

The order price. The order size.

updateNewsBulletin()
This method is triggered for each new bulletin if the client has subscribed (i.e. by calling the reqNewsBulletins() method. void updateNewsBulletin(int msgId, int msgType, String message, String origExchange) Parameter msgId msgType Description The bulletin ID, incrementing for each new bulletin. Specifies the type of bulletin. Valid values include: message origExchange 1 = Reqular news bulletin 2 = Exchange no longer available for trading 3 = Exchange is available for trading

The bulletin's message text. The exchange from which this message originated.

API Reference Guide

298

Java Java EWrapper Methods

receiveFA()
This method receives previously requested FA configuration information from TWS. receiveFA(long faDataType, string xml) Parameter faDataType Description Specifies the type of Financial Advisor configuration data being received from TWS. Valid values include: xml 1 = GROUPS 2 = PROFILE 3 =ACCOUNT ALIASES

The XML string containing the previously requested FA configuration information.

historicalData()
This method receives the requested historical data results. void historicalData (int reqId, String date, double open, double high, double low, double close, int volume, int count, double WAP, boolean hasGaps) Parameter reqId date open high low close volume count Description The ticker Id of the request to which this bar is responding. The date-time stamp of the start of the bar. The format is determined by the reqHistoricalData() formatDate parameter. The bar opening price. The high price during the time covered by the bar. The low price during the time covered by the bar. The bar closing price. The volume during the time covered by the bar. When TRADES historical data is returned, represents the number of trades that occurred during the time period the bar covers The weighted average price during the time covered by the bar. Whether or not there are gaps in the data.

WAP hasGaps

API Reference Guide

299

Java Java EWrapper Methods

scannerParameters()
This method receives an XML document that describes the valid parameters that a scanner subscription can have. void scannerParameters(String xml) Parameter xml Description A document describing available scanner subscription parameters.

scannerData()
This method receives the requested market scanner data results. void scannerData(int reqId, int rank, ContractDetails contractDetails, String distance, String benchmark, String projection, String legsStr) Parameter reqId rank contractDetails distance benchmark projection legsStr Description The ID of the request to which this row is responding. The ranking within the response of this bar. This structure contains a full description of the contract that was executed. Varies based on query. Varies based on query. Varies based on query. Describes combo legs when scan is returning EFP.

scannerDataEnd()
This method is called when the snapshot is received and marks the end of one scan. void scannerDataEnd(int reqId) Parameter reqId Description The ID of the market data snapshot request being closed by this parameter.

API Reference Guide

300

Java Java EWrapper Methods

realtimeBar()
This method receives the real-time bars data results. void realtimeBar(int reqId, long time, double open, double high, double low, double close, long volume, double wap, int count) Parameter reqId time open high low close volume wap count Description The ticker ID of the request to which this bar is responding. The date-time stamp of the start of the bar. The format is determined by the reqHistoricalData() formatDate parameter. The bar opening price. The high price during the time covered by the bar. The low price during the time covered by the bar. The bar closing price. The volume during the time covered by the bar. The weighted average price during the time covered by the bar. When TRADES historical data is returned, represents the number of trades that occurred during the time period the bar covers.

currentTime()
This method receives the current system time on the server side. void currentTime(long time) Parameter time Description The current system time on the server side

fundamentalData()
This method is called to receive Reuters global fundamental market data. There must be a subscription to Reuters Fundamental set up in Account Management before you can receive this data. void fundamentalData(int reqId, String data) Parameter reqId data Description The ID of the data request. One of three XML reports: Estimates (estimates) Financial statements (finstat) Summary (snapshot)

API Reference Guide

301

Java Java SocketClient Properties

Java SocketClient Properties

The tables below define attributes for the following classes:

Execution ExecutionFilter Contract ContractDetails ComboLeg Order OrderState ScannerSubscription UnderComp

API Reference Guide

302

Java Java SocketClient Properties

Execution

Attribute int m_orderId int m_clientId String m_execId String m_time String m_acctNumber String m_exchange String m_side

Description The order id. Note: TWS orders have a fixed order id of "0." The id of the client that placed the order. Note: TWS orders have a fixed client id of "0." Unique order execution id. The order execution time. The customer account number. Exchange that executed the order. Specifies if the transaction was a sale or a purchase. Valid values are: BOT SLD

int m_shares double m_price int m_permId int m_liquidation int m_cumQty double m_avgPrice

The number of shares filled. The order execution price. The TWS id used to identify orders, remains the same over TWS sessions. Identifies the position as one to be liquidated last should the need arise. Cumulative quantity. Used in regular trades, combo trades and legs of the combo. Average price. Used in regular trades, combo trades and legs of the combo.

ExecutionFilter

Attribute int m_clientId String m_acctCode

Description Filter the results of the reqExecutions() method based on the clientId. Filter the results of the reqExecutions() method based on an account code. Note: this is only relevant for Financial Advisor (FA) accounts. Filter the results of the reqExecutions() method based on execution reports received after the specified time. The format for timeFilter is "yyyymmdd-hh:mm:ss" Filter the results of the reqExecutions() method based on the order symbol.

String m_time

String m_symbol

API Reference Guide

303

Java Java SocketClient Properties

Attribute String m_secType

Description Filter the results of the reqExecutions() method based on the order security type. Note: Refer to the Contract struct for the list of valid security types. Filter the results of the reqExecutions() method based on theorder exchange. Filter the results of the reqExecutions() method based on the order action. Note: Refer to the Order class for the list of valid order actions.

String m_exchange String m_side

API Reference Guide

304

Java Java SocketClient Properties

Contract

Attribute String m_symbol String m_secType

Description This is the symbol of the underlying asset. This is the security type. Valid values are: STK OPT FUT IND FOP CASH BAG

String m_expiry double m_strike String m_right String m_multiplier

The expiration date. Use the format YYYYMM. The strike price. Specifies a Put or Call. Valid values are: P, PUT, C, CALL. Allows you to specify a future or option contract multiplier. This is only necessary when multiple possibilities exist. The order destination, such as Smart. Specifies the currency. Ambiguities may require that this field be specified, for example, when SMART is the exchange and IBM is being requested (IBM can trade in GBP or USD). Given the existence of this kind of ambiguity, it is a good idea to always specify the currency. This is the local exchange symbol of the underlying asset. Identifies the listing exchange for the contract (do not list SMART). If set to true, contract details requests and historical data queries can be performed pertaining to expired contracts. Note: Historical data queries on expired contracts are limited to the last year of the contracts life, and are initially only supported for expired futures contracts, Description for combo legs Dynamic memory structure used to store the leg definitions for this contract. The unique contract identifier.

String m_exchange String m_currency

String m_localSymbol String m_primaryExch boolean m_includeExpired

String m_comboLegsDescrip Vector m_comboLegs int m_conId

API Reference Guide

305

Java Java SocketClient Properties

Attribute String m_secIdType

Description Security identifier, when querying contract details or when placing orders. Supported identifiers are: ISIN (Example: Apple: US0378331005) CUSIP (Example: Apple: 037833100) SEDOL (Consists of 6-AN + check digit. Example: BAE: 0263494) RIC (Consists of exchange-independent RIC Root and a suffix identifying the exchange. Example: AAPL.O for Apple on NASDAQ.)

String m_secId

Unique identifier for the secIdType.

ContractDetails

Attribute Contract m_summary String m_marketName String m_tradingClass double m_minTick String m_priceMagnifier

Description A contract summary. The market name for this contract. The trading class name for this contract. The minimum price tick. Allows execution and strike prices to be reported consistently with market data, historical data and the order price, i.e. Z on LIFFE is reported in index points and not GBP. The list of valid order types for this contract. The list of exchanges this contract is traded on. The underlying contract ID. Descriptive name of the asset. For Bonds. The nine-character bond CUSIP or the 12-character SEDOL. For Bonds. Identifies the credit rating of the issuer. A higher credit rating generally indicates a less risky investment. Bond ratings are from Moody's and S&P respectively. For Bonds. A description string containing further descriptive information about the bond. For Bonds. The type of bond, such as "CORP." For Bonds. The type of bond coupon. For Bonds. Values are True or False. If true, the bond can be called by the issuer under certain conditions. For Bonds. Values are True or False. If true, the bond can be sold back to the issuer under certain conditions.

String m_orderTypes String m_validExchanges String m_underConId String m_longName String m_cusip String m_ratings

String m_descAppend String m_bondType String m_couponType boolean m_callable boolean m_putable

API Reference Guide

306

Java Java SocketClient Properties

Attribute double m_coupon

Description For Bonds. The interest rate used to calculate the amount you will receive in interest payments over the course of the year. For Bonds. Values are True or False. If true, the bond can be converted to stock under certain conditions. For Bonds. The date on which the issuer must repay the face value of the bond. For Bonds. The date the bond was issued. For Bonds, only if bond has embedded options. For Bonds, only if bond has embedded options. For Bonds, only if bond has embedded options. For Bonds, if populated for the bond in IB's database The contract month. Typically the contract month of the underlying for a futures contract. The industry classification of the underlying/product. For example, Financial. The industry category of the underlying. For example, InvestmentSvc. The industry subcategory of the underlying. For example, Brokerage. The ID of the time zone for the trading hours of the product. For example, EST. The trading hours of the product. For example, 20090507:0700-1830,1830-2330;20090508:CLOSED. The liquid trading hours of the product. For example, 20090507:0930-1600;20090508:CLOSED.

boolean m_convertible String m_maturity String m_issueDate String m_nextOptionDate String m_nextOptionType boolean m_nextOptionPartial String m_notes String m_contractMonth String m_industry String m_category String m_subcategory String m_timeZoneId String m_tradingHours String m_liquidHours

ComboLeg

Attribute int m_conId String m_action int m_ratio

Description The unique contract identifier specifying the security. The side (buy or sell) for the leg you are constructing. Select the relative number of contracts for the leg you are constructing. To help determine the ratio for a specific combination order, refer to the Interactive Analytics section of the User's Guide. The exchange to which the complete combination order will be routed.

String m_exchange

API Reference Guide

307

Java Java SocketClient Properties

Attribute int m_openClose

Description Specifies whether the order is an open or close order. Valid values are: 0 - Same as the parent security. This is the only option for retail customers. 1 - Open. This value is only valid for institutional customers. 2 - Close. This value is only valid for institutional customers. Unknown - (3) 0 - inapplicable (i.e. retail customer or not short leg) 1 - clearing broker 2 - third party. If this value is used, you must enter a designated location.

int m_shortSaleSlot

For institutional customers only.

String m_designatedLocation

If shortSaleSlot == 2, the designatedLocation must be specified. Otherwise leave blank or orders will be rejected.

API Reference Guide

308

Java Java SocketClient Properties

Order

Attribute int m_orderId int m_clientId int m_permid String m_action long m_totalQuantity String m_orderType

Description The id for this order. The id of the client that placed this order. The TWS id used to identify orders, remains the same over TWS sessions. Identifies the side. Valid values are: BUY, SELL, SSHORT. The order quantity. Identifies the order type. Valid values are: MKT MKTCLS LMT LMTCLS PEGMKT SCALE STP STPLMT TRAIL REL VWAP TRAILLIMIT

double m_lmtPrice

This is the LIMIT price, used for limit, stop-limit and relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero. This is the STOP price for stop-limit orders, and the offset amount for relative orders. In all other cases, specify zero. The time in force. Valid values are: DAY, GTC, IOC, GTD. Identifies an OCA (one cancels all) group.

double m_auxPrice

String m_tif String m_ocaGroup

API Reference Guide

309

Java Java SocketClient Properties

Attribute int m_ocaType

Description Tells how to handle remaining orders in an OCA group when one order or part of an order executes. Valid values include: 1 = Cancel all remaining orders with block 2 = Remaining orders are proportionately reduced in size with block

3 = Remaining orders are proportionately reduced in size with no block If you use a value "with block" gives your order has overfill protection. This means that only one order in the group will be routed at a time to remove the possibility of an overfill. String m_account String m_openClose int m_origin String m_orderRef bool m_transmit The account. For institutional customers only. Specifies whether the order is an open or close order. For institutional customers only. Valid values are O, C. The order origin. For institutional customers only. Valid values are 0 = customer, 1 = firm The order reference. For institutional customers only. Specifies whether the order will be transmitted by TWS. If set to false, the order will be created at TWS but will not be sent. The order ID of the parent order, used for bracket and auto trailing stop orders. If set to true, specifies that the order is an ISE Block order. If set to true, specifies that the order is a Sweep-to-Fill order. The publicly disclosed order size, used when placing Iceberg orders.

int m_parentId boolean m_blockOrder boolean m_sweepToFill int m_displaySize

API Reference Guide

310

Java Java SocketClient Properties

Attribute int m_triggerMethod

Description Specifies how Simulated Stop, Stop-Limit and Trailing Stop orders are triggered. Valid values are: 0 - The default value. The "double bid/ask" method will be used for orders for OTC stocks and US options. All other orders will used the "last" method. 1 - use "double bid/ask" method, where stop orders are triggered based on two consecutive bid or ask prices. 2 - "last" method, where stop orders are triggered based on the last price. 3 - double last method. 4 - bid/ask method. 7 - last or bid/ask method. 8 - mid-point method.

boolean m_outsideRth boolean m_hidden

If set to true, allows orders to also trigger or fill outside of regular trading hours. If set to true, the order will not be visible when viewing the market depth. This option only applies to orders routed to the ISLAND exchange. The amount off the limit price allowed for discretionary orders. The trade's "Good After Time," format "YYYYMMDD hh:mm:ss (optional time zone)" Use an empty String if not applicable. You must enter a tif value of GTD. The trade's "Good Till Date," format is: YYYYMMDD hh:mm:ss (optional time zone) Use an empty String if not applicable. The Financial Advisor group the trade will be allocated to -- use an empty String if not applicable. The Financial Advisor allocation profile the trade will be allocated to -- use an empty String if not applicable. The Financial Advisor allocation method the trade will be allocated with -- use an empty String if not applicable. The Financial Advisor percentage concerning the trade's allocation -- use an empty String if not applicable. Values are 1 or 2. Use only when shortSaleSlot value = 2. Cancel on Fill with Block = 1 Reduce on Fill with Block = 2 Reduce on Fill without Block = 3

double m_discretionaryAmt String m_goodAfterTime

String m_goodTillDate

String m_faGroup String m_faProfile String m_faMethod

String m_faPercentage int m_shortSaleSlot String m_designatedLocation int m_ocaType

API Reference Guide

311

Java Java SocketClient Properties

Attribute int m_overridePercentageConstrai nts

Description Precautionary constraints are defined on the TWS Presets page, and help ensure tha tyour price and size order values are reasonable. Orders sent from the API are also validated against these safety constraints, and may be rejected if any constraint is violated. To override validation, set this parameters value to True. Valid values include: 0 = False 1 = True Individual = 'I' Agency = 'A', AgentOtherMember = 'W' IndividualPTIA = 'J' AgencyPTIA = 'U' AgentOtherMemberPTIA = 'M' IndividualPT = 'K' AgencyPT = 'Y' AgentOtherMemberPT = 'N'

string m_rule80A

Valid values are:

string m_settlingFirm string m_clearingAccount

Institutional only. For IBExecution customers: Specifies the true beneficiary of the order. This value is required for FUT/FOP orders for reporting to the exchange. For IBExecution customers: Valid values are: IB, Away, and PTA (post trade allocation). yes=1, no=0 Identifies a minimum quantity order type. The percent offset amount for relative orders. Trade with electronic quotes. yes = 1, no = 0 Trade with firm quotes. yes = 1, no = 0 The maximum Smart order distance from the NBBO. Valid values are: match = 1 improvement = 2

string m_clearingIntent boolean m_allOrNone int m_minQty double m_percentOffset boolean m_eTradeOnly boolean m_firmQuoteOnly double m_nbboPriceCap int m_auctionStrategy

transparent = 3 For BOX exchange only. double m_startingPrice The starting price. Valid on BOX orders only.

API Reference Guide

312

Java Java SocketClient Properties

Attribute double m_stockRefPrice

Description The stock reference price. The reference price is used for VOL orders to compute the limit price sent to an exchange (whether or not Continuous Update is selected), and for price range monitoring. The stock delta. Valid on BOX orders only. The lower value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. The upper value for the acceptable underlying stock price range. For price improvement option orders on BOX and VOL orders with dynamic management. What the price is, computed via TWSs 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. How the volatility is calculated. Daily = 1 Annual = 2

double m_delta double m_stockRangeLower

double m_stockRangeUpper

double m_volatility

int m_volatilityType

string m_ deltaNeutralOrderType

VOL orders only. Enter an order type to instruct TWS to submit a delta neutral trade on full or partial execution of the VOL order. For no hedge delta order to be sent, specify NONE. VOL orders only. Use this field to enter a value if the value in the deltaNeutralOrderType field is an order type that requires an Aux price, such as a REL order. Used for dynamic management of volatility orders. Determines whether TWS is supposed to update the order price as the underlying moves. If 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 underlying price changes. Used for dynamic management of volatility orders. Set to 1 = Average of National Best Bid or Ask, or set to 2 = National Best Bid when buying a call or selling a put; and National Best Ask when selling a call or buying a put.

int m_deltaNeutralAuxPrice

int m_continuousUpdate

int m_referencePriceType

double m_trailStopPrice int m_scaleInitLevelSize

For TRAILLIMIT orders only For Scale orders: Defines the size of the first, or initial, order component.

API Reference Guide

313

Java Java SocketClient Properties

Attribute int m_scaleSubsLevelSize

Description For Scale orders: Defines the order size of the subsequent scale order components. Used in conjunction with scaleInitLevelSize(). For Scale orders: Defines the price increment between scale components. This field is required. For EFP orders only For EFP orders only Use to request pre-trade commissions and margin information. If set to true, margin and commissions data is received back via the OrderState() object for the openOrder() callback.

double m_scalePriceIncrement

double m_basisPoints int m_basisPointsType boolean m_whatIf

OrderState

Attribute string m_status String m_initMargin String m_maintMargin String m_equityWithLoan double m_commission double m_minCommission

Description Displays the order status. Shows the impact the order would have on your initial margin. Shows the impact the order would have on your maintenance margin. Shows the impact the order would have on your equity with loan value. Shows the commission amount on the order. Used in conjunction with the maxCommission field, this defines the lowest end of the possible range into which the actual order commission will fall. Used in conjunction with the minCommission field, this defines the highest end of the possible range into which the actual order commission will fall. Shows the currency of the commission value. Displays a warning message if warranted.

double m_maxCommission

String m_commissionCurrency String m_warningText

API Reference Guide

314

Java Java SocketClient Properties

ScannerSubscription

Attribute int m_numberOfRows String m_instrument String m_locationCode String m_scanCode double m_abovePrice double m_belowPrice int m_aboveVolume double m_marketCapAbove double m_marketCapBelow String m_moodyRatingAbove String m_moodyRatingBelow String m_spRatingAbove String m_spRatingBelow String m_maturityDateAbove String m_maturityDateBelow double m_couponRateAbove double m_couponRateBelow String m_excludeConvertible String m_scannerSettingPairs

Description Defines the number of rows of data to return for a query. Defines the instrument type for the scan. The location. Can be left blank. Filter out contracts with a price lower than this value. Can be left blank. Filter out contracts with a price higher than this value. Can be left blank. Filter out contracts with a volume lower than this value. Can be left blank. Filter out contracts with a market cap lower than this value. Can be left blank. Filter out contracts with a market cap above this value. Can be left blank. Filter out contracts with a Moody rating below this value. Can be left blank. Filter out contracts with a Moody rating above this value. Can be left blank. Filter out contracts with an S&P rating below this value. Can be left blank. Filter out contracts with an S&P rating above this value. Can be left blank. Filter out contracts with a maturity date earlier than this value. Can be left blank. Filter out contracts with a maturity date later than this value. Can be left blank. Filter out contracts with a coupon rate lower than this value. Can be left blank. Filter out contracts with a coupon rate higher than this value. Can be left blank. Filter out convertible bonds. Can be left blank. Can leave empty. For example, a pairing "Annual, true" used on the "top Option Implied Vol % Gainers" scan would return annualized volatilities. Can leave empty.

int m_averageOptionVolumeAbove

API Reference Guide

315

Java Java SocketClient Properties

Attribute String m_stockTypeFilter

Description Valid values are: ALL (excludes nothing) STOCK (excludes ETFs) ETF (includes ETFs)

UnderComp

Attribute int m_conId double m_delta double m_price

Description The unique contract identifier specifying the security. Used for Delta-Neutral Combo contracts. The underlying stock or future delta. Used for Delta-Neutral Combo contracts. The price of the underlying. Used for Delta-Neutral Combo contracts.

API Reference Guide

316

Java Placing a Combination Order

Placing a Combination Order

A combination order is a special type of order that is constructed of many separate legs but executed as a single transaction. Submit combo orders such as calendar spreads, conversions and straddles using the BAG security type (defined in the Contract object). The key to implementing a successful API combination order using the API is to knowing how to place the same order using Trader Workstation. If you are familiar with placing combination orders in TWS, then it will be easier to place the same order using the API, because the API only imitates the behavior of TWS. Example In this example, a customer places a BUY order on a calendar spread for GOOG. To buy one calendar spread means: Leg 1: Sell 1 GOOG OPT SEP 18 '09 150.0 CALL (100) Leg 2: Buy 1 GOOG OPT JAN 21 '11 150.0 CALL (100) Here is a summary of the steps required to place a combo order using the API:

Obtain the contract id (conId) for each leg. Get this number by invoking the reqContractDetails() method. Include each leg on the ComboLeg object by populating the related fields. Implement the placeOrder() method with the Contract and Order socket client properties.

To place this combo order 1 Get the Contract IDs for both leg definitions: //First leg Contract con1 = new Contract(); con1.m_symbol = "GOOG"; con1.m_secType = "OPT"; con1.m_expiry = 200909; con1.m_strike = 150.0 con1.m_right = C con1.m_multiplier = 100 con1.m_exchange = "SMART; con1.m_currency = "USD"; .reqContractDetails(1, con1);

API Reference Guide

317

Java Placing a Combination Order

//Second leg Contract con2 = new Contract(); con2.m_symbol = "GOOG"; con2.m_secType = "OPT"; con2.m_expiry = 201101; con2.m_strike = 150.0 con2.m_right = C con2.m_multiplier = 100 con2.m_exchange = "SMART; con2.m_currency = "USD"; .reqContractDetails(2, con2); //All conId numbers are delivered by the ContractDetail() static public String contractDetails(int reqId, ContractDetails contractDetails) { Contract contract = contractDetails.m_summary; /*Base on the request above, reqId = 1 is corresponding to the first request or first leg reqId = 2 is corresponding to the second request or second leg*/ if (reqId == 1) { Leg1_conId = contract.m_conId;} // to obtain conId for first leg if (reqId == 2) { Leg2_conId = contract.m_conId;} // to obtain conId for second leg } 2 Once the program has acquired the conId value for each leg, include it in the ComboLeg object: ComboLeg leg1 = new ComboLeg(); // for the first leg ComboLeg leg2 = new ComboLeg(); // for the second leg Vector addAllLegs = new Vector(); leg1.m_conId = Leg1_conId; leg1.m_ratio = 1; leg1.m_action = "SELL"; leg1.m_exchange = "SMART"; leg1.m_openClose = 0; leg1.m_shortSaleSlot = 0; leg1.m_designatedLocation = "";

API Reference Guide

318

Java Placing a Combination Order

leg2.m_conId = Leg2_conId; leg2.m_ratio = 1; leg2.m_action = "BUY"; leg2.m_exchange = "SMART"; leg2.m_openClose = 0; leg2.m_shortSaleSlot = 0; leg2.m_designatedLocation = ""; addAllLegs.add(leg1); addAllLegs.add(leg2); 3 Invoke the placeOrder() method with the appropriate contract and order objects: Contract contract = new Contract(); Order order = new Order(); contract.m_symbol = "USD"; // For combo order use USD as the symbol value all the time contract.m_secType = "BAG"; // BAG is the security type for COMBO order contract.m_exchange = "SMART"; contract.m_currency = "USD"; contract.m_comboLegs = addAllLegs; //including combo order in contract object order.m_action = BUY; order.m_totalQuantity = 1; order.m_orderType = MKT .placeOrder(OrderId, contract, order); Note: For more information on combination orders, see the TWS Users Guide topics About Combination Orders and Notes on Combination Orders.

API Reference Guide

319

Java Placing a Combination Order

API Reference Guide

320

Advisors

6
Financial Advisor Orders and Account Configuration Excel DDE Support Support by Other API Technologies Improved Financial Advisor Execution Reporting Allocation Methods for Account Groups

This chapter describes API functionality for users with Financial Advisor accounts, including the following topics:

API Reference Guide

321

Advisors Financial Advisor Orders and Account Configuration

Financial Advisor Orders and Account Configuration

This section assumes familiarity on the part of the reader with TWS Financial Advisor account configuration and order placement. API FA functionality became significantly more powerful in TWS release 821 and higher, in that the now deprecated "allocation string" method was replaced by the much more powerful Financial Advisor order allocation methods. Prior to those new methods being used, TWS had to be configured to understand the desired FA order groups, profiles, and account aliases. This can be done manually in TWS, or via the API, or via both.

Excel DDE Support

Starting with TWS release 824, DDE orders now have six Extended Order Attributes: Good After Time, Good Till Date, FA Group, FA Method, FA Percentage, and FA Profile. These can be left empty if they do not apply to an order. TWS Financial Advisor account configuration should be done manually for DDE access. You can place FA orders on the Advisors page in the most recent release of the TwsDde.xls DDE for Excel API spreadsheet. For more information, see the Advisors Page topic.

Support by Other API Technologies

For all ActiveX, Java, or C++ based API technologies, TWS Financial Advisor account configuration is done via two new methods and one new event. The methods are called replaceFA, and requestFA. The event is called receiveFA. These methods and that event pertain to the following three parts of TWS FA account configuration: creating groups, profiles, and account aliases.

requestFA(int faDataType) is a method that is called by an API application to request one of those types of FA configuration data. receiveFA(int faDataType, string XML) receives the requested data from TWS, via an event that TWS sends that contains the data requested. The event includes an XML string containing the requested information. replaceFA(int faDataType, string XML) can be called from the API if the API application wishes to replace the previous FA configuration information with a new XML string.

In accordance with the existence of this new functionality, all placeOrder methods, whether ActiveX, Java, or C++ based, have four new parameters pertaining to Financial Advisor order placement: faGroup, faMethod, faPercentage, and faProfile. When one or more of these new values is not relevant to an order, simply pass in an empty string.

API Reference Guide

322

Advisors Improved Financial Advisor Execution Reporting

Improved Financial Advisor Execution Reporting

When using TWS version 823 or higher, the execution messages resulting from a new FA order will report both the initial execution of the order, as well as its being allocated to its various subaccounts. The following example will serve to explain the new reporting scheme: Assume that 100 shares of IBM is being bought on the NYSE by a Financial Advisor who has three sub-accounts, and who wants them allocated with Equal Quantity to each. The following seven execution messages will occur:

FA Account: Order filled on NYSE to BUY 100 IBM FA Account: allocation of 34 shares out of FA account and into sub account 1. Message says "BUY -34 IBM." The negative quantity reflects the fact that the execution being reported is reducing the purchase. SUB1 Account: BUY 34 IBM. FA Account: allocation of 33 shares out of FA account and into sub account 2. Message says "BUY -33 IBM." SUB2 Account: BUY 33 IBM. FA Account: allocation of 33 shares out of FA account and into sub account 3. Message says "BUY -33 IBM." SUB3 Account: BUY 33 IBM."

API Reference Guide

323

Advisors Allocation Methods for Account Groups

Allocation Methods for Account Groups

Note that you must type the method name in exactly as appears here, or your order won't work. EqualQuantity Method Requires you to specify an order size. This method distributes shares equally between all accounts in the group. Example: You transmit an order for 400 shares of stock ABC. If your Account Group includes four accounts, each account receives 100 shares. If your Account Group includes six accounts, each account receives 66 shares, and then 1 share is allocated to each account until all are distributed. NetLiq Method Requires you to specify an order size. This method distributes shares based on the net liquidation value of each account. The system calculates ratios based on the Net Liquidation value in each account and allocates shares based on these ratios. Example: You transmit an order for 700 shares of stock XYZ. The account group includes three accounts, A, B and C with Net Liquidation values of $25,000, $50,000 and $100,000 respectively. The system calculates a ratio of 1:2:4 and allocates 100 shares to Client A, 200 shares to Client B, and 400 shares to Client C. AvailableEquity Method Requires you to specify an order size. This method distributes shares based on the amount of equity with loan value currently available in each account. The system calculates ratios based on the Equity with Loan value in each account and allocates shares based on these ratios. Example: You transmit an order for 700 shares of stock XYZ. The account group includes three accounts, A, B and C with available equity in the amounts of $25,000, $50,000 and $100,000 respectively. The system calculates a ratio of 1:2:4 and allocates 100 shares to Client A, 200 shares to Client B, and 400 shares to Client C. PctChange Method This method only works when you already hold a position in the selected instrument. Do not specify an order size. Since the quantity is calculated by the system, the order size is displayed in the Quantity field after the order is acknowledged. This method increases or decreases an already existing position. Positive percents will increase a position, negative percents will decrease a position. Example 1: Assume that three of the six accounts in this group hold long positions in stock XYZ. Client A has 100 shares, Client B has 400 shares, and Client C has 200 shares. You want to increase their holdings by 50%, so you enter "50" in the percentage field. The system calculates that your order size needs to be equal to 350 shares. It then allocates 50 shares to Client A, 200 shares to Client B, and 100 shares to Client C. Example 2: You want to close out all long positions for three of the five accounts in a group. You create a sell order and enter "-100" in the Percentage field. The system calculates 100% of

API Reference Guide

324

Advisors Allocation Methods for Account Groups

each position for every account in the group that holds a position, and sells all shares to close the positions. These handy charts make it easy to see how negative and positive percent values will affect long and short positions for both buy and sell orders. Phew, that was a mouthful! BUY ORDER Long Position Short Position Positive Percent Increases position No effect Negative Percent No effect Decreases position

SELL ORDER Long Position Short Position

Positive Percent No effect Increases position

Negative Percent Decreases position No effect

API Reference Guide

325

Advisors Allocation Methods for Account Groups

API Reference Guide

326

ActiveX for Excel

This chapter describes the ActiveX for Excel sample spreadsheet, including the following topics: Getting Started with the ActiveX for Excel API Using the ActiveX for Excel Sample Spreadsheet

The ActiveX for Excel sample spreadsheet, TwsActiveX.xls, duplicates the functionality of the ActiveX for Excel API spreadsheet but internally uses an ActiveX component, Tws.ocx. One of the benefits of using this spreadsheet is that it can connect to a TWS or IB Gateway session that is running on a remote PC. The DDE for Excel API spreadsheet cannot do this. The methods, events and COM objects used in the code for the ActiveX for Excel sample spreadsheet are the same as those used in the ActiveX API. See the ActiveX chapter for complete details about the ActiveX API. The following figure shows the Tickers page in the ActiveX for Excel API sample spreadsheet.

API Reference Guide

327

ActiveX for Excel Getting Started with the ActiveX for Excel API

Getting Started with the ActiveX for Excel API

We have created a sample Excel spreadsheet, TwsActiveX.xls, that uses an ActiveX control, Tws.ocx. You can use this spreadsheet with TWS as is, or use it create your own custom TWS API Excel application. It's easy to get started:

Download the API components, which includes the ActiveX for Excel sample spreadsheet, TwsActiveX.xls. Ensure that either: the application server is running and that it is configured to support ActiveX or the IB Gateway is running.

Open the spreadsheet and start using the ActiveX for Excel API.

The sample spreadsheet currently comprises several pages complete with sample data and action buttons that make it easy for you to get market data, send orders and view your activity.

Download the API Components and Spreadsheet

We recommending using the sample Excel spreadsheet that we provide as a starting point toward creating your own ActiveX for Excel API. Follow the steps below to download the sample spreadsheet. To install the ActiveX for Excel sample spreadsheet 1 2 From the IB homepage, select API Solutions from the Software menu. Click the IB API icon, and on the API Software page, find the column appropriate to your operating system, click Download latest version. Note: Windows users can download the beta test version of the API by using the Windows Beta column, or revert to the previous production version by selecting Downgrade to Previous Version.

3 4 5 6

Save the installation program to your computer, and if desired, select a different directory. Click Save. Close any versions of TWS and Excel that you have running. Locate the installation program you just saved to your computer, then double-click the file to begin the API installation. Follow the instructions in the installation wizard.

Before you can use the spreadsheet, you must have TWS running and configured to support the ActiveX API. See Run the API through TWS for detailed instructions.

API Reference Guide

328

ActiveX for Excel Getting Started with the ActiveX for Excel API

Running the ActiveX for Excel API on 64-bit Windows XP Systems

To run the ActiveX for Excel API on 64-bit Windows XP systems, do the following: 1 2 3 Install Microsoft Visual C++ 2005 SP1 Redistributable Package (x86). Install Microsoft Visual J# 2.0 Redistributable Package. Download and install the API software.

Open the Sample Spreadsheet

After you have downloaded the sample spreadsheet and configured the application to allow the ActiveX for Excel API to link to it, open the spreadsheet and save it as your personal file. Note:
Note that not more than one API application can simultaneously access a single instance. The API application does not need to be running on the same computer on which the application is running.

To open the sample spreadsheet 1 2 3 4 Go to the API installation folder in which the Excel API sample spreadsheet was installed (typically C:\Jts\Excel) and double-click TwsActiveX.xls. Save the spreadsheet with a different file name. This lets you customize the spreadsheet without changing the original. Click the General tab. Modify the default values in the Host, Port, and ClientID cells, then click Connect to TWS on the Toolbar.

If you select the Show Errors Message Box check box, error messages display when you connect to TWS. In this case, you must click OK to dismiss any messages that appear.

API Reference Guide

329

ActiveX for Excel Using the ActiveX for Excel Sample Spreadsheet

Using the ActiveX for Excel Sample Spreadsheet

The ActiveX for Excel API sample spreadsheet, TwsDde.xls, includes the following pages (tabs): Page General Tickers Description Lets you connect to and disconnect from TWS, set the server log level and request the current time. Lets you set up your ticker lines and request market data. You can view market data for all asset types including EFPs and combination orders. Lets you subscribe to and view IB News Bulletins. Lets you view market depth for selected quotes. Lets you send and modify orders, set up combination orders and EFPs, and request open orders. Lets you create an order whose submission is contingent on other conditions being met, for example an order based on a prior fill. Lets you send and modify advanced orders types that require the use of extended order attributes, such as Bracket, Scale and Trailing Stop Limit orders. Used in conjunction with the Basic Orders, Advanced Orders, Conditional Orders and Advisors pages, this page lets you change the time in force, create Hidden or Iceberg orders and apply many other order attributes. Shows you all transmitted orders, including those that have been accepted by the IB system, and those that are working at an exchange. Provides up to date account information and displays your portfolio. Displays all your current positions. Lets you view all execution reports, and includes a filtering box so you can limit your results. Request historical data for an instrument based on data you enter in a query. Lets you collect contract-specific information you will need for other actions, including the conid and supported order types for a contract Lets you collect bond contract-specific information you will need for other actions, including bond coupon and maturity date. Lets you request and view real time bars from TWS. Lets you view market scanner parameters and subscribe to TWS market scanners. Lets you request and view Fundamentals data from TWS. Lets Financial Advisors send and modify FA orders. Lets you view all error messages.
330

Bulletins Market Depth Basic Orders Conditional Orders Advanced Orders

Extended Order Attributes

Open Orders

Account Portfolio Executions Historical Data Contract Details

Bond Contract Details

Real Time Bars Market Scanner Fundamentals Advisors Log

API Reference Guide

ActiveX for Excel General Page

General Page
Use the General page to:

Connect to TWS. Disconnect from TWS. Set the level of log entry detail used by the server when processing API requests. Request the current server time.

API Reference Guide

331

ActiveX for Excel General Page

To connect to TWS 1 Click Connect to TWS in the toolbar.

If required, change the values in the Host, Port and ClientID cells. Select the Show Errors Message Box to display errors when connecting to TWS.

To disconnect from TWS 1 Click Disconnect from TWS in the toolbar.

To set the server log level 1 Type one of the following values in the Log Level cell:

1 = SYSTEM 2 = ERROR 3 = WARNING 4 = INFORMATION 5 = DETAIL

The higher the number, the greater the level of detail and performance overhead.

Click Set Server Log Level in the toolbar.

API Reference Guide

332

ActiveX for Excel General Page

To request the current time 1 Click Request Current Time in the toolbar.

General Page Toolbar Buttons

The toolbar on the General page includes the buttons described below. Button Connect to TWS Disconnect from TWS Set Server Log Level Request Current Time Description Connects to TWS. Disconnects from TWS. Sets the level of detail of entries in the log.txt log file. Requests the current server time.

The toolbar also includes the Show Errors Message Box check box, which when selected, displays error when connecting to TWS.

API Reference Guide

333

ActiveX for Excel Tickers Page

Tickers Page
Use the Tickers page to:

Create market data (ticker) lines. Request market data. Create a combination order for options. Create market data line for Exchange for Physical (EFP) combination orders.

Using the Tickers Page

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To create a ticker using the Create Ticker button 1 2 Click the Tickers tab at the bottom of the spreadsheet. Click the line number to the left of a blank row to select the row. You must have a blank row selected to create a ticker line.

API Reference Guide

334

ActiveX for Excel Tickers Page

3 4

Click the Create Ticker button on the toolbar and enter information in the Create Tickers dialog. Click OK. For stocks, you only need to specify the Symbol, Type, Exchange (usually SMART), and Currency.

To create a ticker on the spreadsheet 1 2 Select a blank cell in the Symbol column and enter a symbol. Tab through the all contract description fields and enter data where necessary, for example if you are entering a stock ticker, you don't need values in the Expiry, Strike, P/C and Multiplier fields. Note: The Exchange field accepts the following values: SMART (for smart order routing), and any valid exchange acronym.

To request market data for a ticker 1 2 3 4 Select the ticker row for which you want to request market data by clicking the row number. Enter a comma-separated list of generic tick values in the Generic Tick List cell. For details about generic tick values, see Generic Tick Types. Optionally, click the Snapshot check box to request a single snapshot of market data. Click Request Market Data on the toolbar. To get market data for a group of tickers, select multiple ticker rows while holding down the Shift key, then click Request Market Data multiple times until all rows are showing data.

API Reference Guide

335

ActiveX for Excel Tickers Page

To set the refresh rate The market data refresh rate determines how often the link to TWS is refreshed.

Enter the refresh rate value (in whole numbers, in seconds) in the Market Data Refresh Rate cell.

TWS market data updates every 3 seconds by default.

Tickers Page Toolbar Buttons

The toolbar on the Tickers page includes the buttons described below. Button Create Ticker Combo Legs Request Market Data Cancel Market Data Clear Market Data Description Opens the Ticker box. Enter information to create a market data line. Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. Select a line and click to get market data for the selected contract. Cancel market data for the selected ticker. Clears all market data from the page.

The toolbar also includes the Snapshot check box, which when selected, requests only a single snapshot of market data.

API Reference Guide

336

ActiveX for Excel Bulletins Page

Bulletins Page
Use the Bulletins page to request and view IB news bulletins. Simply click Request News Bulletins in the toolbar. News bulletins display in the table on the page. To request all the existing bulletins for the current day and any new ones, select the All Day News check box on the toolbar. If this check box is not selected, you will receive only new bulletins.

Bulletins Page Toolbar Buttons

The toolbar on the Tickers page includes the buttons described below. Button Request News Bulletins Cancel News Bulletins Clear News Bulletins Description Requests all the new news bulletins. Cancels receipt of all news bulletins. Clears all news bulletins from the page.

The toolbar also includes the All Day News check box, which when selected, requests all the existing bulletins for the current day and any new ones.

API Reference Guide

337

ActiveX for Excel Market Depth Page

Market Depth Page

Use the Market Depth page to view market depth for selected contracts. You can also view market depth for NYSE-listed products through the Open Book Market Data Subscription, and NASDAQ-listed products through the TotalView Market Data Subscriptions, if you have signed up for those subscriptions.

API Reference Guide

338

ActiveX for Excel Market Depth Page

Using the Market Depth Page

Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To request market depth for a contract 1 2 3 Click the Market Depth tab at the bottom of the spreadsheet to open the Market Depth page. Select the ticker symbol for which you want to request the market depth, or enter a new ticker on a blank line. Click the Request Market Depth button on the toolbar.

To reset the market data refresh rate for market depth 1 Type the desired market data refresh rate in seconds in the Market Depth Refresh Rate cell. The value must be in whole numbers from 1 to 9.

Market Depth Page Toolbar Buttons

The toolbar on the Market Depth page includes the following buttons: Button Request Market Depth Cancel Market Depth Clear Market Depth Description View bid/ask depth prices for the selected contract. Cancel market depth for the selected contract. Clears all market depth data from the page.

The page also includes a Market Depth Refresh Rate cell, which lets you rest the market depth refresh rate in seconds, in whole numbers from 1 - 9. The default refresh rate is 3 seconds.

API Reference Guide

339

ActiveX for Excel Basic Orders Page

Basic Orders Page

Use the Basic Orders page to:

Create an order. Place a what if order, which shows you the margin and commission information before you place an order. Create a "basket" of orders. Modify and cancel orders. Create combination orders.

API Reference Guide

340

ActiveX for Excel Basic Orders Page

Placing Orders
This topic describes how to place the following types of orders on the Orders page:

Simple orders Basket orders Modified orders Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

Note:

To place an order 1 2 3 Click the Basic Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields. You must define the Action (Buy, Sell or Short Sell), Quantity, Order Type, Limit Price (unless it's a market order) and if necessary, the Aux. Price for order types that require it. 4 If desired, select the contract (the ticker row) and apply extended order attributes by clicking the Apply Extended Template button on the toolbar. This applies all attributes you have defined on the Extended Order Attributes page to the selected contract. Click the Place/Modify Order button on the toolbar.

To place a "basket" of orders 1 2 3 4 5 Click the Basic Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using fields in the Order Description section. Repeat Steps 1 and 2 for additional orders. Select a group of orders.

To select a group of contiguous orders, highlight the first order, hold down the Shift key, then highlight the last order of the group. To select a group of non-contiguous orders, hold the Ctrl key down as you select each order.

Click the Place/Modify Order button.

API Reference Guide

341

ActiveX for Excel Basic Orders Page

To modify an order (or group of orders) 1 2 On the Basic Orders page, change any necessary parameters in an order or group of orders. Select the order or a group of orders.

To select a group of contiguous orders, highlight the first order, hold down the Shift key, then highlight the last order of the group. To select a group of non-contiguous orders, hold the Ctrl key down as you select each order.

Click the Place/Modify Order button.

Placing a Combination Order

A combination order is a special type of order that is constructed of many separate legs but executed as a single transaction. To buy a calendar spread, you would:

Buy 1 OPT JUL03 17.5 CALL (100) Sell 1 OPT AUG03 17.5 CALL (100)

To create a calendar spread order The following example walks you through the process of placing a hypothetical calendar spread order for XYZ on ISE.

API Reference Guide

342

ActiveX for Excel Basic Orders Page

Use the Contract Details page to get the contract id for both of the leg definitions.

The conid for XYZ option JUL08 17.5 CALL on ISE is "12345678". The conid for XYZ option AUG08 17.5 CALL on ISE is "12345679".

Click the Basic Orders tab to build the combo leg definitions. Click the Combo Legs button on the Basic Orders page toolbar and enter leg information. Your leg information is translated into the format: [CMBLGS]_[NumOfLegs]_[Combo Leg Definitions]_[CMBLGS] where:

[CMBLGS] is the delimiter used to identify the start and end of the leg definitions [NumOfLegs] is the number of leg definitions [Combo Leg Definitions] defines N leg definitions, and each leg definition consists of [conid]_[ratio]_[action]_[exchange]_[openClose], so the resulting combo substring looks as follows: CMBLGS_2_17496957_1_BUY_EMPTY_0_15910089_1_SELL_EMPTY_0_CMBL GS

The combination leg definitions must occur before the extended order attributes. The full place order DDE request string will look like this: =acctName|ord!id12345?place?BUY_1_XYZ_BAG_ISE_LMT_1_CMBLGS_2_1234 5678_1_BUY_EMPTY_0_12345679_1_SELL_EMPTY_0_CMBLGS_DAY_EMPTY_0_O_0 _EMPTY_0_EMPTY_0_0_0EMPTY_0_0 If the order legs do not constitute a valid combination, one of the following errors will be returned:

312 = The combo details are invalid. 313 = The combo details for '<leg number>' are invalid. 314 = Security type 'BAG' requires combo leg details. 315 = Stock combo legs are restricted to SMART exchange.

Notes:

1. The exchange for the leg definition must match that of the combination order. The exception is for a STK leg definition, which must specify the SMART exchange. 2. The openClose leg definition value is always 'SAME' (i.e.0) for retail accounts. For institutional accounts, the value may be any of the following: (SAME, OPEN, CLOSE).

API Reference Guide

343

ActiveX for Excel Basic Orders Page

Supported Order Types

The order types currently supported through the ActiveX for Excel API are:

Limit (LMT) Market (MKT) Limit if Touched (LIT) Market if Touched (MIT) Market on Close (MOC) Limit on Close (LOC) Pegged to Market (PEGMKT) Relative (REL) Stop (STP) Stop Limit (STPLMT) Trailing Stop (TRAIL) Trailing Stop Limit (TRAILLIMIT) Volume-Weighted Average Price (VWAP) Volatility orders (VOL)

Basic Orders Page Toolbar Buttons

The toolbar on the Basic Orders page includes the following buttons: Button Create Ticker Combo Legs Description Opens the Ticker box. Enter information to create a market data line. Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. You can also enter Delta Neutral information. Applies the current values on the Extended Order Attributes page to the highlighted order row. After you have completed the Order Description fields, and defined any extended attributes, click to create an order for the selected contract. This button cancels the selected order(s). Clears all order status information from the page.

Apply Extended Template Place/Modify Orders

Cancel Order Clear Order Statuses

There is also a WhatIf check box on the toolbar. When checked, you will receive margin and commission data as if the order were placed, but the order will NOT be placed.

API Reference Guide

344

ActiveX for Excel Conditional Orders Page

Conditional Orders Page

Use the Conditional Orders page to create an order whose submission is contingent on other conditions being met, for example, an order based on a prior fill or a change in the bid or ask price. To see the Conditional Statement fields (in blue), use the scroll bar on the bottom of the page to scroll to the right.

Setting Up Conditional Orders

Note: Ensure that TWS is running, and that you have entered your user name in the User Name field in the Which Trader Workstation? section of all pages in the Excel spreadsheet to properly connect to TWS.

To set up a conditional order 1 On the Conditional Orders page, first create the order you want transmitted when a condition is met by defining the contract in the Contract Description fields, and then using the Order Description area to set up the order parameters. In the blue Condition Statements area, use the Statement field to set the criteria which must be met to trigger the order. When the Statement = TRUE, your order will be submitted. The sample spreadsheet includes a pair of orders, with the second orders transmission depending on the first order being completely filled. In this case, the Statement field

API Reference Guide

345

ActiveX for Excel Conditional Orders Page

trigger is that the value in cell T10 (the Filled field) must be equal to the value in M10 (the order Quantity field). 3 4 Type ADD in the ADD/MOD field because you are creating a one-time order. Define the remaining order parameters just as you did in the Order Description area.

Complete the necessary fields on the Conditional Orders page according to the syntax in the following table. Description An Excel function which returns a true or false. When true, the order will be submitted; when false, nothing happens. Use ADD for a one-time order. Use MOD to continue checking and modifying the order until it is completely filled. This is the field that activates a conditional order, and orders will be activated only with the "ADD" or "MOD" tags. BUY SELL Enter the quantity of the order. Refer to list of supported order types. The limit price for Limit and Stop Limit order types. The stop-election price for Stop and Stop Limit order types, or the offset for relative orders.

Field Statement ADD/MOD

Action Quantity Order Type Lmt Price Aux. Price

All of the fields described above may be variables that depend on other cells, so any type of conditional order may be created.

Conditional Order Examples

If-Filled order An if-filled order is an order that executes if a prior order executes. To create an if-filled order with the condition "If a Buy order fully executes, enter a sell limit order at a price of $50.00": Field Statement ADD/MOD Action Quantity Value Filled cell = 100 ADD SELL 100

API Reference Guide

346

ActiveX for Excel Conditional Orders Page

Field Order Type Lmt Price Aux. Price Price-change order

Value LMT 50 empty

A price-change order will be triggered if a specific bid or ask price is greater than, less than or equal to a specific price. To create a price change order with the condition "If the bid price drops below 81.20, submit a buy limit order for 200 shares with a limit price of $81.10: Field Statement Value On the Tickers page, put your cursor in the bid price field you want to use, then copy the value that appears in the formula bar (= entry field) at the top of the spreadsheet. This value looks something like this: =username|tik!id4?bid where "4" identifies the bid price for a specific contract. Paste this in the formula bar ("=" entry field) for the Statement, and add your qualifier, "=" ">" or "<" followed by the price. In this example, the formula would be: =username|tik!id4?bid<81.20 ADD BUY 200 LMT 81.10 Not used in this example.

ADD/MOD Action Quantity Order Type Lmt Price Aux. Price

To modify an order (or basket of orders) 1 Select the order or a group of orders.

To select a group of contiguous orders, highlight the first order, hold down the Shift key, then highlight the last order of the group. To select a group of non-contiguous orders, hold the Ctrl key down as you select each order.

2 3

Click the Place/Modify Order button. Change any necessary parameters, then click the Place/Modify Order button.

API Reference Guide

347

ActiveX for Excel Conditional Orders Page

Conditional Orders Page Toolbar Buttons

The toolbar on the Conditional Orders page includes the following buttons: Button Combo Legs Description Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. After you have completed the Order Description fields, and defined any extended attributes, click to create an order for the selected contract. Applies all attributes on the Extended Order Attributes page to the selected order(s). This button cancels the order(s) you have highlighted. Jumps to the Error Code field and shows the error code.

Place/Modify Order

Apply Extended Template Cancel Order Show Errors

API Reference Guide

348

ActiveX for Excel Advanced Orders Page

Advanced Orders Page

Use the Advanced Orders page to:

Create complex orders that require the use of extended order attributes, including:

Bracket orders VOL orders Trailing Stop Limit Orders Scale Orders Relative Orders

API Reference Guide

349

ActiveX for Excel Advanced Orders Page

This page includes several example orders with mouseover help to assist you in learning how to place these orders. Simply move your mouse over the red triangle of the corner of cells on the page to display pop-up help.

For more information about using extended order attributes for individual orders or groups of orders, see Apply Extended Order Attributes to Individual Orders and Groups of Orders

API Reference Guide

350

ActiveX for Excel Advanced Orders Page

Placing a Bracket Order

Bracket orders in the ActiveX for Excel sample spreadsheet require the use of the extended order attributes Transmit and Parent Order Id. You must turn Transmit off until the order is completely set up, and you must identify the first order in the bracket as the Parent Order. To place a Buy-Limit bracket order 1 2 Click the Advanced Orders tab at the bottom of the spreadsheet. Enter the contract descriptions and order descriptions for all three orders on three contiguous rows:

The first order should be a BUY LMT order. The second order should be a SELL STP order. The third order should be a SELL LMT order.

Click the Extended Order Attributes tab. Change the value for Transmit to 0 (row 13 on the Extended Order Attributes page). This ensures that your orders are not transmitted until you have completed the order setup.

Click the Advanced Orders tab, highlight the first order in the bracket order, then click the Place/Modify Order button. The order is not executed, but the system generates an Order ID.

Copy the Order ID for the first order, omitting the id prefix, then click the Extended Order Attributes tab and paste the Order ID into the Value field for Parent Order Id (row 14). This value will be applied to all subsequent orders until you remove it from the Extended Order Attributes page. The first order of the bracket order is now the primary order.

Click the Advanced Orders tab, highlight the second order, then click the Place/Modify Order button. The order is not executed but is now associated with the primary order by means of the Parent Order Id extended order attribute.

7 8 9

Click the Extended Order Attributes tab and change the value for Transmit back to 1 (row 13). Click the Advanced Orders tab, highlight the third order in the bracket order, then click the Place/Modify Order button. The entire bracket order is transmitted. When you are done placing your bracket order, go to the Extended Order Attributes page and delete the Parent Order Id value you entered. If you do not, this value will be applied to all subsequent orders that you place in the spreadsheet.

API Reference Guide

351

ActiveX for Excel Advanced Orders Page

Placing a Volatility Order

In the ActiveX for Excel sample spreadsheet, you place VOL orders by entering values for the following extended order attributes:

Volatility Volatility Type Reference Price Type Continuous Update Underlying Range (Low) - optional Underlying Range (High) - optional Hedge Delta Order Type - optional Hedge Delta Aux Price - optional

To place a VOL order 1 2 3 Click the Advanced Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields.

Enter VOL in the Order Type field.

Click the Extended Order Attributes tab. Enter values in the Value field for the following extended order attributes:

Volatility - This value represents the volatility to use in calculating a limit price for the option. Enter this value as a percentage, not as the market data is displayed. For example, enter 17.12 instead of .1712. Volatility Type - Enter 1 for daily volatility or 2 for annual volatility. Reference Price Type - This value is used to compute the limit price sent to an exchange and for stock range price monitoring. Enter 1 to use the average of the best bid and ask; or 2 to use NBB (bid) when buying a call or selling a put, or the NBO (ask) when selling a call or buying a put. Continuous Update - Enter 1 to automatically update the option price as the underlying stock price (or futures price, for index options) moves. Enter 0 if you do not want to use this feature.

On the Extended Order Attributes page, enter values in the Value field for the following optional extended order attributes:

Underlying Range (Low) - Enter a low-end acceptable stock price relative to the selected option order. If the price of the underlying instrument falls below the lower stock range price, the option order will be canceled. Underlying Range (High) - Enter a high-end acceptable stock price relative to the selected option order. If the price of the underlying instrument rises above the higher stock range price, the option order will be canceled.

API Reference Guide

352

ActiveX for Excel Advanced Orders Page

Hedge Delta Order Type - Enter LMT, MKT or REL. Enter NONE if you do not want to use delta hedging. Hedge Delta Aux Price - If you have entered LMT or REL as the Hedge Delta Order Type, enter the price as the value for this attribute.

6 7

Click the Advanced Orders tab, then highlight the order row. Click the Apply Extended Template button. The values you entered for the extended order attributes are applied to the order row and displayed in the Extended Order Attributes section of the page. With the order row highlighted, click the Place/Modify Order button. When you are done placing VOL orders, go to the Extended Order Attributes page and delete the VOL order values you entered. If you do not, these values will be applied to all subsequent orders that you place in the spreadsheet.

8 9

Placing a Trailing Stop Limit Order

In TWS, there are four values that make up a trailing stop limit order:

trailing amount stop price limit price limit offset

In the ActiveX for Excel API spreadsheet, you enter the trailing amount, stop price and limit price. There is no field or extended order attribute for the limit offset value. You must include the limit offset in the stop price (the Trail Stop Price extended order attribute). To create a Trailing Stop Limit Order 1 2 3 Click the Advanced Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields.

Enter BUY or SELL in the Action field. Enter the limit price in the Lmt Price field. Enter TRAILLIMIT in the Order Type field. Enter the trailing amount in the Aux Price field.

Click the Extended Order Attributes tab. Specify the trailing stop price as an extended order attribute. Type this value in the Trail Stop Price Value field.

The Trail Stop Price value must include the limit offset. For a sell order: Trail Stop Price = Limit Price - Trailing Amount - Limit Offset

API Reference Guide

353

ActiveX for Excel Advanced Orders Page

For a buy order: Trail Stop Price = Limit Price + Trailing Amount + Limit Offset 5 On the Advanced Orders page, select the order row and click the Apply Extended Template button. The Trail Stop Price value is applied to the selected order and displayed in the Trail Stop Price field in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done placing your order, go to the Extended Order Attributes page and delete the Trail Stop Price value you entered. If you do not, this value will be applied to all subsequent orders that you place in the spreadsheet.

6 7

Placing a Scale Order

In the ActiveX for Excel sample spreadsheet, you place scale orders by entering values for the following extended order attributes:

Scale Component Size Scale Price Increment

To place a scale order 1 2 3 4 Click the Advanced Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields. The order type should be LMT or REL. Click the Extended Order Attributes tab. Enter values in the Value field for the following extended order attributes:

Scale Component Size - Enter the size of the first, or initial, order component. For example, if you submit a 10,000-share order with a Scale Component Size value of 1000, the first component will be fore 1000 shares. Scale Price Increment - Enter the amount used to calculate the per-unit price of each component in the scale ladder. This cannot be a negative number. As of API Release 9.41, the Scale Num Components not supported.

Note: 5

On the Advanced Orders page, select the order row and click the Apply Extended Template button. The scale order values are applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done placing your order, go to the Extended Order Attributes page and delete the scale order values you entered. If you do not, these values will be applied to all subsequent orders that you place in the spreadsheet.

6 7

API Reference Guide

354

ActiveX for Excel Advanced Orders Page

Placing a Relative Order

In the ActiveX for Excel sample spreadsheet, you place relative orders by entering a value for the Percent Offset extended order attribute. To place a relative order 1 2 3 Click the Advanced Orders tab at the bottom of the spreadsheet. Define a contract by typing a symbol in a blank Symbol field, then entering information in the relevant contract description fields. Select a contract and set up the order using the Order Description fields.

Enter REL as the order type. Enter the price cap in the Lmt Price cell.

4 5

Click the Extended Order Attributes tab. Enter a percentage in decimal form in the Value field for the Percent Offset extended order attribute. On the Advanced Orders page, select the order row and click the Apply Extended Template button. The percent offset value is applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done placing your order, go to the Extended Order Attributes page and delete the Percent Offset value you entered. If you do not, this value will be applied to all subsequent orders that you place in the spreadsheet.

6 7

Advanced Orders Page Toolbar Buttons

The toolbar on the Advanced Orders page includes the following buttons: Button Create Ticker Combo Legs Apply Extended Template Place/Modify Orders Description Opens the Ticker box. Enter information to create a market data line. Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. Applies the current values on the Extended Order Attributes page to the highlighted order row. After you have completed the Order Description fields, and defined any extended attributes, click to create an order for the selected contract. This button cancels the selected order(s). Clears all order status information from the page.

Cancel Order Clear Order Statuses

There is also a WhatIf check box on the toolbar. When checked, you will receive margin and commission data as if the order were placed, but the order will NOT be placed.

API Reference Guide

355

ActiveX for Excel Extended Order Attributes Page

Extended Order Attributes Page

The Extended Order Attributes page includes all of the optional attributes you can use when you send an order, such as setting a display size to create an iceberg order, adding orders to an OCA group, and setting the transmit date for a Good After Time order. Once you define the attributes on this page, you can apply them to a single order or selected group of orders using the Apply Extended Template button, which occurs on both the Orders page and the Conditional Orders page. The attributes populate the extended order attributes fields that follow the Order Status fields to the far right of the page.

For a complete list of extended order attributes supported by the API, see Extended Order Attributes.

API Reference Guide

356

ActiveX for Excel Extended Order Attributes Page

Manually Program Extended Order Attributes

Observe the following guidelines when you manually assign an attribute:

When appended to orderDescription, the number and order of attributes cannot be changed. For any attribute that is not defined, use the value 'EMPTY' or {}. Since a string length is limited to 255 characters, we recommend using the open/close curly braces {}. A place order message for a simple stock limit day order looks as follows, with the primary exchange "ISLAND" separating the extended attributes: =psmith12|ord!'id1814454745?place?BUY_1_MSFT_STK_SMART_USD_LMT_26 _{}_DAY_{}_{}_O_0_{}_1_{}_0_0_0_0_0_0_{}_{}_{}_{}_{}_{}_{}_{}_ISL AND_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_{}_1_2_3_4_5'

Apply Extended Order Attributes to Individual Orders and Groups of Orders

Normally, values that you enter on the Extended Order Attributes page apply to all subsequent orders. However, you also can apply selected attributes to an individual order or a group of orders on the Orders page. Note: You can also use this procedure to apply extended order attributes to orders on the Conditional Orders page.

To apply extended order attributes to individual orders or a group of orders 1 2 3 Enter the value or values on the Extended Order Attributes page that you want to apply to an individual order or group of orders. On the Orders page, select the order or group of orders. Click the Apply Extended Template button. The extended order attributes are applied to the order(s) and the values you entered on the Extended Order Attributes page are added to the corresponding fields in the Extended Order Attributes section of the Orders page. When you place the order or group of orders, the extended order attribute values you entered are applied to the order. For example, you might want to assign a unique Order Ref number to a group or basket of orders. To do this, you would enter the number for the Order Ref attribute on the Extended Order Attributes page, then select all the orders in the group on the Orders page and click Apply Extended Template. 4 Delete the value of the extended order attributes you used for the order from the Extended Order Attributes page. These values will still apply to all subsequent orders that you place from the ActiveX for Excel API spreadsheet unless you remove the value.

API Reference Guide

357

ActiveX for Excel Open Orders Page

Open Orders Page

The Open Orders page shows you all transmitted orders, including those that have been accepted by the IB system, and those that are working at an exchange. Once you have subscribed, the page is updated each time you submit a new order, either through the API or in TWS. Once an order executes, it remains on the Open Orders page for 30 seconds, with the Status value changed to FILLED. Then the filled order is cleared and you can see it on the Executions page if you subscribed to real-time executions.

API Reference Guide

358

ActiveX for Excel Open Orders Page

Viewing Open Orders

Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To view open orders: 1 2 Click the Open Orders tab at the bottom of the spreadsheet. Do one of the following:

To request open orders from the current ActiveX for Excel spreadsheet, click Subscribe to Open Orders on the toolbar. To request all open orders for the current account, click Request All Open Orders on the toolbar. To associate all newly created TWS orders with the current client, click Request Auto Open Orders on the toolbar. Note that the Client ID must be 0.

All of the requested open orders are displayed on the page, including orders you enter in the spreadsheet and in TWS. Orders that fill remain on the page for 30 seconds with a value of Fill in the Status field. To remove open orders 1 2 Click the Cancel Open Orders Subscription button on the toolbar. Click the Clear Open Orders button.

Open Orders Tab Toolbar

The toolbar on the Open Orders page includes the following buttons: Button Request Open Orders Description Queries TWS and returns all open orders. Once you subscribe to open orders, this page updates each time there is a new open order. Queries TWS and returns all open orders from the current account. Once you subscribe to open orders, this page updates each time there is a new open order. Queries TWS and associate all newly created TWS orders with the current client, which must be Client ID 0. Cancels association of newly created TWS orders with the client Removes all open orders from the page.

Request All Open Orders

Request Auto Open Orders Cancel Auto Open Orders Clear Open Orders

API Reference Guide

359

ActiveX for Excel Account Page

Account Page
Use the Account page to:

View account details including your current Equity with Loan Value and Available funds. View list of advisor-managed account codes. Financial Advisors can view FA information. View your current portfolio.

Using the Account Page

Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To view account information 1 2 Click the Account tab at the bottom of the spreadsheet. Click Request Account Updates on the toolbar.

To remove account information 1 2

API Reference Guide

Click the Account tab at the bottom of the spreadsheet. Click Cancel Account Updates on the toolbar to stop receiving account updates.
360

ActiveX for Excel Account Page

Click Clear Account Data on the toolbar to clear all data from the page.

To request the list of Financial Advisor (FA) managed account codes 1 2 Click the Account tab at the bottom of the spreadsheet. Click Request Managed Accounts on the toolbar. A comma-separated list of all managed account numbers displays in the Managed Accounts cell.

To request Financial Advisor (FA) information 1 2 3 Click the Account tab at the bottom of the spreadsheet. In the Account Code cell, type the account code for which you want details. In the FA Data Type cell, enter a numeric value representing the type of data you wish you receive:

Type 1 for groups. Type 2 for profiles. Type 3 for account aliases.

Click Request Managed Accounts on the toolbar.

API Reference Guide

361

ActiveX for Excel Account Page

Account Page Toolbar Buttons

The toolbar on the Account page includes the following buttons. Button Request Account Updates Description Each click gives you data for a specific account value. All blank lines that precede the Account Portfolio section will hold data. Continue to click until all lines are populated. Click this button one time for each position you hold. When you get a line of "0's" you know you have downloaded all current positions. These values continue to update in real-time. For advisor accounts, receives a list of managed accounts and displays them as a comma-separated list in the Management Accounts cell. For advisor accounts, displays FA data of the type specified in the FA Data Type cell. Clears all information from the page. You must first cancel your subscription before you can clear the data.

Cancel Account Updates

Request Managed Accounts Request FA Clear Account Data

API Reference Guide

362

ActiveX for Excel Portfolio Page

Portfolio Page
Use the Portfolio page to:

Displays all of your current positions. Exercise options. Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

Note:

Viewing Your Portfolio

To view your portfolio 1 2 Click the Account tab on the bottom of the worksheet, then click Request Account Updates on the toolbar. Click the Portfolio tab at the bottom of the worksheet to view your portfolio.

To remove portfolio information 1 2 Click the Account tab on the bottom of the worksheet, then click Cancel Account Updates on the toolbar to stop receiving portfolio updates. Click the Clear Portfolio Data button to clear all data from the page.

Exercising Options
You can exercise options or let options lapse on the Portfolio page. To exercise an option or let an option lapse 1 2 Click the Portfolio tab at the bottom of the worksheet. Enter values in the Exercise Options Parameters cells at the far right side of the page:

Exercise Action - Enter 1 to exercise the selected option; 2 to let the option lapse. Exercise Quantity - Enter the number of contracts you wish to exercise or let lapse. Override - Enter 1 to override the systems natural action; 2 to not override.

3
API Reference Guide

Click Exercise Options in the toolbar. The Status column updates.

363

ActiveX for Excel Portfolio Page

Portfolio Page Toolbar Buttons

The toolbar on the Portfolio page includes the following buttons. Button Exercise Options Description Exercises the selected option or lets the selected option lapse, depending on the value in the Exercise Action cell. Removes all data from the page.

Clear Portfolio Data

API Reference Guide

364

ActiveX for Excel Executions Page

Executions Page
When you subscribe to executions, the Executions page displays information about all completed trades.

API Reference Guide

365

ActiveX for Excel Executions Page

Viewing Executions
Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To view executions 1 2 Click the Executions tab at the bottom of the spreadsheet. Optionally, filter your executions by entering values in the Execution Filter cells:

Filter executions by client ID, account code, date/time, symbol, security type, exchange or side.

Click Request Executions on the toolbar.

To remove execution data 1 Click Clear Executions Table on the toolbar. All data is removed from the page.

Executions Page Toolbar Buttons

The toolbar on the Executions page includes the following buttons: Button Request Executions Description Queries TWS and returns information about all valid executions. After you subscribe to executions, this page updates each time an order executes. Removes all execution reports from the page.

Clear Executions Table

API Reference Guide

366

ActiveX for Excel Historical Data Page

Historical Data Page

Use the Historical Data page to request historical data for an instrument based on data you enter in query fields. The query results display on a separate worksheet page and creates a new page for the results if the page doesn't currently exist.

Note:

For a information about historical data request limitations, see Historical Data Limitations.

API Reference Guide

367

ActiveX for Excel Historical Data Page

Viewing Historical Data

Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To request historical data 1 2 Click the Historical Data tab at the bottom of the spreadsheet. Create a ticker by filling in the fields in the Contract Description section of the page, or by clicking the Create Ticker button on the toolbar and entering the required information in the Ticker box. Enter the parameters of your query in the Query Specification fields. For complete descriptions of the query fields, Historical Data Page Query Specification Fields. Select the line, then click the Request Historical Data button. The status of your request displays in the Request Status cell. In the Activate Page cell, enter TRUE to display the results page on top of the current window. Enter FALSE to display the page on a separate tab in the spreadsheet without displaying on top of the current window. The results are displayed on a new tabbed page in the spreadsheet, the name of which is specified in the Page Name cell. To request historical data for expired contracts 1 On the Historical Data page, create a ticker by filling in the fields in the Contract Description section of the page, or by clicking the Create Ticker button on the toolbar and entering the required information in the Ticker box. Enter the parameters of your query in the Query Specification fields. In the Incl Expired cell in the Query Specification section, enter TRUE. Select the line, then click Request Historical Data on the toolbar. The status of your request displays in the Request Status cell. In the Activate Page cell, enter TRUE to display the results page on top of the current window. Enter FALSE to display the page on a separate tab in the spreadsheet without displaying on top of the current window. The results are displayed on a new tabbed page in the spreadsheet, the name of which is specified in the Page Name cell. 5 Historical data queries on expired contracts are limited to the last year of the life of the contract.

3 4

2 3 4

API Reference Guide

368

ActiveX for Excel Historical Data Page

The following figure shows a typical historical data results page.

API Reference Guide

369

ActiveX for Excel Historical Data Page

Historical Data Page Query Specification Fields

Parameter End Date/Time

Description Use the format yyyymmdd {space}hh:mm:ss{space}tmz where the time zone is allowed (optionally)after a space at the end. This is the time span the request will cover, and is specified using the format integer {space} unit, where valid units are: S (seconds) D (days) W (weeks)

Duration

Y (years) This unit is currently limited to one. If no unit is specified, seconds are used. Bar Size Specifies the size of the bars that will be returned. The following bar sizes may be used, and are specified using the parametric value: Bar Size String Integer Value 1 second 1 5 seconds 2 15 seconds 3 30 seconds 4 1 minutes 5 2 minutes 6 3 minutes 16 5 minutes 7 15 minutes 8 30 minutes 9 1 hour 10 1 day 11 1 week 12 1 month 13 3 months 14 1 year 15 On the query return page, each "bar" is represented by a line in the spreadsheet. If you specify a duration of 300 seconds, and a bar size of "1" (one second) your return will include 300 lines, and the value in each line is equal to one second, or is a one-second bar. Note that you can use either the Integer value of the Bar Size String or the Integer Value to define the bar sizes.

API Reference Guide

370

ActiveX for Excel Historical Data Page

Parameter What to Show

Description Determines the nature of the data extracted. Valid values include: Trades Midpoint Bid Ask

Bid/Ask All but the Bid/Ask data contain the start time, open, high, low, close, volume and weighted average price during the time slice queried. For the Bid/Ask query, the open and close values are the time-weighted average bid and the time-weighted average offer, respectively. These bars are identical to the TWS charts' candlestick bars. RTH Only Regular Trading Hours only. Valid values include: 0 - all data available during the time span requested is returned, including time intervals when the market in question was outside of regular trading hours. 1 - only data within the regular trading hours for the product requested is returned, even if the time span falls partially or completely outside. 1 - dates that apply to bars are returned in the format yyyymmdd{space}{space}hh:mm:dd (the same format used when reporting executions). 2 - the dates are returned as an integer specifying the number of seconds since 1/1/1970 GMT.

Date Format Style

Valid values include:

Page Name Activate page

The name of the results page. This appears in the tab for the results page at the bottom of the worksheet. Enter TRUE to display the results page on top of the current window. Enter FALSE to display the results on a new page in the spreadsheet without appearing on top of the current window.

Note that the new page is added to the right of the existing tabs on the worksheet.

API Reference Guide

371

ActiveX for Excel Historical Data Page

Historical Data Page Toolbar Buttons

The toolbar on the Historical Data page includes the following buttons. Button Create Ticker Combo Legs Description Opens the Ticker box. Enter information to create a market data line. Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. Submits your historical data query to TWS and displays the results on a separate worksheet page. Cancels the historical data request.

Request Historical Data

Cancel Historical Data

API Reference Guide

372

ActiveX for Excel Contract Details Page

Contract Details Page

Use the Contract Details page to request contract-specific information such as supported order types, valid exchanges, the contract ID, and so on.

Requesting Contract Details

Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To request details for a contract 1 2 3 4 Click the Contract Details tab at the bottom of the spreadsheet to open the Contract Details page. Select or enter the ticker symbol for which you want to request contract details. To request contract details for an expired contract, type TRUE in the Incl Expired cell. Select the row, then click Request Contract Details on the toolbar. The status of your request displays in the Request Status cell. In the Activate Page cell, enter TRUE to display the results page on top of the current window. Enter FALSE to display the page on a separate tab in the spreadsheet without displaying on top of the current window.

API Reference Guide

373

ActiveX for Excel Contract Details Page

The results are displayed on a new tabbed page in the spreadsheet, the name of which is specified in the Page Name cell. The following figure shows a typical contract details page.

Contract Details Page Toolbar Buttons

The toolbar on the Contract Details page includes the following button: Button Request Contract Details Description Returns information on the selected contract.

API Reference Guide

374

ActiveX for Excel Bond Contract Details Page

Bond Contract Details Page

Use the Bond Contract Details page to request contract-specific information for bonds, including the coupon, ratings, bond type, maturity date, and so on.

Requesting Bond Contract Details

Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To request details for a bond contract 1 2 3 Click the Bond Contract Details tab at the bottom of the spreadsheet to open the Bond Contract Details page. Select or enter the ticker symbol for which you want to request bond contract details. Select the row, then click Request Bond Contract Details on the toolbar. The status of your request displays in the Request Status cell. In the Activate Page cell, enter TRUE to display the results page on top of the current window. Enter FALSE to display the page on a separate tab in the spreadsheet without displaying on top of the current window. The results are displayed on a new tabbed page in the spreadsheet, the name of which is specified in the Page Name cell.
API Reference Guide 375

ActiveX for Excel Bond Contract Details Page

The following figure shows a typical bond contract details page.

Bond Contract Details Page Toolbar Buttons

The toolbar on the Bond Contract Details page includes the following button: Button Request Bond Contract Details Description Gets bond information data for the selected contract.

API Reference Guide

376

ActiveX for Excel Real Time Bars Page

Real Time Bars Page

Real time bars allow you to get a summary of real-time market data every five seconds, including the opening and closing price, and the high and the low within that five-second period (using TWS charting terminology, we call these five-second periods "bars"). You can also get data showing trades, midpoints, bids or asks. You request real time bars on the Real Time Bars page, which is shown below.

To request real time bars Note: 1 2 Ensure that TWS is running, and that you have connected the spreadsheet to TWS. Click the Real Time Bars tab at the bottom of the spreadsheet to open the Real Time Bars page. Select or enter the ticker symbol for which you want to request real time bars.

API Reference Guide

377

ActiveX for Excel Real Time Bars Page

Enter the following information for the selected row:

In the What to Show cell, enter TRADES, BID, ASK or MIDPOINT. In the RTH Only cell, enter 0 to return all data available during the time span requested, including time intervals when the market in question was outside of regular trading hours. Enter 1 to return only data within the regular trading hours for the product requested is returned, even if the time span falls partially or completely outside.

Select the row, then click Request Real Time Bars on the toolbar. The status of your request displays in the Subscription Status cell. Results are displayed in the Real Time Bars cells on the right side of the page.

Real Time Bars Page Toolbar Buttons

The toolbar on the Real Time Bars page includes the following buttons. Button Create Ticker Request Real Time Bars Description Opens the Ticker box. Enter information to create a market data line. Submits your real time bars request to TWS and displays the results in the dark gray cells the right side of the page. Cancels the real time bars request. Clears all real time bar data from the page.

Cancel Real Time Bars Clear Real Time Bars Table

API Reference Guide

378

ActiveX for Excel Market Scanner Page

Market Scanner Page

Use the Market Scanner page to subscribe to TWS market scanners. These scanners allow you to define criteria and set filters that return the top x number of underlyings which meet all scan criteria. The scan is continually updated in real time. You can also display market scanner parameters from this page.

API Reference Guide

379

ActiveX for Excel Market Scanner Page

Starting a Market Scanner Subscription

Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To start a scanner subscription 1 2 Click the Market Scanner tab at the bottom of the spreadsheet. Highlight an existing scanner row, or enter information for a different market scanner: a b Type the name of the scan results page in the Page Name cell. Type TRUE or FALSE in the Activate Page cell. Setting this cell to TRUE forces the scan results page to pop to the front of your application every time it updates. To stop this behavior, set the value of this field to FALSE. c 3 Type values for the rest of the scan parameters in the lightly shaded section of the page. You can get all of the scan codes from the market scanner parameters.

Click Request Scanner Subscription on the toolbar. A new page for the scanner is created and is displayed after the subscription is processed.

Market Scanner Parameters

You can display all of the market scanner parameters from the Market Scanner page. Scanner parameters are returned to the spreadsheet from TWS as an XML file. Note: Ensure that TWS is running, and that you have connected the spreadsheet to TWS.

To view scanner parameters 1 2 Click the Market Scanner tab at the bottom of the spreadsheet. Click Request Scanner Parameters on the toolbar. The entire scanner parameters XML file is displayed in a window. 3 To save the parameters in a convenient file on your computer, manually select part or all of the contents of the XML file in the Scanner Parameters window, then copy and paste it into a separate text document. Click OK to close the Scanner Parameters window. The Scanner Parameters window is shown on the next page.

API Reference Guide

380

ActiveX for Excel Market Scanner Page

API Reference Guide

381

ActiveX for Excel Market Scanner Page

Available Market Scanners

The following table shows the available market scanners in the ActiveX for Excel API spreadsheet. Market Scanner (Scan Code) Low Opt Volume P/C Ratio (LOW_OPT_VOL_PUT_CALL_RATIO)* High Option Imp Vol Over Historical (HIGH_OPT_IMP_VOLAT_OVER_HIST) * Low Option Imp Vol Over Historical (LOW_OPT_IMP_VOLAT_OVER_HIST) * Highest Option Imp Vol (HIGH_OPT_IMP_VOLAT)*

Description Put option volumes are divided by call option volumes and the top underlying symbols with the lowest ratios are displayed. Shows the top underlying contracts (stocks or indices) with the largest divergence between implied and historical volatilities. Shows the top underlying contracts (stocks or indices) with the smallest divergence between implied and historical volatilities. Shows the top underlying contracts (stocks or indices) with the highest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months. Shows the top underlying contracts (stocks or indices) with the largest percent gain between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Shows the top underlying contracts (stocks or indices) with the largest percent loss between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Put option volumes are divided by call option volumes and the top underlying symbols with the highest ratios are displayed. Put option volumes are divided by call option volumes and the top underlying symbols with the lowest ratios are displayed. Displays the most active contracts sorted descending by options volume. Shows the top underlying contracts for highest options volume over a 10-day average. Returns the top 50 contracts with the highest put/call ratio of outstanding option contracts. Returns the top 50 contracts with the lowest put/call ratio of outstanding option contracts. Contracts whose last trade price shows the highest percent increase from the previous night's closing price.
382

Top Option Imp Vol % Gainers (TOP_OPT_IMP_VOLAT_GAIN)*

Top Option Imp Vol % Losers (TOP_OPT_IMP_VOLAT_LOSE)*

High Opt Volume P/C Ratio (HIGH_OPT_VOLUME_PUT_CALL_ RATIO) Low Opt Volume P/C Ratio (LOW_OPT_VOLUME_PUT_CALL_ RATIO) Most Active by Opt Volume (OPT_VOLUME_MOST_ACTIVE) Hot by Option Volume (HOT_BY_OPT_VOLUME) High Option Open Interest P/C Ratio (HIGH_OPT_OPEN_INTEREST_PUT_ CALL_RATIO) Low Option Open Interest P/C Ratio (LOW_OPT_OPEN_INTEREST_PUT_ CALL_RATIO) Top % Gainers (TOP_PERC_GAIN)

API Reference Guide

ActiveX for Excel Market Scanner Page

Market Scanner (Scan Code) Most Active (MOST_ACTIVE)

Description Contracts with the highest trading volume today, based on units used by TWS (lots for US stocks; contract for derivatives and non-US stocks). The sample spreadsheet includes two Most Active scans: Most Active List, which displays the most active contracts in the NASDAQ, NYSE and AMEX markets, and Most Active US, which displays the most active stocks in the United States. Contracts whose last trade price shows the lowest percent increase from the previous night's closing price. Contracts where: today's Volume/avgDailyVolume is highest. avgDailyVolume is a 30-day exponential moving average of the contract's daily volume.

Top % Losers (TOP_PERC_LOSE) Hot Contracts by Volume (HOT_BY_VOLUME)

Top % Futures Gainers (TOP_PERC_GAIN) Hot Contracts by Price (HOT_BY_PRICE)

Futures whose last trade price shows the highest percent increase from the previous night's closing price. Contracts where: (lastTradePrice-prevClose)/avgDailyChan ge is highest in absolute value (positive or negative). The avgDailyChange is defined as an exponential moving average of the contract's (dailyClose-dailyOpen)

Top Trade Count (TOP_TRADE_COUNT) Top Trade Rate (TOP_TRADE_RATE) Top Price Range (TOP_PRICE_RANGE) Hot by Price Range (HOT_BY_PRICE_RANGE) Top Volume Rate (TOP_VOLUME_RATE) Lowest Option Imp Vol (LOW_OPT_IMP_VOLAT)

The top trade count during the day. Contracts with the highest number of trades in the past 60 seconds (regardless of the sizes of those trades). The largest difference between today's high and low, or yesterday's close if outside of today's range. The largest price range (from Top Price Range calculation) over the volatility. The top volume rate per minute. Shows the top underlying contracts (stocks or indices) with the lowest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months.

API Reference Guide

383

ActiveX for Excel Market Scanner Page

Market Scanner (Scan Code) Most Active by Opt Open Interest (OPT_OPEN_INTEREST_MOST_ ACTIVE) Not Open (NOT_OPEN) Halted (HALTED) Top % Gainers Since Open (TOP_OPEN_PERC_GAIN) Top % Losers Since Open (TOP_OPEN_PERC_LOSE) Top Close-to-Open % Gainers (HIGH_OPEN_GAP) Top Close-to-Open % Losers (LOW_OPEN_GAP) Lowest Option Imp Vol (LOW_OPT_IMP_VOLAT)*

Description Returns the top 50 underlying contracts with the (highest number of outstanding call contracts) + (highest number of outstanding put contracts) Contracts that have not traded today. Contracts for which trading has been halted. Shows contracts with the highest percent price INCREASE between the last trade and opening prices. Shows contracts with the highest percent price DECREASE between the last trade and opening prices. Shows contracts with the highest percent price INCREASE between the previous close and today's opening prices. Shows contracts with the highest percent price DECREASE between the previous close and today's opening prices. Shows the top underlying contracts (stocks or indices) with the lowest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months. Shows the top underlying contracts (stocks or indices) with the largest percent gain between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Shows the top underlying contracts (stocks or indices) with the largest percent loss between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. The highest price for the past 13 weeks. The lowest price for the past 13 weeks. The highest price for the past 26 weeks. The lowest price for the past 26 weeks. The highest price for the past 52 weeks. The lowest price for the past 52 weeks.

Top Option Imp Vol % Gainers (TOP_OPT_IMP_VOLAT_GAIN)*

Top Option Imp Vol % Losers (TOP_OPT_IMP_VOLAT_LOSE)*

13-Week High (HIGH_VS_13W_HL) 13-Week Low (LOW_VS_13W_HL) 26-Week High (HIGH_VS_26W_HL) 26-Week Low (LOW_VS_26W_HL) 52-Week High (HIGH_VS_52W_HL) 52-Week Low (LOW_VS_52W_HL)

API Reference Guide

384

ActiveX for Excel Market Scanner Page

Market Scanner (Scan Code) EFP - High Synth Bid Rev Yield (HIGH_SYNTH_BID_REV_NAT_ YIELD)

Description Highlights the highest synthetic EFP interest rates available. These rates are computed by taking the price differential between the SSF and the underlying stock and netting dividends to calculate an annualized synthetic implied interest rate over the period of the SSF. The High rates may present an investment opportunity. Highlights the lowest synthetic EFP interest rates available. These rates are computed by taking the price differential between the SSF and the underlying stock and netting dividends to calculate an annualized synthetic implied interest rate over the period of the SSF. The Low rates may present a borrowing opportunity.

EFP - Low Synth Bid Rev Yield (LOW_SYNTH_BID_REV_NAT_ YIELD)

*30-day (V30) Implied Volatilities: Implied volatility is calculated using a 100-step binary tree for American style options, and a Black-Scholes model for European style options. Interest rates are calculated using the settlement prices from the day's Eurodollar futures contracts, and dividends are based on historical payouts. The IB 30-day volatility is the at-market volatility estimated for a maturity thirty calendar days forward of the current trading day. It is based on option prices from two consecutive expiration months. The first expiration month is that which has at least eight calendar days to run. The implied volatility is estimated for the eight options on the four closest to market strikes in each expiry. The implied volatilities are fit to a parabola as a function of the strike price for each expiry. The at-the-market implied volatility for an expiry is then taken to be the value of the fit parabola at the expected future price for the expiry. A linear interpolation (or extrapolation, as required) of the 30-day variance based on the squares of the at-market volatilities is performed. V30 is then the square root of the estimated variance. If there is no first expiration month with less than sixty calendar days to run, we do not calculate a V30.

API Reference Guide

385

ActiveX for Excel Market Scanner Page

Market Scanner Page Toolbar Buttons

The toolbar on the Market Scanner page includes the following buttons. Button Request Scanner Parameters Request Scanner Subscription Cancel Scanner Subscription Description Displays all scanner parameters in an XML file in a separate window. Creates and displays a new page for results of the selected market scanner. Cancels the market scanner.

API Reference Guide

386

ActiveX for Excel Fundamentals Page

Fundamentals Page
Use the Fundamentals page to receive Reuters global fundamental data and fundamental ratios. There must be a paid subscription to Reuters Fundamental set up in Account Management before you can receive this data.

To receive Reuters global fundamental data and fundamental ratios Note: 1 2 3 Ensure that TWS is running, and that you have connected the spreadsheet to TWS. Click the Fundamentals tab at the bottom of the spreadsheet to display the Fundamentals page. Enter information about the contract for which you want fundamentals data or ratios into the Contract Description cells. In the Report Type cell, enter the type of report you wish to view:

finstat - Financial Statement estimates - Estimates snapshot - Summary

API Reference Guide

387

ActiveX for Excel Fundamentals Page

4 5

In the Generic Tick Type cell, enter 258 as the tick type value. For details on generic tick type values, see Generic Tick Types. Enter the following information in the Fundamentals section of the page for fundamental data, or the Fundamental Ratios section for fundamental ratios: a b Fundamental data and ratio results display on a new page in the spreadsheet. Type the name of the results page in the Page Name cell. Type TRUE or FALSE in the Activate Page cell. Setting this cell to TRUE forces the results page to pop to the front of your application every time it updates. To stop this behavior, set the value of this field to FALSE.

Do one of the following:

Click Request Fundamentals on the toolbar to view fundamentals data. A new page for the results is created and is displayed after the request is processed. Click Fundamentals Ratios on the toolbar to view fundamentals ratios. A new page for the results is created and is displayed after the request is processed.

The status of your request appears in the Subscription Status cell.

Fundamentals Page Toolbar Buttons

The toolbar on the Market Scanner page includes the following buttons. Button Request Fundamentals Description Requests fundamentals data, which displays on a new page in the spreadsheet based on the information you enter on the page. Cancels fundamentals data. Requests fundamentals ratios, which displays on a new page in the spreadsheet based on the information you enter on the page. Cancels fundamentals ratios.

Cancel Fundamentals Fundamental Ratios

Cancel Fundamental Ratios

API Reference Guide

388

ActiveX for Excel Advisors Page

Advisors Page
If you are a Financial Advisor and manage multiple accounts, use the Advisors page to create FA orders that:

allocate shares to a single managed account use FA account groups and methods use allocation profiles

Note:

You must set up your managed accounts, account groups, methods and allocation profiles in TWS before you can place FA orders in the ActiveX for Excel API sample spreadsheet.

API Reference Guide

389

ActiveX for Excel Advisors Page

Allocating Shares to a Single Account

You can use the Advisors page to set up an order and allocate all shares in the order to a single account. To allocate shares to a single account: Note: 1 2 3 4 5 6 Ensure that TWS is running, and that you have connected the spreadsheet to TWS. Create an account group in TWS. Click the Advisors tab at the bottom of the spreadsheet. Enter the contract information in the Contract Description cells, then enter the order information in the Order Description cells. Click the Extended Order Attributes tab. Enter the account code in the Value cell for the Account (Institutional only) extended order attribute. Click the Advisors tab. Highlight the order row, then click the Apply Extended button to apply the Account order attribute value to the order. The Account value is applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done allocating shares to the account, delete the Account value from the Extended Order Attributes page. If you do not delete this value, it will be applied to all subsequent orders placed from the ActiveX for Excel spreadsheet.

7 8

Optionally, you can receive margin and commission information that would result from the order if you placed it by selecting the WhatIf check box on the toolbar. In this case, your order is not actually placed. Deselect the check box to place your order without seeing the margin and commission information ahead of time.

API Reference Guide

390

ActiveX for Excel Advisors Page

Placing an Order using an FA Account Group and Method

You can also use the Advisors page to set up an order using an FA account group and FA method. To place an order using an FA account group and FA method: 1 2 3 4 Create the FA account group(s) and FA method(s) in TWS. Click the Advisors tab at the bottom of the spreadsheet. Enter the contract information in the Contract Description cells, then enter the order information in the Order Description cells. Click the Extended Order Attributes tab. Enter values for the following extended order attributes:

FA Group - Enter the name of the account group. FA Method - Enter the name of the allocation method to use for this order. FA Percentage - Enter the percentage used by the PctChange allocation method to use for this order. This attribute applies only to FA groups that use this method.

5 6

Click the Advisors tab. Highlight the order row, then click the Apply Extended button to apply the extended order attribute values to the order. The values for FA Group, FA Method and FA Percentage are applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done allocating shares to the account, delete the values you entered on the Extended Order Attributes page. If you do not delete these values, they will be applied to all subsequent orders placed from the ActiveX for Excel spreadsheet.

7 8

Optionally, you can receive margin and commission information that would result from the order if you placed it by selecting the WhatIf check box on the toolbar. In this case, your order is not actually placed. Deselect the check box to place your order without seeing the margin and commission information ahead of time.

API Reference Guide

391

ActiveX for Excel Advisors Page

Placing an Order using an Allocation Profile

You can also use the Advisors page to set up an order using an FA allocation profile. To place an order using an FA allocation profile: 1 2 3 4 5 6 Create the FA allocation profile in TWS. Click the Advisors tab at the bottom of the spreadsheet. Enter the contract information in the Contract Description cells, then enter the order information in the Order Description cells. Click the Extended Order Attributes tab. Enter the name of the allocation profile in the Value field for the FA Profile extended order attribute. Click the Advisors tab. Highlight the order row, then click the Apply Extended button to apply the extended order attribute value to the order. The value for FA Profile is applied to the selected order and displayed in the Extended Order Attributes section of the page. Click the Place/Modify Order button. When you are done allocating shares to the account, delete the FA Profile value you entered on the Extended Order Attributes page. If you do not delete this value, it will be applied to all subsequent orders placed from the ActiveX for Excel spreadsheet.

7 8

Optionally, you can receive margin and commission information that would result from the order if you placed it by selecting the WhatIf check box on the toolbar. In this case, your order is not actually placed. Deselect the check box to place your order without seeing the margin and commission information ahead of time.

API Reference Guide

392

ActiveX for Excel Advisors Page

Advisors Page Toolbar Buttons

The toolbar on the Basic Orders page includes the following buttons: Button Create Ticker Combo Legs Apply Extended Template Place/Modify Orders Description Opens the Ticker box. Enter information to create a market data line. Opens the Combination Legs box. Enter contract details to create legs of a combination order one by one. Applies the current values on the Extended Order Attributes page to the highlighted order row. After you have completed the Order Description fields, and defined any extended attributes, click to create an order for the selected contract. This button cancels the order(s) you have highlighted. Clears all information from the Order Status cells.

Cancel Order Clear Order Statuses

API Reference Guide

393

ActiveX for Excel Log Page

Log Page
The Log page displays all error messages received while logged into TWS and using the ActiveX for Excel spreadsheet. You can clear all the information on the page by clicking Clear Log on the toolbar. Here is an example of a typical Log page:

API Reference Guide

394

POSIX
This chapter describes the POSIX API.

8
Although the pre-existing public interface has been preserved, you must recompile your client applications.

The POSIX API is based on our C++ API code. The C++ code was refactored so it could be built on any POSIX-compliant platform. Use this new POSIX API to build a TWS API on Linux, and on Windows in non-MFC applications. Note:

We also include a POSIX test client. The API installation directory includes these directories for the POSIX API: PosixSocketClient and TestPosixSocketClient. The POSIX test client uses the same methods as the C++ Socket client, plus it exposes several extra methods that clients must call when data is available on a socket for read/write. Refer to TestPosixSocketClient as an example. Please note that this test client is greatly simplified. For real POSIX API applications, you will have to use a select system of some kind to manage several sockets and/or asynchronous events. To run the POSIX test client on a Windows machine, see Running the POSIX Client on a Windows Machine.

API Reference Guide

395

POSIX Running the POSIX Client on a Windows Machine

Running the POSIX Client on a Windows Machine

To run the POSIX client on a Windows machine 1 Run vcvars32.bat at the command prompt. In the example below, vcvars32.bat is located in C:\Program Files\Microsoft Visual Studio 8\VC\bin\.

If you ran vcvars32.bat successfully, the command prompt should look like this:

Navigate to C:\... \TestPosixSocketClient in the same command prompt window. In the example below, TestPosixSocketClient is located in the C:\IB_API_963.

Type nmake -f Makefile.win at the command prompt.

Now run the POSIX sample application by running PosixSocketClientTest.exe in the same C:\...\TestPosixSocketClient directory.

API Reference Guide

396

Reference Tables
This chapter includes the following TWS API reference information:

API Message Codes Tick Types Generic Tick Types TAG Values for FUNDAMENTAL_RATIOS tickType Supported Order Types Extended Order Attributes Available Market Scanners IBAlgo Parameters

API Reference Guide

397

Reference Tables API Message Codes

API Message Codes

This section lists all of the API Error, System and Warning message codes and their descriptions. Message codes shown below that end with a colon ( : ) display additional information. Error Codes Code 100 101 102 103 104 105 106 107 109 110 111 113 114 115 116 117 118 119 120 121 122 123 124 125 126 129 Description Max rate of messages per second has been exceeded. Max number of tickers has been reached. Duplicate ticker ID. Duplicate order ID. Can't modify a filled order. Order being modified does not match original order. Can't transmit order ID: Cannot transmit incomplete order. Price is out of the range defined by the Percentage setting at order defaults frame. The order will not be transmitted. The price does not conform to the minimum price variation for this contract. The TIF (Tif type) and the order type are incompatible. The Tif option should be set to DAY for MOC and LOC orders. Relative orders are valid for stocks only. Relative orders for US stocks can only be submitted to SMART, SMART_ECN, INSTINET, or PRIMEX. The order cannot be transmitted to a dead exchange. The block order size must be at least 50. VWAP orders must be routed through the VWAP exchange. Only VWAP orders may be placed on the VWAP exchange. It is too late to place a VWAP order for today. Invalid BD flag for the order. Check "Destination" and "BD" flag. No request tag has been found for order: No record is available for conid: No market rule is available for conid: Buy price must be the same as the best asking price. Sell price must be the same as the best bidding price. VWAP orders must be submitted at least three minutes before the start time.

API Reference Guide

398

Reference Tables API Message Codes

Code 131 132 133 134 135 136 137 138 139 140 141 142 143 144

Description The sweep-to-fill flag and display size are only valid for US stocks routed through SMART, and will be ignored. This order cannot be transmitted without a clearing account. Submit new order failed. Modify order failed. Can't find order with ID = This order cannot be cancelled. VWAP orders can only be cancelled up to three minutes before the start time. Could not parse ticker request: Parsing error: The size value should be an integer: The price value should be a double: Institutional customer account does not have account info Requested ID is not an integer number. Order size does not match total share allocation. To adjust the share allocation, right-click on the order and select Modify > Share Allocation. Error in validating entry fields Invalid trigger method. The conditional contract info is incomplete. A conditional order can only be submitted when the order type is set to limit or market. This order cannot be transmitted without a user name. The "hidden" order attribute may not be specified for this order. EFPs can only be limit orders. Orders cannot be transmitted for a halted security. A sizeOp order must have a username and account. A SizeOp order must go to IBSX An order can be EITHER Iceberg or Discretionary. Please remove either the Discretionary amount or the Display size. You must specify an offset amount or a percent offset value. The percent offset value must be between 0% and 100%. The size value cannot be zero. Cancel attempted when order is not in a cancellable state. Order permId = Historical market data Service error message. The price specified would violate the percentage constraint specified in the default order settings.
399

145 146 147 148 151 152 153 154 155 156 157 158 159 160 161 162 163

API Reference Guide

Reference Tables API Message Codes

Code 164 165 166 167 168

Description There is no market data to check price percent violations. Historical market Data Service query message. HMDS Expired Contract Violation. VWAP order time must be in the future. Discretionary amount does not conform to the minimum price variation for this contract.

Code 200 201 202 203

Description No security definition has been found for the request. Order rejected - Reason: Order cancelled - Reason: The security <security> is not available or allowed for this account.

Code 300 301 302 303 304 305 306 307 308 309

Description Can't find EId with ticker Id: Invalid ticker action: Error parsing stop ticker string: Invalid action: Invalid account value action: Request parsing error, the request has been ignored. Error processing DDE request: Invalid request topic: Unable to create the 'API' page in TWS as the maximum number of pages already exists. Max number (3) of market depth requests has been reached. Note: TWS currently limits users to a maximum of 3 distinct market depth requests. This same restriction applies to API clients, however API clients may make multiple market depth requests for the same security. Can't find the subscribed market depth with tickerId: The origin is invalid. The combo details are invalid. The combo details for leg '<leg number>' are invalid. Security type 'BAG' requires combo leg details. Stock combo legs are restricted to SMART order routing.

310 311 312 313 314 315

API Reference Guide

400

Reference Tables API Message Codes

Code 316 317 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336

Description Market depth data has been HALTED. Please re-subscribe. Market depth data has been RESET. Please empty deep book contents before applying any new entries. Invalid log level <log level> Server error when reading an API client request. Server error when validating an API client request. Server error when processing an API client request. Server error: cause - %s Server error when reading a DDE client request (missing information). Discretionary orders are not supported for this combination of exchange and order type. Unable to connect as the client id is already in use. Retry with a unique client id. Only API connections with clientId set to 0 can set the auto bind TWS orders property. Trailing stop orders can be attached to limit or stop-limit orders only. Order modify failed. Cannot change to the new order type. Only FA or STL customers can request managed accounts list. Internal error. FA or STL does not have any managed accounts. The account codes for the order profile are invalid. Invalid share allocation syntax. Invalid Good Till Date order Invalid delta: The delta must be between 0 and 100. The time or time zone is invalid. The correct format is hh:mm:ss xxx where xxx is an optionally specified time-zone. E.g.: 15:59:00 EST Note that there is a space between the time and the time zone. If no time zone is specified, local time is assumed. The date, time, or time-zone entered is invalid. The correct format is yyyymmdd hh:mm:ss xxx where yyyymmdd and xxx are optional. E.g.: 20031126 15:59:00 EST Note that there is a space between the date and time, and between the time and time-zone. If no date is specified, current date is assumed. If no time-zone is specified, local time-zone is assumed.

337

API Reference Guide

401

Reference Tables API Message Codes

Code 338 339 340 341

Description Good After Time orders are currently disabled on this exchange. Futures spread are no longer supported. Please use combos instead. Invalid improvement amount for box auction strategy. Invalid delta. Valid values are from 1 to 100. You can set the delta from the "Pegged to Stock" section of the Order Ticket Panel, or by selecting Page/Layout from the main menu and adding the Delta column. Pegged order is not supported on this exchange. The date, time, or time-zone entered is invalid. The correct format is yyyymmdd hh:mm:ss xxx where yyyymmdd and xxx are optional. E.g.: 20031126 15:59:00 EST Note that there is a space between the date and time, and between the time and time-zone. If no date is specified, current date is assumed. If no time-zone is specified, local time-zone is assumed. The account logged into is not a financial advisor account. Generic combo is not supported for FA advisor account. Not an institutional account or an away clearing account. Short sale slot value must be 1 (broker holds shares) or 2 (delivered from elsewhere). Order not a short sale -- type must be SSHORT to specify short sale slot. Generic combo does not support "Good After" attribute. Minimum quantity is not supported for best combo order. The "Regular Trading Hours only" flag is not valid for this order. Short sale slot value of 2 (delivered from elsewhere) requires location. Short sale slot value of 1 requires no location be specified. Not subscribed to requested market data. Order size does not conform to market rule. Smart-combo order does not support OCA group. Your client version is out of date. Smart combo child order not supported. Combo order only supports reduce on fill without block(OCA). No whatif check support for smart combo order. Invalid trigger price. Invalid adjusted stop price.

342 343

344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362

API Reference Guide

402

Reference Tables API Message Codes

Code 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390

Description Invalid adjusted stop limit price. Invalid adjusted trailing amount. No scanner subscription found for ticker id: No historical data query found for ticker id: Volatility type if set must be 1 or 2 for VOL orders. Do not set it for other order types. Reference Price Type must be 1 or 2 for dynamic volatility management. Do not set it for non-VOL orders. Volatility orders are only valid for US options. Dynamic Volatility orders must be SMART routed, or trade on a Price Improvement Exchange. VOL order requires positive floating point value for volatility. Do not set it for other order types. Cannot set dynamic VOL attribute on non-VOL order. Can only set stock range attribute on VOL or RELATIVE TO STOCK order. If both are set, the lower stock range attribute must be less than the upper stock range attribute. Stock range attributes cannot be negative. The order is not eligible for continuous update. The option must trade on a cheap-to-reroute exchange. Must specify valid delta hedge order aux. price. Delta hedge order type requires delta hedge aux. price to be specified. Delta hedge order type requires that no delta hedge aux. price be specified. This order type is not allowed for delta hedge orders. Your DDE.dll needs to be upgraded. The price specified violates the number of ticks constraint specified in the default order settings. The size specified violates the size constraint specified in the default order settings. Invalid DDE array request. Duplicate ticker ID for API scanner subscription. Duplicate ticker ID for API historical data query. Unsupported order type for this exchange and security type. Order size is smaller than the minimum requirement. Supplied routed order ID is not unique. Supplied routed order ID is invalid.

API Reference Guide

403

Reference Tables API Message Codes

Code 391

Description The time or time-zone entered is invalid. The correct format is hh:mm:ss xxx where xxx is an optionally specified time-zone. E.g.: 15:59:00 EST. Note that there is a space between the time and the time zone. If no time zone is specified, local time is assumed. Invalid order: contract expired. Short sale slot may be specified for delta hedge orders only. Invalid Process Time: must be integer number of milliseconds between 100 and 2000. Found: Due to system problems, orders with OCA groups are currently not being accepted. Due to system problems, application is currently accepting only Market and Limit orders for this contract. Due to system problems, application is currently accepting only Market and Limit orders for this contract. < > cannot be used as a condition trigger. Order message error

392 393 394 395 396 397 398 399

Code 400 401 402 403 404

Description Algo order error. Length restriction. Conditions are not allowed for this contract. Invalid stop price. Shares for this order are not immediately available for short sale. The order will be held while we attempt to locate the shares. The child order quantity should be equivalent to the parent order size. The currency < > is not allowed. The symbol should contain valid non-unicode characters only. Invalid scale order increment. Invalid scale order. You must specify order component size. Invalid subsequent component size for scale order. The "Outside Regular Trading Hours" flag is not valid for this order. The contract is not available for trading. What-if order should have the transmit flag set to true.

405 406 407 408 409 410 411 412 413

API Reference Guide

404

Reference Tables API Message Codes

Code 414 415 416 417 418 419 420 421 422 423

Description Snapshot market data subscription is not applicable to generic ticks. Wait until previous RFQ finishes and try again. RFQ is not applicable for the contract. Order ID: Invalid initial component size for scale order. Invalid scale order profit offset. Missing initial component size for scale order. Invalid real-time query. Invalid route. The account and clearing attributes on this order may not be changed. Cross order RFQ has been expired. THI committed size is no longer available. Please open order dialog and verify liquidity allocation. FA Order requires allocation to be specified. FA Order requires per-account manual allocations because there is no common clearing instruction. Please use order dialog Adviser tab to enter the allocation. None of the accounts have enough shares. Mutual Fund order requires monetary value to be specified. Mutual Fund Sell order requires shares to be specified. Delta neutral orders are only supported for combos (BAG security type). We are sorry, but fundamentals data for the security specified is not available. What to show field is missing or incorrect. Commission must not be negative. Invalid "Restore size after taking profit" for multiple account allocation scale order. The order size cannot be zero. You must specify an account. You must specify an allocation (either a single account, group, or profile). Order can have only one flag Outside RTH or Allow PreOpen. The application is now locked. Order processing failed. Algorithm definition not found. Order modify failed. Algorithm cannot be modified. Algo attributes validation failed: Specified algorithm is not allowed for this order. Order processing failed. Unknown algo attribute.

424 425

426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443

API Reference Guide

405

Reference Tables API Message Codes

Code 444 445 446 447 448 449 40

Description Volatility Combo order is not yet acknowledged. Cannot submit changes at this time. The RFQ for this order is no longer valid. Missing scale order profit offset. Missing scale price adjustment amount or interval. Invalid scale price adjustment interval. Unexpected scale price adjustment amount or interval. Dividend schedule query failed.

Code 501 502 503 504 505 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529

Description Already connected. Couldn't connect to TWS. Confirm that API is enabled in TWS via the Configure>API menu command. Your version of TWS is out of date and must be upgraded. Not connected. Fatal error: Unknown message id. Request market data - sending error: Cancel market data - sending error: Order - sending error: Account update request - sending error: Request for executions - sending error: Cancel order - sending error: Request open order - sending error: Unknown contract. Verify the contract details supplied. Request contract data - sending error: Request market depth - sending error: Cancel market depth - sending error: Set server log level - sending error: FA Information Request - sending error: FA Information Replace - sending error: Request Scanner subscription - sending error: Cancel Scanner subscription - sending error: Request Scanner parameter - sending error: Request Historical data - sending error: Cancel Historical data - sending error: Request real-time bar data - sending error:

API Reference Guide

406

Reference Tables API Message Codes

Code 530 531

Description Cancel real-time bar data - sending error: Request Current Time - Sending error:

System Message Codes Code 1100 1101 1102 1300 Description Connectivity between IB and TWS has been lost. Connectivity between IB and TWS has been restored- data lost.* Connectivity between IB and TWS has been restored- data maintained. TWS socket port has been reset and this connection is being dropped. Please reconnect on the new port - <port_num>

*Market and account data subscription requests must be resubmitted Warning Message Codes Code 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 Description New account data requested from TWS. API client has been unsubscribed from account data. Unable to subscribe to account as the following clients are subscribed to a different account. Unable to modify this order as it is still being processed. A market data farm is disconnected. A market data farm is connected. A historical data farm is disconnected. A historical data farm is connected. A historical data farm connection has become inactive but should be available upon demand. A market data farm connection has become inactive but should be available upon demand. Order Event Warning: Attribute Outside Regular Trading Hours is ignored based on the order type and destination. PlaceOrder is now processed.

API Reference Guide

407

Reference Tables Tick Types

Tick Types
The following table lists all possible values for the tickType parameter, which is used in the following ActiveX events, C++ EWrapper functions, and Java EWrapper methods:

tickPrice() tickSize() tickOptionComputation() tickGeneric() tickString() tickEFP

Tick Value 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

Description BID_SIZE BID_PRICE ASK_PRICE ASK_SIZE LAST_PRICE LAST_SIZE HIGH LOW VOLUME CLOSE_PRICE BID_OPTION_COMPUTATION ASK_OPTION_COMPUTATION LAST_OPTION_COMPUTATION MODEL_OPTION_COMPUTATION OPEN_TICK LOW_13_WEEK HIGH_13_WEEK LOW_26_WEEK HIGH_26_WEEK LOW_52_WEEK HIGH_52_WEEK AVG_VOLUME OPEN_INTEREST

Event/Function/Method tickSize() tickPrice() tickPrice() tickSize() tickPrice() tickSize() tickPrice() tickPrice() tickSize() tickPrice() tickOptionComputation() See Note 1 below tickOptionComputation() See Note 1 below tickOptionComputation() See Note 1 below tickOptionComputation() See Note 1 below tickPrice() tickPrice() tickPrice() tickPrice() tickPrice() tickPrice() tickPrice() tickSize() tickSize()

API Reference Guide

408

Reference Tables Tick Types

Tick Value 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53

Description OPTION_HISTORICAL_VOL OPTION_IMPLIED_VOL OPTION_BID_EXCH OPTION_ASK_EXCH OPTION_CALL_OPEN_INTEREST OPTION_PUT_OPEN_INTEREST OPTION_CALL_VOLUME OPTION_PUT_VOLUME INDEX_FUTURE_PREMIUM BID_EXCH ASK_EXCH AUCTION_VOLUME AUCTION_PRICE AUCTION_IMBALANCE MARK_PRICE BID_EFP_COMPUTATION ASK_EFP_COMPUTATION LAST_EFP_COMPUTATION OPEN_EFP_COMPUTATION HIGH_EFP_COMPUTATION LOW_EFP_COMPUTATION CLOSE_EFP_COMPUTATION LAST_TIMESTAMP SHORTABLE FUNDAMENTAL_RATIOS RT_VOLUME HALTED BIDYIELD ASKYIELD LASTYIELD CUST_OPTION_COMPUTATION

Event/Function/Method tickGeneric() tickGeneric() NOT USED NOT USED tickSize() tickSize() tickSize() tickSize() tickGeneric() tickString() tickString() NOT USED NOT USED NOT USED tickPrice() tickEFP() tickEFP() tickEFP() tickEFP() tickEFP() tickEFP() tickEFP() tickString() tickGeneric() tickString() tickGeneric() See Note 2 below. tickPrice() See Note 3 below tickPrice() See Note 3 below tickPrice() See Note 3 below tickOptionComputation()

API Reference Guide

409

Reference Tables Tick Types

Note 1: Tick types BID_OPTION_COMPUTATION, ASK_OPTION_COMPUTATION, LAST_OPTION_COMPUTATION, and MODEL_OPTION_COMPUTATION return all Greeks (delta, gamma, vega, theta), the underlying price and the stock and option reference price when requested. MODEL_OPTION_COMPUTATION also returns model implied volatility. Note 2: When trading is halted for a contract, TWS receives a special tick: haltedLast=1. When trading is resumed, TWS receives haltedLast=0. A tick type, HALTED, tick ID = 49, is now available in regular market data via the API to indicate this halted state. Possible values for this new tick type are: 0 = Not halted 1 = Halted. Note 3: Applies to bond contracts only.

API Reference Guide

410

Reference Tables Generic Tick Types

Generic Tick Types

For all socket-based API technologies, including the socket client library, ActiveX and Java, we provide several types of market data ticks that can be requested as a part of the market data request. Starting with API version 9.0 (client version 30), version 6 of the REQ_MKT_DATA message is sent containing a new field that specifies the requested ticks as a list of comma-delimited integer Ids (generic tick types). Requests for these ticks will be answered if the tick type requested pertains to the contract at issue. Note that Generic Tick Tags cannot be specified if you elect to use the Snapshot market data subscription. The generic market data tick types are: Integer ID Value 100 101 104 106 162 165 221 225 233 236 256 258 Resulting Tick Value (see list below) 29, 30 27, 28 23 24 31 15, 16, 17, 18, 19, 20, 21 37 34, 35, 36 48 46 47

Tick Type Option Volume (currently for stocks) Option Open Interest (currently for stocks) Historical Volatility (currently for stocks) Option Implied Volatility (currently for stocks) Index Future Premium Miscellaneous Stats Mark Price (used in TWS P&L computations) Auction values (volume, price and imbalance) RTVolume Shortable Inventory Fundamental Ratios

API Reference Guide

411

Reference Tables Generic Tick Types

Using the SHORTABLE Tick

In TWS, there is a SHORTABLE column, as shown below. The column describes number of shares with which the security can be sold short.

The color GREEN indicates that at least 1000 shares are available to sell short. DARK GREEN indicates that this contract can be sold short but that at the moment there are no shares available for short sale, and that the system is searching for shares. RED indicates that no shares are available for short sale. With API 9.30 or higher, the shorting indicator is supported for all socket connections. The functionality equates to the SHORTABLE column in the TWS workstation. When invoking the reqMktDataEx()/reqMktData() methods, you must include generic ticktype 236 in the argument to obtain the shortable value. For example: The Shortable tick determines if SHORT SELL orders for a contract will be accepted. Analyze the value returned from tickGeneric(int tickerId, int tickType, double value) as follows: if (value > 2.5) { // 3.0 // There are at least 1000 shares available for a short sale // In TWS, this is identical to GREEN status } else if (value > 1.5) { // 2.0 // This contract will be available for short sale if shares can be // located // In TWS, this is identical to DARK GREEN status } else if (value > 0.5) { // 1.0 // Not available for short sale // In TWS, this is identical to RED status } else { // unknown value } Note: This feature is supported as of server version 33 (872 release of TWS).

API Reference Guide

412

Reference Tables TAG Values for FUNDAMENTAL_RATIOS tickType

TAG Values for FUNDAMENTAL_RATIOS tickType

The FUNDAMENTAL_RATIOS tickType (Tick Value 47) lets you request fundamental ratios in the form TAG=VALUE, TAG2=VALUE2, and so on. This ratios are sent using the tickGeneric() callback. The following table lists all the TAG values for FUNDAMENTAL_RATIOS. TAG NPRICE Description Closing Price This is the closing price for the issue from the day it last traded. It is also referred to as the Current Price. Note that some issues may not trade every day, and therefore it is possible for this price to come from a date prior to the last business day. 3 year trailing twelve months growth. Trailing twelve months over trailing twelve months. High Price This price is the highest price the stock traded at in the last 12 months. This could be an intra-day high. Low Price This price is the lowest price the stock traded at in the last 12 months. This could be an intra-day low. Pricing date The pricing date is the date at which the issue was last priced. Volume This is the daily average of the cumulative trading volume for the last ten days. Market capitalization This value is calculated by multiplying the current Price by the current number of shares outstanding. EPS excluding extraordinary items This is the Adjusted Income Available to Common Stockholders for the trailing twelve months divided by the trailing twelve month Diluted Weighted Average Shares Outstanding. EPS Normalized This is the Normalized Income Available to Common Stockholders for the most recent annual period divided by the same period's Diluted Weighted Average Shares Outstanding. Revenue/share This value is the trailing twelve month Total Revenue divided by the Average Diluted Shares Outstanding for the trailing twelve months. Note: Most banks and insurance companies do not report revenues when they announce their preliminary quarterly financial results in the press. When this happens, the trailing twelve month values will not be available (NA).

Three_Year_TTM_ Growth TTM_over_TTM NHIG

NLOW

PDATE VOL10DAVG

MKTCAP

TTMEPSXCLX

AEPSNORM

TTMREVPS

API Reference Guide

413

Reference Tables TAG Values for FUNDAMENTAL_RATIOS tickType

TAG QBVPS

Description Book value (Common Equity) per share This is defined as the Common Shareholder's Equity divided by the Shares Outstanding at the end of the most recent interim period. Book Value is the Total Shareholder's Equity minus Preferred Stock and Redeemable Preferred Stock. Book value (tangible) per share This is the interim Tangible Book Value divided by the Shares Outstanding at the end of the most recent interim period. Tangible Book Value is the Book Value minus Goodwill and Intangible Assets for the same period. Cash per share This is the Total Cash plus Short Term Investments divided by the Shares Outstanding at the end of the most recent interim period. Note: This does NOT include cash equivalents that may be reported under long term assets. Cash Flow per share This value is the trailing twelve month Cash Flow divided by the trailing twelve month Average Shares Outstanding. Cash Flow is defined as the sum of Income After Taxes minus Preferred Dividends and General Partner Distributions plus Depreciation, Depletion and Amortization. Dividends per share This is the sum of the Cash Dividends per share paid to common stockholders during the last trailing twelve month period. Dividend rate This value is the total of the expected dividend payments over the next twelve months. It is generally the most recent cash dividend paid or declared multiplied by the dividend payment frequency, plus any recurring extra dividends. P/E excluding extraordinary items This ratio is calculated by dividing the current Price by the sum of the Diluted Earnings Per Share from continuing operations BEFORE Extraordinary Items and Accounting Changes over the last four interim periods. P/E Normalized This is the Current Price divided by the latest annual Normalized Earnings Per Share value.

QTANBVPS

QCSHPS

TTMCFSHR

TTMDIVSHR

IAD

PEEXCLXOR

APENORM

API Reference Guide

414

Reference Tables TAG Values for FUNDAMENTAL_RATIOS tickType

TAG TMPR2REV

Description Price to sales This is the current Price divided by the Sales Per Share for the trailing twelve months. If there is a preliminary earnings announcement for an interim period that has recently ended, the revenue (sales) values from this announcement will be used in calculating the trailing twelve month revenue per share. NOTE: Most Banks and Finance companies do not report revenues when they announce their preliminary interim financial results in the press. When this happens, the trailing twelve month values will not be available (NA) until the complete interim filing is released. Price to Tangible Book This is the Current Price divided by the latest annual Tangible Book Value Per Share. Tangible Book Value Per Share is defined as Book Value minus Goodwill and Intangible Assets divided by the Shares Outstanding at the end of the fiscal period. Price to Cash Flow per share This is the current Price divided by Cash Flow Per Share for the trailing twelve months. Cash Flow is defined as Income After Taxes minus Preferred Dividends and General Partner Distributions plus Depreciation, Depletion and Amortization. Price to Book This is the Current Price divided by the latest interim period Book Value Per Share. Current ratio This is the ratio of Total Current Assets for the most recent interim period divided by Total Current Liabilities for the same period. NOTE: This item is Not Available (NA) for Banks, Insurance companies and other companies that do not distinguish between current and long term assets and liabilities. Quick ratio Also known as the Acid Test Ratio, this ratio is defined as Cash plus Short Term Investments plus Accounts Receivable for the most recent interim period divided by the Total Current Liabilities for the same period. NOTE: This item is Not Available (NA) for Banks, Insurance companies and other companies that do not distinguish between current and long term assets and liabilities. LT debt/equity This ratio is the Total Long Term Debt for the most recent interim period divided by Total Shareholder Equity for the same period. Total debt/total equity This ratio is Total Debt for the most recent interim period divided by Total Shareholder Equity for the same period. NOTE: This is Not Meaningful (NM) for banks.

PR2TANBK

TTMPRCFPS

PRICE2BK

QCURRATIO

QQUICKRATI

QLTD2EQ

QTOTD2EQ

API Reference Guide

415

Reference Tables TAG Values for FUNDAMENTAL_RATIOS tickType

TAG TTMPAYRAT

Description Payout ratio This ratio is the percentage of the Primary/Basic Earnings Per Share Excluding Extraordinary Items paid to common stockholders in the form of cash dividends during the trailing twelve months. Revenue This is the sum of all revenue (sales) reported for all operating divisions for the most recent TTM period. NOTE: Most banks and Insurance companies do not report revenues when they announce their preliminary quarterly financial results in the press. When this happens, the quarterly value will not be available (NA). EBITD Earnings Before Interest, Taxes, Depreciation and Amortization (EBITDA) is EBIT for the trailing twelve months plus the same period's Depreciation and Amortization expenses (from the Statement of Cash Flows). NOTE: This item is only available for Industrial and Utility companies. Earnings before taxes Also known as Pretax Income and Earnings Before Taxes, this is Total Revenue for the most recent TTM period minus Total Expenses plus Non-operating Income (Expenses) for the same period. Net Income available to common This is the trailing twelve month dollar amount accruing to common shareholders for dividends and retained earnings. Income Available to Common Shareholders is calculated as trailing twelve month Income After Taxes plus Minority Interest and Equity in Affiliates plus Preferred Dividends, General Partner Distributions and US GAAP Adjustments. NOTE: Any adjustment that is negative (ie. Preferred Stock Dividends) would be subtracted from Income After Taxes. Earnings before taxes Normalized This is the Income Before Tax number excluding the impact of all unusual/one-time/special charges items for the most recent annual period. Net Income Available to Common, Normalized This is the annual dollar amount accruing to common shareholders for dividends and retained earnings excluding the impact of all unusual/one-time/special charges items. Gross Margin This value measures the percent of revenue left after paying all direct production expenses. It is calculated as the trailing 12 months Total Revenue minus the trailing 12 months Cost of Goods Sold divided by the trailing 12 months Total Revenue and multiplied by 100. NOTE: This item is only available for Industrial and Utility companies.

TTMREV

TTMEBITD

TTMEBT

TTMNIAC

AEBTNORM

ANIACNORM

TTMGROSMGN

API Reference Guide

416

Reference Tables TAG Values for FUNDAMENTAL_RATIOS tickType

TAG TTMNPMGN

Description Net Profit Margin % Also known as Return on Sales, this value is the Income After Taxes for the trailing twelve months divided by Total Revenue for the same period and is expressed as a percentage. NOTE: Most Banks and Finance companies do not report revenues when they announce their preliminary quarterly financial results in the press. When this happens, the trailing twelve month value will not be available (NA). Operating margin This value measures the percent of revenues remaining after paying all operating expenses. It is calculated as the trailing 12 months Operating Income divided by the trailing 12 months Total Revenue, multiplied by 100. Operating Income is defined as Total Revenue minus Total Operating Expenses. Pretax margin This value represents Income Before Taxes for the most recent fiscal year expressed as a percent of Total Revenue for the most recent fiscal year. Return on average assets This value is the Income After Taxes for the trailing twelve months divided by the Average Total Assets, expressed as a percentage. Average Total Assets is calculated by adding the Total Assets for the 5 most recent quarters and dividing by 5. Return on average equity This value is the Income Available to Common Stockholders for the trailing twelve months divided by the Average Common Equity and is expressed as a percentage. Average Common Equity is calculated by adding the Common Equity for the 5 most recent quarters and dividing by 5. Return on investment This value is the trailing twelve month Income After Taxes divided by the average Total Long Term Debt, Other Long Term Liabilities and Shareholders Equity, expressed as a percentage. Revenue Change % This value is calculated as the most recent interim period Sales minus the Sales for the same interim period 1 year ago divided by the Sales for the same interim period one year ago, multiplied by 100. Revenue Change % This is the percent change in the trailing twelve month Sales as compared to the same trailing twelve month period one year ago. It is calculated as the trailing twelve month Sales minus the trailing twelve month Sales one year ago divided by the trailing twelve month Sales one year ago, multiplied by 100. Revenue growth rate The Five Year Revenue Growth Rate is the annual compounded growth rate of Revenues over the last 5 years.

TTMOPMGN

APTMGNPCT

TTMROAPCT

TTMROEPCT

TTMROIPCT

REVCHNGYR

TTMREVCHG

REVTRENDGR

API Reference Guide

417

Reference Tables TAG Values for FUNDAMENTAL_RATIOS tickType

TAG EPSCHNGYR

Description EPS Change % This value is calculated as the most recent interim period EPS minus the EPS for the same interim period 1 year ago divided by the EPS for the same interim period one year ago, multiplied by 100. NOTE: EPS must be positive for both periods. If either EPS value is negative, the result in Not Meaningful (NM). EPS Change % This is the percent change in the trailing twelve month EPS as compared to the same trailing twelve month period one year ago. It is calculated as the trailing twelve month EPS minus the trailing twelve month EPS one year ago divided by the trailing twelve month EPS one year ago, multiplied by 100. NOTE: If either value has a negative value, the resulting value will be Not Meaningful (NM). EPS growth rate This growth rate is the compound annual growth rate of Earnings Per Share Excluding Extraordinary Items and Discontinued Operations over the last 5 years. NOTE: If the value for either the most recent year or the oldest year is zero or negative, the growth rate cannot be calculated and a 'NA' (Not Available) code will be used. Growth rate % - dividend The Dividend Growth Rate is the compound annual growth rate in dividends per share. DIVGR% is calculated for 3 years whenever 4 years of dividends are available.

TTMEPSCHG

EPSTRENDGR

DIVGRPCT

API Reference Guide

418

Reference Tables Supported Order Types

Supported Order Types

IBs API technologies support the order types listed below. API orders only mimic the behavior of Trader Workstation (TWS). Test each order type, ensuring that you can successfully submit each one in TWS, before you submit the same order using the API.

Order Type Limit Risk Bracket Market-to-Limit Market with Protection Request for Quote Stop Stop Limit Trailing Limit if Toucched Trailing Market If Touched Trailing Stop Trailing Stop Limit Speed of Execution At Auction Discretionary Market Market-if-Touched Market-on-Close Market-on-Open Pegged-to-Market Relative Sweep-to-Fill Price Improvement Box Top Price Improvement Auction Block Limit-on-Close Limit-on-Open Limit if Touched Pegged-to-Midpoint

Abbreviation

MTL MKT PRT QUOTE STP STP LMT TRAIL LIT TRAIL MIT TRAIL TRAIL LIMIT

MKT MIT MOC MOO PEG MKT REL

BOX TOP

LOC LOO LIT PEG MID

API Reference Guide

419

Reference Tables Supported Order Types

Order Type Privacy Hidden Iceberg/Reserve VWAP - Guaranteed Time to Market All-or-None Fill-or-Kill Good-after-Time/Date Good-till-Date/Time Good-till-Canceled Immediate-or-Cancel Advanced Trading One-Cancels-All Spreads Volatility Algorithmic Trading (Algos) Arrival Price Balance Impact and Risk Minimize Impacet Percent of volume Scale TWAP VWAP - Best Effort

Abbreviation

VWAP

GAT GTD GTC IOC OCA VOL

API Reference Guide

420

Reference Tables Extended Order Attributes

Extended Order Attributes

The extended order attributes below can be used in all placeOrder functions and Open_Order events. Attribute string m_tif string m_ocaGroup string m_account string m_openClose int m_origin string m_orderRef boolean m_transmit Possible Values Day, GTC, IOC, GTD Identifies a member of a one-cancels-all group. Institutional only. Institutional only. Institutional only. Customer defined order ID tag. Specifies whether the order will be transmitted by TWS. If set to false, order is created by not transmitted. The order ID of the parent, used for bracket, auto stop and trailing stop orders. If set to true, specifies that the order is a block order. If set to true, specifies that the order is a Sweep-to-fill order. The publicly disclosed order size to be used when placing iceberg orders. Specifies how Simulated Stop, Stop-Limit and Trailing Stop orders are triggered. Valid values are: O - the default value. The "double bid/ask" method will be used for orders for OTC stocks and US options. All other orders will used the "last" method. 1 - use "double bid/ask" method, where stop orders are triggered based on two consecutive bid or ask prices. 2 - "last" method, where stop orders are triggered based on the last price. 3 - "double-last" method, where stop orders are triggered based on last two prices.

int m_parentId boolean m_blockOrder boolean m_sweepToFill int m_displaySize int m_triggerMethod

boolean m_ignoreRth boolean m_hidden

If set to true, allows triggering of orders outside of regular trading hours. If set to true, the order will not be visible when viewing the market depth. The only applies to orders routed to INet.

API Reference Guide

421

Reference Tables Extended Order Attributes

Attribute string m_goodAfterTime

Possible Values Indicates that the trade should be submitted after the time and date set, with format YYYYMMDD HH:MM:SS (seconds are optional). Use an empty string if not applicable. Indicates that the trade should remain working until the time and date set, with format YYYYMMDD HH:MM:SS (seconds are optional). You must set the tif to GTD when using this string. Use an empty string if not applicable. The advisor group to which the trade will be allocated. Use an empty string if not applicable. The advisor allocation profile to which the trade will be allocated. Use an empty string if not applicable. The advisor allocation method with which the trade will be allocated. Use an empty string if not applicable. The advisor percentage concerning the trade's allocation. Use an empty string if not applicable. To clarify any ambiguity for Smart-routed contracts, include the primary exchange, along with the Smart designation, for the destination. For institutional customers only. 0 - unapplicable (i.e. retail customer or not sshort leg) 1 - clearing broker 2 - third party. If this value is used, you must enter a designated location.

string m_goodTillDate

string m_faGroup string m_faProfile string m_faMethod

string m_faPercentage string m_primaryExch

int m_shortSaleSlot

string m_designatedLocation long ocaType

Only valid when shortSaleSlot value = 2. Otherwise leave blank or orders will be rejected. Cancel on Fill with Block = 1 Reduce on Fill with Block = 2 Reduce on Fill without Block = 3 Regular trading hours only. yes=1, no=0

int rthOnly

API Reference Guide

422

Reference Tables Extended Order Attributes

Attribute String rule80A

Possible Values Individual = 'I' Agency = 'A', AgentOtherMember = 'W' IndividualPTIA = 'J' AgencyPTIA = 'U' AgentOtherMemberPTIA = 'M' IndividualPT = 'K' AgencyPT = 'Y' AgentOtherMemberPT = 'N'

String settlingFirm

Institutional only

String clearingAccount

The true beneficiary of the order. This value must be sent on FUT/FOP orders for reporting the exchange. IB, Away, or PTA yes=1, no=0 Identifies a minimum quantity order type. The percent offset for relative orders. Trade with electronic quotes. yes=1, no=0 Trade with firm quotes. yes=1, no=0 Maximum SMART order distance from the NBBO. match = 1 improvement = 2 transparent = 3 For BOX exchange only. Starting price. For BOX exchange only. The stock reference price. For BOX exchange only.

String clearingIntent int allOrNone long minQty double percentOffset int eTradeOnly

int firmQuoteOnly

double nbboPriceCap long auctionStrategy

double startingPrice double stockRefPrice

API Reference Guide

423

Reference Tables Extended Order Attributes

Attribute double delta double stockRangeLower double stockRangeUpper double m_volatility

Possible Values For BOX exchange only. The lower value of the acceptable stock range. For BOX exchange only. The upper value of the acceptable stock range. For BOX exchange only. The option price in volatility, as calculated by TWS' Option Analytics. This value is expressed as a percent and is used to calculate the limit price sent to the exchange. 1 = Daily; 2 = Annual 0 = false; 1 = True 1 = Average; 2 = BidorAsk Enter an accepted order type such as: MKT, LMT, REL etc. Enter the Aux Price for Hedge Delta order types that require one. For Scale orders: Defines the number of component orders into which the parent order will be split, thereby backing into the number of units within each component. For Scale orders: Defines the number of units per component, backing into the number of components into which the parent order is split. For Scale orders: Defines the price increment per scale component. EFP orders EFP orders

int m_volatilityType m_continuousUpdate int m_referencePriceType String m_deltaNeutralOrderType double m_deltaNeutralAuxPrice int m_scaleNumComponents

int m_scaleComponentSize

double m_scalePriceIncrement double m_basisPoints int basisPointsType

API Reference Guide

424

Reference Tables Available Market Scanners

Available Market Scanners

The following table shows a list (current as of July 2008) of the available scanners. Market Scanner (Scan Code) Low Opt Volume P/C Ratio (LOW_OPT_VOL_PUT_CALL_ RATIO)* High Option Imp Vol Over Historical (HIGH_OPT_IMP_VOLAT_OVE R_HIST)* Low Option Imp Vol Over Historical (LOW_OPT_IMP_VOLAT_OVE R_HIST)* Highest Option Imp Vol (HIGH_OPT_IMP_VOLAT)*

Description Put option volumes are divided by call option volumes and the top underlying symbols with the lowest ratios are displayed. Shows the top underlying contracts (stocks or indices) with the largest divergence between implied and historical volatilities. Shows the top underlying contracts (stocks or indices) with the smallest divergence between implied and historical volatilities. Shows the top underlying contracts (stocks or indices) with the highest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months. Shows the top underlying contracts (stocks or indices) with the largest percent gain between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Shows the top underlying contracts (stocks or indices) with the largest percent loss between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Put option volumes are divided by call option volumes and the top underlying symbols with the highest ratios are displayed. Put option volumes are divided by call option volumes and the top underlying symbols with the lowest ratios are displayed. Displays the most active contracts sorted descending by options volume. Shows the top underlying contracts for highest options volume over a 10-day average. Returns the top 50 contracts with the highest put/call ratio of outstanding option contracts.

Top Option Imp Vol % Gainers (TOP_OPT_IMP_VOLAT_GAIN )* Top Option Imp Vol % Losers (TOP_OPT_IMP_VOLAT_LOSE )*

High Opt Volume P/C Ratio (HIGH_OPT_VOLUME_PUT_C ALL_ RATIO) Low Opt Volume P/C Ratio (LOW_OPT_VOLUME_PUT_CA LL_ RATIO) Most Active by Opt Volume (OPT_VOLUME_MOST_ACTIV E) Hot by Option Volume (HOT_BY_OPT_VOLUME) High Option Open Interest P/C Ratio (HIGH_OPT_OPEN_INTEREST _PUT_CALL_RATIO)

API Reference Guide

425

Reference Tables Available Market Scanners

Market Scanner (Scan Code) Low Option Open Interest P/C Ratio (LOW_OPT_OPEN_INTEREST _PUT_ CALL_RATIO) Top % Gainers (TOP_PERC_GAIN) Most Active (MOST_ACTIVE)

Description Returns the top 50 contracts with the lowest put/call ratio of outstanding option contracts. Contracts whose last trade price shows the highest percent increase from the previous night's closing price. Contracts with the highest trading volume today, based on units used by TWS (lots for US stocks; contract for derivatives and non-US stocks). The sample spreadsheet includes two Most Active scans: Most Active List, which displays the most active contracts in the NASDAQ, NYSE and AMEX markets, and Most Active US, which displays the most active stocks in the United States. Contracts whose last trade price shows the lowest percent increase from the previous night's closing price. Contracts where: today's Volume/avgDailyVolume is highest. avgDailyVolume is a 30-day exponential moving average of the contract's daily volume. Futures whose last trade price shows the highest percent increase from the previous night's closing price. Contracts where: (lastTradePrice-prevClose)/avgDailyCha nge is highest in absolute value (positive or negative). The avgDailyChange is defined as an exponential moving average of the contract's (dailyClose-dailyOpen) The top trade count during the day. Contracts with the highest number of trades in the past 60 seconds (regardless of the sizes of those trades). The largest difference between today's high and low, or yesterday's close if outside of today's range.

Top % Losers (TOP_PERC_LOSE) Hot Contracts by Volume (HOT_BY_VOLUME)

Top % Futures Gainers (TOP_PERC_GAIN) Hot Contracts by Price (HOT_BY_PRICE)

Top Trade Count (TOP_TRADE_COUNT) Top Trade Rate (TOP_TRADE_RATE) Top Price Range (TOP_PRICE_RANGE)

API Reference Guide

426

Reference Tables Available Market Scanners

Market Scanner (Scan Code) Hot by Price Range (HOT_BY_PRICE_RANGE) Top Volume Rate (TOP_VOLUME_RATE) Lowest Option Imp Vol (LOW_OPT_IMP_VOLAT)

Description The largest price range (from Top Price Range calculation) over the volatility. The top volume rate per minute. Shows the top underlying contracts (stocks or indices) with the lowest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months. Returns the top 50 underlying contracts with the (highest number of outstanding call contracts) + (highest number of outstanding put contracts) Contracts that have not traded today. Contracts for which trading has been halted. Shows contracts with the highest percent price INCREASE between the last trade and opening prices. Shows contracts with the highest percent price DECREASE between the last trade and opening prices. Shows contracts with the highest percent price INCREASE between the previous close and today's opening prices. Shows contracts with the highest percent price DECREASE between the previous close and today's opening prices. Shows the top underlying contracts (stocks or indices) with the lowest vega-weighted implied volatility of near-the-money options with an expiration date in the next two months. Shows the top underlying contracts (stocks or indices) with the largest percent gain between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility. Shows the top underlying contracts (stocks or indices) with the largest percent loss between current implied volatility and yesterday's closing value of the 15 minute average of implied volatility.

Most Active by Opt Open Interest (OPT_OPEN_INTEREST_MOS T_ ACTIVE) Not Open (NOT_OPEN) Halted (HALTED) Top % Gainers Since Open (TOP_OPEN_PERC_GAIN) Top % Losers Since Open (TOP_OPEN_PERC_LOSE) Top Close-to-Open % Gainers (HIGH_OPEN_GAP) Top Close-to-Open % Losers (LOW_OPEN_GAP) Lowest Option Imp Vol (LOW_OPT_IMP_VOLAT)*

Top Option Imp Vol % Gainers (TOP_OPT_IMP_VOLAT_GAIN )* Top Option Imp Vol % Losers (TOP_OPT_IMP_VOLAT_LOSE )*

API Reference Guide

427

Reference Tables Available Market Scanners

Market Scanner (Scan Code) 13-Week High (HIGH_VS_13W_HL) 13-Week Low (LOW_VS_13W_HL) 26-Week High (HIGH_VS_26W_HL) 26-Week Low (LOW_VS_26W_HL) 52-Week High (HIGH_VS_52W_HL) 52-Week Low (LOW_VS_52W_HL) EFP - High Synth Bid Rev Yield (HIGH_SYNTH_BID_REV_NAT _ YIELD)

Description The highest price for the past 13 weeks. The lowest price for the past 13 weeks. The highest price for the past 26 weeks. The lowest price for the past 26 weeks. The highest price for the past 52 weeks. The lowest price for the past 52 weeks. Highlights the highest synthetic EFP interest rates available. These rates are computed by taking the price differential between the SSF and the underlying stock and netting dividends to calculate an annualized synthetic implied interest rate over the period of the SSF. The High rates may present an investment opportunity. Highlights the lowest synthetic EFP interest rates available. These rates are computed by taking the price differential between the SSF and the underlying stock and netting dividends to calculate an annualized synthetic implied interest rate over the period of the SSF. The Low rates may present a borrowing opportunity.

EFP - Low Synth Bid Rev Yield (LOW_SYNTH_BID_REV_NAT _ YIELD)

API Reference Guide

428

Reference Tables IBAlgo Parameters

IBAlgo Parameters
Beginning with TWS API Release 9.6, the ActiveX, C++ and Java APIs support IBAlgo orders. The following table lists all of the IBAlgo strategies and parameters supported by the API. Algo Strategy For US Stocks: Arrival Price (ArrivalPx) Max percentage: maxPctVol (double in a range 0.01 to 0.5) Urgency/Risk aversion: riskAversion (Valid values: Get Done; Aggressive; Neutral; Passive) Attempt completion by EOD: forceCompletion (boolean) Target Percentage: pctVol (double in a range 0.01 to 0.5) Max Percentage: maxPctVol (double in a range 0.01 to 0.5) Trade when: strategyType (Valid values: Marketable; Matching Midpoint; Matching Same Side; Matching Last Max percentage: maxPctVol (double in a range 0.01 to 0.5) Urgency/Risk aversion: riskAversion (Valid values: Get Done; Aggressive; Neutral; Passive) Attempt completion by EOD: forceCompletion (boolean) Max Percentage: maxPctVol (double in a range 0.01 to 0.5) Parameters

Percentage of Volume (PctVol) Volume-Weighted Average Price (Vwap) Time-Weighted Average Price (Twap) For US Options: Balance Impact and Risk (BalanceImpactRisk)

Minimize Impact (MinImpact)

API Reference Guide

429

Reference Tables IBAlgo Parameters

API Reference Guide

430

Index
A
about the APIs 1-14 account details in ActiveX for Excel 7-360 account details in Excel DDE 2-69 account information, removing in Excel 2-70 account information, viewing in ActiveX for Excel 7-360 account information, viewing in Excel 2-70 Account page 2-69 field values 2-71 in ActiveX for Excel 7-360 toolbar buttons 2-75, 7-362 Account page, using 2-70 Account page, using in ActiveX for Excel 7-360 Active X 3-113 ActiveX linking to TWS 3-114 placing a combination order 3-204 registering third-party controls 3-115 ActiveX API on 64-bit systems 3-115 ActiveX COM objects 3-183, 3-184, 3-186, 3-188, 3-189, 3-190, 3-196 ActiveX events 3-152, 3-153, 3-154, 3-155, 3-157, 3-158, 3-159, 3-160, 3-161, 3-163, 3-168, 3-169, 3-170, 3-171, 3-172, 3-173, 3-174, 3-175, 3-176, 3-177, 3-179, 3-180, 3-181, 3-182 ActiveX factory methods 3-149, 3-150, 3-151 ActiveX for Excel Account page 7-360 Advanced Orders page 7-349 Advisors page 7-389 allocating shares to a single account 7-390 Basic Orders page 7-340 Bond Contract Details page 7-375 bracket orders in 7-351 Bulletins page 7-337 connecting to TWS 7-332 Contract Details page 7-373 disconnecting from TWS 7-332 download API components 7-328 Executions page 7-365 Extended Order Attributes page 7-356 FA orders using account group and method 7-391 FA orders using allocation profile 7-392 Fundamentals page 7-387 General page 7-331 getting started 7-328 Historical Data page 7-367 Log page 7-394 Market Depth page 7-338 Market Scanner page 7-379 Open Orders page 7-358 opening sample spreadsheet 7-329 placing orders in 7-341 Real Time Bars page 7-377 relative orders in 7-355 requesting current time 7-333 scale orders in 7-354 setting server log level in 7-332 Tickers page 7-334 trailing stop limit orders in 7-353 ActiveX for Excel historical data expired contracts 7-368 ActiveX for Excel sample spreadsheet using 7-330 ActiveX methods 3-117, 3-119, 3-135, 3-141, 3-143, 3-144, 3-145, 3-147, 3-148, 3-149 ActiveX properties 3-199 ActiveX sample program 3-116 addComboLeg() 3-134 Advanced Orders 2-56 in ActiveX for Excel 7-349 Advanced Orders page toolbar buttons 2-62, 7-355 advisors 6-321 financial reporting for 6-323 Advisors page 2-99 in ActiveX for Excel 7-389 toolbar buttons 2-103, 7-393 advisors, Excel DDE support for 6-322 algo parameters 9-429 allocation methods for account groups 6-324 API recommendations 1-18 API components, downloading 2-30, 7-328 API components, using 1-14 API components. configurign in TWS 2-31 API overview 1-13, 9-397 API software uninstalling 1-28 API, about 1-14 API, for financial advisor accounts 6-321 Apply Extended Template button 2-47, 7-357 available market scanners 9-425 available market scanners in ActiveX for Excel 7-382 available market scanners in Excel 2-87 AvailableEquity Method 6-324

B
bar size settings for historical data 1-22 Basic Orders page 2-39 combination orders 7-342 in ActiveX for Excel 7-340 modifying orders 7-342 placing orders in ActiveX for Excel 7-341 toolbar buttons 2-45, 7-344 basket orders, in ActiveX for Excel 7-341

API Reference Guide

431

Index

basket orders, in Excel 2-40 Bond Contract Details page 2-94 in ActiveX for Excel 7-375 toolbar buttons 2-95, 7-376 bond contract details, requesting in ActiveX for Excel 7-375 bond contract details, requesting in Excel 2-94 bondContractDetails() 3-179, 4-242, 5-296 bracket orders in ActiveX for Excel 7-351 in DDE for Excel 2-57 bracket orders, in Excel 2-57 Bulletins page in ActiveX for Excel 7-337 toolbar buttons 7-337

C
C++ 4-207 Class EClientSocket methods 4-215 Class EWrapper functions 4-229 combinations orders 4-259 linking to TWS 4-208 using the sample program 4-213 C++ SocketClient properties 4-245 calcOptionPriceAndGreeks 3-122 calculateImpliedVolatility 3-122, 4-217, 5-274 calculateOptionPrice 4-218, 5-275 calendar spread order in Excel 2-41, 7-342 calendar spread order, in C++ 4-259 cancelCalculateImpliedVolatility 3-122, 4-218, 5-275 cancelCalculateOptionPrice 3-123, 4-218, 5-275 cancelHistoricalData() 3-147, 4-226, 5-282 cancelMktData() 3-122, 4-217, 5-274 cancelMktDepth() 3-133, 4-221, 5-277 cancelNewsBulletins() 3-135, 4-221, 5-278 cancelOrder() 3-127, 4-219, 5-275 cancelRealTimeBars() 3-149, 4-227, 5-283 cancelScannerSubscription() 3-147, 4-226, 5-280 checkMessages() 4-219 Class EClientSocket methods 4-215, 4-216, 4-217, 4-218, 4-219, 4-220, 4-221, 4-222, 4-223, 4-225, 4-226, 4-227 Class EWrapper functions 4-229, 4-230, 4-231, 4-232, 4-234, 4-235, 4-236, 4-237, 4-238, 4-239, 4-240, 4-241, 4-242, 4-243, 4-244 Clear All Links button 2-37 clearComboLegs() 3-135 combination order, in ActiveX 3-204 combination order, in ActiveX for Excel 7-342 combination order, in Excel 2-41 combination orders, in C++ 4-259 combination orders, in Java 5-317 ComboLeg 4-251, 5-307 conditional orders in Excel, examples of 2-53, 7-346 Conditional Orders page 2-52, 7-345 toolbar buttons 2-55, 7-348 Conditional Orders page, modifying orders 2-54, 7-347 conditional orders, in Excel 2-52, 7-345 configure TWS 1-15 configuring TWS 2-31 connect() 3-119

connecting to TWS using ActiveX for Excel 7-332 connectionClosed() 3-158, 4-236, 5-293 Contract 4-248, 5-305 Contract Details page 2-92 in ActiveX for Excel 7-373 toolbar buttons 2-93, 7-374 contract details, requesting in ActiveX for Excel 7-373 contract details, requesting in Excel 2-92 ContractDetails 4-250, 5-306 contractDetails() 3-172, 3-173, 4-239, 5-296 contractDetailsEx() 3-172 createComboLegList() 3-149 createContract() 3-150 createExecutionFilter() 3-150 createOrder() 3-150 createScannerSubscription() 3-150 createTagValueList 3-150 createUnderComp() 3-151 creating a ticker in ActiveX for Excel 7-334 creating a ticker in Excel 2-35 current time requesting in ActiveX for Excel 7-333 currentTime() 3-182, 4-244, 5-301

D
DDE for Excel allocating shares to a single account 2-100 FA orders using account group and method 2-101 FA orders using allocation profile 2-102 DDE for Excel historical data expired contracts 2-79 DDE syntax 2-104 DDE syntax reference 2-107 DDE, defined 2-29 delta-neutral RFQs 1-26 disconnect() 3-119 disconnecting from TWS using ActiveX for Excel 7-332 displaying lines of market depth in Excel 2-97 downloading API components 2-30, 7-328

E
EClient Socket methods 5-272, 5-273, 5-274, 5-275, 5-276, 5-277, 5-278, 5-279, 5-280, 5-281, 5-282, 5-283, 5-284 EClientSocket functions 4-215 EClientSocket() 4-215, 5-273 eConnect() 4-216, 5-273 eDisconnect() 4-216, 5-273 EqualQuantity Method 6-324 errMsg() 3-158 error codes 9-398 error messages viewing in ActiveX for Excel 7-394 error() 4-235, 5-292 EWrapper methods 5-286 Excel 2007 Name Manager 2-106 Excel DDE 2-29, 7-327, 8-395 download API components 2-30

API Reference Guide

432

Index

getting started 2-30 macros in 2-106 named ranges in 2-105 opening sample spreadsheet 2-33 pages 2-34, 7-330 placing orders in 2-40 supported order types 2-43, 7-344 syntax 2-107 viewing sample spreadsheet code 2-104 Visual Basic Editor 2-104 Excel DDE API reference 2-104 Excel DDE sample spreadsheet, installing 2-30, 7-328 Excel DDE, extended order attributes 2-46, 7-356 Excel DDE, Extended Order attributes page 2-46, 7-356 Excel DDE, financial advisor support 6-322 Excel DDE, supported order types 2-43, 7-344 execDetails() 3-174, 4-239, 5-296 execDetailsEnd() 3-175, 4-240, 5-297 execDetailsEx() 3-173 Execution 4-246, 5-303 execution reporting, for financial advisors 6-323 execution reporting, in ActiveX for Excel 7-365 execution reporting, in Excel DDE 2-65 execution reports types of 2-68 execution reports, running in Excel 2-68 ExecutionFilter 4-246, 5-303 Executions page 2-65, 2-67 in ActiveX for Excel 7-365 toolbar buttons 2-66, 7-366 executions reporting, in Excel DDE 2-67 executions, viewing in ActiveX for Excel 7-366 executions, viewing in Excel 2-65 exerciseOptions() 3-144, 4-225, 5-284 exerciseOptionsEx() 3-143 exercising options in ActiveX for Excel 7-363 extended order attributes applying to individual or groups of orders 2-47, 7-357 extended order attributes in Excel 2-48 Extended Order Attributes page 2-46 in ActiveX for Excel 7-356 extended order attributes, manually programming in ActiveX for Excel 7-357 extended order attributes, manually programming in Excel 2-47

filtering execution reports in Excel DDE 2-67 Financial Advisors allocation methods for account groups 6-324 financial advisors 6-321 execution reporting for 6-323 orders and account configuration 6-322 financial advisors, Excel DDE support for 6-322 financial advisors, support by other API technologies 6-322 fundamental data in ActiveX for Excel 7-387 report types 7-387 fundamental ratios in ActiveX for Excel 7-387 FUNDAMENTAL_RATIOS tickType 9-413 Fundamentals page in ActiveX for Excel 7-387 toolbar buttons 7-388

G
General page toolbar buttons 7-333 generic ticktypes SHORTABLE 9-412 getting started with ActiveX for Excel

sample spreadsheet
with Excel DDE 2-30

7-328

H
historical data duration and bar size settings 1-22 viewing in ActiveX for Excel 7-368 viewing in Excel 2-79 historical data limitations 1-21 Historical Data page 2-78 in ActiveX for Excel 7-367 query specification fields 2-81, 7-370 toolbar buttons 2-83, 7-372 historicalData 4-242 historicalData() 3-177, 4-242, 5-299

I
IB Gateway running the API through 1-16 IBAlgo parameters 9-429 IComboLeg 3-189 IContract 3-186 IContractDetails 3-188 IExecution 3-184 IExecutionFilter 3-184 if-filled order, in Excel 2-53, 7-346 Index Premium data 1-27 installing Excel DDE sample spreadsheet 2-30, 7-328 IOrder 3-190 IOrderState 3-196 isConnected() 4-216, 5-273

F
FA information in ActiveX for Excel 7-361 FA managed accounts, in ActiveX for Excel 7-361 Portfolio page 7-363 FA managed accounts, in Excel 2-70 FA orders allocating shares to a single account 2-100, 7-390 allocation profiles 2-102, 7-392 using account group and method 2-101, 7-391 FA orders in ActiveX for Excel 7-389 FA orders in DDE for Excel 2-99

API Reference Guide

433

Index

J
Java 5-261 combination orders 5-317 linking to TWS 5-262 sample program 5-265 Java EClient Socket methods 5-272 Java EWrapper methods 3-173, 4-239, 5-286, 5-287, 5-288, 5-289, 5-291, 5-292, 5-293, 5-294, 5-295, 5-296, 5-297, 5-298, 5-299, 5-300, 5-301 java sample program 5-269 classes 5-269 Java SocketClient properties 5-302, 5-303, 5-305, 5-306, 5-307, 5-309, 5-314, 5-315 Java Test Client 5-269 overview 5-269 running 5-265

N
Name Manager, in Excel 2007 2-106 named ranges 2-105 NetLiq Method 6-324 nextValidId() 3-171, 4-239, 5-295

O
open orders removing in Excel 2-64 Open Orders page 2-63 ActiveX for Excel 7-358 toolbar buttons 2-64, 7-359 open orders, viewing in ActiveX for Excel 7-359 open orders, viewing in Excel 2-64 opening the ActiveX sample program 3-116 openOrder() 4-236, 5-293 openOrder1() 3-159 openOrder2() 3-160 openOrder3() 3-161 openOrder4() 3-163 openOrderEx() 3-159 options exercising in ActiveX for Excel 7-363 Order 4-252, 5-309 order attributes in Excel 2-44 order IDs 1-25 order types in Excel DDE 2-43, 7-344 order types supported 9-419 order types, in Excel 2-43, 7-344 orders 1-23 placing in ActiveX for Excel 7-341 placing in Excel 2-40 orders and account configuration, for financial advisors 6-322 Orders page combination orders 2-41 modifying orders 2-41 placing basket orders 2-57 placing orders 2-40 orders, modifying in ActiveX for Excel 7-342 orders, modifying in Excel 2-41 OrderState 4-256, 5-314 orderStatus() 3-157, 4-234, 5-291 overview 1-13, 9-397

L
limitations of historical data requests 1-21 linking to TWS, using ActiveX 3-114 log level, setting in Excel 2-37 Log page in ActiveX for Excel 7-394

M
macros in Excel 2-106 managedAccounts() 3-177, 4-236, 5-293 market depth requesting in ActiveX for Excel 7-339 requesting in Excel 2-97 Market Depth page 2-96 in ActiveX for Excel 7-338 toolbar buttons 2-98 toolbar buttons in ActiveX for Excel 7-339 using 2-97 using ActiveX for Excel 7-339 market depth, displaying more lines in Excel 2-97 Market Scanner page 2-84 in ActiveX for Excel 7-379 supported market scanners 9-425 toolbar buttons 2-91, 7-386 market scanner parameters in ActiveX for Excel 7-380 market scanner subscription, starting in ActiveX for Excel 7-380 market scanner subscription, starting in Excel 2-85 market scanners, available in ActiveX for Excel 7-382 market scanners, available in Excel 2-87 Message codes 9-407 message codes 9-398 modifying orders in ActiveX for Excel 7-342 modifying orders in Excel 2-41 modifying orders, on Conditional Orders page 2-54, 7-347 modules in Excel VB code 2-105

P
pages 2-34, 7-330 PctChange Method 6-324 permId() 3-171 placeOrder() 3-123, 4-218, 5-275 placeOrder2() 3-126 placeOrderEx() 3-123 placing orders basket 2-40, 2-57, 7-341 combination order in ActiveX for Excel 7-342 combination order in Excel 2-41 conditional orders in Excel 2-52, 7-345 placing orders in ActiveX for Excel 7-341 placing orders in Excel 2-40
434

API Reference Guide

Index

portfolio data in Excel DDE 2-76 portfolio data in FA managed accounts, in ActiveX for Excel 7-363 Portfolio page 2-76 in FA managed accounts, in ActiveX for Excel 7-363 toolbar buttons 2-77, 7-364 portfolio, viewing in Excel 2-76 portfolio, viewing in FA managed accounts, in ActiveX for Excel 7-363 POSIX running client on Windows machine 8-396 premium data 1-27 price-change order, in Excel 2-54, 7-347 processing rate, on Tickers page 2-37

Q
query specification fields, on Historical Data page in ActiveX for Excel 7-370 query specification fields, on Historical Data page in Excel 2-81

R
real time bars in ActiveX for Excel 7-377 Real Time Bars page toolbar buttons 7-378 realtimeBar() 3-181, 4-244, 5-301 receiveFA() 3-177, 4-242, 5-299 recommendations for using API 1-18 reference tables 9-397 refresh rate, for market depth in Excel 2-97, 7-339 refresh rate, on ActiveX for Excel Tickers page 7-336 refresh rate, on Tickers page 2-37 registering third-party ActiveX controls 3-115 relative orders, in ActiveX for Excel 7-355 relative orders, in DDE for Excel spreadsheet 2-61 removing open orders, in Excel 2-64 replaceFA() 4-223, 5-279 reqAccountUpdates() 3-136, 4-219, 5-276 reqAllOpenOrders 5-278 reqAllOpenOrders() 3-128, 4-221 reqAutoOpenOrders() 3-128, 4-222, 5-278 reqContractDetails() 3-130, 4-220, 5-277 reqContractDetails2() 3-131 reqContractDetailsEx() 3-129 reqCurrentTime() 3-149, 4-227, 5-284 reqExecutions() 3-128, 4-220, 5-276 reqExecutionsEx() 3-128 reqHistoricalData() 3-141, 4-223, 5-281 reqHistoricalDataEx() 3-138 reqIDs() 4-220 reqIds() 3-129 reqManagedAccts() 3-136, 4-222, 5-279 reqMktData() 3-120, 4-217, 5-274 reqMktData2() 3-121 reqMktDataEx() 3-119 reqMktDepth() 3-132, 4-220, 5-277 reqMktDepth2() 3-133 reqMktDepthEx() 3-131

reqNewsBulletins() 3-135, 4-221, 5-277 reqOpenOrders() 3-128, 4-219, 5-276 reqRealTimeBars() 3-148, 4-226, 5-283 reqRealTimeBarsEx() 3-147 reqScannerParameters() 3-144, 4-225, 5-280 reqScannerSubscription() 3-145, 4-225, 5-280 reqScannerSubscriptionEx() 3-145 Request for Quote 1-26 requestFA() 3-136, 4-222, 5-279 requesting bond contract details in ActiveX for Excel 7-375 requesting bond contract details in Excel 2-94 requesting contract details in ActiveX for Excel 7-373 requesting contract details in Excel 2-92 requesting market data, in ActiveX for Excel 7-335 requesting market data, in Excel 2-36 requesting market depth in ActiveX for Excel 7-339 in Excel 2-97 Reuters global fundamentals in ActiveX for Excel 7-387 RFQs 1-26 running execution reports in Excel 2-68 running the API through IB Gateway 1-16

S
sample program ActiveX 3-116 C++ 4-213 Java 5-265 sample spreadsheet Account page 2-69 Advanced Orders page 2-56 Advisors page 2-99 Basic Orders page 2-39 Bond Contract Details page 2-94 bracket orders in 2-57 Conditional Orders page 2-52, 7-345 Contract Details page 2-92 Executions page 2-65 Executions Reporting page 2-67 Extended Order Attributes page 2-46 Historical Data page 2-78 macros in 2-106 Market Depth page 2-96 Market Scanner page 2-84 Open Orders page 2-63 opening 2-33, 7-329 pages in 2-34, 7-330 Portfolio page 2-76 relative orders in 2-61 scale orders in 2-60 Tickers page 2-35 trailing stop limit orders in 2-59 using 2-34 viewing VB code 2-104 sample spreadsheet, installing 2-30, 7-328 scale orders in ActiveX for Excel 7-354

API Reference Guide

435

Index

scale orders, in DDE for Excel spreadsheet 2-60 scannerData() 3-180, 4-243, 5-300 scannerDataEnd() 4-243, 5-300 scannerDataEx() 3-180 scannerParameters() 3-180, 4-243, 5-300 ScannerSubscription 4-257, 5-315 server log level setting in ActiveX for Excel 7-332 serverVersion() 4-227, 5-284 setLogLevel() 4-221 setServerLogLevel() 3-135, 5-278 setting log level, on Tickers page 2-37 setting the processing rate on Tickers page 2-37 SHORTABLE tick 9-412 SocketClient Properties 4-245 SocketClient properties 4-246, 4-248, 4-250, 4-251, 4-252, 4-256, 4-257 SocketClient properties, in Java API 5-302 starting market scanner in ActiveX for Excel 7-380 starting market scanner in Excel 2-85

T
TAG values for FUNDAMENTAL_RATIOS tickType 9-413 TestJavaClient 5-265 third-party controls, for ActiveX 3-115 tickEFP() 3-155, 4-232, 5-289 ticker, creating in ActiveX for Excel 7-334 ticker, creating in Excel 2-35 Tickers page 2-35 clearing all links 2-37 in ActiveX for Excel 7-334 requesting market data 2-36 requesting market data in ActiveX for Excel 7-335 setting log level 2-37 setting the processing rate 2-37 setting the refresh rate 2-37 setting the refresh rate in ActiveX for Excel 7-336 toolbar buttons 2-38 toolbar buttons in ActiveX for Excel 7-336 Tickers page, using 2-35 Tickers page, using ActiveX for Excel 7-334 tickGeneric() 3-154, 4-231, 5-289 tickOptionComputation() 3-154, 4-231, 5-288 tickPrice() 3-153, 5-287 tickPrice()Class EWrapper Functions 4-230 tickSize() 3-153, 4-230, 5-288 tickString() 4-232, 5-289 toolbar buttons on Account page 2-75 on ActiveX for Excel Advanced Orders page 7-355 on ActiveX for Excel Advisors page 7-393 on ActiveX for Excel Basic Orders page 7-344 on ActiveX for Excel Bond Contract Details page 7-376 on ActiveX for Excel Contract Details page 7-374 on ActiveX for Excel Executions page 7-366 on ActiveX for Excel Fundamentals page 7-388 on ActiveX for Excel Historical Data page 7-372

ActiveX for Excel Market Depth page 7-339 ActiveX for Excel Market Scanner page 7-386 ActiveX for Excel Open Orders page 7-359 ActiveX for Excel Portfolio page 7-364 ActiveX for Excel Real Time Bars page 7-378 Advanced Orders page 2-62 Advisors page 2-103 Basic Orders page 2-45 Bond Contract Details page 2-95 Conditional Orders page 2-55, 7-348 Contract Details page 2-93 Executions page 2-66 FA managed accounts, in ActiveX for Excel Account page 7-362 on Historical Data page 2-83 on Market Depth page 2-98 on Market Scanner page 2-91 on Open Orders page 2-64 on Portfolio page 2-77 toolbar buttons, on ActiveX for Excel Bulletins page 7-337 toolbar buttons, on ActiveX for Excel General page 7-333 toolbar buttons, on ActiveX for Excel Tickers page 7-336 toolbar buttons, on Tickers page 2-38 trailing stop limit orders, in ActiveX for Excel 7-353 trailing stop limit orders, in DDE for Excel spreadsheet 2-59 TWS linking from Java 5-262 TWS precautionary settings 1-23 TWS, configuring for API 1-15, 2-31 TWS, linking from C++ 4-208 TWS, linking using ActiveX 3-114 TwsConnectionTime() 4-227, 5-284 TwsSocketClient.dll 4-208 linking to 4-208

on on on on on on on on on on on on on

U
udpateMktDepthL2() 5-298 uninstalling the API software 1-28 updateAccountTime() 3-171, 4-238, 5-295 updateAccountValue() 3-168, 4-237, 5-294 updateMktDepth() 3-175, 4-240, 5-297 updateMktDepthL2 5-298 updateMktDepthL2() 3-176, 4-240 updateNewsBulletin() 3-176, 4-241, 5-298 updatePortfolio() 3-170, 4-238, 5-295 updatePortfolioEx() 3-169 using Account page in ActiveX for Excel 7-360 using Account page in Excel 2-70 using API components 1-14 using the ActiveX for Excel sample spreadsheet 7-330 using the ActiveX for Excel Tickers page 7-334 using the Market Depth page in ActiveX for Excel 7-339 using the Market Depth page in Excel 2-97 using the sample spreadsheet 2-34 using the Tickers page 2-35

API Reference Guide

436

Index

V
VB code, in sample spreadsheet 2-104 VB modules 2-105 VB_API_sample.vbp opening 3-116 VBE 2-104 viewing executions, in ActiveX for Excel 7-366 viewing executions, in Excel 2-65 viewing historical data in ActiveX for Excel 7-368 viewing historical data in Excel 2-79 viewing open orders in ActiveX for Excel 7-359

viewing open orders in Excel 2-64 viewing portfolio data in Excel 2-76 viewing portfolio data in FA managed accounts, in ActiveX for Excel 7-363 Visual Basic Editor 2-104 Visual Basic sample program, for ActiveX 3-116 VOL orders in ActiveX for Excel 7-352

W
winError() 4-235

API Reference Guide

437