# Interactive Brokers (IBKR) Trading Guide

QuantDinger supports US stocks and Hong Kong stocks live trading via Interactive Brokers TWS or IB Gateway.

## Overview

This feature enables automated trading execution for US and HK stock markets through your Interactive Brokers account. Once configured, your trading strategies can automatically place orders via the IBKR API.

## Prerequisites

- Interactive Brokers account
- TWS (Trader Workstation) or IB Gateway installed
- Market data subscription (for real-time quotes)

## Installation

The `ib_insync` library is already included in `requirements.txt`. If you need to install manually:

```bash
pip install ib_insync
```

## Port Reference

| Client | Live Port | Paper Port |
|--------|-----------|------------|
| TWS    | 7497      | 7496       |
| IB Gateway | 4001  | 4002       |

## TWS / IB Gateway Configuration

1. Open TWS or IB Gateway
2. Go to **Configure** → **API** → **Settings**
3. Enable the following options:
   - ✅ Enable ActiveX and Socket Clients
   - ✅ Allow connections from localhost only
4. Set Socket port (refer to the table above)
5. Click Apply / OK

## Strategy Configuration

When creating a strategy for US or HK stocks, configure the IBKR connection in the "Live Trading" section:

| Field | Description | Example |
|-------|-------------|---------|
| **Broker** | Select "Interactive Brokers" | - |
| **Host** | TWS/Gateway host address | `127.0.0.1` |
| **Port** | TWS/Gateway API port | `7497` (TWS Live) |
| **Client ID** | Unique client identifier | `1` |
| **Account** | Account ID (optional) | Leave empty to auto-select |

## Symbol Format

| Market | Format | Examples |
|--------|--------|----------|
| US Stock | Ticker symbol | `AAPL`, `TSLA`, `GOOGL`, `MSFT` |
| HK Stock | `XXXX.HK` or digits | `0700.HK`, `00700`, `700` |

## Trading Flow

```
Strategy Signal → Pending Order Queue → IBKR Execution → Position Update
```

1. Your strategy generates a buy/sell signal
2. The signal is queued as a pending order
3. The background worker connects to IBKR and executes the order
4. Position and trade records are updated

## Supported Signal Types

| Signal | Action | Description |
|--------|--------|-------------|
| `open_long` | BUY | Open a long position |
| `add_long` | BUY | Add to existing long position |
| `close_long` | SELL | Close long position |
| `reduce_long` | SELL | Reduce long position |

> **Note**: Short selling is not supported in the current implementation.

## API Endpoints

### Connection Management

```
GET  /api/ibkr/status          # Get connection status
POST /api/ibkr/connect         # Connect to TWS/Gateway
POST /api/ibkr/disconnect      # Disconnect
```

### Account Queries

```
GET  /api/ibkr/account         # Account information
GET  /api/ibkr/positions       # Current positions
GET  /api/ibkr/orders          # Open orders
```

### Trading

```
POST   /api/ibkr/order         # Place order
DELETE /api/ibkr/order/<id>    # Cancel order
```

### Market Data

```
GET  /api/ibkr/quote?symbol=AAPL&marketType=USStock
```

## Usage Examples

### Test Connection (via curl)

```bash
curl -X POST http://localhost:5000/api/ibkr/connect \
  -H "Content-Type: application/json" \
  -d '{"host": "127.0.0.1", "port": 7497, "clientId": 1}'
```

### Place Order

```bash
# Market order: buy 10 shares of AAPL
curl -X POST http://localhost:5000/api/ibkr/order \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL", "side": "buy", "quantity": 10, "marketType": "USStock"}'

# Limit order: sell 100 shares of Tencent
curl -X POST http://localhost:5000/api/ibkr/order \
  -H "Content-Type: application/json" \
  -d '{"symbol": "0700.HK", "side": "sell", "quantity": 100, "marketType": "HShare", "orderType": "limit", "price": 300}'
```

## Important Notes

1. **TWS/Gateway must be running**: Ensure TWS or IB Gateway is started and logged in before trading
2. **Market data subscription**: Real-time quotes may require market data subscription from IBKR
3. **Client ID**: Use different clientId if multiple programs connect to the same TWS/Gateway
4. **Account selection**: Specify `account` parameter if you have multiple sub-accounts
5. **Trading hours**: Orders will only execute during market hours

## Troubleshooting

| Error | Cause | Solution |
|-------|-------|----------|
| Connection failed | TWS/Gateway not running | Start and login to TWS/Gateway |
| Connection failed | Wrong port | Check API port setting in TWS/Gateway |
| Connection failed | API not enabled | Enable Socket API in TWS/Gateway settings |
| Client ID conflict | Same clientId already connected | Use a different clientId |
| Invalid contract | Wrong symbol format | Check symbol format |
| Order rejected | Insufficient funds/margin | Check account balance |

## Docker Deployment

When running QuantDinger in Docker, TWS/IB Gateway must be accessible from the container:

1. Run TWS/Gateway on host machine
2. Use `host.docker.internal` as the host address (Docker Desktop)
3. Or configure host network mode

## Security Recommendations

- Only enable "Allow connections from localhost only" in TWS/Gateway
- Use paper trading account for testing
- Set appropriate position limits in your strategy
- Monitor your account regularly

## See Also

- [Python Strategy Development Guide](STRATEGY_DEV_GUIDE.md)
- [Interactive Brokers API Documentation](https://interactivebrokers.github.io/tws-api/)
