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

Configure your desired_pets.json or 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 to define a flat mapping of pet species IDs to maximum buyout prices.

{
  "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 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 allows you to group pets by item level, quality, and breed, filtering only specific stat combinations.

[
  {
    "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) 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 performs several setup steps:

1. Load Desired Pets: It reads desired_pets.json and 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 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.
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 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.
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:

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 and optionally desired_pet_ilvl_list.json in the AzerothAuctionAssassinData/ directory. Then execute the main runner:

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 for simple sniping or desired_pet_ilvl_list.json for advanced level/quality filtering.
• Data Loading: The MegaData class in utils/mega_data_setup.py ingests these files and fetches pet names from Blizzard’s API (with fallback to StaticData/pet_names.json).
• Scanning Logic: 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 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 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 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 or 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, 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 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 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.

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