ShopPyBot

Overview

ShopPyBot is a drop-in plugin framework that monitors item availability and can automatically purchase across 7 retail platforms: Amazon, BestBuy, Walmart, Target, GameStop, NewEgg, and Square Enix. Community contributors can add support for a new platform by dropping a single plugin file into plugins/ — no changes to the core framework required.

Disclaimer

This software is provided for personal, non-commercial use only. It is offered "as is", without warranty of any kind, express or implied. You use it entirely at your own risk.

Automated availability checking and purchasing may violate the Terms of Service (TOS) of Amazon, BestBuy, or any other retailer. By using this software you acknowledge that you are solely responsible for ensuring your use complies with each retailer's Terms of Service and applicable law. The developer(s) accept no liability for any consequences arising from its use.

WARNING: The use of this software can result in a retailer restricting or suspending access to your account, banning your account, or otherwise making it difficult for you to purchase products, with or without the bot. By using this software, you acknowledge and accept these risks. These restrictions cannot and will not be resolved by the developer(s). If this is a major concern for you, you should avoid using this software.

Account restrictions may be triggered by any of the following: 1) running multiple instances on one device, 2) running multiple instances on different devices, using the same account, regardless of their IP, proxy, or location, 3) configuring an instance to check stock too frequently/aggressively (default settings not guaranteed to be safe).

Features

• Plugin framework — add a new retail platform via a single file in plugins/, no core changes required
• Automated availability checks and automated purchasing across all 7 supported platforms (Amazon, BestBuy, Walmart, Target, GameStop, NewEgg, Square Enix)
• Optional web dashboard (pip install -e .[web]) with observability: a live status stream (Server-Sent Events), a health surface, and log filtering by plugin and level
• Price monitoring — alert or auto-buy on a target price or a percentage price drop
• Anti-detection — fingerprint and proxy rotation, plus 2captcha-backed CAPTCHA solving
• Encrypted session persistence (Fernet + scrypt) so logins survive restarts
• CAPTCHA detection and notification
• Configurable via config.yml
• Logging and error handling

Setup

Prerequisites

• Python 3.11+
• pip (Python package installer)
• Google Chrome or Chromium installed locally. Selenium drives this browser directly; chromedriver itself is auto-downloaded via webdriver_manager (see selenium.driver_path in config.yml), but the Chrome/Chromium binary is not installed for you.

Best Buy

• A BestBuy account (create one) with a saved payment method (credit card)

Amazon

• A valid Amazon account (presave your address and payment method!)
• Your OTP device on hand (manual login required)

Installation

1. Clone the repository:

git clone https://github.com/thezoid/ShopPyBot.git
cd ShopPyBot

2. Create and activate a virtual environment:

python -m venv .venv
.venv\Scripts\activate  # On Windows
source .venv/bin/activate  # On macOS/Linux

3. Install the project in editable mode with the web extra (FastAPI/uvicorn/jinja2, needed for the optional web dashboard):

pip install -e .[web]

This also registers the shoppybot console command (see Running the Bot).

Configuration

1. Copy the sample configuration file and update it with your details:

cp sample.config.yml config.yml

2. Edit config.yml to add the items you want to monitor. config.yml holds only non-secret item and behavior settings — it never holds account credentials.

3. Account credentials go in environment variables, never in config.yml. Copy .env.example to .env and populate your platform credentials there; .env is gitignored and must never be committed. See SECURITY.md for the full credential-handling policy.

*If you update config.yml, please do not commit it to your local repository! I do not take responsibility for any PII or other sensitive data that may leak through your commits!

Changing the Alert Sound

The bundled alert sounds (core/sounds/notification.wav, core/sounds/available.wav, core/sounds/buy.wav) are original, royalty-free tones generated from scratch by scripts/generate_alert_sounds.py (public domain / CC0, no third-party samples). Regenerate them any time with:

python scripts/generate_alert_sounds.py

To use your own sounds, drop a file of the same name (notification, available, or buy) into core/sounds/. Both .mp3 and .wav are supported; utils.py loads .mp3 first, then falls back to .wav.

Running the Bot

shoppybot

shoppybot is the console entry point registered by pip install -e .[web]. python main.py still works as an alternative if you prefer running from a source checkout directly.

Contributing

Contributions are welcome! Please read the contributing guidelines for more information.

Versioning

Product releases follow SemVer, automated via release-please and seeded at 2.0.0 (matching the pre-existing v2.0 git tag). The v4.0/v4.1 tags in this repository's history are internal planning-milestone markers, not product releases, and are unrelated to the release-please-managed SemVer series — do not compare them numerically.

Credits

Final Fantasy 14 Sound Fan Kit - Square Enix