Insider Flow Radar

SEC Form 4 insider-transaction radar for investors, analysts, and finance builders. It fetches/parses ownership reports, classifies open-market insider buys and sells, detects clustered buying, scores the signal, and writes a clean markdown research brief.

This is designed as a serious finance-data engineering project: API-free SEC data, deterministic parsing, transparent scoring, tests, CI, and a useful CLI.

Why it matters

Insider transactions are noisy. A single sale can be tax planning. But clustered open-market buying by officers/directors can be a useful signal worth investigating. Insider Flow Radar turns raw Form 4 XML into a readable signal report.

Features

• Fetch recent Form 4 / Form 4-A filings from SEC submissions data
• Parse SEC ownership XML
• Extract issuer, ticker, insider name, role, transaction code, shares, price, and market value
• Classify transactions as buy / sell / other
• Score the signal based on:
  • open-market purchase value
  • clustered buying across multiple insiders
  • officer/director participation
  • net insider buying vs selling
• Generate markdown reports
• Resolve ticker symbols to SEC CIKs automatically
• Configurable SEC User-Agent via CLI option or environment variable
• Respectful SEC access with retries, exponential backoff, and a local cache
• CSV export and watchlist scanning
• Transparent score audit trail with transaction-code explanations
• CLI demo mode with deterministic sample data
• Tests and GitHub Actions CI

Install

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Usage

Run a deterministic demo:

insider-flow-radar demo

Scan a real company by CIK or ticker:

insider-flow-radar scan 320193 --limit 10
insider-flow-radar scan AAPL --limit 10 --user-agent "your-app/1.0 your.email@example.com"

Apple's CIK is 320193. The tool pads it to SEC's 10-digit format automatically.

You can also configure the SEC User-Agent with an environment variable:

export INSIDER_FLOW_RADAR_SEC_USER_AGENT="your-app/1.0 your.email@example.com"

Export transactions to CSV:

insider-flow-radar scan AAPL --csv aapl-form4.csv
insider-flow-radar demo --csv demo.csv

Scan a watchlist file containing newline- or comma-separated tickers/CIKs:

insider-flow-radar scan AAPL --watchlist watchlist.txt --csv watchlist-form4.csv

SEC responses are cached under ~/.cache/insider-flow-radar for 24 hours by default to avoid unnecessary repeat requests. Override the cache directory with INSIDER_FLOW_RADAR_CACHE_DIR.

Example output

# Insider Flow Radar: ACME

**Issuer:** ACME CORP  
**Signal score:** 100/100  
**Net insider flow:** $305,000  
**Open-market buys:** $305,000  
**Open-market sells:** $0

## Signal Flags
- Cluster buying: 2 distinct insiders bought shares
- Material open-market buying: $305,000
- Positive net insider buying of $305,000
- Officer participation detected

Transaction code guide

Code	Meaning	Treatment
P	Open-market purchase	Bullish / buy signal
S	Open-market sale	Selling pressure / negative signal
Other	Grants, awards, conversions, derivative events	Usually ignored or treated as other

Methodology

The score is intentionally simple and inspectable:

1. Parse Form 4 XML transactions.
2. Keep open-market purchase and sale codes prominent.
3. Sum buy value and sell value.
4. Count distinct buyers and sellers.
5. Reward clustered buying and officer/director participation.
6. Penalize large sales.
7. Output a 0-100 signal score plus human-readable flags.
8. Include a score audit table showing every point adjustment and why it was applied.

This is not financial advice. It is a research triage tool.

Development

pytest -q

Project fit

This repo complements AI/finance projects like equity research copilots, portfolio risk engines, and market dashboards by adding an SEC-native insider-flow signal layer.