SEC Cluster Buy Tracker

A lightweight, automated Python scraper that monitors the SEC EDGAR database for Form 4 insider trading filings. It specifically filters for open-market purchases and identifies instances where multiple corporate insiders buy company stock with personal capital on the same day.

When the script detects a cluster buy, it structures it into a Pandas DataFrame and fires a formatted Markdown table directly to your personal Telegram bot.

Architecture/Tech Stack

• Language: Python 3.11+
• Dependency Management: uv
• Web Scraping: requests, BeautifulSoup4
• Data Structuring: pandas
• CI/CD: GitHub Actions
• Alerts: Telegram Bot API

Quickstart

this project uses uv for dependency management, so you do not need to manually create venv's or install pip requirements.

1. Clone the Repository

git clone [https://github.com/vcsniper7/sec_bot.git](https://github.com/vcsniper7/sec_bot.git)
cd sec_bot

2. Setup Environment Variables

in your repository secrets, add these 4 secrets:

SEC_NAME=Your Name SEC_EMAIL=your_email@example.com TELEGRAM_BOT_TOKEN=your_bot_token_here TELEGRAM_CHAT_ID=your_chat_id_here

To get a telegram bot token, message /newbot to @botfather in telegram, then copy the token. Start your telegram bot by messaging it /start. Your chat ID can be found from the bot @userinfobot, just message it /start and copy the ID it gives.

3. Execute the Scraper

Run the script using uv. It will automatically resolve dependencies on the fly, parse the SEC live feed, and push an alert if any cluster buys are found.

uv run main.py

(Optional) Cloud Automation Through Github Actions

This repository is designed to run via GitHub Actions runners with the scraper.yml file. The native runner uses the official setup-uv action to boot, install dependencies, and execute the script in under 20 seconds.

The workflow is structured around the SEC EDGAR database hours and insider filing habits. Insiders typically file Form 4's after market close to avoid intraday volatility.

The cron schedule is optimized for Pacific Daylight Time (PDT) / Coordinated Universal Time (UTC):

• 6:27 AM PDT: Pre-market wrap-up of late evening filings.

• 2:00 PM – 4:00 PM PDT: Afternoon filings after the market wave.

• 5:00 PM – 7:00 PM PDT: late-night filings.

License

Distributed under the MIT License. See LICENSE for more information.