▶ Video Starting SOAP2 before IB (reconnect procedure) (0:41) · all videos
## What This Guide Covers You start SOAP2 and, without you clicking anything, a lot happens: your trades load, IB data starts to flow, one Options Analysis window opens, numbers get computed and saved. This guide lists those things in the order they happen, says what they cost (IB data lines, network calls, disk), and says which ones depend on your edition or a setting, so you can tell "normal" from "something is wrong". Everything here is automatic. Nothing in this guide places an order or changes an account. > Good to know: SOAP2 never needs you to be connected to start. If TWS is not running, it starts in **Offline mode** with the last saved data (see the last section). ## The Short Version 1. **Splash screen** — settings, licence, folders, watchlist and trades load from your disk. 2. **Connect to TWS** with the saved connection settings (if TWS is up). 3. **Contract and chain definitions** are requested for every watchlist symbol. 4. **One Options Analysis (OA) window** opens for your default symbol, and its live option data starts streaming. 5. **Trade prices** start updating once a second. 6. **Background jobs** (rates, VIX/vol-index history, rules, Outlook, index statistics, margin records) start, some immediately, some only after the "initial loading" message. The status bar at the bottom ends the sequence with *"Ready (Connected). Initial loading completed in N secs"*. Jobs marked **after Ready** below wait for that line on purpose, so they never compete with the start-up requests. ## Step 1 — Before You See the Main Window (local only, no IB) These need no connection and no internet beyond the two small checks noted. - **Previous crash report.** If the last session did not shut down cleanly, SOAP2 offers to email or copy the report before clearing it. - **Settings and licence.** `soapconfig.json` is read, your licence edition is resolved from the saved token, and the title bar shows the edition. Your edition decides which of the jobs below run. - **Folders** under your SOAP2 data folder are created if missing. - **Watchlist.** `Watchlist.csv` is read (a default watchlist is seeded on a first run). The Free edition shows a short fixed list; the file itself is untouched. - **Accounts** are read, and **every account's trades** are loaded, not just the one selected. Fills for each open trade are read into memory. - **Housekeeping on load:** - A trade with **no open legs** (fully closed, or expired and settled to zero) is **archived automatically**, with a Message Log line and a notice in the status strip you can click to review. - Saved **models** that contain an expired leg are removed. - Option history files for **long-expired expiries** are deleted (background thread). - Back/Forward history of existing trades is built from their fills where none exists, and the history of deleted or long-archived trades is swept. - Trade Builder shortlists forget expired or old entries. - **Last known results** (the "last known state" of each analytical tool under `Results\`) are loaded, so tools can show their previous answer before anything recomputes. Two small network calls also start in the background and never block the start: a **check for a newer SOAP2 version** (one Message Log line if there is one) and, until it has succeeded once, a **region check** used to decide which default watchlist symbols apply. ## Step 2 — Connecting to TWS SOAP2 first checks that TWS is reachable and the API is enabled, then connects with your saved settings (host, port, client id; default `127.0.0.1:7497`). If it connects: - Contract details are requested for **every watchlist symbol** (this confirms the contract ids, which IB can in principle change). - The **Rates** job starts (next section) and, in Premium and above, the **history recorders** (see "Background jobs"). - Account summary and positions feed the Accounts windows and the account-level [Trade Rules](./trade_rules_user_guide.md.html). If it cannot connect, you get the reason in the Message Log, the status bar goes red, and the Offline path runs (last section). Connecting later from the SOAP menu runs the same steps then. ## Step 3 — Chain Definitions When contract details are back, SOAP2 asks IB for the **option chain definitions** (expiries and strikes available) for: 1. your **default symbol** first, then 2. every **other watchlist symbol** one after another, with a short pause between requests so IB is not flooded. Definitions are saved to `Definitions\{Symbol}_ChainsDefinitions.csv` as they arrive, and the Message Log says *"All watchlist chain definitions are now available"* at the end. Watchlist prices start streaming and SOAP2 begins resolving each symbol's **anchor price** (the market-maker price used to centre strike ranges). **Why you will see more requests ten minutes later:** ten minutes after the first chain definitions arrive, and then **every 8 hours** (change this in General Settings > IB tab), SOAP2 refreshes the full contract list of your current symbol's open OA windows. It is a large burst (thousands of requests on a big chain), so it waits if a Volatility Surface cycle is running and retries a minute later. Contracts IB does not know are summarised in a single Message Log line, not listed one by one. ## Step 4 — The First Options Analysis Window Only **one** OA opens by itself, for the default symbol (the one in the toolbar), and only when its chain definitions are available. (Setting: *Auto-create OA on symbol change*.) On opening, the OA: - Applies the symbol's **Preferred Settings**. If they are missing or incomplete, the settings window opens and no chain request is made for that symbol until you complete them (that avoids a flood of IB "no security definition" errors). - Builds the strike grid and **subscribes market data for the visible rows only**; scrolling subscribes the new rows and releases the old ones. All streams go through one place, so SOAP2 can always count them (status bar: *Num Data*, *Watchlist*, *TLog*, *Chain*). - Reuses a **Volatility Surface fit** from disk if it is less than an hour old; otherwise no surface cycle is run at start-up, only when you open the VolSurface tool. - Loads the **selected trade** (if any) and subscribes its legs. - Starts the **ATM / skew bookkeeping** (next section). Two optional settings go further: **Open default OA on startup** forces the OA window onto the screen at Ready, and **Open Portfolio on startup** opens the [Portfolio](./portfolio_user_guide.md.html) window too. With neither, the main window shows a tip pointing at the green arrow. ## Background Jobs: The Complete List ### Running from the first seconds | What | How often | Cost | Edition | |---|---|---|---| | **Trade prices.** Marks and IV for the legs of every monitored trade, even with no OA open; trades whose contracts were not yet known at start-up are retried | every second | IB lines for the trade legs | all | | **Status bar and connection watch.** Counts of data lines per owner, unowned or stale request ids, socket check; red/green connection light | every 2 s (set in General Settings > Performance) | none | all | | **Interest rates.** Uses the live SR3 futures curve when one exists; otherwise fetches Treasury yields from the web, saves them and falls back to the saved file if the fetch fails. Bank holidays load at the same time | at start, then daily (retry in 10 min on failure) | small web fetch, or a few futures lines at connect that are released once priced | all | | **Tips.** One hint in the status strip | periodic | none | all | | **Licence re-check.** Asks the licensing server whether your entitlement is still valid; failure only logs, your saved licence keeps working | every 6 hours | tiny web call | all | | **Local AI bridge.** The service the Claude/MCP assistant talks to starts at launch. Help search is open to everyone; live-state answers need the AI setting and the right edition | idle until asked | none until a request | all (calls gated) | | **Market-maker price proxy.** Fills anchor prices for watchlist symbols that have no live quote | until every watchlist price resolves | a few temporary lines | all | ### Running from the OA window once it is open | What | How often | Cost | Edition | |---|---|---|---| | **ATM IV and ATM term structure** of the selected expiry and of the other expiries in the skew set, **published to the stored results** in every display mode (also in Risk Graph) | with each skew tick | the lines the OA already streams | all that include the OA | | **Risk summary and probabilities** for the loaded trade or models, published once complete (a pass with missing marks is never stored as the answer) | when marks change | none extra | all | | **Data repair.** Rows whose data id no longer matches their strike are re-requested; after a disconnect the grid re-subscribes by itself on reconnect | continuous | as needed | all | Live data only is stored; [Rewind](./rewind_user_guide.md.html) and CBOE playback never overwrite the last known state. ### Starting only after "Ready" (so they never compete with start-up) | What | When | Cost | Edition | |---|---|---|---| | **Trade Rules.** Evaluates every monitored trade's and account's rules; alerts appear in the dashboard and the OA overlay, plus a Windows notification if you enabled **Notify** | every 60 s | none (reads data already in memory) | Regular and above | | **Underlying Outlook** for SPX, NDX and RUT: multi-timeframe read, stored for the AI bridge and the dashboard | every 30 min while the US regular session is open, plus once after the close; a failed try waits 5 min | IB historical-data requests (one symbol at a time) | Premium | | **Index distribution statistics** for SPX, NDX and RUT (daily bars) | once a day, starting 30 min after the close, only for an index not yet done for that session | IB historical requests | Premium | | **VIX term structure** (VIX plus VX/VXM futures found in your watchlist) | every 60 s once all are priced, or after 3 min with a note on what is missing; never replaced by an empty pass | none (watchlist ticks) | all | | **Margin records.** The peak RegT-at-expiry margin of each trade is recomputed from fills when they change (3 trades per pass) and stored for Trade Reports | every 10 s | none, no data request | all with Trade Reports | | **Entry context.** When a trade appears *during* this session, SOAP2 freezes the market state (regimes, GEX, ATM…) from the stored results so Reports can group by entry. Trades that already existed at start-up are never captured (their entry is unknown) | every 20 s | none | all with Trade Reports | ### Started when IB connects (Premium and above) These record history so tools such as Rewind and the Feature Store have data, and fill the gap since the last session. They stop when the connection drops and resume on reconnect. - **VIX and rate-curve recorder** — VIX daily bars and the resolved rate curve. - **Dispersion recorder** — daily closes of SPX, SPW, DSPX, COR1M and VVIX (feeds the [Dispersion](./dispersion_regime_user_guide.md.html)/Correlation regime). - **Implied-volatility recorder** — daily closes of the VIX, RVX and VXN families. The first run downloads the **full history once** (slow; paced at 250 ms per request); later runs fill only the gap since the last row. Each uses one fixed streaming request per symbol, kept up to date, so they hold a handful of IB data lines for the whole session. ### Only when something wants them - **GEX/VEX background pass.** A running OA computes the selected expiry's [GEX/VEX](./gexvex_user_guide.md.html) without showing it only if a **consumer** asks: the Trade Builder on a 0DTE tab, or the AI bridge (`run_analysis ib_gex`, which takes a 5-minute renewable lease). It never starts while HSkew, VSkew, VolSurface, GEX/VEX, [Hedging Flow](./hedgingflow_user_guide.md.html) or [TRACE](./trace_user_guide.md.html) is on screen, and only while the account is under its request budget. Nothing runs by default. - **Tastytrade market data.** Off unless you enabled it in General Settings (Regular and above). When on, it serves option rows and watchlist fills instead of IB lines; the status bar then shows a *TT:* count. - **CBOE CDN flow poller (Hedging Flow history).** Developer builds only, and only if switched on; it is a plain web fetch, independent of IB. - **"Since you left" digest.** Not active in the current release. ## What Start-Up Will Not Do - It does not place or change orders. - It does not open one OA per watchlist symbol; only the default symbol gets a window. - It does not run a Volatility Surface, HSkew/VSkew history, TRACE, or Hedging Flow session: those start when you open them, and switching to Risk Graph or Calendar later never cancels one already running. - It does not send your trades, positions or market data to a server. The only server contacts are the version check, the region check, the licence check and, if the Treasury fallback is used, the yields fetch. (Calculation servers are used only for tools you open.) ## Offline Start If TWS is not up, SOAP2 says *"SOAP is in Offline mode"* and: - loads the **saved chain definitions** of your default symbol and opens its OA from the last saved grid (status: *OFFLINE. Data may be stale — connect to IB to refresh*), or says no cached chain is available; - still loads trades, rules, results and reports, all from disk; - skips every job above that needs IB (trade prices, recorders, Outlook, index statistics). When you connect later, SOAP2 runs the connection steps then: contract details, chain definitions, the trade price timer, the rate curve and, in Premium and above, the recorders. Open OA and [Data Chart](./datachart_indicators_user_guide.md.html) windows resume by themselves. ## If Something Looks Wrong | Symptom | Likely reason | |---|---| | Status bar stays on "initial loading" | The watchdog gives up after a time-out, logs why, and leaves the app usable; pick a symbol and click the green arrow. Check Preferred Settings for the symbol. | | No OA opened | Chain definitions for the default symbol have not arrived, or *Auto-create OA* is off. | | Trade shows no prices right after start | Its contracts were not known yet; it is retried every second. Check the *TLog* count in the status bar. | | Burst of requests ten minutes in | The full-chain refresh (see Step 3). It repeats every 8 hours by default. | | Trade disappeared from the list | It had no open legs at load and was archived; click the archive notice in the status strip. | | Outlook, index statistics or recorders never run | Premium feature, or not yet past the "Ready" line, or not connected. | | *Num Data* near your cap | Open OA windows and background tools share one account-wide budget; close what you are not using. | ## How It Fits Your Workflow 1. Start TWS first, then SOAP2, so the whole sequence runs in one go. 2. Wait for **Ready** before opening heavy tools (VolSurface, TRACE); the background Outlook and statistics jobs start then too. 3. Leave SOAP2 running through the session: the recorders, the stored results and the margin records only get better with time connected. 4. After a disconnect you do not need to restart: reconnect from the SOAP menu and the steps above resume by themselves.