Radon

Reconstructing market structure from institutional signals.

Radon is a market-structure reconstruction system that detects institutional positioning and turns it into convex options trades using dark pool flow, volatility signals, and cross-asset positioning data.

Detects hidden positioning through dark pool, options flow, and cross-asset signals
Evaluates every trade through a strict three-gate framework
Generates portfolio, scan, and scenario reports with a real-time trading terminal on top

No narrative trades. No TA trades. Flow signal or nothing.

What Radon Does

Radon reconstructs market structure from multiple institutional signals and converts that information into executable trade ideas, risk reports, and portfolio decisions.

Inputs

Dark pool and OTC flow from Unusual Whales
Options flow, volatility surface, and open-interest change data
Real-time quotes and options chains from Interactive Brokers
Cross-asset volatility relationships, CTA positioning, and analyst context

Processing

Signal detection and scoring
Strategy-specific modeling
Convex options structure design
Fractional Kelly sizing and portfolio risk checks

Outputs

Trade candidates and evaluations
HTML reports for scans, portfolio state, and stress tests
Live portfolio and order-state monitoring in the web terminal
Execution and post-trade management through Interactive Brokers

Trade Validation Framework

Every trade must pass three sequential gates. If any gate fails, no trade is taken.

1. Convexity

Potential gain must be at least 2x potential loss.

Default posture: defined-risk structures
Typical structures: long options, vertical spreads, calendars
Exception: risk reversals are explicit manager-override trades

2. Edge

A trade needs a specific, data-backed signal that has not fully moved price yet.

Dark pool accumulation or distribution
LEAP implied volatility mispricing
Cross-asset volatility divergence
Credit-volatility dislocations or crash-risk regime shifts

3. Risk Management

Trades are sized using fractional Kelly with hard limits.

Max position size: 2.5% of bankroll
No pyramiding into weak signals
Portfolio-level exposure is monitored continuously

Strategies

Six active strategies drive the system.

Strategy	Signal	Market Inefficiency	Typical Structure	Timeframe	Risk
Dark Pool Flow	Institutional accumulation or distribution	Price lag versus hidden liquidity	Calls, puts, vertical spreads	2-6 weeks	Defined
LEAP IV Mispricing	Realized vol materially above long-dated IV	Long-dated volatility underpricing	Long LEAPs, diagonals	Weeks-9 months	Defined
GARCH Convergence	Cross-asset vol repricing lag	Surface adjustment is slower than regime change	Calendars, verticals	2-8 weeks	Defined
Risk Reversal	Skew distortion between puts and calls	Put demand richer than equivalent call demand	Risk reversal	2-8 weeks	Undefined
Volatility-Credit Gap (VCG)	VIX/VVIX/HYG divergence	Credit markets are lagging vol stress	Index puts, put spreads	1-5 days	Defined
Crash Risk Index (CRI)	CTA deleveraging plus correlation stress	Systematic positioning unwind	Index puts, tactical hedges	3-5 days	Defined

Full strategy specs live in docs/strategies.md. VCG research notes live in docs/VCG_institutional_research_note.md.

System Architecture

Interactive Brokers ----\
Unusual Whales ---------+--> Signal Detection Engine --> Strategy Evaluation
MenthorQ / CTA Data ----/                                  |
Exa / Research ---------/                                  v
                                                   Convex Structure Builder
                                                            |
                                                            v
                                                   Kelly Position Sizing
                                                            |
                                                            v
                                                   Execution / Monitoring
                                                            |
                                                            v
                                                       Radon Terminal

At a high level:

scripts/ contains scanners, evaluators, pricing logic, reporting, and broker integrations
web/ contains the Next.js terminal for portfolio, flow, orders, and AI-assisted workflows
data/ holds runtime artifacts and scan outputs

Quick Start

Prerequisites

Python 3.9+
Node.js 18+
Interactive Brokers TWS or Gateway running locally
Unusual Whales API access

Install and run

git clone https://github.com/joemccann/radon.git
cd radon
pip install -r requirements.txt
cd web && npm install && cd ..
python scripts/ib_sync.py
python scripts/scanner.py --top 15

Setup Details

Environment Variables

Web app in web/.env:

ANTHROPIC_API_KEY=your-anthropic-key
UW_TOKEN=your-unusual-whales-key
EXA_API_KEY=your-exa-key

Python scripts in the project root .env:

MENTHORQ_USER=your-menthorq-email
MENTHORQ_PASS=your-menthorq-password

Optional shell exports:

export XAI_API_KEY="your-xai-api-key"

Additional Dependencies

MenthorQ-based workflows require Playwright and httpx:

pip install playwright httpx
playwright install chromium

Interactive Brokers connects locally on port 4001 for Gateway or 7497 for TWS. No broker API key is required, but TWS or Gateway must be running before live workflows.

Radon Terminal

Radon includes a real-time trading terminal built with Next.js 16. It streams Interactive Brokers prices, computes live greeks, visualizes portfolio exposures, and serves as the operator interface for scans, evaluation, and monitoring.

cd web
npm install
npm run dev

Visit http://localhost:3000.

Key capabilities

Real-time price streaming with live greeks
Multi-leg position monitoring and per-leg P&L
Order management, including combo spread workflows
Flow analysis, regime views, and thesis checks
AI chat interface for command execution and analysis

Example Workflow

Run scan to surface dark pool and regime-aware candidates.
Run evaluate NVDA to execute the full seven-milestone validation flow.
If edge passes, design a convex structure and size it with Kelly constraints.
Send or stage the trade through Interactive Brokers.
Monitor the position in the Radon Terminal and portfolio report.

CLI Commands

Scanning

Command	Description
`scan`	Watchlist dark pool flow scan with CRI regime overlay and HTML report
`discover`	Market-wide or targeted discovery scan for new candidates
`leap-scan [TICKERS]`	Find LEAP IV mispricing opportunities
`garch-convergence [TICKERS]`	Cross-asset implied-versus-realized volatility divergence scan
`seasonal [TICKERS]`	Monthly seasonality analysis from EquityClock
`analyst-ratings [TICKERS]`	Ratings, price targets, and recent changes

Evaluation And Risk

Command	Description
`evaluate [TICKER]`	Full seven-milestone trade evaluation
`stress-test`	Interactive bear/base/bull scenario report for the current portfolio
`risk-reversal [TICKER]`	IV-skew analysis for directional risk-reversal structures
`vcg`	Cross-asset volatility-credit gap scan
`cri-scan`	Crash Risk Index with CTA exposure model

Portfolio And Operations

Command	Description
`portfolio`	Live portfolio report with dark pool thesis checks
`free-trade`	Analyze multi-leg positions for free-trade progression
`journal`	View recent trade log entries
`sync`	Pull live portfolio data from Interactive Brokers
`blotter`	Today's fills, grouped spreads, and commission totals
`blotter-history`	Historical trades via IB Flex Query

Research And System

Command	Description
`strategies`	Show the strategy registry
`menthorq-cta`	Fetch institutional CTA positioning data
`x-scan [@ACCOUNT]`	Fetch X sentiment through xAI
`x-scan-browser [@ACCOUNT]`	Fetch X sentiment through browser scraping
`commands`	Display the full command registry

Project Structure

radon/
├── scripts/          # Python scanners, evaluators, broker integrations
├── web/              # Next.js terminal
├── docs/             # Strategy and implementation documentation
├── brand/            # Radon design system
├── data/             # Runtime data and generated artifacts
├── config/           # launchd and service configuration
├── requirements.txt  # Python dependencies
├── CLAUDE.md         # Agent and workflow rules
└── .pi/              # Command registry and agent skills

Important directories:

scripts/clients/ for broker and data-provider adapters
scripts/tests/ for the Python test suite
web/components/ and web/app/ for terminal UI and routes
brand/ for the design system and tokens

Data Sources

Market-data priority is intentionally strict:

Interactive Brokers for real-time quotes, options chains, and portfolio state
Unusual Whales for dark pool flow, sweeps, options flow, and analyst data
Exa for company and market research
Yahoo Finance as a last-resort fallback

Auxiliary sources:

MenthorQ for CTA positioning used in CRI analysis
xAI / browser scraping for X-account sentiment workflows

Testing

Radon includes Python, frontend, and end-to-end test coverage.

Python: pytest for scanners, evaluation logic, utilities, and adapters
Frontend: Vitest for web logic
E2E: Playwright for browser workflows

python -m pytest scripts/tests/ -v
cd web && npm test
cd web && npx playwright test

Unit tests use mocked API calls where possible, so most development work does not require a live IB or Unusual Whales connection.

Services

The repo includes background-service support for the live trading environment:

Service	Purpose
Secure IBC service (`local.ibc-gateway`)	Maintains the local broker session for live quotes, execution, and reports
CRI scan service	Refreshes crash-risk regime data intraday
Monitor daemon	Tracks fills and manages post-entry workflows
Data refresh services	Keeps portfolio and order-state data current

Historical setup helpers remain in scripts/, and the broader implementation notes live in docs/implement.md.

Phase 1 Remote IBC Access

The current working path for iPhone control is standard macOS SSH over Tailscale to the secure machine-local IBC wrappers in ~/ibc/bin/.

Dependencies:

Tailscale.app on the Mac
Tailscale on the iPhone, connected to the same tailnet
macOS Remote Login
iPhone SSH client such as Termius, Blink Shell, or Prompt
Optional: dedicated public key in ~/.ssh/authorized_keys for key-based login

Reference docs:

Direct command example:

ssh joemccann@macbook-pro '~/ibc/bin/status-secure-ibc-service.sh'

Glossary

Term	Definition
Convexity	An asymmetric payoff where expected upside materially exceeds downside
CRI	Crash Risk Index, a composite crash-risk and deleveraging model
CTA	Commodity Trading Advisor, typically systematic trend-following funds
Dark Pool	Private off-exchange venue used for institutional trading
Edge	A specific reason the market is mispricing an outcome
Kelly Criterion	Position-sizing framework used to scale exposure to edge and odds
VCG	Volatility-Credit Gap, a divergence model across VIX, VVIX, and credit

Name		Name	Last commit message	Last commit date
.claude		.claude
.figma		.figma
.gemini		.gemini
.github		.github
.pi		.pi
brand		brand
config		config
context		context
data		data
docs		docs
lib		lib
logs		logs
reports		reports
scripts		scripts
site		site
tasks		tasks
web		web
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
PROGRESS.md		PROGRESS.md
README.md		README.md
VERSION		VERSION
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Radon

What Radon Does

Trade Validation Framework

1. Convexity

2. Edge

3. Risk Management

Strategies

System Architecture

Quick Start

Setup Details

Environment Variables

Additional Dependencies

Radon Terminal

Example Workflow

CLI Commands

Scanning

Evaluation And Risk

Portfolio And Operations

Research And System

Project Structure

Data Sources

Testing

Services

Phase 1 Remote IBC Access

Glossary

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Radon

What Radon Does

Trade Validation Framework

1. Convexity

2. Edge

3. Risk Management

Strategies

System Architecture

Quick Start

Setup Details

Environment Variables

Additional Dependencies

Radon Terminal

Example Workflow

CLI Commands

Scanning

Evaluation And Risk

Portfolio And Operations

Research And System

Project Structure

Data Sources

Testing

Services

Phase 1 Remote IBC Access

Glossary

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages