Beginner setup guide

Interactive Brokers through TWS

Allow 8–12 minutes
Written guide: 16 steps

Use the full Trader Workstation with an Interactive Brokers paper account. This path uses the paper socket port 7497 and begins with read-only API access.

Start the stepsWatch the videoPrint → Save as PDF
Paper / SIM onlyPaper-account walkthrough with captions and a written recovery path.

This guide never requires a funded account or a live order. Do not enter a password, account number, QR code, API key, or install token into a screenshot or support message.

Before you start: TWS uses Global Configuration → API → Settings. Use the Setup Wizard for the initial authenticated identity and account discovery; Settings diagnostics come after setup. Confirm the paper login and port in TWS. If you are using IB Gateway instead, follow its separate guide.

Words used in this guide

Trader Workstation (TWS)
Interactive Brokers’ full desktop trading application. It must stay open for this local connection.
Paper account
An Interactive Brokers practice account used for this guide. It is separate from BrokerBridge’s Local account.
Socket port
The local numbered doorway used by BrokerBridge to talk to TWS. The paper default is 7497.
Read-only
A broker-app setting that blocks API orders while you verify the connection.

One action at a time

Follow the steps

  1. 1

    TWS

    Start with a paper Interactive Brokers login.

    What you should see
    Paper is visible before credentials are submitted.
    If it looks different
    Stop if the login is live.
    Paper / SIM safety
    Paper account only. Keep login details private.
    Why this matters

    Paper and live logins can look similar. Check the mode before signing in.

  2. 2

    Your computer

    Install Trader Workstation from Interactive Brokers.

    What you should see
    TWS opens after installation.
    If it looks different
    Use the official download page.
    Paper / SIM safety
    No funded or live account.
    Why this matters

    Install the broker application before connecting it to BrokerBridge.

  3. 3

    TWS

    Open TWS and sign in to the paper account.

    What you should see
    TWS reaches its paper workspace.
    If it looks different
    Recheck the login mode and sign in again.
    Paper / SIM safety
    Keep the paper badge visible.
    Why this matters

    The paper label identifies the environment; a successful login alone does not prove it is paper.

  4. 4

    TWS

    Open Global Configuration → API → Settings.

    What you should see
    The API settings panel opens.
    If it looks different
    Open Global Configuration using the settings cog. If the API menu differs, check the help for your installed TWS version or contact support.
    Paper / SIM safety
    Do not change live settings.
    Why this matters

    API settings control the connection from other applications, including BrokerBridge.

  5. 5

    TWS

    Confirm socket clients are enabled.

    What you should see
    API socket access is enabled.
    If it looks different
    Stop if the control is unavailable or unclear.
    Paper / SIM safety
    Leave Read-Only API enabled first.
    Why this matters

    IBKR can change menu labels between versions. Match the setting’s purpose, and ask support if you are unsure.

  6. 6

    TWS

    Confirm the paper socket port is 7497.

    What you should see
    The paper session shows port 7497.
    If it looks different
    Correct only the paper session. Never select 7496 for this guide.
    Paper / SIM safety
    Paper port only.
    Why this matters

    BrokerBridge and the broker application must use the same socket port to communicate.

  7. 7

    TWS

    Leave Read-Only API enabled for the first connection.

    What you should see
    Read-only remains checked.
    If it looks different
    Turn it on before continuing.
    Paper / SIM safety
    No API order authority.
    Why this matters

    Read-only access lets you verify the account without allowing API orders.

  8. 8

    TWS / BrokerBridge

    Leave TWS logged in and open the BrokerBridge Setup Wizard at the Broker connection step.

    What you should see
    TWS remains available while the broker connection step is visible.
    If it looks different
    Log in again if TWS logged out, then restart the wizard if the step is unavailable.
    Paper / SIM safety
    Paper only.
    Why this matters

    BrokerBridge uses the signed-in broker application. Closing it interrupts that connection.

  9. 9

    BrokerBridge

    Open Connect a local IBKR account.

    What you should see
    The IB Gateway and TWS choices are visible.
    If it looks different
    Stop if the disclosure is missing or the controls are unclear.
    Paper / SIM safety
    Do not test or save a live endpoint.
    Why this matters

    Choose the same application that is currently logged in to your paper account.

  10. 10

    BrokerBridge

    Choose the TWS paper preset.

    What you should see
    Host 127.0.0.1 and port 7497 fill in; BrokerBridge assigns a free local client ID when you test.
    If it looks different
    If allocation reports an active local session, stop that other local BrokerBridge session and retry.
    Paper / SIM safety
    Preset is paper only; connection is not verified yet.
    Why this matters

    The preset fills the local address and paper port, but you still need to test the account identity.

  11. 11

    BrokerBridge

    Click Test broker connection in the Setup Wizard.

    What you should see
    The authenticated setup result reports a ready session or requests account selection; a reachable port alone is not enough.
    If it looks different
    Continue only when the authenticated account state confirms the intended paper session.
    Paper / SIM safety
    No order is submitted.
    Why this matters

    A reachable port shows only that something is listening. The authenticated result identifies your account.

  12. 12

    BrokerBridge

    If an account selector appears, choose the masked paper account and click Test broker connection again.

    What you should see
    The authenticated paper account is selected and the connection result is ready.
    If it looks different
    Stop if the mode is not clearly paper or identity remains unknown.
    Paper / SIM safety
    Never expose the full account number.
    Why this matters

    One login can expose more than one account. Select the paper account you intend to use.

  13. 13

    BrokerBridge

    Click Continue, complete the remaining Setup Wizard questions, and click Finish setup.

    What you should see
    The paper setup is saved and the paper mode remains visible.
    If it looks different
    Return to the Broker step if the authenticated paper result is missing.
    Paper / SIM safety
    Paper only.
    Why this matters

    Complete the remaining questions so BrokerBridge can save the tested connection.

  14. 14

    BrokerBridge

    Open Settings → Broker Accounts and run IBKR Diagnostics.

    What you should see
    Diagnostics report a known paper session, not merely an open port.
    If it looks different
    Follow the named recovery card.
    Paper / SIM safety
    Read-only connection.
    Why this matters

    Diagnostics help distinguish a connection problem from an account or permission problem.

  15. 15

    Your computer / BrokerBridge

    Restart TWS and BrokerBridge, then confirm reconnection.

    What you should see
    The saved paper session reconnects.
    If it looks different
    Missing identity is a failure, not an empty account.
    Paper / SIM safety
    Paper only.
    Why this matters

    Restarting checks that your saved setup reconnects without repeating the configuration.

  16. 16

    TWS / BrokerBridge

    Optional: after paper identity is reverified, open TWS API settings, turn off Read-Only API for this paper-only chapter, and submit one approved paper LIMIT trade plan.

    What you should see
    Read-Only is explicitly off only for the paper session, and one paper LIMIT order has a visible receipt and state.
    If it looks different
    If the order is still waiting, cancel it and verify whether any quantity filled. If shares or contracts filled, closing that position is a separate order; confirm it is flat and check for remaining working orders. If the outcome is unknown, inspect the paper broker account before retrying. Return to Read-Only after the test is resolved.
    Paper / SIM safety
    Paper only; never use a funded account.
    Why this matters

    This optional step changes paper-order permission. You can finish the connection lesson without sending any order.

Matching video

Captioned

Captions are enabled by default. Read the transcript if video playback is unavailable.

  1. 00:00 Safety and paper login
  2. 03:00 Global Configuration and port 7497
  3. 05:00 Paper preset and connection test
  4. 07:00 Account, finish, diagnostics
  5. 09:00 Restart proof
  6. 10:30 Optional paper LIMIT chapter

Stop conditions

Stop if the account is live, its identity is unknown, or you cannot tell what a control will do. Keep passwords and account details private when sharing an error with support. Use Troubleshooting for recovery.

← IB Gateway paper guideFirst practice walkthrough →
Browse documentation