Metadata-Version: 2.3
Name: pfund-ibapi
Version: 10.42.1
Summary: Interactive Brokers TWS Python API repackaged for easy install
Author: IBG LLC, Stephen Yau
Author-email: IBG LLC <api@interactivebrokers.com>, Stephen Yau <softwareentrepreneer+pfund-ibapi@gmail.com>
License: TWS API Non-Commercial License
         This TWS API Non-Commercial License ("License") is an agreement between Interactive Brokers LLC ("IB") and You, and governs Your use of the API Code. By clicking the "I AGREE" button below, you acknowledge that You consent to be legally bound by this Agreement.
         
         0. Introduction. IB has developed application program interface ("API") code to permit its customers to use their own internal proprietary software tools in managing their accounts with IB. This License is intended only for users who wish to use the API Code by itself as is, or in connection with or for the development of their own internal proprietary tools to manage their own IB accounts. This License is NOT for anybody who is developing software applications that they wish to: (a) sell to third party users for a fee, or (b) give to third party users to generate an indirect financial benefit (e.g., commissions). If You wish to make a software application for the purposes described in the preceding sentence then please contact Shail Mangla at opensource@interactivebrokers.com.
         
         1. Definitions.
         1.1. "API Code" means the client code for IB's Trader Workstation API that is made available to You.
         
         1.2. "Non-Commercial Purposes" means using API Code by itself as is, or in connection with or for the development of applications, programs, or other works that (a) interface with IB's trading platform, and (b) allow You to access Your account information, access market data, perform analytics, enter orders, or perform any other transactions or functions all in connection with Your account at IB.
         
         1.3. "You" or "Your" means an individual or a legal entity exercising rights under this License. For legal entities, "You" or "Your" includes any entity which controls, is controlled by, or is under common control with, You, where "control" means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of fifty percent (50%) or more of the outstanding shares or beneficial ownership of such entity.
         
         2. License Grant.
         2.1. Subject to the terms of this License, IB hereby grants You, effective on the date You accept this License and download the API Code, a personal, royalty-free, non-exclusive, non-sublicensable, non-transferable, restricted right and license to install, modify and use the API Code solely for Non-Commercial Purposes.
         
         3. Restrictions.
         3.1. You acknowledge and agree that You shall only use the API Code for Non-Commercial Purposes. Any other uses of the API Code are expressly prohibited.
         
         3.2. You must retain and reproduce in all copies of API Code the copyright and other proprietary notices and disclaimers of IB as they appear in the API Code, and keep intact all notices in the API Code that refer to this License.
         
         3.3. You agree not to publish, disseminate, or redistribute the API Code to any third party.
         
         3.4. You agree that You will maintain an account at IB for the duration of this License.
         
         3.5. You agree not to use the API for any purpose that violates any law or regulation, any right of any person, including but not limited to intellectual property rights, rights of privacy, or rights of personality, or in any manner inconsistent with IB's terms of use, privacy policy or this License.
         
         4. Ownership of API Code.
         4.1. Except as expressly set forth herein, IB or its licensors shall own all right, title and interest in and to the API Code.
         
         5. DISCLAIMER OF WARRANTIES.
         5.1. You expressly acknowledge and agree that although IB grants the license to the API Code set forth herein, IB and its licensors provide no assurances that the API Code does not infringe the patent or other intellectual property rights of any other entity. IB and its licensors disclaim any liability to You for claims brought by any other person or entity based on infringement of intellectual property rights or otherwise.
         
         5.2. The API Code may contain in whole or in part pre-release, untested, or not fully tested works. The API Code may contain errors that could cause failures or loss of data, and may be incomplete or contain inaccuracies. You expressly acknowledge and agree that use of the API Code, or any portion thereof, is at Your sole and entire risk. YOU UNDERSTAND AND AGREE THAT THE API CODE IS PROVIDED "AS IS" AND ON AN "AS-AVAILABLE" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE API CODE IS FREE OF DEFECTS, MERCHANTABLE, NON-INFRINGING OR FIT FOR A PARTICULAR PURPOSE. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY API CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
         
         6. LIMITATION OF LIABILITY.
         6.1. YOU UNDERSTAND AND AGREE THAT IB, ITS AFFILIATES, AND ITS LICENSORS SHALL NOT BE LIABLE TO YOU UNDER ANY THEORY OF LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES IN CONNECTION WITH OR ARISING OUT OF OR RELATING TO THE API CODE OR THE USE OF THE API CODE, INCLUDING ANY TRADING LOSS, LOSS OF PROFIT, LOSS OF BUSINESS, OR LOSS OF DATA, WHETHER OR NOT IB OR ITS REPRESENTATIVES HAVE BEEN ADVISED OF OR SHOULD HAVE BEEN AWARE OF THE POSSIBILITY OF ANY SUCH LOSSES ARISING.
         7. Indemnification.
         7.1. To the maximum extent permitted by law, You agree to defend, indemnify and hold harmless IB, its affiliates and their respective directors, officers, employees and agents from and against any and all claims, actions, suits or proceedings, as well as any and all losses, liabilities, damages, costs and expenses (including reasonable attorneys fees) arising out of or accruing from (a) Your use of the API Code, (b) any application You develop with the API Code that infringes any copyright, trademark, trade secret, trade dress, patent or other intellectual property right of any person, and (c) any non-compliance by You with this License.
         
         8. Termination.
         8.1. This License and the rights granted hereunder will terminate automatically: (a) if You fail to comply with any term(s) of this License and fail to cure such breach within 30 days of becoming aware of such breach; (b) if You are no longer a customer of IB; or (c) if You, at any time during the term of this License, commence an action for patent infringement against IB (provided that IB did not first commence an action for patent infringement against You in that instance).
         
         8.2. You shall destroy all copies of the API Code upon termination of this License, and shall not retain the API Code in any form after such destruction.
         
         8.3. The following sections shall survive any termination: 3, 4, 5, 6, 7, 8, and 9.
         
         9. General.
         9.1. You agree that if IB does not exercise or enforce any legal right or remedy which is contained in this License or is available to IB under any applicable law), this will not be taken to be a formal waiver of IB's rights and that those rights or remedies will still be available to IB.
         
         9.2. If any court of law, having the jurisdiction to decide on this matter, rules that any provision of this License is invalid, then that provision will be removed from this License without affecting the rest of this License. The remaining provisions of this License will continue to be valid and enforceable.
         
         9.3. This License constitutes the whole legal agreement between You and IB and governs Your use of the API Code, and completely replaces any prior agreements between You and IB in relation to the API Code.
         
         9.4. If You are entering into this Agreement on behalf of your employer or other entity, You represent and warrant that You have full legal authority to bind your employer or such entity to this Agreement.
         
         9.5. You may not assign the rights granted in this License without IB's prior written approval.
         
         9.6. This License shall be governed by the laws of the State of Connecticut without regard to its conflicts of laws provisions. You agree to submit to the exclusive jurisdiction of the courts located within the county of Fairfield, Connecticut to resolve any legal matter arising from this License. Notwithstanding this, You agree that IB shall be allowed to apply for injunctive remedies in any jurisdiction.
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: protobuf==5.29.5
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# pfund-ibapi
Interactive Brokers TWS Python API repackaged for easy install

Python API (the `ibapi` folder) was downloaded from https://interactivebrokers.github.io/index.html.

## Installation
```bash
pip install pfund-ibapi
```

## Documentation
https://www.interactivebrokers.com/campus/ibkr-api-page/twsapi-doc/

---
### TODO:
- set up CI/CD pipeline to download IBKR TWS API, build and publish to PyPI.
- attach original zip file to the release.
---
Below is the original README.md from the IBKR TWS API solely for reference.

**Installation Guide for TWS API Library**

This guide provides step-by-step instructions for setting up the TWS API library, including creating virtual environments using both Anaconda and standard Python, building distributions, and testing the installation.

*Please see Understanding Code Organization and Functionality section at the bottom for  an explanation of the key terms, conventions, and code organization used.*

Step 1: Clone the TWS API repository and set up a virtual environment:

- Open a terminal or Anaconda prompt on your Windows laptop.
- Change to the directory where you want to store the TWS API repository.
- Clone the TWS API repository from GitHub using git:

```bash
git clone https://github.com/your_username/tws-api.git
```

Replace `your_username` with your actual GitHub username.

Step 2: Create a new Python virtual environment (using Anaconda):

- First, ensure you are within the '\tws-api\source\pythonclient' folder inside the "tws-api" repository:

```Anaconda Prompt
cd tws-api/source/pythonclient
```

- Create a new Python virtual environment using Anaconda:

```Anaconda Prompt
conda create -n tws_env python=3.9
```

Replace `tws_env` with your desired environment name. Here, we are using Python 3.9 as an example, but you can choose another Python version if needed.

- *Alternative: Create a new Python virtual environment without Anaconda:*

```bash
python3 -m venv tws_env
```

Replace `tws_env` with your desired environment name.

Step 3: Activate the virtual environment:

- Activate the newly created virtual environment:

```Anaconda Prompt
conda activate tws_env
```

- *Alternative: Activate the virtual environment without Anaconda:*

```bash
source tws_env/bin/activate
```

Step 4: Install the TWS API library:

- Build the source distribution:

```Anaconda Prompt
python setup.py sdist
```

- Build the wheel distribution:

```Anaconda Prompt
python setup.py bdist_wheel
```

- Retrieve the wheel distribution file name from the dist folder under the tws-api/source/pythonclient folder:

  For instance, if the wheel distribution file name is `ibapi-9.76.1-py3-none-any.whl`

- Install the wheel distribution using `pip` with the `--user` flag using the following command:

```Anaconda Prompt
python3 -m pip install --user --upgrade dist/ibapi-9.76.1-py3-none-any.whl
```

Step 5: Create a new Jupyter kernel with the virtual environment:

- Install Jupyter if you haven't already (skip this step if you have Jupyter installed):

```Anaconda Prompt
conda install jupyter
```

- Install the ipykernel package to enable creating a Jupyter kernel for the virtual environment:

```Anaconda Prompt
conda install ipykernel
```

- Create a new Jupyter kernel for the virtual environment:

```Anaconda Prompt
python -m ipykernel install --user --name tws_env --display-name "TWS Environment"
```

Replace `tws_env` with the same environment name used in Step 2.

Step 6: Open Jupyter Notebook and select the new kernel:

- Launch Jupyter Notebook:

```Anaconda Prompt
jupyter notebook
```

Step 7: Create a new Jupyter Notebook and test the TWS API library installed:

- In the Jupyter Notebook interface, create a new notebook by clicking on "New" and then selecting "TWS Environment" from the list of available kernels.

- Run the following code in the first cell of the notebook to test the TWS API library:
```
import ibapi

print("TWS API version:", ibapi.__version__)
```
Congratulations, now you have a new Jupyter Notebook with the TWS API library installed in the virtual environment, and you can start coding and testing your trading strategies using the TWS API.



**Understanding Code Organization and Functionality**

This section provides insights into how the TWS API library is structured, how messages are received and sent, and how to interact with the Wrapper class for handling incoming messages. Understanding these concepts will help you effectively utilize the TWS API for your trading automation needs.

A couple of things/definitions/conventions:
* a *low level message* is some data prefixed with its size
* a *high level message* is a list of fields separated by the NULL character; the fields are all strings; the message ID is the first field, the come others whose number and semantics depend on the message itself
* a *request* is a message from client to TWS/IBGW (IB Gateway)
* an *answer* is a message from TWS/IBGW to client


How the code is organized:
* *comm* module: has tools that know how to handle (eg: encode/decode) low and high level messages
* *Connection*: glorified socket
* *Reader*: thread that uses Connection to read packets, transform to low level messages and put in a Queue
* *Decoder*: knows how to take a low level message and decode into high level message
* *Client*:
  + knows to send requests
  + has the message loop which takes low level messages from Queue and uses Decoder to transform into high level message with which it then calls the corresponding Wrapper method
* *Wrapper*: class that needs to be subclassed by the user so that it can get the incoming messages


The info/data flow is:

* receiving:
  + *Connection.recv_msg()* (which is essentially a socket) receives the packets
    - uses *Connection._recv_all_msgs()* which tries to combine smaller packets into bigger ones based on some trivial heuristic
  + *Reader.run()* uses *Connection.recv_msg()* to get a packet and then uses *comm.read_msg()* to try to make it a low level message. If that can't be done yet (size prefix says so) then it waits for more packets
  + if a full low level message is received then it is placed in the Queue (remember this is a standalone thread)
  + the main thread runs the *Client.run()* loop which:
    - gets a low level message from Queue
    - uses *comm.py* to translate into high level message (fields)
    - uses *Decoder.interpret()* to act based on that message
  + *Decoder.interpret()* will translate the fields into function parameters of the correct type and call with the correct/corresponding method of *Wrapper* class

* sending:
  + *Client* class has methods that implement the _requests_. The user will call those request methods with the needed parameters and *Client* will send them to the TWS/IBGW.


Implementation notes:

* the *Decoder* has two ways of handling a message (essentially decoding the fields)
    + some message very neatly map to a function call; meaning that the number of fields and order are the same as the method parameters. For example: Wrapper.tickSize(). In this case a simple mapping is made between the incoming msg id and the Wrapper method:

    IN.TICK_SIZE: HandleInfo(wrap=Wrapper.tickSize), 

    + other messages are more complex, depend on version number heavily or need field massaging. In this case the incoming message id is mapped to a processing function that will do all that and call the Wrapper method at the end. For example:

    IN.TICK_PRICE: HandleInfo(proc=processTickPriceMsg), 