# How to Set Up Battle Pet Sniping in Azeroth Auction Assassin (AAA)

> Learn to set up battle pet sniping in Azeroth Auction Assassin AAA. Configure pet lists, set API keys, and get instant Discord alerts for rare pets. Master the market now

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

---

**Configure your [`desired_pets.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pets.json) or [`desired_pet_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pet_ilvl_list.json) files in the `AzerothAuctionAssassinData/` directory, set your Blizzard API credentials as environment variables, and run the scanner to receive real-time Discord alerts when battle pets matching your criteria appear on the auction house.**

Battle pet sniping in Azeroth Auction Assassin (AAA) relies on a data-driven pipeline that monitors auction house listings against user-defined criteria. This open-source tool, available at `ff14-advanced-market-search/azerothauctionassassin`, processes caged pet auctions by species ID and alerts you instantly when profitable opportunities arise.

## Configuration Files for Pet Sniping

AAA stores user preferences in JSON files under `AzerothAuctionAssassinData/`. For battle pets, you have two configuration options depending on how granular you want your sniping to be.

### Simple Pet Sniping with desired_pets.json

The simplest method uses [`desired_pets.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pets.json) to define a flat mapping of pet species IDs to maximum buyout prices.

```json
{
  "12345": 100000,
  "67890": 50000
}

```

In this example, the scanner triggers an alert if pet species `12345` appears for 10,000 gold or less, or species `67890` for 5,000 gold or less. The `MegaData` class in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py) loads this into the `DESIRED_PETS` dictionary via the `__set_desired_items` method. You may also set the `DESIRED_PETS` environment variable to this JSON string if you prefer not to use a file.

### Advanced Ilvl-Based Sniping with desired_pet_ilvl_list.json

For advanced users, [`desired_pet_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pet_ilvl_list.json) allows you to group pets by item level, quality, and breed, filtering only specific stat combinations.

```json
[
  {
    "ilvl": 200,
    "price": 120000,
    "minLevel": 1,
    "max_ilvl": 300,
    "bonus_lists": [],
    "excludeBreeds": [],
    "petID": 11111,
    "minQuality": 2
  }
]

```

The `MegaData.__set_desired_pet_ilvl_list` method (lines 866-916 in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py)) validates these entries and stores them in `DESIRED_PET_ILVL_LIST`. During scanning, AAA checks if a pet matches any group’s criteria, including `minLevel`, `minQuality`, and `excludeBreeds`.

## How the Scanner Processes Pets

Understanding the internal flow helps you debug configuration issues and optimize your sniping strategy.

### The MegaData Class and Data Loading

When AAA initializes, the `MegaData` class in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py) performs several setup steps:

1. **Load Desired Pets**: It reads [`desired_pets.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pets.json) and [`desired_pet_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pet_ilvl_list.json) (or their environment variable equivalents) into memory.
2. **Fetch Pet Names**: It calls `get_petnames` from [`utils/api_requests.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/api_requests.py) to retrieve a mapping of `petID` to human-readable names from Blizzard’s API. If the API fails, it falls back to `get_pet_names_backup`, which loads [`StaticData/pet_names.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/StaticData/pet_names.json).
3. **Store Lookup Tables**: The data is stored in `self.DESIRED_PETS`, `self.DESIRED_PET_ILVL_LIST`, and `self.PET_NAMES` for fast access during scans.

### Auction Matching Logic in process_ah_entries

The core scanning logic resides in [`mega_alerts.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/mega_alerts.py) within the `process_ah_entries` function (around lines 270-290). For each auction entry:

1. **Identify Caged Pets**: The code checks if the item ID is `82800` (the standard ID for Pet Cage). The actual species is extracted from `item["pet_species_id"]`.
2. **Match Against Criteria**: It checks if the species exists in `mega_data.DESIRED_PETS` or matches any entry within `mega_data.DESIRED_PET_ILVL_LIST` (validating level, quality, and breed constraints).
3. **Build Alert Data**: When a match occurs, the entry is added to `pet_ah_buyouts` or `pet_ah_bids`. The code retrieves the pet name from `mega_data.PET_NAMES[pet_id]` and generates a clickable link using `create_oribos_exchange_pet_link` from [`utils/helpers.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/helpers.py).
4. **Send Notifications**: If `MEGA_WEBHOOK_URL` is configured, a Discord embed is constructed with the pet name, price, and Undermine Exchange link, then sent via webhook.

## Environment Setup and Execution

Before running the scanner, export your Blizzard API credentials and optional Discord webhook:

```bash
export WOW_CLIENT_ID="your_client_id"
export WOW_CLIENT_SECRET="your_client_secret"
export WOW_REGION="eu"  # or "us", "kr", etc.

export MEGA_WEBHOOK_URL="https://discord.com/api/webhooks/..."

```

Place your [`desired_pets.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pets.json) and optionally [`desired_pet_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pet_ilvl_list.json) in the `AzerothAuctionAssassinData/` directory. Then execute the main runner:

```bash
python mega_alerts.py

```

The script will initialize `MegaData`, load your pet configurations, fetch current auction house data for your specified realms, and begin monitoring for battle pet sniping opportunities.

## Summary

- **Configuration**: Define target pets in [`AzerothAuctionAssassinData/desired_pets.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/AzerothAuctionAssassinData/desired_pets.json) for simple sniping or [`desired_pet_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pet_ilvl_list.json) for advanced level/quality filtering.
- **Data Loading**: The `MegaData` class in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py) ingests these files and fetches pet names from Blizzard’s API (with fallback to [`StaticData/pet_names.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/StaticData/pet_names.json)).
- **Scanning Logic**: [`mega_alerts.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/mega_alerts.py) identifies caged pets (item ID `82800`) via `pet_species_id`, matches them against your criteria, and generates alerts with links from `utils/helpers.py::create_oribos_exchange_pet_link`.
- **Execution**: Set `WOW_CLIENT_ID`, `WOW_CLIENT_SECRET`, `WOW_REGION`, and optionally `MEGA_WEBHOOK_URL`, then run the scanner to receive real-time battle pet sniping alerts.

## Frequently Asked Questions

### What is the difference between desired_pets.json and desired_pet_ilvl_list.json?

The [`desired_pets.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pets.json) file provides a simple key-value mapping where each pet species ID maps to a maximum buyout price in copper. This is ideal when you only care about acquiring a specific pet regardless of its level or breed. The [`desired_pet_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pet_ilvl_list.json) file allows for granular control, letting you specify minimum pet levels, quality thresholds, breed exclusions, and item level ranges. This advanced format is processed by `MegaData.__set_desired_pet_ilvl_list` and is essential for sniping high-stat pets used in pet battles.

### How does AAA identify battle pets in auction house listings?

AAA identifies caged battle pets by checking if the auction item ID equals `82800`, which is Blizzard’s standard ID for Pet Cage. The actual species is determined by reading the `pet_species_id` field from the auction data. This logic resides in [`mega_alerts.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/mega_alerts.py) within the `process_ah_entries` function, which then compares the species ID against your `DESIRED_PETS` and `DESIRED_PET_ILVL_LIST` configurations to determine if an alert should trigger.

### Why am I not receiving Discord notifications for pet alerts?

Discord notifications require the `MEGA_WEBHOOK_URL` environment variable to be set to a valid Discord webhook URL before starting the scanner. Additionally, ensure that your [`desired_pets.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pets.json) or [`desired_pet_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_pet_ilvl_list.json) files are correctly placed in `AzerothAuctionAssassinData/` and contain valid JSON. If the `MegaData` class cannot parse these files during initialization in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py), the `DESIRED_PETS` dictionary will remain empty, and no matches will occur to trigger webhook calls.

### Can I run battle pet sniping without a Blizzard API key?

No, a valid Blizzard API client ID and secret are mandatory. The `MegaData` class calls `get_petnames` from [`utils/api_requests.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/api_requests.py) during initialization to fetch the current pet species ID to name mapping. Without `WOW_CLIENT_ID` and `WOW_CLIENT_SECRET` set as environment variables, the API authentication will fail. While AAA includes a static fallback file at [`StaticData/pet_names.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/StaticData/pet_names.json) accessed via `get_pet_names_backup`, the application still requires API credentials to fetch live auction house data from Blizzard’s servers, which is essential for the sniping functionality to operate.