Metadata-Version: 2.4
Name: qx_ibbridge
Version: 1.0.0
Summary: Drop-in FastAPI + SDK bridge for ib_async and ib_insync-style Interactive Brokers workflows
Author-email: Alpha Quant Capital <vignesh@alphaquantcapital.com>
Project-URL: Homepage, https://superinvestor.io
Project-URL: Documentation, https://superinvestor.io
Project-URL: Company, https://fund.alpha-techlab.com
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn[standard]>=0.23
Requires-Dist: ib_async>=2.1
Requires-Dist: websockets>=11
Requires-Dist: requests>=2.31
Requires-Dist: websocket-client>=1.7
Provides-Extra: desktop
Requires-Dist: customtkinter>=5.2; extra == "desktop"
Requires-Dist: pillow; extra == "desktop"
Requires-Dist: pyinstaller>=6.0; extra == "desktop"
Dynamic: license-file

<p align="center">
  <img src="assets/app-logo.png" width="72" height="72" alt="QX-IB Bridge Server">
</p>

<h1 align="center">QuantX-IB Bridge Server</h1>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/framework-FastAPI-009688" alt="FastAPI">
  <img src="https://img.shields.io/badge/protocol-WebSocket%20%2B%20HTTP-6B46C1" alt="WebSocket + HTTP">
  <img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License">
</p>

<p align="center">
  One IB connection. Every script shares it. Zero <code>clientId</code> collisions.
</p>

---

`QX-IB Bridge Server` is a **thin multiplexer** for traders already using
`ib_async`, `ib_insync`, or direct IB Gateway/TWS scripts who have hit the
same scaling wall: too many strategies, too many direct broker connections,
and too many `clientId` conflicts. It is a FastAPI + SDK wrapper around
`ib_async`, not a reimplementation of the IB stack, so the wire protocol,
order state machines, and ticker logic still come from the real
`ib_async.IB`.

Instead of opening many separate broker API sessions, the bridge keeps one
managed IB connection alive and lets the rest of your scripts share it through
a local HTTP/WebSocket layer. In practice, that means one real IB connection,
many strategies, and a near-drop-in migration path.

> This is not a replacement for the Interactive Brokers Python ecosystem. It is an **operational
> upgrade** for people already in it.

## Why it exists

| Without a bridge                                                     | With QuantX-IB Bridge                             |
| -------------------------------------------------------------------- | ------------------------------------------------- |
| Every script connects directly to IB Gateway/TWS                     | One bridge process owns the real IB connection    |
| Every script consumes an API client slot                             | Many scripts share a single connection            |
| `clientId` collisions and contention                               | No collisions — bridge manages the single client |
| Scaling means connection juggling and manual `clientId` discipline | Scaling stays inside one shared bridge            |

## Architecture at a glance

```
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  Strategy 1 │   │  Strategy 2 │   │  Strategy N │
│  (SDK)      │   │  (SDK)      │   │  (SDK)      │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │ HTTP/WS         │ HTTP/WS         │ HTTP/WS
       └─────────────────┼─────────────────┘
                         ▼
              ┌─────────────────────┐
              │  QX-IB Bridge       │
              │  FastAPI Server     │
              │  (single process)   │
              └──────────┬──────────┘
                         │ ib_async.IB
                         ▼
              ┌─────────────────────┐
              │  IB Gateway / TWS   │
              │  (1 connection)     │
              └─────────────────────┘
```

**What ib_async does** (you don't touch): wire protocol, serialization, order
state machines, ticker price aggregation, event loop management.

**What the bridge does**: keeps one managed IB session open, exposes it over a
local FastAPI + WebSocket server, and gives existing IB Python code a much
cleaner way to scale.

## What you keep

- Familiar `IB()` / `connect()` / `disconnect()` usage
- Familiar request patterns like `reqHistoricalData()`, `placeOrder()`, `positions()`
- Your existing Python scripts and strategy layout

## What changes

- One import line: `from qx_ibbridge import *`
- Your scripts point at the local bridge instead of the raw broker socket

## Quick start

Install the package:

```bash
pip install qx_ibbridge
```

Start the IB Gateway:

1. Download the latest IB Gateway from [Interactive Brokers](https://www.interactivebrokers.com/en/trading/ibgateway-latest.php)
2. Install and launch IB Gateway
3. Log in with your Interactive Brokers credentials
4. Ensure it listens on `localhost:4004` (default)

Start the bridge:

```bash
qx-server --ib-host localhost --ib-port 4004 --host 127.0.0.1 --port 4002
```

Default local model:

- external IB Gateway/TWS API socket: `localhost:4004`
- local QuantX bridge server: `localhost:4002`

## Drop-in SDK workflow

The same `pip install qx_ibbridge` package gives you both:

- the `qx-server` CLI for running the bridge server
- the `qx_ibbridge` import for drop-in strategy scripts

Then change your script from:

```python
from ib_async import *
# or
from ib_insync import *
```

to:

```python
from qx_ibbridge import *
```

and keep the same shape:

```python
ib = IB()
ib.connect(host="localhost", port=4002)
print(ib.managedAccounts())
```

The SDK defaults to the local bridge at `localhost:4002`.

For `ib_async` users, this is the intended drop-in path. For `ib_insync`
users, the workflow is the same in spirit: keep your IB-style code, but route
it through one local bridge instead of many direct broker sessions.

## Use it your way

### 1. Python

```bash
qx-server --ib-host localhost --ib-port 4004 --host 127.0.0.1 --port 4002
```

### 2. Desktop app

<p align="center">
  <img src="assets/server-app-screenshot.png" width="500" alt="QuantX IB Bridge Server Desktop App">
</p>

Download the latest desktop app from
[GitHub Releases](https://github.com/KVignesh122/qx-ib-bridge/releases).

If you prefer to launch the desktop UI from Python instead of downloading the
packaged app:

```bash
pip install "qx_ibbridge[desktop]"
qx-ib-bridge-server-desktop
```

The desktop app is optional. It is only a launcher for the same bridge server,
for users who prefer clicking a UI over running `qx-server`. It does not bundle
IB Gateway, and it does not change the underlying bridge or SDK behavior. The
core product already works through `pip install qx_ibbridge`; the desktop app
is only an add-on for server-launch convenience.

## Examples

- [sample.py](sample.py): direct `ib_async` example against raw IB Gateway/TWS
- [sample_copy.py](sample_copy.py): bridge example using `qx_ibbridge`

## Project layout

| Directory                | Purpose                               |
| ------------------------ | ------------------------------------- |
| `server/`              | Canonical FastAPI implementation      |
| `ib_bridge_server/`    | Generic Python server package and CLI |
| `qx_ibbridge/`         | Drop-in SDK package                   |
| `qx_ib_bridge_server/` | Desktop launcher                      |

## Behind this repo

<p align="center">
  <img src="assets/quantx-logo-text.png" height="48" alt="QuantX" style="margin-right: 32px">
  <img src="assets/alpha-logo.png" height="48" alt="Alpha Technologies">
</p>

QX-IB Bridge Server is open-sourced by **Alpha Technologies**.

Across the broader ecosystem, the team builds investor education, quant
research, and operating workflows around systematic, data-driven trading.

- [superinvestor.io](https://superinvestor.io) and [alpha-techlab.com](https://alpha-techlab.com) — QuantX hands-on learning, guided
  challenges, live market sessions, and practical quant-investing courses
- [fund.alpha-techlab.com](https://fund.alpha-techlab.com) — Regulated fund management and investors entry
  point

## Acknowledgements

This project stands on the work of two open-source efforts:

- **[ib_async](https://github.com/ib-api-reloaded/ib_async)** — the actively maintained IB API library that this bridge wraps. The bridge server delegates all wire-protocol, order state machine, and ticker logic to `ib_async.IB`, and the SDK re-exports its contract and order types so existing scripts keep working without change.

- **[ib_insync](https://github.com/erdewit/ib_insync)** by Ewald de Wit — the original Python IB API library whose elegant synchronous-style API design this SDK is compatible with. `ib_async` is itself a maintained fork of `ib_insync`.

## Disclaimer

This software is provided "as is" without warranty of any kind. It is not
financial advice, a solicitation to trade, or a guarantee of profitability.
You are solely responsible for any trades placed using this software. The
authors and contributors are not liable for any financial losses incurred.

## Notes

- Not affiliated with Interactive Brokers
- IB Gateway/TWS remains external and user-managed
- This bridge solves `clientId` contention but does not remove IB pacing,
  market data, or broker-side account limits
- Released under the Apache License 2.0; see [LICENSE](LICENSE)
- Never commit IB credentials to this repository

See also:

- [CHANGELOG.md](CHANGELOG.md)
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [SECURITY.md](SECURITY.md)
