# Blizzard Bonus IDs for Sniping in AzerothAuctionAssassin: Complete Guide

> Master Blizzard bonus IDs for auction house sniping with AzerothAuctionAssassin. Find socket, stat, and item level upgrades using Raidbots data. Enhance your WoW gameplay.

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

---

**AzerothAuctionAssassin dynamically retrieves and categorizes Blizzard bonus IDs from Raidbots to enable precise auction house sniping for sockets, tertiary stats, and item level upgrades.**

The open-source tool AzerothAuctionAssassin leverages Blizzard's bonus ID system to identify undervalued auctions with specific enhancements. Rather than hard-coding these IDs, the application fetches live definitions from Raidbots and organizes them into searchable categories that power the sniping engine.

## How AzerothAuctionAssassin Retrieves Blizzard Bonus IDs

The application maintains an up-to-date mapping of all bonus IDs through a dual-source retrieval system that prioritizes live data while ensuring offline functionality.

### Fetching from Raidbots API

The primary data source is the Raidbots static endpoint. In [`utils/api_requests.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/api_requests.py), the function `get_raidbots_bonus_ids()` makes a GET request to `https://www.raidbots.com/static/data/live/bonuses.json` to retrieve the complete JSON definition of all current bonus IDs【[api_requests.py L176-L184](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/api_requests.py#L176-L184)】.

This approach ensures that when Blizzard adds new bonus IDs or modifies existing ones, AzerothAuctionAssassin automatically incorporates these changes without requiring a code update.

### Static Backup Fallback

If the Raidbots API call fails due to network issues or service unavailability, the system falls back to a repository-bundled backup located at [`StaticData/bonuses.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/StaticData/bonuses.json). This static file contains a snapshot of the bonus ID definitions, ensuring that sniping functionality remains available even when external services are unreachable.

## Categorizing Bonus IDs for Auction Sniping

Once retrieved, the raw bonus ID data is processed by [`utils/bonus_ids.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/bonus_ids.py) to create logical groupings that the sniping engine can consume. The `get_bonus_ids()` function parses the JSON and organizes IDs into the following categories【[bonus_ids.py L4-L63](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/bonus_ids.py#L4-L63)】:

### Socket Bonus IDs

Any bonus ID whose value contains a `"socket"` key is categorized under **sockets**. These IDs indicate items that have additional gem slots beyond the base item, significantly increasing their market value for players seeking to maximize secondary stats.

### Item Level Addition IDs

The **ilvl_addition** category captures bonus IDs whose value consists exactly of `["id", "level"]`. These represent item-level upgrades that add a flat offset to the base item level, such as those from post-midnight upgrade tokens or warforged mechanics.

### Secondary Stat Categories

The parser extracts tertiary and secondary stats from the `"rawStats"` array within each bonus ID definition:

- **Leech** (`name: "Leech"`) – Example ID: 41
- **Avoidance** (`name: "Avoidance"`) – Example ID: 40  
- **Speed** (`name: "RunSpeed"`) – Example ID: 42
- **Haste** (`name: "Haste"`) – Example ID: 18
- **Crit** (`name: "Crit"`) – Example ID: 17
- **Mastery** – Part of multi-stat combos (e.g., IDs 45, 46)
- **Versatility** (`name: "Vers"` in JSON) – Part of multi-stat combos (e.g., IDs 87-107)

The function returns a comprehensive dictionary containing all these categories under keys like `"sockets"`, `"leech"`, `"avoidance"`, `"speed"`, `"ilvl_addition"`, `"haste"`, `"crit"`, `"mastery"`, `"versatility"`, and `"bonuses_by_id"` for raw lookups.

## Implementing Bonus ID Filters in Sniping Logic

For efficient sniping, AzerothAuctionAssassin provides convenience functions that convert these categorized IDs into usable filter sets.

### Retrieving Bonus ID Sets

The `get_bonus_id_sets()` function in [`utils/bonus_ids.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/bonus_ids.py) extracts just the ID keys for the most common sniping filters (sockets, leech, avoidance, speed, and ilvl addition) and returns them as Python `set` objects. This is the entry point used by the mega-data preparation pipeline in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py)【[mega_data_setup.py L18-L19](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py#L18-L19)】.

```python
from utils.bonus_ids import get_bonus_ids, get_bonus_id_sets

# Full categorised dictionary

bonus_data = get_bonus_ids()
print("Socket IDs:", list(bonus_data["sockets"].keys()))
print("Leech IDs:", list(bonus_data["leech"].keys()))

# Convenience sets for quick look-ups

socket_ids, leech_ids, avoidance_ids, speed_ids, ilvl_addition = get_bonus_id_sets()
print("Set of socket IDs:", socket_ids)

```

### Building PBS Bonus-List Strings

The sniping engine constructs Price Backend Service (PBS) queries by converting selected bonus IDs into comma-separated strings. When a user wants to snipe items with specific sockets or tertiary stats, the application maps the selected categories to their corresponding ID sets and formats them for the PBS API.

```python
def build_bonus_list(selected_socket_ids):
    # PBS expects a comma-separated list of numeric IDs

    return ",".join(str(bid) for bid in selected_socket_ids)

# Example: User selects socket IDs 123 and 456

pbs_bonus = build_bonus_list({123, 456})
print("PBS bonus-list:", pbs_bonus)  # → "123,456"

```

### Filtering by Secondary Stats

For tertiary stat sniping (such as Leech ≥ 30%), the application checks if any of the item's bonus lists intersect with the categorized ID sets.

```python
def filter_by_leech(item, leech_threshold=30):
    # Each item's bonus IDs are stored in item['bonus_lists']

    leech_ids = get_bonus_ids()["leech"]
    return any(bid in leech_ids for bid in item["bonus_lists"])

```

## Key Source Files and Functions

Understanding the codebase structure helps developers extend the bonus ID system or debug sniping filters.

| File | Role | Key Functions |
|------|------|---------------|
| [`utils/api_requests.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/api_requests.py) | Retrieves raw bonus ID definitions from Raidbots | `get_raidbots_bonus_ids()` – fetches from `https://www.raidbots.com/static/data/live/bonuses.json` with fallback to [`StaticData/bonuses.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/StaticData/bonuses.json)【[L176-L184](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/api_requests.py#L176-L184)】 |
| [`utils/bonus_ids.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/bonus_ids.py) | Parses and categorizes bonus IDs into logical groups | `get_bonus_ids()` – returns categorized dictionary; `get_bonus_id_sets()` – returns Python sets of IDs for sockets, leech, avoidance, speed, and ilvl【[L4-L63](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/bonus_ids.py#L4-L63)】 |
| [`StaticData/bonuses.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/StaticData/bonuses.json) | Static backup of Blizzard bonus ID definitions | Used when Raidbots API is unavailable |
| [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py) | Consumes bonus ID sets for sniping data preparation | Imports ID sets via `get_bonus_id_sets()` for PBS query construction【[L18-L19](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py#L18-L19)】 |

## Summary

AzerothAuctionAssassin dynamically manages **Blizzard bonus IDs for sniping** through the following architecture:

- **Live Data Retrieval**: The system fetches current bonus ID definitions from the Raidbots API endpoint, ensuring compatibility with the latest World of Warcraft patches.
- **Categorization Engine**: Raw bonus IDs are automatically sorted into functional groups including sockets, item-level additions, and specific secondary stats (Leech, Avoidance, Speed, Haste, Crit, Mastery, Versatility).
- **Sniping Integration**: The categorized IDs are exposed as Python sets via `get_bonus_id_sets()` and consumed by the mega-data pipeline to construct PBS (Price Backend Service) queries that filter auctions for specific item enhancements.
- **Resilient Architecture**: A static backup at [`StaticData/bonuses.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/StaticData/bonuses.json) ensures sniping functionality persists even during API outages.

## Frequently Asked Questions

### What are Blizzard bonus IDs?

Blizzard bonus IDs are numeric identifiers attached to World of Warcraft items that modify their base properties. Each ID represents a specific enhancement, such as adding a gem socket, increasing item level, or granting tertiary stats like Leech or Avoidance. AzerothAuctionAssassin uses these IDs to identify undervalued auctions with desirable modifications.

### How does AzerothAuctionAssassin update bonus IDs?

The application updates bonus IDs dynamically by calling `get_raidbots_bonus_ids()` in [`utils/api_requests.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/api_requests.py), which retrieves the latest definitions from `https://www.raidbots.com/static/data/live/bonuses.json`. If the network request fails, the system automatically falls back to the static [`StaticData/bonuses.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/StaticData/bonuses.json) file bundled with the repository, ensuring continuous operation.

### Which bonus IDs are most valuable for sniping?

The most valuable bonus IDs for auction sniping typically include **socket** IDs (which add gem slots for additional stats), **Leech** (ID 41), **Avoidance** (ID 40), and **Speed** (ID 42) for their utility in high-end content. Additionally, **item-level addition** IDs are crucial for identifying upgraded gear. The `get_bonus_id_sets()` function specifically extracts these high-priority categories for quick filtering.

### How do I filter auctions by specific bonus IDs?

To filter auctions, you use the categorized ID sets provided by `get_bonus_ids()` or `get_bonus_id_sets()` to construct PBS (Price Backend Service) bonus-list strings. For example, if targeting socketed items, you would extract the socket ID set, convert it to a comma-separated string (e.g., `"123,456"`), and pass this to the PBS query parameters. The [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py) module automates this integration for the sniping interface.