Getting Started with NeonChainX - IBKR Setup & TWS API Ports

This guide walks you through getting NeonChainX running from purchase to first trade execution with Interactive Brokers (IBKR).

⚠️ First-Time Users: We strongly recommend using a paper trading account when you first run NeonChainX to ensure everything works correctly before trading with real money.

TWS API ports: 7497 (paper) vs 7496 (live)

NeonChainX connects to Trader Workstation (TWS) or IB Gateway on your machine. Use these default socket ports in both IB settings and NeonChainX:

Mac install issue? If macOS blocks the app with a "damaged" error, see Fix App Is Damaged on Mac.

In the app (v2.3.2)

Full list: Releases and Changes (v2.3.2).

Prerequisites

System Requirements

• Windows: Windows 10+ (no additional installs needed)
• macOS: macOS 12+ (no additional installs needed)
• Ubuntu: Ubuntu 20.04+ (officially supported Linux distribution)

Ubuntu Additional Setup

# Ubuntu/Debian
sudo apt update && sudo apt install libxcb-cursor0 libgl1-mesa-glx

Interactive Brokers Account

• Active IBKR account with trading permissions
• TWS or IB Gateway installed

Step 1: Purchase NeonChainX

1. Visit /pricing
2. Choose your preferred plan
3. Complete checkout with your email
4. Save your license key from the confirmation email

Step 2: Download & Install

Download

1. Go to /downloads
2. Enter your license email and key
3. Download for your platform

Install

Windows:

1. Run the .exe file directly
2. If Windows Defender/SmartScreen warning appears:
   • Click "More info" then "Run anyway"
   • Or go to Downloads folder, right-click the file > Properties > "Unblock" > OK

macOS:

1. Open .dmg file
2. Drag to Applications folder
3. If security prompt: System Preferences > Security & Privacy > "Open Anyway"

Ubuntu:

1. Extract the downloaded archive to a folder of your choice
2. Run the automatic installation script by first changing the permission chmod +x install.sh
3. Run the automatic installation script ./install.sh
4. The script will automatically handle dependencies, desktop integration, and PATH setup

Step 3: Configure Interactive Brokers

Enable API Access

First, you need to enable API access in either TWS or IB Gateway. This allows NeonChainX to connect to your IBKR account.

TWS (Trader Workstation) - Recommended:

1. Open TWS and log in
2. Go to File > Global Configuration > API > Settings
3. Check "Enable ActiveX and Socket Clients"
4. Uncheck "Read-Only API" (required for trading - this is critical!)
5. Set Socket port:
   • 7497 for paper trading
   • 7496 for live trading
6. Add 127.0.0.1 to Trusted IP Addresses (click "Add" if needed)
7. Click Apply and OK

📚 Reference: For detailed information about TWS API settings and configuration, you can also check the official IBKR TWS API Settings documentation.

API Precautions (Recommended):

For smoother API operation, configure API Precautions:

1. Go to File > Global Configuration > API > Precautions
2. Recommended settings:
   • Check "Bypass Order Precautions for API Orders" - Allows API to execute orders without manual confirmations
   • Check "Bypass 'same action pair trade' warning for API orders" - Prevents duplicate trade warnings
   • Leave other precautions unchecked unless you have specific needs
3. Click Apply and OK
4. Restart TWS for all changes to take effect

IB Gateway:

IB Gateway uses the same API settings as TWS, with only the port numbers being different. When you launch IB Gateway:

1. Launch IB Gateway and log in
2. When prompted, configure API Settings (same settings as TWS):
   • Check "Enable ActiveX and Socket Clients"
   • Uncheck "Read-Only API" (required for trading)
   • Set Socket port:
     • 4002 for paper trading
     • 4001 for live trading
   • Add 127.0.0.1 to trusted IPs
3. Configure API Precautions (same as TWS):
   • Go to API > Precautions in the configuration menu
   • Use the same recommended settings as shown for TWS above
4. Click OK

Important: The account type you use to log in to TWS/Gateway (paper or live) determines what account NeonChainX will access. Log in with your paper account to trade paper money, or live account for real trading.

Activate your license

1. In NeonChainX, open the Settings tab
2. Enter your license email and key
3. Click Verify and Save License

That button verifies what is in the fields. Clearing the key does not put a previously saved key back.

Configure NeonChainX Connection

1. In NeonChainX, go to the Settings tab (license, IB connection, appearance, help)
2. Set connection parameters:
   • Host: 127.0.0.1
   • Port:
     • TWS: 7497 (paper) / 7496 (live)
     • Gateway: 4002 (paper) / 4001 (live)
   • Client ID: 1
3. Click out of the field (host, port, and client ID save when you leave them). There is no Save on this tab for those fields.

Optional: Settings → Appearance sets the desk theme (NCX default, Contrast, Easy on the Eyes, or Terminal) and Display size. Click Smaller or Larger to pick 90% to 200%. Text, tables, columns, and buttons all grow together, like the font size adjustment in TWS. Click Restart now to apply it; NeonChainX reopens and reconnects to IB. If TP/SL is watching an open position, you'll get a warning first: rules come back paused after the restart, so open TP/SL on each position and click Set Rules to turn them back on. Terminal drops the color heatmap so bid/ask/strike sit on one field.

Position sizing and TP/SL defaults live on the Risk & Sizing tab. After you change them, click Save Settings. The line under the button shows Settings saved. when they are written.

Quantity presets sit under Default Contract Size: three sizes you use often (1, 10, and 100 to start). Leave a box blank to skip it. On the Trading tab, each symbol's Quantity (next to Order) has a button for each preset plus your default, and one click sets that symbol's size. The current size is highlighted, and you can still type any size in the box. Set all quantities next to Add shows the same buttons, including your default, and changes every symbol to that size in one click. The size you choose is kept for that symbol. Presets are hidden when you size by dollar amount.

Step 4: Connect & Test

1. Ensure TWS/Gateway is running and logged in
2. In NeonChainX, click Connect in the top bar
3. Wait for green connection status
4. Verify the top bar shows your account type (Demo/Live), balance, and trading preferences (position sizing method)
5. Test: Add symbol AAPL (Type Stock) and verify options data loads. StrikeAt fills from last price once on a new row; if you clear it, it stays empty until you type a value.

Adding stock, index, and futures symbols

Use the Type dropdown next to the symbol box, then click Add:

MGC (Micro Gold) often has no bid/ask in TWS, so quotes and mid orders may not work. Use GC instead.

Full walkthrough: Trade futures options on IBKR.

You also need the matching IBKR market data subscription (US options for stocks/indexes; CME / NYMEX / COMEX futures data for those roots).

Arrange the tables your way. Drag a column edge to resize it, or drag a header to move the column. Right-click any header to hide that column, pick columns from the Columns list (in Buy to Open, ITM, ATM, and OTM each have one checkbox for the group), show them all again, or reset widths and order. Your layout is kept after a restart.

Note: When reconnecting, NeonChainX restores your previously added symbols automatically. Market data loads in the background so you can get back to trading quickly.

Step 5: First Trade (Use Paper Trading)

Recommended: Start with paper trading ports to practice risk-free

• TWS paper: port 7497
• Gateway paper: port 4002

Basic Flow

1. Research in TWS/charts
2. Execute trades in NeonChainX
3. Monitor positions
4. Manage exits/adjustments

Troubleshooting

Connection Issues

• "Connection failed": Check TWS/Gateway is running, port numbers match, and 127.0.0.1 is trusted
• "API not enabled": Enable API in settings and restart TWS/Gateway

License Issues

• "Invalid license": Verify email/key exactly as received, check for extra spaces
• Key field empty after Verify: Verify and Save License uses what is in the boxes. Clearing the key does not put a saved key back. Paste the key and verify again. Restarting the app still loads a key saved on disk.

Ubuntu Display Issues

If GUI doesn't display properly:

# Install additional dependencies
sudo apt install libfontconfig1 libfreetype6 libx11-6