How to Set Up Azeroth Auction Assassin for World of Warcraft: Complete Installation Guide

To set up Azeroth Auction Assassin, install Python 3.11+ or Node.js 18+, clone the ff14-advanced-market-search/azerothauctionassassin repository, install dependencies via pip install -r requirements.txt or npm install, configure your Blizzard API credentials, Discord webhook, and Saddlebag Exchange token, then launch the scanner to monitor the Auction House for underpriced items.

Azeroth Auction Assassin (AAA) is an open-source desktop application that continuously scans the World of Warcraft Auction House across every realm in your region, alerting you via Discord when items sell below market average. This guide explains how to set up Azeroth Auction Assassin for World of Warcraft using either the native PyQt5 Python interface or the cross-platform Electron frontend, both of which share the same data-processing core and JSON configuration files.

Installation Methods

The repository provides three distinct runtime environments. Choose based on whether you prefer the Python GUI or the Node.js-based interface.

Option 1: Python Standalone Installation

The primary interface is built with PyQt5 in AzerothAuctionAssassin.py. This method provides the full native desktop experience on Windows, macOS, or Linux.

1. Install Python 3.11 or newer from python.org.
2. Clone the repository:

git clone https://github.com/ff14-advanced-market-search/AzerothAuctionAssassin.git
cd AzerothAuctionAssassin

3. Install the pinned dependencies from requirements.txt:

pip install -r requirements.txt

This installs PyQt5, pandas, requests, tenacity, and other required packages specified in the repository manifest. 4. Launch the application:

python AzerothAuctionAssassin.py

The script automatically creates a log directory at AzerothAuctionAssassinData/logs/ and redirects stdout/stderr to a file via the StreamToFile class defined in AzerothAuctionAssassin.py.

Option 2: Electron UI Installation

The node-ui/ directory contains a lightweight Electron frontend that mirrors the Python interface. It reads and writes the same configuration files, allowing you to switch between frontends interchangeably.

1. Install Node.js 18 or newer.
2. From the repository root, install dependencies:

npm install

3. Start the application:

npm start

The Electron bootstrap logic in node-ui/main.js loads the interface, while node-ui/renderer.js handles form inputs and the start/stop button actions. Both scripts watch the same JSON files as the Python version.

Option 3: Docker Deployment (Optional)

For containerized environments, run docker compose up from the repository root. The provided Dockerfile starts the scanner without requiring local Python or Node.js installations.

First-Time Configuration

Before scanning, you must authenticate with three external services. All settings are stored in AzerothAuctionAssassinData/mega_data.json.

Blizzard API Credentials

Create an OAuth client at the Blizzard Developer Portal. Copy your Client ID and Client Secret into the Settings tab fields labeled WoW Client ID and WoW Client Secret. The application calls utils/api_requests.get_wow_access_token using these credentials to obtain a bearer token required for Auction House queries.

Discord Webhook Setup

Create a webhook URL in your desired Discord channel. Paste this URL into the Discord Webhook field. When the scanner finds deals, it posts embeds via utils/api_requests.send_embed_discord.

Saddlebag Exchange Token

Join the Saddlebag Exchange Discord and run the /wow auctionassassintoken command. Enter the returned token in the Auction Assassin Token field. This token authenticates requests to the market data endpoint that retrieves average prices via Item_And_Pet_Statistics.run.

Saving Your Snipe List

Click Save Data in the UI to write your configuration to AzerothAuctionAssassinData/mega_data.json. The file structure follows this format:

{
  "MEGA_WEBHOOK_URL": "https://discord.com/api/webhooks/…",
  "MEGA_TOKEN": "your-saddlebag-token",
  "REGION": "EU",
  "ITEMS": {
    "19019": 500000,
    "19020": 250000
  },
  "PETS": {}
}

Item keys represent WoW item IDs, and values represent maximum buyout prices in copper (100 copper = 1 silver, 10000 copper = 1 gold).

Understanding the Core Architecture

The application consists of a shared Python data layer supporting two independent frontends.

The Data and API Layer

All external communication flows through utils/api_requests.py. Key functions include:

• get_wow_access_token: Authenticates with Blizzard OAuth
• send_embed_discord: Posts alert embeds to your webhook
• get_itemnames: Retrieves item metadata, falling back to StaticData/item_names.json if the live API is unavailable

Network calls are wrapped with @retry(stop=stop_after_attempt(3)) from the tenacity library to automatically retry transient failures.

Realm Data Resolution

The scanner loads connected realm IDs from AzerothAuctionAssassinData/<region>-wow-connected-realm-ids.json, populated by utils/realm_data.py. The utils/helpers.py file contains additional utilities such as Russian realm filtering logic.

Scanning Workflow

1. Authentication: Obtains a Blizzard access token using your client credentials.
2. Market data download: Queries the Saddlebag Exchange "mega-item-names" endpoint (sending the required WOW_DISCORD_CONSENT string) to retrieve current average prices via Item_And_Pet_Statistics.run.
3. Realm iteration: Loads the appropriate connected-realm list for your selected region.
4. Filtering: Applies your discount percentage, item level rules, and bonus ID filters to Auction House results from each realm.
5. Notification: Sends Discord embeds for items priced below your thresholds.

Running Your First Auction House Scan

After completing configuration:

1. Click Start Alerts in either the PyQt5 or Electron interface.
2. The scanner immediately pulls fresh market data from the Saddlebag Exchange API.
3. It iterates through every realm in your selected region, querying the Blizzard Auction House API using the token obtained via utils/api_requests.get_wow_access_token.
4. Matching deals appear in your Discord channel within seconds via utils/api_requests.send_embed_discord.

Summary

• Install either Python 3.11+ with PyQt5 dependencies or Node.js 18+ for the Electron UI in node-ui/
• Configure three credentials: Blizzard OAuth client, Discord webhook URL, and Saddlebag Exchange token
• Store settings in AzerothAuctionAssassinData/mega_data.json, where the ITEMS object maps item IDs to maximum buyout prices in copper
• Launch with python AzerothAuctionAssassin.py or npm start to begin cross-realm scanning
• Rely on automatic retries via tenacity.retry decorators in utils/api_requests.py for stable API communication

Frequently Asked Questions

Do I need both Python and Node.js installed to run the application?

No. Choose one runtime environment. The Python version launches AzerothAuctionAssassin.py with the PyQt5 interface, while the Node.js version runs the Electron frontend via node-ui/main.js and node-ui/renderer.js. Both applications read and write identical JSON configuration files, so you can switch between them without losing your snipe lists.

What file contains my item snipe lists and settings?

All user-defined snipe lists and configuration data are stored in AzerothAuctionAssassinData/mega_data.json. The ITEMS object within this file maps WoW item IDs to maximum buyout prices in copper. You can edit this file manually or use the Settings tab in either UI to modify values safely.

Why does the scanner require Blizzard OAuth credentials?

The Blizzard API requires authentication to access Auction House data. The application uses your Client ID and Secret to request a temporary access token via the get_wow_access_token function in utils/api_requests.py. Without valid credentials, the scanner cannot query realm Auction House endpoints.

How does the application handle API failures or rate limiting?

All network requests in utils/api_requests.py are decorated with @retry(stop=stop_after_attempt(3)) from the tenacity library. This automatically retries failed requests up to three times, ensuring temporary network issues or rate limits do not interrupt long scanning sessions across multiple realms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}