# 🔴 CRITICAL ISSUE: TWS API Handshake Timeout
## Current Status: Connection Blocked
### Diagnosis Complete ✅
Your diagnostic output shows:
```
INFO:ib_async.client:Connecting to 127.0.0.1:7496 with clientId 0...
INFO:ib_async.client:Connected ← Socket works ✅
ERROR:ib_async.client:API connection failed: TimeoutError() ← API fails ❌
```
**Translation:**
- ✅ TWS is running on port 7496
- ✅ Network/socket connection works (telnet succeeds)
- ✅ ib_async can connect to the socket
- ❌ **TWS is NOT completing the IB API handshake**
## The Problem
The IB API requires a specific handshake protocol after the socket connects. TWS is not responding to this handshake, which means:
**TWS API is either:**
1. Not enabled properly in settings
2. Blocking the connection for security reasons
3. In a bad state and needs restart
## The Solution
### 🔥 MOST LIKELY FIX: TWS API Settings
**Go to TWS:**
```
File → Global Configuration → API → Settings
```
**Make sure these are set:**
- ✅ **"Enable ActiveX and Socket Clients"** = CHECKED
- ✅ **Socket port** = 7496
- ✅ **"Read-Only API"** = UNCHECKED (unless you only want read-only)
- ✅ If "Allow connections from localhost only" = CHECKED
- Then **"Trusted IP Addresses"** MUST include `127.0.0.1`
**CRITICAL:** After changing ANY settings:
1. Click "OK"
2. **Completely QUIT TWS** (File → Exit)
3. Wait 10 seconds
4. **Restart TWS**
5. Log in and wait for it to fully load
6. Try the connection again
### 🧪 Test After Restart
```bash
# Run the minimal test
uv run python test_minimal_tws.py
```
**Expected when working:**
```
✅ SUCCESS! API connection established.
📊 Connected accounts: ['DU123456']
✅ TWS API IS WORKING CORRECTLY
```
## Files Created for You
1. **`test_minimal_tws.py`** - Simplest possible connection test
```bash
uv run python test_minimal_tws.py
```
2. **`test_tws_connection.py`** - Full diagnostic with verbose logging
```bash
uv run python test_tws_connection.py --client-id 0
```
3. **`docs/TWS_API_HANDSHAKE_TIMEOUT.md`** - Complete troubleshooting guide
## Quick Actions
### Action 1: Verify TWS Settings ⚡
```
TWS → File → Global Configuration → API → Settings
✓ Enable ActiveX and Socket Clients
✓ Socket port = 7496
✓ Trusted IPs includes 127.0.0.1
→ Click OK
→ RESTART TWS (completely quit and restart)
```
### Action 2: Test Again
```bash
uv run python test_minimal_tws.py
```
### Action 3: If Still Failing
Check TWS logs for error messages:
- Windows: `C:\Users\<you>\Jts\<you>\log\api.*.log`
- Mac/Linux: `~/Jts/<you>/log/api.*.log`
Look for messages about rejected connections or authentication errors.
## Alternative: Try IB Gateway
If TWS continues to fail, IB Gateway is more reliable for API access:
1. Download IB Gateway (lighter than TWS)
2. Configure for API connections
3. Use port 4001 (live) or 4002 (paper)
4. Update .env: `TWS_PORT=4001`
## What We've Ruled Out
- ❌ Event loop issues (fixed by migrating to ib_async)
- ❌ Network/firewall blocking (telnet works)
- ❌ Wrong port (7496 is confirmed listening)
- ❌ ib_async library issues (connects to socket fine)
- ❌ Client ID conflicts (tried multiple IDs)
## What It Is
- ✅ **TWS API configuration or state issue**
The handshake requires TWS to actively respond. It's listening but not responding = configuration or TWS state problem.
## Status
🔴 **BLOCKED** - Waiting for TWS API to be properly configured
**Next Step:** Fix TWS API settings, restart TWS, run `test_minimal_tws.py`
