IBKR setup wizard

Prepare TWS or IB Gateway for your first API connection

Use this guided checklist to record the workstation, port, socket settings, client ID, and first verification result before connecting Python tools or automated services.

Safety first

This page is educational and technical only. It is not financial, investment, trading, tax, or legal advice. Prefer paper trading, read-only API checks, and small reversible tests before any live workflow.

Checklist

Setup path

Choose the workstation you want to connect

Use Trader Workstation (TWS) when you also want the full desktop trading interface open.
Use IB Gateway when you want a smaller login session dedicated to API connectivity.
Start with the paper environment until your connection, permissions, and code paths are verified.

Confirm the socket port before writing code

TWS commonly uses port 7497 for paper sessions and 7496 for live sessions.
IB Gateway commonly uses port 4002 for paper sessions and 4001 for live sessions.
If you changed the port in settings, write down the custom value and use that exact number in your client.

Enable local API socket access

In TWS or Gateway, open the API settings and enable socket clients.
Keep trusted IP access narrow. Local examples should connect to 127.0.0.1 or localhost.
Consider read-only API access for the first verification pass so no order placement is possible.

Pick a stable client ID

Use a unique client ID for each script, notebook, service, or manual test session.
Avoid reusing a client ID that is already connected, because IBKR can reject or replace sessions.
Record the client ID alongside the environment, port, and machine name for repeatable debugging.

Verify the first connection safely

Connect from the same machine first, then request a harmless value such as the server time.
Check that the host, port, client ID, and paper/live environment all match what you intended.
Disconnect cleanly and review any TWS or Gateway API messages before moving on to data or order examples.

Paper and live port reference

These are common defaults. Your local TWS or Gateway settings are the source of truth if they differ.

Application	Environment	Default port	Suggested use
TWS	Paper	`7497`	Interactive desktop testing
TWS	Live	`7496`	Only after paper checks pass
IB Gateway	Paper	`4002`	Headless-style paper testing
IB Gateway	Live	`4001`	Controlled production connectivity

First connection

Verification checklist

Check 1: TWS or Gateway is open, logged in, and showing the expected paper or live account.
Check 2: API socket clients are enabled and the socket port matches your chosen environment.
Check 3: Your client uses host 127.0.0.1, a unique client ID, and a read-only action for the first test.
Check 4: The connection succeeds, returns server time or account metadata, and then disconnects without errors.

Minimal verification shape

A first script should connect to 127.0.0.1, use the selected port and client ID, request server time or another non-trading value, print the result, and disconnect. Save the exact host, port, client ID, and environment with your notes.

Next step

After the checklist is complete, continue with local read-only data examples before considering any workflow that can transmit orders or modify account state.

Back to IBKR reference Home

This content is for educational and technical research purposes only. It is not financial advice, investment advice, trading advice, tax advice, or legal advice. Backtests and examples may contain errors or omissions. Past performance does not guarantee future results. Always test code in a safe environment before using it with real accounts or live trading systems.

Interactive Brokers, IBKR, Trader Workstation, and IB Gateway are trademarks or registered trademarks of their respective owners. InQuantWeTrust is independent and is not affiliated with, endorsed by, or sponsored by Interactive Brokers.