IBKR Paper TWS setup and troubleshooting for Lumiere

Before connecting: verify the account is simulated

IBKR states that the paper interface clearly indicates when a simulated account is in use. If that indication is absent, the session may be a production account and filled trades can create real obligations. Existing individual account holders can generally select production or paper trading when logging into TWS, while some account structures and regions require separate paper credentials.

Platform source: IBKR: About Paper Trading Accounts, last updated January 30, 2026 when reviewed.

Connection checklist

1. Open IBKR Paper TWS.Confirm the interface visibly identifies the account as simulated before changing any API setting.
2. Enable socket clients.Use the API settings in TWS and limit access to the local machine unless you have a separately reviewed network design.
3. Keep Read-Only API enabled.Lumiere V1 needs quotes, bars, daily volume, and connection status. It does not need customer order transmission.
4. Confirm the paper socket port.The Lumiere beta defaults to port 7497 for Paper TWS. If TWS uses a different configured port, the connector and TWS must match.
5. Start the versioned connector.Download the current artifact from the authenticated Lumiere account page and run it locally.
6. Check local health.Confirm the connector reports ready before relying on IBKR-labeled context in the Lumiere app.
7. Verify source labels in Lumiere.If broker context is unavailable, Lumiere may label another provider or unavailable state. Do not assume fallback data came from IBKR.

Platform source reviewed August 4, 2026: IBKR Campus: Installing & Configuring TWS for the API. IBKR documents the socket-client control, the Read-Only setting that blocks API orders, and default ports 7496 for live TWS and 7497 for Paper TWS. Configured ports can differ, so the connector and TWS values must match.

Paper trading limitations that matter

Because of those limitations, a successful paper fill is evidence that a workflow was practiced—not proof that the same order would fill at the same price or in the same way live.

Simulator source reviewed August 4, 2026: IBKR Campus: Paper Trading Account. IBKR identifies the environment as simulated and documents top-of-book, stop-order, complex-order, and other paper-account limitations.

Troubleshoot the failed layer, in order

Do not turn every connection failure into an application restart. First identify whether the failed layer is the simulated account, the local socket, TWS-to-IB connectivity, market-data permission, or Lumiere’s source handoff.

1. The account looks live

Stop. Do not continue until the TWS interface clearly identifies the simulated account. Lumiere’s read-only control does not change which account is open in TWS.

2. The connector cannot reach TWS

Confirm TWS is fully open, “Enable ActiveX and Socket Clients” is selected, the host is local, and the configured ports match. IBKR error 502 specifically points to disabled socket connectivity or a port mismatch.

3. The connection broke after a TWS upgrade

Recheck the API settings before changing Lumiere. IBKR’s 2026 release notes state that TWS and IB Gateway 10.45 clear “Enable ActiveX and Socket Clients” and “Allow connections from localhost only” once, with a prompt directing the user back to Global Configuration.

4. TWS reports 503 or the client reports 504

IBKR documents 503 for an out-of-date TWS or IB Gateway and 504 for a request made without a working connection. Upgrade or restore the connection before retrying the market-data request.

5. TWS reports 1100, 1101, or 1102

These are TWS-to-IB connectivity states. Code 1100 means connectivity was lost; 1101 means it returned but market-data requests were lost and must be resubmitted; 1102 means data was maintained.

6. TWS reports 1300

The socket port changed while the API client was connected. Reconnect using the new port named in the message; do not silently fall back to the live-session default.

7. Quotes are missing or delayed

Check TWS market-data permissions, subscriptions, account configuration, and connection status. IBKR notes that paper-trading permissions and market-data configuration follow the associated account.

8. Lumiere shows a fallback source

Read the source label and freshness timestamp. Treat broker-aligned context as unavailable until the IBKR lane reports ready. A fallback label is a boundary, not proof that the TWS connection recovered.

9. A paper fill differs from expectations

Compare the behavior with IBKR’s documented simulator limitations. Do not infer that production execution is broken—or that it would match the simulation.

When to collect logs—and when not to share them

IBKR documents API message logging, an option to include market data, and a Detail logging level for troubleshooting. Enable only the detail needed to reproduce a persistent connection problem, then return to the normal setting. Treat the resulting log as sensitive operational data: do not paste it into a public issue, newsletter, partner channel, or Lumiere support request unless the specific fields and transfer are privacy-reviewed.

Platform source reviewed August 4, 2026: IBKR TWS API: API Logs.

Use IBKR’s native pre-order checks too

IBKR TWS can preview commissions, margin impact, and order details before transmission, and Risk Navigator can compare current and hypothetical portfolio risk. These native tools complement a Lumiere review; neither removes market or execution risk. Follow the separate risk-first IBKR pre-trade workflow to place those broker checks after the written thesis, invalidation, dollar-risk size, and no-trade condition.