Asset Classes

Free investment financial education


Multilingual content from IBKR

Close Navigation
Learn more about IBKR accounts
Implementing Market Scanners using TWS API – Part I

Implementing Market Scanners using TWS API – Part I

Posted January 4, 2021 at 10:30 am
Mayank Rasu

The TWS market scanner functionality provided by Interactive Brokers is a very popular feature allowing traders to scan multiple products (stocks, ETFs, bonds, options etc.) across various markets (both US and non US). This feature allows users to configure their own scanners through a wide range of filters and parameters.  

Setting up and configuring a scanner tool in TWS is quite straightforward and it can be done by clicking on the “New Window” menu and then choosing the Scanners option. 

As apparent from the above screenshot, IB allows four different types of scanners and depending on your requirement you can chose and configure your scanner. Below I am sharing the screenshots of both the Mosaic Market Scanner and Advanced Market Scanner. As you can see from the images, the scanner GUI is quite intuitive and users can easily configure their scanners by choosing their parameters and tuning their filters. 

Mosaic Market Scanner lets users chose the markets and tune the filters as per requirement.  

Advanced Market Scanner gives users the additional feature of further refining their scan criteria by choosing from a wide suite of parameters such as top gainers, top gap ups and downs, fundamental ratios and even some technical indicator based parameters. 

Since this article is about implementing scanner functionality algorithmically and not manually, I leave it to the readers to use some wonderful articles and YouTube tutorials available online on how to set up and configure TWS scanners manually. I will now explain how TWS API can be used to implement scanners programmatically. 

Quick Introduction to IBAPI 

TWS API (also called IBAPI) is an interface which can be used by Interactive Brokers clients to establish connection with TWS, extract information, place trades and manage accounts programmatically. In essence, TWS API is a set of programs (supported in multiple programming languages such as C++, C#, Python, Java and VB) which allows users to automate their trading. Needless to say, some basic programming proficiency in any of the above languages is required to harness the potential of TWS API. I have used Python API in this article but the same can be replicated using any of the other supported programming languages. 

TWS API helps establish a websocket connection between TWS and your trading application (which can be a simple Python code). Once the connection is established, data can be extracted and commands executed using the websocket connection. There are two mainstays of the TWS API architecture which are the EClient and the EWrapper classes (warning – elements of object oriented programming concepts ahead J ). I would spare you the technical details in this article but essentially, the EClient class lets you send messages (such as requesting data, placing orders etc.) to the TWS and the EWrapper class helps deliver the response received from the TWS in a readable format. Below is an example of a basic trading application created using the EClient and EWrapper classes. 

This trading application does not do anything but simply establishes a persistent websocket connection with the TWS programmatically. It can be figured out from the above code that the TradingApp class inherits from the EWrapper and EClient classes meaning this trading application can harness all the functions of its two parent classes. Therefore when we created the object named “app” of TradingApp class, we made it capable of executing any function defined in the EClient class and then handling and presenting that information using the relevant EWrapper function. Another thing to note in this code is that we are connecting to port 7497 of your local machine. “” is the standard localhost address which refers to local machine. If you want to connect to the TWS remotely, you will have to provide the relevant IP address of the machine and make corresponding changes in the security settings of your TWS. Port 7497 is used to connect to the paper trading account whereas port 7496 is used for the real trading account. 

Let us expand the scope of our TradingApp and extract contract details for a given instrument. Refer below code 

You can notice a few changes in the code compared to the basic trading app but I would like to draw your attention towards the app.reqContractDetails() function call and the contractDetails function definition within TradingApp. Since we want our trading app to extract contract information, we have to use the reqContractDetails() function call on our app. This is an ECleint function specifically defined to extract contract information. However, this function call necessitated our TradingApp to define the corresponding EWrapper function (contractDetails) which is defined to handle the response from the reqContractDetails function call. The relevant EClient and EWrapper functions for various applications (such as requesting historical data, streaming market data, placing orders etc.) can be obtained from the TWS API documentation (

Below is the output that we will receive if we run above code. 

No need to get alarmed seeing all the Error messages. Error -1 code refers to generic messages sent by TWS once a connection is successfully established. We handle these messages using the error function (which is another EWrapper function defined in our Trading App). As you can see, the contract details for Apple stock was printed on the console. If you are not happy with how the message is handled by the contractDetails function, you can make the required changes in the contractDetails function. 

Stay tuned for the next installment in this series in which the author will discuss Market Scanners using TWS API.

The author can be reached at

If you found this article interesting, you may consider enrolling in the author’s TWS API course ( The course starts from the basics of TWS API and some key programming concepts such as OOPs basics and threading and then gradually delves into more advanced concepts to help you build fully automated trading applications on Interactive Brokers’ platform.  

Disclosure: Interactive Brokers

Information posted on IBKR Campus that is provided by third-parties does NOT constitute a recommendation that you should contract for the services of that third party. Third-party participants who contribute to IBKR Campus are independent of Interactive Brokers and Interactive Brokers does not make any representations or warranties concerning the services offered, their past or future performance, or the accuracy of the information provided by the third party. Past performance is no guarantee of future results.

This material is from Rasuquant and is being posted with its permission. The views expressed in this material are solely those of the author and/or Rasuquant and Interactive Brokers is not endorsing or recommending any investment or trading discussed in the material. This material is not and should not be construed as an offer to buy or sell any security. It should not be construed as research or investment advice or a recommendation to buy, sell or hold any security or commodity. This material does not and is not intended to take into account the particular financial conditions, investment objectives or requirements of individual customers. Before acting on this material, you should consider whether it is suitable for your particular circumstances and, as necessary, seek professional advice.

IBKR Campus Newsletters

This website uses cookies to collect usage information in order to offer a better browsing experience. By browsing this site or by clicking on the "ACCEPT COOKIES" button you accept our Cookie Policy.