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

> Install Azeroth Auction Assassin for WoW. Follow this guide to set up Python or Node.js, clone the repo, install dependencies, configure API keys, and launch the scanner to find underpriced items.

- Repository: [FF14 Advanced Market Search/azerothauctionassassin](https://github.com/ff14-advanced-market-search/azerothauctionassassin)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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:

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

```

3. Install the pinned dependencies from [`requirements.txt`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/requirements.txt):

```bash
pip install -r requirements.txt

```

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

```bash
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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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:

```bash
npm install

```

3. Start the application:

```bash
npm start

```

The Electron bootstrap logic in [`node-ui/main.js`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/node-ui/main.js) loads the interface, while [`node-ui/renderer.js`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/AzerothAuctionAssassinData/mega_data.json). The file structure follows this format:

```json
{
  "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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/realm_data.py). The [`utils/helpers.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/AzerothAuctionAssassin.py) with the PyQt5 interface, while the Node.js version runs the Electron frontend via [`node-ui/main.js`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/node-ui/main.js) and [`node-ui/renderer.js`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/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.