OraCore v3 requires Python 3.11+, PostgreSQL, and your API keys configured. Follow these steps exactly:

• Clone the repo and run pip install -r requirements.txt
• Copy .env.example → .env and fill in all REQUIRED keys (Alpaca, Polygon, PostgreSQL)
• Run DB migrations: psql -f database/init.sql
• Run the market data ingest: ./run.sh
• Start the trading engine: python -m trading.runtime.run_breakout20_manager

REQUIRED to run: ALPACA_API_KEY_ID, ALPACA_API_SECRET_KEY, MASSIVE_API_KEY_SSLABS (Polygon), DATABASE_URL

REQUIRED for Knowledge Brain: OPENAI_API_KEY (for LLM harvest), GITHUB_TOKEN (for GitHub harvest)

OPTIONAL: Discord (alerts only), Telegram, Webull (alternate broker), IEX/Finnhub (fallback data)

Webull provides a developer API through its open platform. Here is the full connection flow:

• Go to developer.webull.com and create a developer account
• Create a new App → get your App Key and App Secret
• Set WEBULL_APP_KEY and WEBULL_APP_SECRET in your .env
• Install the SDK: pip install webull
• Authenticate: wb.login(app_key, app_secret)

OraCore runs in paper mode by default. Switching to live requires 3 changes:

• Set ALPACA_PAPER=false in .env
• Change ALPACA_ENDPOINT to https://api.alpaca.markets
• Replace paper API keys with live API keys from Alpaca dashboard

Breakout20 identifies momentum breakouts on 15-minute bars. It fires when a symbol breaks above its 20-period high with above-average volume confirmation.

Gates (in order):

• Price closes above 20-bar high
• Volume is ≥ 1.5x the 20-bar average volume
• ATR spread is within acceptable range (no gap-and-go traps)
• VWAP is below current price (trend confirmation)
• Confidence score ≥ 0.65 (else REJECTED)

GRAIL is a multi-condition strategy combining trend structure, volume, and momentum. Fires on 15m bar close when multiple conditions align simultaneously.

Gates include: EMA alignment, RSI confirmation, VWAP position, volume surge, and structural support/resistance validation.

Profiles: Strict (all gates must pass, production), Lax (relaxed gates, shadow mode only for missed-signal analysis).

Production: Signals from this profile flow through the full pipeline and result in real (or paper) orders being placed.

Shadow: Signals are generated and logged, but NEVER submitted to the broker. Used to measure what a strategy WOULD have done without risking capital.

Diagnostic: Even looser — records raw scanner hits with no filtering, for pure analysis.

OraCore uses ATR-based position sizing. The risk per trade is a fixed dollar amount ($R). Shares = $R ÷ (Entry Price − Stop Price).

This ensures every trade risks exactly $R regardless of the stock's price or volatility.

TP1: Sell 50% of position at first profit target (typically 1.5R–2R). Activates trailing stop on remainder.

TP2: Exit remaining 50% at second target (typically 3R–4R).

Trailing Stop: Moves stop up as price advances post-TP1. Locks in profits. Uses ATR multiplier to avoid noise.

Time Stop: Exits position if held past a time threshold (e.g. 2 hours) with no progress toward TP1.

Hard Stop: Always active. Market-sell triggered if price hits stop level.

The Kill Switch is the master entry blocker. When activated, NO new signal can result in a trade entry — but all existing positions continue to be managed normally (exits, stop adjustments, reconciliation).

When to use it: Major news events, earnings announcements, unusual market volatility, system debugging, or anytime you want to let existing trades run but take no new ones.

Activate it with the ☠ KILL SWITCH button in the top navigation bar.

The Daily Risk Guard tracks cumulative realized losses for the current trading day. Once losses reach the configured threshold ($1,000 by default), the guard automatically blocks all new entries for the remainder of the session.

The limit resets at midnight UTC (start of next trading day).

Panic Close sends market-sell orders for ALL open positions simultaneously. It bypasses all normal exit logic and submits orders immediately.

Access via: Trading page → Panic Close All button (red, top right).

The Runner Lock prevents more than one orchestrator process from running at the same time. If you accidentally start a second instance, it immediately detects the lock file and exits — preventing duplicate bar processing and double-order submissions.

Lock file location: .runner.lock in the project root.

The ingest system has 3 phases that run in sequence on startup:

• Flatfile Catch-Up: Downloads bulk historical data from Polygon.io flat files (S3-backed). Fills the last 7 days of candles for all 847 symbols across all 6 timeframes. Runs once on startup if data is stale.
• REST Delta Pass: Fetches any missing bars since the flatfile cutoff using the Polygon REST API. Fills gaps precisely.
• Live Ingest Loop: During market hours (9:30 AM–4:00 PM ET), polls Polygon REST every N seconds (default 60s) to fetch the latest completed bars.

The universe starts from a WatchListScanner (WLS) CSV file and is then filtered through 4 gates before being stored in the filtered_universe PostgreSQL view:

• outstanding_shares: excludes micro/nano-cap shells
• price_snapshot: excludes symbols with no recent trade data
• min_volume: minimum daily dollar volume threshold
• locale_us: US-listed securities only

The resulting 847-symbol universe is what the scanners run against on every bar close.

Each symbol is health-checked before the scanner runs. A symbol is HEALTHY if it has complete candle data for the required timeframes with no gaps exceeding a threshold.

A symbol is WARNING if it has minor gaps (e.g., a few missing 5m bars). It still scans but results may be less reliable.

Health results are cached in .cache/shortfalls.csv and shown on the Market Data page health distribution chart.

The harvest pipeline ingests content from 5 sources and chunks it into 512-character segments (64-char overlap) before embedding into ChromaDB:

• GitHub — README.md files from relevant repos (requires GITHUB_TOKEN, free)
• LLM — GPT-4o generates synthetic role-specific content (requires OPENAI_API_KEY)
• Web — DuckDuckGo search + scrape for each role query
• YouTube — Transcript extraction from relevant videos
• PDF — Upload documents via the CLI for ingestion

The REST API (FastAPI on :8500) exposes semantic search over all 48,291 chunks. Queries are embedded using all-MiniLM-L6-v2 and matched against stored vectors via cosine similarity.

The role filter restricts results to chunks from a specific role's knowledge collection.

The candidate scorer takes a resume or profile text, embeds it, and compares it against the knowledge chunks for a target role. It returns a match score (0–100) indicating how well-aligned the candidate is to the role's knowledge profile.

Returns: {"score": 74.2, "top_matches": [...], "gaps": [...]}

All timestamps stored in PostgreSQL are in UTC. Eastern Time (ET) is only derived at session-logic boundaries (e.g., checking if a bar falls within RTH hours). This eliminates DST ambiguity that would otherwise cause the system to misfire on clock change days (March and November).

OraCore uses two separate idempotency layers to prevent duplicate orders on restarts:

• Layer 1 — Signal Claim: A signal is "claimed" with a unique key before any order logic runs. If the same signal fires again, it's ignored.
• Layer 2 — trade_orders table: Each order written to DB before broker submission. On restart, existing orders are reconciled against Alpaca fills before any new entries.

When multiple signals are approved simultaneously and only N slots are available, OraCore selects in this exact order: confidence → fired_at → dollar_volume → signal_id

This deterministic ordering ensures that a system restart after a crash produces exactly the same selection result as if it had never crashed — critical for avoiding phantom position divergence.