{"id":29222300,"url":"https://github.com/harold2828/exchangealert","last_synced_at":"2025-10-08T13:38:10.792Z","repository":{"id":301957155,"uuid":"1010773750","full_name":"Harold2828/ExchangeAlert","owner":"Harold2828","description":"⚡ Exchange Rate Alert Automation – A Python script that checks the daily USD to COP exchange rate and sends an email alert if it exceeds a defined threshold. Built with clean OOP architecture, dotenv config, and scheduled execution via schedule.","archived":false,"fork":false,"pushed_at":"2025-06-29T19:28:30.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-29T20:31:39.396Z","etag":null,"topics":["currency-tracking","email-alert","exchange-rate","python-automation","scheduler"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Harold2828.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-29T19:17:39.000Z","updated_at":"2025-06-29T19:33:31.000Z","dependencies_parsed_at":"2025-06-29T20:31:41.387Z","dependency_job_id":"58b4c86e-a2a3-4c9b-b851-09136d1982c0","html_url":"https://github.com/Harold2828/ExchangeAlert","commit_stats":null,"previous_names":["harold2828/exchangealert"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Harold2828/ExchangeAlert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Harold2828%2FExchangeAlert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Harold2828%2FExchangeAlert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Harold2828%2FExchangeAlert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Harold2828%2FExchangeAlert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Harold2828","download_url":"https://codeload.github.com/Harold2828/ExchangeAlert/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Harold2828%2FExchangeAlert/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263250591,"owners_count":23437288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["currency-tracking","email-alert","exchange-rate","python-automation","scheduler"],"created_at":"2025-07-03T03:08:29.758Z","updated_at":"2025-10-08T13:38:05.756Z","avatar_url":"https://github.com/Harold2828.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!IMPORTANT]\n\u003e This project currently uses the **free tier** of [ExchangeRate-API](https://www.exchangerate-api.com/), which may have limitations.\n\n# 📊 Exchange Alert Automation\n\nA Python-based automation tool that checks the daily **USD to COP exchange rate** (or any pair you configure) and **sends an email alert** if the rate exceeds a specified threshold.  \nIdeal for freelancers, travelers, or anyone monitoring currency fluctuations.\n\n---\n\n### ✉️ Email Notification Preview\n\nBelow is a sample email generated by the system:\n\n![Email Screenshot](assets/screenshot_email.png)\n\nIt clearly shows the **base currency** (e.g., USD) and the **target currency** (e.g., COP), along with the current exchange rate and timestamp.\n\n---\n\n## 🚀 Features\n\n- 📈 Fetches real-time exchange rates from [ExchangeRate-API](https://www.exchangerate-api.com/)\n- 📨 Sends email notifications via SMTP when your defined threshold is exceeded\n- 🕒 Automatically runs **once per day**\n- 🧱 Built with a clean and modular **OOP architecture**\n- 🔐 Uses environment variables through `.env` for secure configuration\n- 🪵 Logs exchange rate activity and errors to a local file\n\n---\n\n## 📦 Requirements\n\n- Python 3.8+\n- Install dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n**Dependencies:**\n```\nrequests\nschedule\npython-dotenv\n```\n\n---\n\n## ⚙️ Setup\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/Harold2828/ExchangeAlert.git\ncd ExchangeAlert\n```\n\n### 2. Configure Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```ini\n# Exchange Alert Configuration\nEXCHANGERATE_API_KEY=your_api_key_here\nEXCHANGERATE_BASE_CURRENCY=USD\nEXCHANGERATE_TARGET_CURRENCY=COP\nTHRESHOLD=4200\n\n# SMTP Configuration\nEMAIL_HOST=smtp.gmail.com\nEMAIL_PORT=587\nEMAIL_SENDER=you@example.com\nEMAIL_PASSWORD=your_app_password\nEMAIL_RECIPIENT=recipient@example.com\n\n# Runtime Configuration\nRUN_TIME=09:00\n```\n\n\u003e 🔐 **Important:** Never commit this file. Use secure tools to manage secrets in production.\n\n---\n\n### 3. Gmail App Password Setup (If Using Gmail SMTP)\n\nIf your email uses Gmail with 2FA enabled, you must create an **App Password**:\n\n#### 🔐 Steps:\n\n1. Visit: https://myaccount.google.com/\n2. Navigate to **Security** → Enable **2-Step Verification** if not yet enabled.\n3. Go to: https://myaccount.google.com/apppasswords\n4. Select:\n   - App: **Mail**\n   - Device: **Other (e.g., Exchange Alert)**\n5. Generate and copy the 16-character password.\n6. Paste it into your `.env` as `EMAIL_PASSWORD`.\n\n\u003e ❗ Do **not** use your regular Gmail password — it will fail with a `534` error.\n\n---\n\n### 4. Run the Script\n\n```bash\npython main.py\n```\n\n- ✅ Checks the current exchange rate immediately\n- ✅ Sends an email alert if the rate exceeds your threshold\n- 🕒 Then waits and reruns daily at the specified `RUN_TIME`\n\n---\n\n## 📁 Project Structure\n\n```\nexchange_alert/\n├── config.py\n├── exchange_rate_service.py\n├── email_notifier.py\n├── exchange_monitor.py\n├── scheduler.py\n├── main.py\n├── .env\n├── exchange_alert.log\n└── assets/\n    └── screenshot_email.png\n```\n\n---\n\n## 🛠️ Customization\n\n| Variable                     | Description                                 |\n|-----------------------------|---------------------------------------------|\n| `THRESHOLD`                 | Exchange rate to trigger the alert          |\n| `RUN_TIME`                  | Daily execution time (e.g., `09:00`)         |\n| `EXCHANGERATE_BASE_CURRENCY` \u0026 `TARGET_CURRENCY` | Currency pair to monitor |\n| `EMAIL_*`                   | Email credentials and recipient settings     |\n\n---\n\n## 🧪 Testing Tip\n\nTo test email alerts manually:\n\n1. Set `THRESHOLD=1` in `.env`\n2. Run:\n\n```bash\npython main.py\n```\n\n---\n\n## 🔒 Security Notes\n\n- `.env` and `*.log` are excluded via `.gitignore`\n- For production, consider using secure email services like **SendGrid** or **Mailgun**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharold2828%2Fexchangealert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharold2828%2Fexchangealert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharold2828%2Fexchangealert/lists"}