capitol-alpha-terminal

# 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](workbook.md)** (setup workbook + the full build prompt) and **[docs/REBUILD_SPEC.md](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) ``` ## 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](ONBOARDING.md) for exactly what it will do. ## Setup by hand (one command) ```bash 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. <details> <summary>Manual steps (what setup does under the hood)</summary> ```bash 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 ``` </details> ## 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): ```bash # 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](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 ```bash 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 ```bash # 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 ```bash 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: | Var | Purpose | |---|---| | `DATABASE_URL` | PostgreSQL connection | | `QUIVER_API_KEY` | Live congress trade data (bulk endpoint) | | `ANTHROPIC_API_KEY` | AI summaries, briefings, console, YouTube segments | | `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` | Push alerts (message your bot once, then set the chat id) | | `DISCORD_WEBHOOK_URL` / `SLACK_WEBHOOK_URL` | Optional alert channels | 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. ```bash 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: ```bash 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.