Beginner setup guide

Interactive Brokers through IB Gateway

Allow 8–12 minutes
Written guide: 17 steps

Use IB Gateway with an Interactive Brokers paper account. Gateway is the lighter option for a session that stays running, and this path 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: IBKR’s official API lesson uses Configure → Settings → API → Settings and documents paper port 4002. Use the Setup Wizard for the initial authenticated identity and account discovery; Settings diagnostics come after setup. Some Gateway versions omit the older socket-client checkbox. Check the paper socket port and use the authenticated connection test; ask support if the result is unclear.

Words used in this guide

Paper account
An Interactive Brokers practice account. It is separate from BrokerBridge’s Local account and does not use funded money.
Socket port
The local numbered doorway that lets BrokerBridge talk to the broker app on the same computer.
Client ID
A number that identifies this local API connection. The tutorial preset receives a free local ID when you test; it is not an account number.
Read-only
A broker-app setting that allows account reads but blocks API orders while you verify the connection.

One action at a time

Follow the steps

  1. 1

    IB Gateway

    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 does not say paper. Do not continue into a live session.
    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 IB Gateway from Interactive Brokers.

    What you should see
    Gateway opens after installation.
    If it looks different
    Use the official download page and do not use an unknown mirror.
    Paper / SIM safety
    No funded or live account.
    Why this matters

    Install the broker application before connecting it to BrokerBridge.

  3. 3

    IB Gateway

    Open Gateway and sign in to the paper account.

    What you should see
    Gateway reaches its logged-in paper screen.
    If it looks different
    Recheck the paper selection and log 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

    IB Gateway

    Open Configure → Settings → API → Settings.

    What you should see
    The API settings panel opens.
    If it looks different
    If the menu differs, check the help for your installed Gateway version or contact support before changing a setting.
    Paper / SIM safety
    Do not change live settings.
    Why this matters

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

  5. 5

    IB Gateway

    Confirm socket clients are enabled, if the installed build exposes that control.

    What you should see
    If the socket-client checkbox is present, it is enabled. Some Gateway versions do not show that checkbox.
    If it looks different
    If the checkbox is absent, continue to check the paper socket port and test the connection. If another setting is unclear, contact support.
    Paper / SIM safety
    Leave Read-Only API enabled for this connection.
    Why this matters

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

  6. 6

    IB Gateway

    Confirm the paper socket port is 4002.

    What you should see
    The paper session shows port 4002.
    If it looks different
    Correct only the paper session. Never select 4001 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

    IB Gateway

    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

    IB Gateway

    Leave Gateway running.

    What you should see
    Gateway stays connected to paper while BrokerBridge is configured.
    If it looks different
    Log in again if it disconnected.
    Paper / SIM safety
    Paper badge stays visible.
    Why this matters

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

  9. 9

    BrokerBridge

    Open the BrokerBridge Setup Wizard and reach the Broker connection step.

    What you should see
    The broker connection step is visible.
    If it looks different
    Use the packaged app and restart the wizard if the step is unavailable.
    Paper / SIM safety
    Do not paste secrets into screenshots.
    Why this matters

    Keep the broker application open while you complete BrokerBridge setup.

  10. 10

    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.

  11. 11

    BrokerBridge

    Choose the IB Gateway paper preset.

    What you should see
    Host 127.0.0.1 and port 4002 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 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.

  12. 12

    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
    Use the exact error card. 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.

  13. 13

    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 account 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.

  14. 14

    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.

  15. 15

    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.

  16. 16

    Your computer / BrokerBridge

    Restart Gateway and BrokerBridge, then confirm reconnection.

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

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

  17. 17

    Gateway / BrokerBridge

    Optional: after paper identity is reverified, open Gateway 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 identity 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 API Settings and port 4002
  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.

TWS paper guide →
Browse documentation