DinQuant/backend_api_python/app/services/ibkr_trading/README.md

Interactive Brokers Trading Module

Supports US stocks trading via TWS or IB Gateway.

Installation

pip install ib_insync

Or the dependency is already in requirements.txt.

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

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

Connect

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

# 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 MSFT
curl -X POST http://localhost:5000/api/ibkr/order \
  -H "Content-Type: application/json" \
  -d '{"symbol": "MSFT", "side": "sell", "quantity": 100, "marketType": "USStock", "orderType": "limit", "price": 400}'

Get Positions

curl http://localhost:5000/api/ibkr/positions

Symbol Format

Market	Format	Examples
US Stock	Ticker symbol	AAPL, TSLA, GOOGL

Important Notes

1. TWS/Gateway must be running: Ensure TWS or IB Gateway is started and logged in before using the API
2. Market data subscription: Real-time quotes may require market data subscription
3. Client ID: Use different clientId if multiple programs connect to the same TWS/Gateway
4. Readonly mode: Set readonly: true to only query without trading
5. Multi-account: Specify account parameter if you have multiple sub-accounts

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

Removing This Module

To remove this module, delete the following files/directories:

backend_api_python/app/services/ibkr_trading/    # Entire directory
backend_api_python/app/routes/ibkr.py            # Route file

Then remove the related import and registration code in app/routes/__init__.py.

Docker Note

When running in Docker, IBKR trading requires TWS/IB Gateway to be accessible from the container. For local deployment, you can:

1. Run TWS/Gateway on host machine
2. Use host network mode or configure port mapping
3. Set host to the host machine's IP address (e.g., host.docker.internal on Docker Desktop)

Note

: IBKR connection parameters are configured per-strategy in the frontend, not via environment variables.