Getting IBKR Paper Trading Connected from Scratch: Ports, API Settings and the First Session

An IBKR paper account takes a few minutes to open. The time goes into the middle part: the desktop application is installed, the API switch is ticked, the port is filled in, and the software still will not connect — or it connects and then shows no market data, or refuses every order. This article walks that stretch in the order a first setup actually happens, and ends with a table organised by symptom.

Everything below happens on your machine, with your account. There is no step that requires handing credentials to anyone.

Separate the three layers first

Beginners tend to merge three things whose failure modes look nothing alike:

• The IBKR desktop application (TWS or IB Gateway). It logs in, holds the session and relays API calls to IBKR. If it is not running, your software can never connect.
• The paper account. An account environment inside IBKR. It decides which balances, positions and orders you are talking to. Swapping between paper and live changes the port, the account number and possibly the market data permissions.
• Your trading software. It connects over a local socket to the layer above and then manages subscriptions, contracts, orders and reconciliation itself.

When the API documentation says "client", it means the third layer. A large share of "it won't connect" problems are in the first layer or the second.

Before touching any setting

1. Have an IBKR account that can log in, with a paper account enabled. In most cases the paper account comes with the main account; if not, create it in account management.
2. Install TWS or IB Gateway — one is enough. We covered the difference in IB Gateway vs TWS for API connections: take TWS if you want a visible interface, IB Gateway if you want a lighter connection layer.
3. Log in to the desktop application manually once. Confirm the account, the balances and contract search all work. This eliminates a whole class of failures that turn out to be login or account problems wearing a connection costume.

Turn the API on

The IBKR desktop application does not accept outside connections by default. You have to enable it:

• TWS: File → Global Configuration → API → Settings
• IB Gateway: Configure → Settings → API → Settings

Then check these:

• Enable ActiveX and Socket Clients — required. Without it, nothing listens on the socket port at all.
• Socket Port — write down the number; it goes into your software. Defaults are in the table below.
• Read-Only API — while ticked, every order request is rejected. Keep it on for the first connection attempts, then clear it once reading account and market data works.
• Trusted IPs — leave it alone or use 127.0.0.1 when software and application share a machine; add the peer address only when they do not.

Most of these take effect after the application restarts. Changing a setting, skipping the restart and then blaming the port is the most common waste of an afternoon in this whole process.

The port table

Worth memorising, because it explains a subtle failure: the wrong port does not always fail to connect. Put the live port in place of the paper port while the desktop application happens to be logged into a live account, and you get a successful connection to a live session. That is exactly why a paper-only product has to verify the account after connecting, not just trust the port number.

The first connection: host, port, client ID

Most desktop software asks for three things:

• Host — 127.0.0.1 when software and IBKR application share a machine.
• Port — from the table above.
• Client ID — an integer that identifies one connecting client.

Uniqueness is a hard requirement. If the ID is already held by another process, the second connection is refused with an error along the lines of "client ID already in use". Do not retry in a loop; find the holder first. It is often a process that did not exit cleanly, or a second client someone left open.

Software usually has its own read-only toggle, and it is not the same switch as the one in the desktop application: one stops this client from sending orders, the other stops the whole application from accepting them. When both are on, "why was my order refused" is usually answered by the second one.

Connected, but the chart is empty

A successful connection only means a session exists. Three causes, in the order they usually appear:

• Market data permissions. API connectivity does not hand you every real-time feed. Entitlements belong to your IBKR account, and a paper account is subject to the same subscription rules. Changing the desktop application will not fix a missing subscription.
• Delayed data. Without a real-time subscription many symbols return delayed quotes. The shape of a chart built from delayed data is not the shape of the live book, and it should not be treated as a real-time sample in a backtest.
• Contract not resolved correctly. Futures need an exact expiry, options need exact strike and expiry, stocks need the right exchange. A bare symbol can resolve to several contracts, and the one the software picked may not be the one you meant. Get the conId from contract details once, then pin it.

Connected is not ready

This is the part that costs money. A restored socket, positive balances and a chart with data can all be true at the same time and still not mean trading should proceed.

A safer order:

Connection restored
        |
Synchronize account
        |
Synchronize positions
        |
Synchronize open orders
        |
Confirm market data
        |
Confirm strategy state
        |
Allow new trading

The reason is concrete: after a reconnect there may be working orders from the previous session, partially filled orders, or a position that no longer has a clear owner. Skipping reconciliation and allowing trading produces duplicated orders and an orphaned position nobody claims.

The daily restart is not a network problem

IBKR's desktop applications restart on a daily schedule, usually late in the US evening. The API session drops with them, and your software sees a disconnection it did not cause.

Two requirements follow:

• Reconnecting must be automatic; reconciling must not be skipped. A successful reconnect is only the start of the seven-step order above.
• Do not assume it fixes itself. The drop is not the problem. Orders changing state while you were disconnected is the problem.

If your software does not separate those two, the symptom is a state mismatch once a day, always near the same time. That regularity is the clue.

Troubleshooting by symptom

If you are using Algoryn

The steps above apply to any client. Algoryn adds three, all of them after the connection succeeds:

1. Confirm the account is a paper account. The public build supports paper trading only and does not enable live trading. If the desktop application is logged into a live account, the connection is refused rather than quietly downgraded.
2. Unlock automated trading permission. It is a separate authorization from connectivity, locked by default, and it does not survive a reconnect automatically.
3. Pass the pre-start reconciliation. Position and working-order reconciliation has to complete before an instance may start, and any unattributed position must be attributed manually or closed at the broker first.

That is why the phrase "connected is not ready" keeps appearing: inside the product it is an actual gate, not a slogan.

A one-page checklist

• Install TWS or IB Gateway, and log in manually once.
• Tick Enable ActiveX and Socket Clients, and note the port.
• Check the port table: TWS 7497, Gateway 4002 for paper.
• Start with read-only, clear it once reading works.
• Keep the client ID unique; find the holder before retrying.
• Check the market data subscription before blaming the connection.
• Pin contracts by conId instead of by resemblance.
• After any reconnect, run the seven-step reconciliation.
• Treat the daily restart as a scheduled maintenance window.

Algoryn is an independent product and is not affiliated with, endorsed by, or sponsored by Interactive Brokers LLC. Menu names, ports and settings follow the IBKR version you are running and its official documentation.