Browse documentation

Beginner setup guide

Interactive Brokers through IB Gateway

Estimated video: 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 stepsVideo planPrint → Save as PDF
Paper / SIM onlyVerified paper-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, transcript, 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. Current Gateway builds may omit the older socket-client checkbox, so confirm the installed label before recording.

Words used in this guide

Paper account
An Interactive Brokers practice account. It is separate from BrokerBridge Practice 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 highlighted control

  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. Never show credentials.
    Why this may feel hard
    Choosing the correct login mode.
  2. 2

    Windows

    Install IB Gateway from Interactive Brokers.

    What you should see
    Gateway is installed without a key or account number appearing in the capture.
    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 may feel hard
    Download and context switch.
  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 may feel hard
    Recognizing a small status indicator.
  4. 4

    IB Gateway

    Open Configure → Settings → API → Settings.

    What you should see
    The API settings panel opens.
    If it looks different
    Record the installed version if the menu label differs; do not guess.
    Paper / SIM safety
    Do not change live settings.
    Why this may feel hard
    Multi-level menu navigation.
  5. 5

    IB Gateway

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

    What you should see
    API socket access is enabled or the current-version equivalent is documented.
    If it looks different
    Stop if the control is absent or unclear and update the source-of-truth worksheet.
    Paper / SIM safety
    Leave Read-Only API enabled for this connection.
    Why this may feel hard
    Version-dependent wording.
  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 may feel hard
    Technical port choice.
  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 may feel hard
    Understanding why read-only is the safe first state.
  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 may feel hard
    Keeping a second application open.
  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 may feel hard
    Switching applications.
  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 may feel hard
    Choosing the broker application you already opened.
  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 may feel hard
    Technical fields are prefilled.
  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 may feel hard
    Separating port reachability from account verification.
  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 may feel hard
    Account discovery and selection.
  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 may feel hard
    Finishing a multi-step setup.
  15. 15

    BrokerBridge

    Open Settings → Broker & Data 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 may feel hard
    Reading a diagnostic summary.
  16. 16

    Windows / 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 may feel hard
    Testing persistence.
  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 harmless paper LIMIT order has a visible identity and state.
    If it looks different
    Cancel or close the paper test and reconcile any unknown receipt manually. Return to Read-Only after the optional chapter.
    Paper / SIM safety
    Paper only. Never use a funded account.
    Why this may feel hard
    Separate optional execution chapter.

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, the account identity is unknown, the app offers a live NT8 path, a token or password would appear in the recording, or a required label differs from the documented product truth. Use Troubleshooting for recovery.

TWS paper guide →