Overview

In this guide, we’ll build a free automated stock alert system that:

  • Runs every day at market open (9 AM KST)
  • Screens Korean stocks using pykrx
  • Sends alerts via Telegram
  • Requires zero server infrastructure (GitHub Actions is free)

Prerequisites

  • GitHub account
  • Telegram account
  • Basic Python knowledge

Step 1: Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot command
  3. Choose a name and username for your bot
  4. Save the API token you receive

Step 2: Get Your Chat ID

  1. Send a message to your new bot
  2. Visit: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
  3. Find your chat_id in the response

Step 3: Create the Alert Script

# alert.py
import requests
from pykrx import stock
from datetime import datetime
import os

TELEGRAM_TOKEN = os.environ["TELEGRAM_TOKEN"]
TELEGRAM_CHAT_ID = os.environ["TELEGRAM_CHAT_ID"]

def send_telegram(message):
    url = f"https://api.telegram.org/bot{TELEGRAM_TOKEN}/sendMessage"
    payload = {"chat_id": TELEGRAM_CHAT_ID, "text": message, "parse_mode": "HTML"}
    requests.post(url, json=payload)

def get_top_movers():
    today = datetime.now().strftime("%Y%m%d")
    df = stock.get_market_ohlcv_by_ticker(today, market="KOSPI")
    df["change_pct"] = (df["종가"] - df["시가"]) / df["시가"] * 100
    top_gainers = df.nlargest(5, "change_pct")
    return top_gainers

def main():
    movers = get_top_movers()
    message = "<b>Korean Market Alert - Top Movers Today</b>\n\n"
    for ticker, row in movers.iterrows():
        name = stock.get_market_ticker_name(ticker)
        message += f"{name} ({ticker}): +{row['change_pct']:.1f}%\n"
    send_telegram(message)

if __name__ == "__main__":
    main()

Step 4: GitHub Actions Workflow

Create .github/workflows/alert.yml:

name: Korean Stock Alert

on:
  schedule:
    - cron: '0 0 * * 1-5'  # 9AM KST = 0:00 UTC
  workflow_dispatch:

jobs:
  alert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install pykrx requests
      - name: Run alert script
        env:
          TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
        run: python alert.py

Step 5: Add Secrets to GitHub

  1. Go to your GitHub repo → Settings → Secrets
  2. Add TELEGRAM_TOKEN
  3. Add TELEGRAM_CHAT_ID

That’s it! Your alert system will now run automatically every weekday morning.