Skip to content

QuantAscent — Setup Guide

See also: Product Overview for a feature summary | Screen Guide for a detailed walkthrough of every tab

This guide walks you through installing QuantAscent, entering your API key, connecting to Interactive Brokers, and getting your first portfolio sync running. If something goes wrong along the way, the Troubleshooting section at the bottom covers the common issues.

1. Install the App

Windows

  1. Run QuantAscent_Setup.exe
  2. Follow the installer prompts (the default install location is fine)
  3. Optionally create a desktop shortcut when prompted
  4. Launch QuantAscent from the Start Menu or desktop shortcut

macOS

  1. Open QuantAscent.dmg
  2. Drag QuantAscent into your Applications folder
  3. Launch QuantAscent from Applications or Spotlight

Note: On first launch, macOS may display a Gatekeeper warning ("QuantAscent can't be opened because it is from an unidentified developer"). If this happens, go to System Settings > Privacy & Security, scroll down, and click Open Anyway next to the QuantAscent message. You only need to do this once.

2. Enter Your API Key

On first launch, a dialog will prompt you for your QuantAscent API key. This key is required to download the financial database that powers the Research, Strategy Builder, Company Analysis, and Company Screener features.

  1. Your account manager will provide the API key (it starts with qa_)
  2. Paste it into the dialog and click Save & Continue
  3. The key is stored locally on your machine only

If you skip this step, you can enter it later in Settings > Database.

3. Database Sync & Metrics Matrix

After you enter your API key, the startup wizard automatically downloads the financial database (~200–300 MB). This is a one-time download containing fundamental data, prices, and computed metrics for ~5,000 US equities spanning 20 years of history.

The database updates automatically each week (Saturday 21:00 ET). You can also trigger a manual update anytime from Settings > Database > Sync Now.

Once the database finishes downloading, the wizard builds a metrics matrix — a precomputed dataset used by the Research tools and Strategy Builder. This takes a few minutes. The matrix is saved locally and only needs to be rebuilt when you want to incorporate newer data or change parameters. You can build additional matrices with different date ranges or lookback periods from the Research tab.

The wizard also generates 39 built-in strategies covering all 11 market sectors in growth and balanced compositions, plus index-tracking strategies. These are ready to use out of the box — deploy them as-is or use them as templates in the Strategy Builder.

4. Connect to Interactive Brokers

QuantAscent connects to IBKR through two separate channels:

Channel Used For Requires Gateway/TWS?
Flex Web Service Daily portfolio snapshots, trade history, positions No (HTTP API)
TWS or IB Gateway Live trading, real-time prices, IBKR holdings Yes

You can use QuantAscent for portfolio tracking and research without TWS or IB Gateway running — the Flex Web Service handles all historical data downloads over HTTP. TWS or IB Gateway is only needed for live trade execution and real-time data.

TWS vs IB Gateway — which should I use?

Both Trader Workstation (TWS) and IB Gateway provide the same API connection to IBKR. The difference is the user interface:

TWS (Trader Workstation) IB Gateway
Interface Full trading platform with charts, order book, positions, and account info Minimal window — just a status panel
Real-time visibility Shows live trades as they execute, current positions, and account balances No trade or account visibility
Resource usage Higher (full UI) Lower (lightweight)
Best for Monitoring trades and verifying account data Headless / automated setups

During alpha testing, we recommend TWS. QuantAscent does its best to display accurate portfolio information, but IBKR maintains the authoritative account data — having TWS open alongside QuantAscent lets you verify that positions, balances, and trade executions all match. Once you're comfortable that everything is working correctly, you can switch to IB Gateway for a lighter footprint.

Download: TWS (select "TWS Latest" for the most up-to-date version) | IB Gateway (the "stable" version)

Step 1: Set Up the Flex Web Service

The Flex Web Service is how QuantAscent downloads your daily account statements (positions, trades, NAV) from IBKR. This works over HTTP and does not require IB Gateway or TWS to be running.

Create a Flex Query

  1. Log in to IBKR Account Management
  2. Navigate to Performance & Reports > Flex Queries
  3. Click Create next to "Activity Flex Queries"
  4. Fill in the top of the form:
  5. Query Name: anything (e.g., "QuantAscent Daily")
  6. Date Period: Last Business Day

  7. Format: XML

  8. In the Sections area, check exactly these seven boxes (leave every other section unchecked):

    Check Section What it provides
    ☑ Cash Report Fees, dividends, interest, ending cash
    ☑ Cash Transactions Deposits, withdrawals, withholding tax
    ☑ Change in NAV Portfolio NAV and external cash flows
    ☑ Corporate Actions Stock splits and spinoffs
    ☑ Open Positions Current holdings and market values
    ☑ Realized and Unrealized Performance Summary in Base Short-term / long-term realized P&L for tax schedules
    ☑ Trades Tax lots and wash-sale adjustments — see note below

  9. Configure each section's options. After checking a section, click the row to open its options panel. The panel has two halves — configure both:

    Bottom half (data field columns) — Currency, Asset Class, Symbol, Conid, Multiplier, Strike, Expiry, and many more. For every section, click Select All here. These are just the XML attributes emitted on each record; missing any required one will break the portfolio log, and extras are harmless.

    Top half (transaction types / Level of Detail) — per section:

    Section What to check in the top half
    Cash Report Click Select All
    Cash Transactions Deposits & Withdrawals + Detail (the rest is optional; Select All is also fine)
    Change in NAV No options in the top half — just the bottom-half fields
    Corporate Actions Click Select All
    Open Positions Check Detail (do not select Summary alone)
    Realized and Unrealized Performance Summary in Base Check Detail
    Trades See the warning below

    Trades has a required sub-option — don't skip this

    In the Trades options panel, scroll to Level of Detail and check both of these boxes:

    • ☑ Closed Lots
    • ☑ Wash Sales

    Without Wash Sales, disallowed-loss adjustments are silently dropped from your tax reports. These are not covered by the bottom-half "Select All" — they're separate toggles in the top half.

  10. Save the query and note the Query ID (a numeric ID shown next to the query name)

QuantAscent will check this for you

After your first portfolio sync, QuantAscent inspects the Flex XML and notifies you if any required section or data field is missing — so if you miss something here, you'll see a warning in the notification bell rather than a silent data gap.

Get Your Flex Token

  1. On the same Flex Queries page, find the Flex Web Service Configuration panel (usually bottom-right of the page)
  2. Click the gear icon to open the token management page
  3. Click Create to generate a new token, or copy your existing one
  4. IBKR may require 2FA before showing the token
  5. Tokens expire periodically; if your daily sync starts failing with an auth error, regenerate here and re-enter it in Settings
  6. The token is a long alphanumeric string — keep it private. Anyone with this token can read your account data

Same page, two separate panels

The Flex Query ID is listed next to your saved query in the main area of the page. The Flex Token is in the separate Flex Web Service Configuration panel (gear icon). You need both values to enter into QuantAscent.

Enter Flex Credentials in QuantAscent

  1. Open QuantAscent and go to Settings
  2. In the IBKR Connection card, enter your Flex Token and Query ID
  3. Click Save

These are stored locally in your AppData folder and are never transmitted anywhere except to IBKR's servers.

Step 2: Set Up TWS or IB Gateway

If you want QuantAscent to execute trades automatically or view real-time IBKR holdings, you need TWS or IB Gateway running on the same machine.

  1. Download TWS from IBKR (select "TWS Latest" for the most up-to-date version)
  2. Install and launch TWS, then log in with your IBKR credentials
  3. Go to Edit > Global Configuration (Windows) or TWS > Settings (macOS)
  4. Navigate to API > Settings and configure:
  5. Enable ActiveX and Socket Clients — checked
  6. Socket port — 7496 (live) or 7497 (paper)
  7. Allow connections from localhost only — checked (for security)
  8. Read-Only API — unchecked (required to place orders)
  9. Click Apply then OK

Leave TWS running while using QuantAscent. You'll see orders appear in real time on the TWS order panel as QuantAscent submits them.

Option B: IB Gateway

  1. Download IB Gateway from IBKR (the "stable" version — available for both Windows and macOS)
  2. Launch IB Gateway. The login screen presents the following options:
  3. API Type — Select IB API (not "FIX CTCI" — that's for institutional FIX protocol connections and is not used by QuantAscent)
  4. Trading Mode — Select Live Trading for your real account, or Paper Trading for a simulated environment
  5. Username / Password — Enter your IBKR credentials
  6. Click Log In
  7. After logging in, go to Configure > Settings > API > Settings and verify:
  8. Enable ActiveX and Socket Clients — checked
  9. Socket port — 7496 (live) or 7497 (paper). This should match the Trading Mode you selected at login
  10. Allow connections from localhost only — checked (for security)
  11. Read-Only API — unchecked (required to place orders)

Paper vs Live trading: Your IBKR paper trading account is a separate simulated environment — trades don't affect your real portfolio or real money. Use paper mode to test QuantAscent's trading features safely before going live. You can switch between paper and live by logging out of Gateway/TWS and logging back in with the other mode selected.

Note: New IBKR accounts may take up to 24 hours for the paper trading account to be fully provisioned. If you can't log in to paper trading right away, log in to your paper account through the IBKR Client Portal first to confirm it's active.

Step 3: Configure the Connection in QuantAscent

Once TWS or IB Gateway is running, point QuantAscent at it:

  1. Go to Settings in QuantAscent
  2. In the IBKR Connection card:
  3. Account Mode — Check "Live Trading Mode" for a live account (port 7496), or leave unchecked for paper trading (port 7497). This must match the mode you selected when logging into TWS or IB Gateway.
  4. IBKR Host — Leave as 127.0.0.1 (this means "this computer" — only change it if Gateway/TWS is running on a different machine)
  5. Client ID — Leave as 1 unless you run multiple API connections simultaneously
  6. Click Save

The sidebar at the bottom of the app shows the current connection status. A green indicator means QuantAscent is connected to TWS or IB Gateway. If it shows disconnected, verify that TWS/Gateway is running and logged in, and that the port settings match.

5. First Portfolio Sync

Once your Flex credentials are entered, the startup wizard automatically downloads your portfolio data via the Flex API. If you skip this step, the app will detect the missing data next time you open it and offer to backfill.

6. Daily Scheduler

The background scheduler starts automatically when the app opens. It runs the following jobs on each trading day:

Time (ET) Job
05:00 Download daily Flex statement
05:05 Process trades
05:10 Log closed lots
05:15 Update benchmarks
05:20 Update strategy logs
05:30 Run backup
07:40 Generate reconciliation report
07:45 Generate tax schedules
Saturday 21:00 Sync financial database

The scheduler only runs while QuantAscent is open. If you close the app for a few days, it will automatically detect the gap and offer to backfill the missed days when you reopen it.

7. Explore the App

After the startup wizard completes, your app is fully configured. Here's what each tab is for:

Tab What You'll Find
Dashboard Portfolio summary, risk metrics, TWR & MWR returns, performance chart, monthly heatmap
Account Deposits, withdrawals, investment gain tracking, and report generation
Holdings Current positions with lot-level detail, order placement
Strategy Performance Compare strategy returns against benchmarks over configurable date ranges
Strategy Manager Allocate capital across strategies, configure rebalance schedules, execute trades
Strategy Builder Design investment strategies with 120+ financial metrics
Backtesting Test strategies against up to 20 years of real history
Research Metric analysis tools — IC rankings, quintile analysis, threshold scanning
Company Analysis Deep fundamental profiles with 8 interactive trend charts
Company Screener Filter 5,000+ stocks in real time across 120+ metrics
Trade Log Complete trade history with realized P&L, lot matching, and tax classification
Settings IBKR connection, trade execution, backups, database, and app preferences

See the Screen Guide for a detailed walkthrough of every screen.

Startup Behavior

Each time you open QuantAscent, it automatically:

  1. Checks for app updates — if a newer version of QuantAscent is available, it downloads and installs silently on Windows. The app restarts automatically with the new version. On macOS, you'll be notified and can download from Settings.
  2. Checks for database updates — if a newer version of the financial database is available, you'll be prompted to update.
  3. Detects stale portfolio data — if you haven't opened the app in a few days, it will backfill the missed trading days using the Flex API (no Gateway needed).

Multiple Portfolios

QuantAscent supports managing more than one portfolio. Open the Portfolio Manager from the sidebar to create, rename, or delete portfolios. Each portfolio has its own type — Live (connected to your real IBKR account on port 7496) or Paper (connected to an IBKR paper trading account on port 7497). Switching portfolios reloads the Dashboard, Holdings, and all strategy data for the selected portfolio.

Quick Reference

Task Where
Enter/update API key Settings > Database
Enter/update IBKR Flex credentials Settings > IBKR Connection
Download database updates Settings > Database > Sync Now
Build a new metrics matrix Research > Build Matrix
Switch between Live and Paper trading Settings > IBKR Connection > Account Mode
Manage multiple portfolios Sidebar > Portfolio Manager
Create a backup Settings > Backup

App Data Location

All user data is stored locally on your machine:

Platform Path
Windows %LOCALAPPDATA%\QuantAscent\ (typically C:\Users\<YourName>\AppData\Local\QuantAscent\)
macOS ~/Library/Application Support/QuantAscent/

Each portfolio gets its own directory under portfolios/<name>/:

Folder/File Contents
portfolios/<name>/portfolio/portfolio_log.csv Daily portfolio metrics (NAV, returns, P&L)
portfolios/<name>/portfolio/benchmark_log.csv Benchmark performance tracking
portfolios/<name>/trading/flex/ Downloaded IBKR Flex XML statements
portfolios/<name>/trading/trade_log.db Trade database (lots, closed trades, P&L)
portfolios/<name>/strategies/ Strategy configurations and logs
portfolios/<name>/settings.json Per-portfolio settings and Flex credentials
global_settings.json Global app settings (shared across portfolios)
data/quant_engine/ Financial database and metrics matrices (shared)

Help & About

Click Help & About in the sidebar to see:

  • Current QuantAscent version number
  • A button to open the log folder (useful for troubleshooting — contains app.log and crash reports)
  • System information (Python version, platform)
  • Instructions for reporting bugs

Troubleshooting

"IB Gateway: Disconnected" in sidebar - Make sure IB Gateway or TWS is running and logged in - Check that API connections are enabled in TWS/Gateway settings (Enable ActiveX and Socket Clients) - Verify the port matches (7496 for live, 7497 for paper) in both TWS/Gateway and QuantAscent Settings

Flex download fails - Verify your Flex Token hasn't expired (tokens expire periodically — regenerate in IBKR Account Management) - Check that your Flex Query ID is correct - IBKR rate-limits Flex requests — if you see retry messages, just wait

Database download fails - Check your internet connection - You can retry from Settings > Database > Check for Updates > Sync Now

Portfolio data seems stale - Restart the app — it will detect the gap and offer to backfill the missing days automatically - Make sure your Flex credentials are entered in Settings

App opens but shows no data on Dashboard - The dashboard needs at least one day of portfolio data. Ensure your Flex credentials are configured in Settings and restart the app to trigger the automatic catch-up

macOS: "QuantAscent can't be opened" (Gatekeeper) - Go to System Settings > Privacy & Security and click Open Anyway - This only needs to be done once — subsequent launches will work normally

macOS: network or firewall prompts - If macOS asks whether QuantAscent can accept incoming network connections, click Allow — this is needed for the IB Gateway API connection on localhost

Need More Help?