---
name: ibkr-gateway-python
description: Use when working in mm-ibkr-gateway to access market data, account summary, positions, PnL, or orders directly in Python via ibkr_core. Covers connecting with IBKRClient, using market/account/order helpers, and safety rules for preview, place, cancel, and status.
---

# IBKR Gateway Python

## Overview

Use ibkr_core modules in Python scripts or notebooks to fetch market data, read account data, and manage orders with safety rails.

## Workflow

1. Confirm safety mode and connectivity.
   - Ensure IBKR Gateway or TWS is running on the configured host/port.
   - Keep `TRADING_MODE=paper` and `ORDERS_ENABLED=false` unless explicitly asked to enable live trading.
   - For offline testing, set `IBKR_MODE=simulation` and use `get_ibkr_client` from `ibkr_core.simulation`.

2. Create and connect a client.
   - Use `IBKRClient(mode="paper")` or `get_ibkr_client()` (respects `IBKR_MODE`).
   - Call `client.connect()` and `client.disconnect()`.

3. Use market data, account, and order helpers.
   - Market data: `get_quote`, `get_quotes`, `get_historical_bars`, `get_streaming_quote`, `get_quote_with_mode`
   - Account: `get_account_summary`, `get_positions`, `get_pnl`, `get_account_status`, `list_managed_accounts`
   - Orders: `preview_order`, `place_order`, `get_order_status`, `cancel_order`, `get_open_orders`, `cancel_order_set`
   - Pass `account_id` when targeting a specific account; omit to use the first managed account.

4. Prefer preview-first order flow.
   - Call `preview_order` before `place_order`.
   - If `ORDERS_ENABLED=false`, `place_order` returns `SIMULATED`.

## References

- `references/python-usage.md` for import lists and code examples.
- `ibkr_core/models.py` and `docs/SCHEMAS.md` for field names and order types.
- `notebooks/02_market_data.ipynb`, `notebooks/03_account_status.ipynb`, and `notebooks/04_orders.ipynb` for end-to-end workflows.