Capitol Alpha Terminal (TradePoli)

A Bloomberg-terminal-style dashboard + MCP server that tracks publicly disclosed U.S. politician stock trades (STOCK Act filings), ranks who is actually worth copying, backtests every politician against their real disclosed exits, and can auto-copy chosen politicians through Alpaca under a strict safety model.

⚠️ This is not insider data. Congressional trade disclosures are public filings that can arrive up to 45 days after the transaction. Amounts are disclosed as ranges, not exact sizes. Everything here is delayed research data, not financial advice.

Highlights

• Live trading-floor Command Center: scrolling market ticker tape, auto-refreshing LIVE FILINGS feed with one-click "is this still actionable?" screening, 30-day congressional money-flow board with consensus detection, and an interactive force-directed trading network (every politician linked to what they trade; zoom, pan, drag, click through).

• Per-ticker trading views: 1-year price chart with every congressional buy/sell plotted on the politician's actual trade date.

• Backtests on real behavior: entries on their trade date or your filing date, exits at their actual disclosed sales, optimal-hold sweeps, delay-cost comparison, and a Best Trades board (every politician's single best trade with the "Filed +Nd" receipt).

• Leaderboards ranked by Copyability Score (confidence-adjusted value of following someone from today, penalizing slow filers and missing exits).

• Follow a politician: auto-copy every buy they file under your rules (stake, max hold, max concurrent, max accepted delay), with data-driven recommendations from their real record. Dry-run by default, exits first, hard caps, one explicit confirmation to go live.

• MCP server so Claude (or any MCP client) can query trades, run backtests, and generate daily briefings.

Want to build your own version from scratch? See workbook.md (setup workbook + the full build prompt) and docs/REBUILD_SPEC.md (the complete spec).

What's inside

apps/
  dashboard/     Next.js 15 dashboard (dark trading-terminal UI)
  mcp-server/    MCP server (stdio + HTTP) and ingestion worker
packages/
  shared/        Shared TypeScript types, freshness labels, disclaimer
  db/            Drizzle ORM schema + query layer (PostgreSQL)
  scoring/       Filing delay, amount ranges, dedup hash, alert scoring (0-100)
  ingestion/     Quiver adapter, CSV import, Yahoo market data, alert pipeline
  ai/            Anthropic summaries/briefings/YouTube segments + legal guardrails
tests/           Integration tests (pipeline, MCP tools, REST API)

Related MCP server: Capitol Trades MCP

Prerequisites

• Node.js 20+ (tested on 22)

• PostgreSQL running locally (DATABASE_URL in .env)

• API keys (see .env.example): Quiver Quantitative (required for live data), Anthropic (required for AI features; everything falls back to templates without it)

Setup with your AI (recommended)

Clone the repo, open it with your AI coding agent (Claude Code, Cursor, etc.), and paste this:

Read ONBOARDING.md in this repo and onboard me. Check my prerequisites, ask me for the API keys it lists (I'll paste them in), create my .env, run the setup, then launch the web server and confirm the dashboard loads at localhost:3000.

The agent walks you through everything: prerequisites, keys, database, one year of data, and launch. See ONBOARDING.md for exactly what it will do.

Setup by hand (one command)

npm run setup

npm run setup is idempotent and does everything: checks Node/Postgres, installs deps, creates the .env (from .env.example, defaulting the DB user to your OS user) if missing, creates the tradepoli database, applies the schema, seeds defaults, pulls ~1 year of filings from Quiver, and precomputes the leaderboards. Run it as many times as you like; it only does what's missing.

First run: if there's no .env yet, setup creates one and stops so you can paste in your keys (QUIVER_API_KEY and ANTHROPIC_API_KEY at minimum), then run npm run setup again.

npm install                          # install all workspaces
cp .env.example .env                 # fill in DATABASE_URL, QUIVER_API_KEY, ANTHROPIC_API_KEY
psql -c "CREATE DATABASE tradepoli;" # or: createdb tradepoli
npm run db:push                      # create tables
npm run db:seed                      # seed example data + default settings
npm run ingest -- --since 2025-07-01 --limit 25000   # ~1 year of filings
npm run leaderboards                 # precompute 30/60/90/365d boards

Moving to another computer

The repo carries the code; two things do not travel and must be recreated: your .env (keys, gitignored) and the local Postgres data (regenerated from Quiver).

Option A · copy the folder (simplest, keeps your .env):

1. Copy the whole tradepoli/ folder to the new machine (USB, cloud drive, rsync). Skip node_modules/ and .next/ if you can (they rebuild).

2. Install Node 20+ and Postgres, then start Postgres.

3. npm run setup (it reuses the copied .env; rebuilds node_modules and the database from scratch).

4. npm run dev.

Option B · git (recommended):

# on the new machine:
git clone https://github.com/daviddme/capitol-alpha-terminal.git tradepoli && cd tradepoli
npm run setup          # creates .env from .env.example, then stops
# paste your QUIVER_API_KEY + ANTHROPIC_API_KEY (and any others) into .env
npm run setup          # finishes: DB, ingest, leaderboards
npm run dev

.env is gitignored on purpose (it holds secrets), so with git you re-enter the keys once on the new machine. Keep your keys somewhere safe (password manager); .env.example lists every variable.

Either way, the first npm run dev also triggers the worker to warm any remaining caches (best trades, optimal-hold sweeps) on boot, so give it a couple of minutes before those pages are fully populated.

Continuing with Claude Code on the new machine

Two context sources let Claude pick up where it left off:

• docs/PLATFORM.md ships in the repo and is the durable design record (every engine, page, finding, and limitation). Point Claude at it first on the new machine.

• Claude Code's project memory lives outside the repo at ~/.claude/projects/<project-hash>/memory/. It won't travel with git or a folder copy. To keep the accumulated notes, copy that memory/ folder to the same path on the new machine (the hash is derived from the repo's absolute path, so keep the repo at a comparable location, or just let Claude rebuild context from PLATFORM.md, which is written for exactly that).

• The repo ships .mcp.json, so Claude Code in this folder auto-connects to the political-trades MCP server once npm run dev (or the stdio server) is running.

Run

npm run dev

Starts three processes:

• Dashboard → http://localhost:3000

• MCP server (HTTP) → http://localhost:8787/mcp

• Worker → ingests Quiver every 6h, rescoring hourly, AI summaries for top trades

Connect Claude to the MCP server

# stdio (recommended; used by .mcp.json in this repo automatically)
claude mcp add political-trades -- npx tsx apps/mcp-server/src/stdio.ts

# or HTTP while npm run dev is running
claude mcp add --transport http political-trades http://localhost:8787/mcp

Then ask Claude things like "What are the freshest politician trades today?" or "Generate today's daily briefing in youtube mode."

MCP tools

get_latest_trades, search_trades, get_politician_profile, rank_politicians, get_ticker_activity, get_alerts, generate_daily_briefing, create_experiment, add_trade_to_experiment, generate_youtube_segment, manage_watchlist, summarize_trade, backtest_politician, backtest_leaderboard, screen_trade, get_golden_opportunities, autotrade_status

Resources: political-trades://latest, ://alerts, ://watchlist, ://experiments, ://daily-briefing, ://schema

Tests

npm test

106 tests: unit (delay calc, amount ranges, dedup hash, alert scoring, backtest engine, screening classification, AI guardrails) + integration against a real local Postgres (ingestion pipeline, stored leaderboards, the autotrade decision pipeline and its safety invariants, follows, exit signals, all MCP tools over a real client/server pair, REST API against the dev server).

Environment variables

See .env.example. Key ones:

Market data is unofficial Yahoo Finance (no key, best effort, MVP only). Swap for Polygon/Tiingo for production use.

Alert scoring

score = freshness + size + watchlist + cluster + politician - stalePenalty, clamped 0-100. Freshness labels: 0-7d Fresh, 8-14d Recent, 15-30d Delayed, 31-45d Very delayed, 45+d Stale.

Backtests (the $10k challenge, simulated)

The Backtests page (F5) simulates copying any politician's disclosed buys with a $10,000 account: equal position sizes, entry at the first close after the public filing, exit when they disclose a sale or after a configurable hold period. You get an equity curve vs SPY with every trade plotted, a win/loss blotter, and a delay comparison chart (enter +0 / +10 / +27 days after each filing) that shows how fast the edge decays. The leaderboard runs the same simulation for the ten most active politicians and ranks them by simulated return.

npm run backtest -- --politician "Ro Khanna" --lookback 365 --hold 30 --delay 0

Price history is cached per ticker in Postgres (price_history); daily results cache in backtest_cache. Simulations ignore fees, slippage, and dividends, and use unofficial Yahoo closes. Research only.

Leaderboard (30/60/90 days, every politician)

The Leaderboard page (F6) runs EVERY politician who filed a tradable disclosure in the window through an identical $10k simulation: same starting equity, same $1k position sizing, same entry rule. Tabs for 30, 60, and 90 days, sparkline equity curves per politician, and a full "if you copied the top 5" combined portfolio chart (one $10k account following all five). The top 5 are picked with hindsight, so that chart is explicitly labelled the most bullish scenario. The Command Center shows the top-5 preview and the combined curve. Boards are recomputed daily by the worker (07:15) and on demand:

npm run leaderboards

MCP tool: get_full_leaderboard (periodDays: 30 | 60 | 90). API: GET /api/leaderboard?period=30.

Their real holding periods (Backtests page)

Sales are disclosed too, so the analyzer FIFO-matches each politician's sale filings against their prior buys of the same ticker (on transaction dates) to measure their REAL holding behavior: median/mean hold, distribution histogram, and how many buys never get a disclosed exit. The exit scenarios chart includes "their actual exits" (follow their sale filings, no time limit) alongside the fixed-hold variants, and the backtester has an exit-mode selector: their sales + max hold (default), their sales only, or fixed hold only. Caveats shown in the UI: one filing = one lot (amounts are ranges), and roughly half of buys have no disclosed exit yet.

Optimal hold analysis (Backtests page)

Politicians rarely disclose exits, so the Backtests page sweeps hold durations from 1 to 90 days to find how long the edge actually lasts, on two bases: entering when THEY did (transaction date) and entering when YOU could (filing date, delay included). It marks the optimal hold for each, shows the median/mean optimal across the 15 most active politicians, and charts three exit scenarios over the same entries: the standard 30-day hold, a fixed hold at the optimal duration, and the perfect-exit ceiling (every position sold at its peak close in-window, impossible to trade, useful as the bound). API: GET /api/backtest/optimal-hold/[politician] and /api/backtest/optimal-hold/aggregate.

My Equity (F8)

With an Alpaca account connected, shows your real portfolio history (1M daily) and open positions. Without one, it shows a transparent, shareable simulation: one $10k account copying the 30-day top-5 leaderboard politicians, clearly badged "SIMULATION · WHAT COULD HAVE HAPPENED". Also previewed at the top of the Command Center. API: GET /api/my-equity.

Alpaca tradability fact-checking

Disclosure data contains instruments no broker can trade: Treasury/bond CUSIPs (91282CGJ4), options, municipal securities, free-text fund names, and dead tickers. Two-layer check before any order:

1. Static (always on): symbol shape + disclosed asset type. Audit the database anytime with npm run audit:tradability (currently ~98.7% of the last 90 days pass; options/CUSIPs/junk fail).

2. Live (when keys exist): GET /v2/assets per symbol, cached 7 days in asset_checks. Catches delisted/renamed tickers and enforces fractionable-asset support for notional orders. Class-share symbology is normalized to Alpaca's dot format (LEN-B → LEN.B).

The autotrader refuses any symbol that fails either layer, with the reason logged in the decision log.

Automation (Alpaca + AI screener)

The Automation page (F11) connects an Alpaca account (paper by default; keys are verified against Alpaca before saving, AES-encrypted when SECRET_ENCRYPTION_KEY is set) and runs fresh filings through a three-stage gate before any order:

1. Hard rules: max filing age (default 21 days, counting delay + time since publication), buys only, watchlist filter, minimum alert score, daily order cap.

2. Drift screen: current price vs the politician's entry close. Past maxDriftPct (10%) the move already happened and the trade is rejected as late. At/below goldenDriftPct (2%), including prices below the entry, it's a golden opportunity.

3. Claude relevance gate: a conservative structured verdict that can veto but never resurrect a rejected trade. Orders only go through at/above minAiScore.

Everything starts in dry-run: the full pipeline runs and logs every decision (including skip reasons and AI vetoes) without touching the broker. Going live requires enabling autotrading, unchecking dry run, AND clicking the explicit live confirmation. Golden opportunities also appear on the Command Center and via the get_golden_opportunities / screen_trade / autotrade_status MCP tools. You are responsible for orders placed with your keys; nothing here is financial advice.

Experiments

Create an experiment (e.g. Preset A: $10,000, copy watchlist trades filed within 30 days, equal weight), add trades from alerts, and the tracker records the price at the moment you saw the filing (not the politician's entry). PnL refreshes against live prices, with SPY / QQQ / NANC / KRUZ benchmark comparison and CSV export.

Data limitations (read this before filming)

1. Filings can be up to 45 days late; some arrive in 1-2 days. Filter hard on filing_delay_days.

2. Amounts are ranges ($1,001 - $15,000, etc.). Position sizes are estimates.

3. Quiver's excess_return is their estimate of post-trade performance, not a prediction.

4. Yahoo prices are unofficial and can be missing for odd tickers (SPCX etc.).

5. Studies on NANC/KRUZ suggest copying Congress does not reliably beat the market risk-adjusted. That honest uncertainty is the story.