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, signing in to your account, 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.

Demo Mode: Until you create a portfolio, QuantAscent runs in Demo Mode — every execution view is pre-populated with a three-year sample portfolio so you can explore the app before committing to the IBKR setup. The Research, Strategy Builder, Backtesting, Company Analysis, and Screener tabs work fully even without a broker connection. When you're ready, click the yellow demo banner on any page (or follow Step 4 below) to start the IBKR setup.

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. Sign In to Your QuantAscent Account

On first launch, a sign-in dialog appears. You'll need a QuantAscent account to download the financial database, install updates, and use the gated features (Research, Strategy Builder, Company Analysis, Company Screener).

If you received an invitation email

  1. Click the link in the invitation email — it'll open a browser tab where you set your password
  2. Once your password is set, return to QuantAscent and enter the same email and password in the sign-in dialog
  3. First sign-in only: QuantAscent will email you a 6-digit verification code. Enter it in the dialog to complete sign-in. You won't need this code again on this computer as long as you stay signed in.
  4. Keep me signed in on this computer is checked by default — leave it on so subsequent launches skip the dialog. Uncheck it if you're on a shared computer.

If you don't have an invitation yet

If your account hasn't been set up yet, head to accounts.quantascent.io/sign-up to create one. QuantAscent is in closed alpha — applications are reviewed individually and you'll receive an email with a decision within 1–2 business days.

In the meantime, you can choose Continue in read-only mode at the bottom of the sign-in dialog to explore the app without an account. Most local features (existing portfolio data, IBKR live data, backtests on cached data) work in read-only mode; live trade execution, scheduler, and database sync require approval.

Account state in Settings

After signing in, Settings > Account shows your email and a status badge:

  • Alpha tester (green) — full access
  • Pending review (yellow) — your application is being reviewed; live features are gated until approval
  • Access revoked (red) — contact [email protected] if this is unexpected

You can sign out of QuantAscent or open the hosted account-management page from the same card.

3. Database Sync & Metrics Matrix

After you sign in, 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 installs the 85 built-in strategies, organized by factor — Equal Weighting, Momentum, Quality, Value, and Financial Strength. Every sector ships all five factor variants, alongside universe-wide and index-tracking strategies, each with a cached 10-year backtest. 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, tick exactly these seven boxes (leave every other section unchecked). Ticking a box only tells IBKR which sections to include — you'll configure each one in step 6.

    Tick 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

  9. Open and configure each section. This is the part that's easy to miss: ticking a section in step 5 doesn't configure it — it just includes it. To configure a section, click the section's name (not the checkbox) and a configuration dialog pops up. Each dialog has two areas, and you need to configure both before closing it.

    Top of the dialog — Options tiles. Most sections show one or more clickable tiles labeled with detail levels (e.g. "Summary", "Lot", "Execution", "Closed Lots"). These control how much detail IBKR includes in the export. Click each required tile so a checkmark appears in its corner. The required tiles per section:

    Section Required tile(s) in the dialog's Options area
    Cash Report Click every tile (or use the section's Select All)
    Cash Transactions Deposits & Withdrawals + Detail
    Change in NAV (no Options tiles — go straight to the data fields below)
    Corporate Actions Click every tile (or use the section's Select All)
    Open Positions Summary ✚ Lot ⚠️ — both tiles, see warning below
    Realized and Unrealized Performance Summary in Base Detail
    Trades Execution ✚ Closed Lots ✚ Order ✚ Wash Sales ⚠️ — see warning below

    Bottom of the dialog — data field columns + "Select All". Below the Options tiles, every dialog has a long list of column checkboxes (Account ID, Symbol, Conid, Currency, etc.) with a Select All checkbox at the top. For every section, click "Select All" here before closing the dialog. These are the XML attributes that get emitted on each record — missing any required one will break QuantAscent's ingest, and extras are harmless.

    Repeat this for all 7 sections you ticked in step 5. Each section's dialog has its own Options tiles and its own Select All — they don't share state.

    Open Positions — must include the 'Lot' tile, not just 'Summary'

    In the Open Positions dialog's Options area, both Summary and Lot must be checked (each tile shows a small checkmark in its top-right corner when active). Lot is off by default in some IBKR UI versions, so it's easy to miss — only Summary is enabled out of the box.

    Without Lot, QuantAscent can't reconstruct positions you opened before your portfolio start date. You'll see phantom holdings in IBKR live data and silent P&L drift on any later sales of those positions.

    Trades — must include all four detail-level tiles

    In the Trades dialog's Options area, all four of these tiles must be checked: Execution, Closed Lots, Order, Wash Sales.

    Without Closed Lots, sales attribution falls back to wash-blind FIFO and ST/LT tax classification can be wrong on wash-replacement lots. Without Wash Sales, disallowed-loss adjustments are silently dropped from your tax reports. These tiles are separate from the section's "Select All" data fields — clicking Select All on the bottom doesn't enable them.

  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, data field, or detail-level option is missing — including the Open Positions Lot detail and Trades Closed Lots detail. If you miss any of these, 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). Each portfolio also has its own Flex Query and token, since IBKR paper accounts have a separate Client Portal session from live — create your paper Flex query while logged into the paper Client Portal, then enter that query ID and token in Settings for your paper portfolio. Switching portfolios reloads the Dashboard, Holdings, and all strategy data for the selected portfolio.

Quick Reference

Task Where
Sign in / sign out / manage account Settings > Account
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?