---
name: wow-api-currency-economy
description: "Complete reference for WoW Retail Currency, Auction House, Token, Store, Trading Post, Black Market, Mail, and Player Trading APIs. Covers C_CurrencyInfo (currency data, tracking, backpack), Auction House (full listing/bidding/buying/selling/search/commodity), C_WowTokenPublic (WoW Token market), AccountStore (in-game shop), CatalogShop, C_PerksProgram (Trading Post — Trader's Tender), BlackMarket (BMAH), TradeInfo (player trading), MailInfo (mailbox), and related events. Use when working with currencies, auction house UI, WoW Tokens, the in-game store, Trading Post, black market, mail, or player-to-player trading."
---

# Currency & Economy API (Retail — Patch 12.0.0)

Comprehensive reference for currency, auction house, store, token, trading post, mail, and trade APIs.

> **Source:** https://warcraft.wiki.gg/wiki/World_of_Warcraft_API
> **Current as of:** Patch 12.0.0 (Build 65655) — January 28, 2026
> **Scope:** Retail only.

---

## Scope

- **C_CurrencyInfo** — Currency data, tracking, backpack display
- **Auction House** — Listing, bidding, buying, selling, commodities
- **C_WowTokenPublic / C_WowTokenUI** — WoW Token market
- **AccountStore / StorePublic** — In-game shop
- **CatalogShop** — Catalog shop system
- **C_PerksProgram** — Trading Post (Trader's Tender)
- **BlackMarket** — Black Market Auction House
- **TradeInfo** — Player-to-player trading
- **MailInfo** — Mailbox system

---

## C_CurrencyInfo — Currency System

### Currency Data

| Function | Returns | Description |
|----------|---------|-------------|
| `C_CurrencyInfo.GetCurrencyInfo(currencyType)` | `currencyInfo` | Currency info by type |
| `C_CurrencyInfo.GetCurrencyInfoFromLink(link)` | `currencyInfo` | From hyperlink |
| `C_CurrencyInfo.GetCurrencyIDFromLink(link)` | `currencyID` | ID from hyperlink |
| `C_CurrencyInfo.GetCurrencyLink(currencyType, amount)` | `link` | Currency hyperlink |
| `C_CurrencyInfo.GetCurrencyListSize()` | `size` | Number of entries |
| `C_CurrencyInfo.GetCurrencyListInfo(index)` | `info` | Entry at index |
| `C_CurrencyInfo.GetCurrencyListLink(index)` | `link` | Link at index |

### Currency Info Fields

- `name` — Currency name
- `description` — Description text
- `currencyID` — Unique ID
- `iconFileID` — Icon texture
- `quantity` — Current amount
- `maxQuantity` — Max cap (0 = none)
- `canEarnPerWeek` — Has weekly cap?
- `quantityEarnedThisWeek` — Earned this week
- `maxWeeklyQuantity` — Weekly max
- `totalEarned` — Total ever earned
- `isTradeable` — Can be traded?
- `quality` — Item quality
- `isDiscovered` — Has been discovered?
- `isShowInBackpack` — Shown in Backpack?

### Backpack & Tracking

| Function | Returns | Description |
|----------|---------|-------------|
| `C_CurrencyInfo.GetBackpackCurrencyInfo(index)` | `currencyData` | Backpack slot |
| `C_CurrencyInfo.GetNumBackpackCurrencies()` | `numSlots` | Num backpack slots |
| `C_CurrencyInfo.SetCurrencyBackpack(index, backpack)` | — | Toggle backpack |
| `C_CurrencyInfo.IsCurrencyTracked(currencyID)` | `isTracked` | Is tracked? |
| `C_CurrencyInfo.SetCurrencyTracked(currencyID, tracked)` | — | Set tracked |

### Currency List Management

| Function | Returns | Description |
|----------|---------|-------------|
| `C_CurrencyInfo.ExpandCurrencyList(index, expand)` | — | Expand/collapse header |
| `C_CurrencyInfo.IsCurrencyHeader(index)` | `isHeader` | Is header? |
| `C_CurrencyInfo.GetFactionGrantedByCurrency(currencyID)` | `factionID` | Associated faction |
| `C_CurrencyInfo.DoesCurrentFilterPassFilter(currencyID)` | `passes` | Passes filter? |

### Gold Functions (Global)

| Function | Returns | Description |
|----------|---------|-------------|
| `GetMoney()` | `copper` | Player's money in copper |
| `GetCoinTextureString(copper)` | `text` | Gold/silver/copper string |
| `GetMoneyString(copper, ...)` | `text` | Formatted money string |

---

## Auction House

### Browse & Search

| Function | Returns | Description |
|----------|---------|-------------|
| `C_AuctionHouse.SearchForItemKeys(itemKeys, sorts)` | — | Search by item keys |
| `C_AuctionHouse.SendBrowseQuery(query)` | — | Browse query |
| `C_AuctionHouse.SendSearchQuery(itemKey, sorts, separateOwnerItems)` | — | Item search |
| `C_AuctionHouse.GetBrowseResults()` | `browseResults` | Browse results |
| `C_AuctionHouse.GetNumItemSearchResults(itemKey)` | `numResults` | Num search results |
| `C_AuctionHouse.GetItemSearchResultInfo(itemKey, index)` | `resultInfo` | Search result info |
| `C_AuctionHouse.RefreshItemSearchResults(itemKey)` | — | Refresh search |
| `C_AuctionHouse.GetFilterGroups()` | `filterGroups` | Available filters |

### Commodities

| Function | Returns | Description |
|----------|---------|-------------|
| `C_AuctionHouse.SendSellSearchQuery(itemKey, sorts, separateOwnerItems)` | — | Commodity search |
| `C_AuctionHouse.GetCommoditySearchResultInfo(itemID, index)` | `resultInfo` | Commodity result |
| `C_AuctionHouse.GetNumCommoditySearchResults(itemID)` | `numResults` | Num commodity results |
| `C_AuctionHouse.StartCommoditiesPurchase(itemID, quantity)` | — | Start commodity buy |
| `C_AuctionHouse.ConfirmCommoditiesPurchase()` | — | Confirm commodity buy |
| `C_AuctionHouse.CancelCommoditiesPurchase()` | — | Cancel commodity buy |
| `C_AuctionHouse.GetCommodityQuote(itemID)` | `quote` | Price quote |

### Listing & Selling

| Function | Returns | Description |
|----------|---------|-------------|
| `C_AuctionHouse.PostItem(itemLocation, duration, quantity, bid, buyout)` | — | List item |
| `C_AuctionHouse.PostCommodity(itemLocation, duration, quantity, unitPrice)` | — | List commodity |
| `C_AuctionHouse.GetItemKeyInfo(itemKey)` | `keyInfo` | Item key info |
| `C_AuctionHouse.MakeItemKey(itemID, itemLevel, itemSuffix, battlePetSpeciesID)` | `itemKey` | Create item key |
| `C_AuctionHouse.GetAvailablePostCount(itemLocation)` | `count` | How many to list |
| `C_AuctionHouse.CalculateItemDeposit(itemLocation, duration, quantity)` | `deposit` | Deposit cost |
| `C_AuctionHouse.GetQuoteDurationRemaining()` | `seconds` | Quote time remaining |

### Bidding & Buying

| Function | Returns | Description |
|----------|---------|-------------|
| `C_AuctionHouse.PlaceBid(auctionID, bidAmount)` | — | Place bid |
| `C_AuctionHouse.GetBidInfo(index)` | `bidInfo` | Bid info |
| `C_AuctionHouse.GetNumBids()` | `numBids` | Active bids |
| `C_AuctionHouse.HasFavorite(itemKey)` | `isFavorite` | Is favorited? |
| `C_AuctionHouse.SetFavoriteItem(itemKey, isFavorite)` | — | Set favorite |
| `C_AuctionHouse.GetFavoriteItems()` | `itemKeys` | All favorites |

### Own Auctions

| Function | Returns | Description |
|----------|---------|-------------|
| `C_AuctionHouse.GetNumOwnedAuctions()` | `numAuctions` | Own auctions |
| `C_AuctionHouse.GetOwnedAuctionInfo(index)` | `auctionInfo` | Own auction info |
| `C_AuctionHouse.CancelAuction(auctionID)` | — | Cancel auction |
| `C_AuctionHouse.QueryOwnedAuctions(sorts)` | — | Query own auctions |

### Auction House State

| Function | Returns | Description |
|----------|---------|-------------|
| `C_AuctionHouse.IsAuctionHouseAvailable()` | `isAvailable` | AH available? |
| `C_AuctionHouse.CloseAuctionHouse()` | — | Close AH |
| `C_AuctionHouse.GetAuctionHouseTimeLeftBand(timeLeftEnum)` | `seconds` | Time left |
| `C_AuctionHouse.ReplicateItems()` | — | Full AH scan |
| `C_AuctionHouse.GetNumReplicateItems()` | `count` | Replicate count |
| `C_AuctionHouse.GetReplicateItemInfo(index)` | `info` | Replicate item |

---

## C_WowTokenPublic — WoW Token

| Function | Returns | Description |
|----------|---------|-------------|
| `C_WowTokenPublic.GetCurrentMarketPrice()` | `price` | Gold price |
| `C_WowTokenPublic.GetGuaranteedPrice()` | `price` | Guaranteed price |
| `C_WowTokenPublic.UpdateMarketPrice()` | — | Request update |
| `C_WowTokenPublic.GetCommerceSystemStatus()` | `status` | System status |
| `C_WowTokenPublic.BuyToken()` | — | Buy token (gold) |
| `C_WowTokenPublic.SellToken(auctionID)` | — | Sell token |

---

## AccountStore / StorePublic — In-Game Shop

| Function | Returns | Description |
|----------|---------|-------------|
| `C_StorePublic.IsEnabled()` | `enabled` | Shop enabled? |
| `C_StorePublic.IsDisabledByParentalControls()` | `disabled` | Parental block? |
| `C_StorePublic.DoesGroupHavePurchaseableProducts(group)` | `hasPurchaseable` | Has products? |

---

## C_PerksProgram — Trading Post

| Function | Returns | Description |
|----------|---------|-------------|
| `C_PerksProgram.GetAvailableActivities()` | `activities` | Current activities |
| `C_PerksProgram.GetPendingChestRewards()` | `rewards` | Pending rewards |
| `C_PerksProgram.GetTimeRemaining()` | `seconds` | Rotation time left |
| `C_PerksProgram.GetCurrencyAmount()` | `amount` | Trader's Tender |
| `C_PerksProgram.GetVendorItemInfo(perksVendorItemID)` | `itemInfo` | Vendor item |
| `C_PerksProgram.GetAvailableVendorItemIDs()` | `itemIDs` | Current rotation |
| `C_PerksProgram.GetFrozenPerksVendorItemInfo()` | `info` | Frozen item |
| `C_PerksProgram.RequestPurchase(perksVendorItemID)` | — | Purchase item |
| `C_PerksProgram.RequestRefund(perksVendorItemID)` | — | Refund item |
| `C_PerksProgram.GetDraggedPerksVendorItemInfo()` | `itemInfo` | Dragged item |
| `C_PerksProgram.IsFrozenItem(perksVendorItemID)` | `isFrozen` | Is frozen? |
| `C_PerksProgram.SetFrozenPerksVendorItem(perksVendorItemID)` | — | Freeze item |
| `C_PerksProgram.ClearFrozenPerksVendorItem()` | — | Unfreeze |
| `C_PerksProgram.GetPerksVendorCategoryIDs()` | `categoryIDs` | Category IDs |
| `C_PerksProgram.GetPerksVendorCategoryInfo(categoryID)` | `categoryInfo` | Category info |

---

## Black Market

| Function | Returns | Description |
|----------|---------|-------------|
| `C_BlackMarket.GetNumItems()` | `numItems` | Current BMAH items |
| `C_BlackMarket.GetItemInfoByIndex(index)` | `info` | BMAH item info |
| `C_BlackMarket.GetHotItem()` | `info` | Hot item of the day |
| `C_BlackMarket.ItemPlaceBid(index, amount)` | — | Place BMAH bid |
| `C_BlackMarket.RequestItems()` | — | Request item list |
| `C_BlackMarket.IsViewOnly()` | `isViewOnly` | View-only mode? |

---

## Trade (Player-to-Player)

| Function | Returns | Description |
|----------|---------|-------------|
| `InitiateTrade(unit)` | — | Start trade |
| `AcceptTrade()` | — | Accept trade |
| `CancelTrade()` | — | Cancel trade |
| `AddTradeMoney()` | — | Add gold offer |
| `SetTradeMoney(copper)` | — | Set gold amount |
| `GetTargetTradeMoney()` | `copper` | Their gold offer |
| `GetPlayerTradeMoney()` | `copper` | Your gold offer |
| `GetTradeTargetItemInfo(slotIndex)` | `name, texture, quantity, quality, isUsable, enchant` | Their item |
| `GetTradePlayerItemInfo(slotIndex)` | `name, texture, quantity, quality, isUsable, enchant` | Your item |
| `ClickTradeButton(slotIndex)` | — | Click trade slot |
| `GetNumTradeItems()` | `numPlayerItems, numTargetItems` | Item counts |

---

## Mail System

| Function | Returns | Description |
|----------|---------|-------------|
| `GetInboxNumItems()` | `numItems, totalItems` | Inbox count |
| `GetInboxHeaderInfo(index)` | `packageIcon, stationeryIcon, sender, subject, money, CODAmount, daysLeft, hasItem, wasRead, wasReturned, textCreated, canReply, isGM` | Mail header |
| `GetInboxText(index)` | `bodyText, stationeryBG, stationeryBGR, stationeryBGG, stationeryBGB, color` | Mail body |
| `GetInboxItem(index, itemIndex)` | `name, itemID, texture, count, quality, canUse` | Attachment |
| `GetInboxItemLink(index, itemIndex)` | `link` | Attachment link |
| `TakeInboxItem(index, itemIndex)` | — | Take attachment |
| `TakeInboxMoney(index)` | — | Take gold |
| `TakeInboxTextItem(index)` | — | Take text item |
| `DeleteInboxItem(index)` | — | Delete mail |
| `ReturnInboxItem(index)` | — | Return mail |
| `AutoLootMailItem(index)` | — | Auto-loot all |
| `InboxItemCanDelete(index)` | `canDelete` | Can delete? |
| `SendMail(recipient, subject, body)` | — | Send mail |
| `SetSendMailMoney(copper)` | — | Set gold to send |
| `SetSendMailCOD(copper)` | — | Set COD amount |
| `GetSendMailPrice()` | `cost` | Sending cost |
| `GetSendMailItem(index)` | `name, texture, count, quality` | Attached item |
| `GetSendMailItemLink(index)` | `link` | Attached link |
| `ClickSendMailItemButton(itemIndex, clearItem)` | — | Add/remove attachment |
| `SendMailCanSend()` | `canSend` | Can send? |

---

## Common Patterns

### Display Currency with Cap

```lua
local function ShowCurrency(currencyID)
    local info = C_CurrencyInfo.GetCurrencyInfo(currencyID)
    if info then
        local text = info.name .. ": " .. info.quantity
        if info.maxQuantity > 0 then
            text = text .. " / " .. info.maxQuantity
        end
        if info.canEarnPerWeek and info.maxWeeklyQuantity > 0 then
            text = text .. " (Weekly: " .. info.quantityEarnedThisWeek .. "/" .. info.maxWeeklyQuantity .. ")"
        end
        print(text)
    end
end
```

### Auction House Search

```lua
-- Register for results
local f = CreateFrame("Frame")
f:RegisterEvent("ITEM_SEARCH_RESULTS_UPDATED")
f:SetScript("OnEvent", function(self, event, itemKey, ...)
    local numResults = C_AuctionHouse.GetNumItemSearchResults(itemKey)
    for i = 1, numResults do
        local result = C_AuctionHouse.GetItemSearchResultInfo(itemKey, i)
        if result then
            print(result.buyoutAmount, "copper -", result.quantity, "available")
        end
    end
end)

-- Initiate search
local itemKey = C_AuctionHouse.MakeItemKey(12345) -- itemID
C_AuctionHouse.SendSearchQuery(itemKey, {}, false)
```

### Check WoW Token Price

```lua
C_WowTokenPublic.UpdateMarketPrice()

local f = CreateFrame("Frame")
f:RegisterEvent("TOKEN_MARKET_PRICE_UPDATED")
f:SetScript("OnEvent", function()
    local price = C_WowTokenPublic.GetCurrentMarketPrice()
    if price then
        print("WoW Token: " .. GetCoinTextureString(price))
    end
end)
```

---

## Key Events

| Event | Payload | Description |
|-------|---------|-------------|
| `CURRENCY_DISPLAY_UPDATE` | currencyType, quantity, quantityChange, quantityGainSource, quantityLostSource | Currency changed |
| `AUCTION_HOUSE_SHOW` | — | AH opened |
| `AUCTION_HOUSE_CLOSED` | — | AH closed |
| `AUCTION_HOUSE_BROWSE_RESULTS_UPDATED` | — | Browse results ready |
| `ITEM_SEARCH_RESULTS_UPDATED` | itemKey | Item search ready |
| `COMMODITY_SEARCH_RESULTS_UPDATED` | itemID | Commodity search ready |
| `AUCTION_HOUSE_NEW_RESULTS_RECEIVED` | itemKey | New results |
| `ITEM_SEARCH_RESULTS_ADDED` | itemKey | Result added |
| `AUCTION_HOUSE_AUCTION_CREATED` | auctionID | Auction posted |
| `AUCTION_CANCELED` | auctionID | Auction canceled |
| `TOKEN_MARKET_PRICE_UPDATED` | result | Token price updated |
| `TOKEN_STATUS_CHANGED` | — | Token status changed |
| `PERKS_PROGRAM_CURRENCY_REFRESH` | — | Trader's Tender updated |
| `PERKS_PROGRAM_PURCHASE_SUCCESS` | — | Trading Post purchase |
| `PERKS_PROGRAM_SET_FROZEN_ITEM` | — | Item frozen |
| `MAIL_INBOX_UPDATE` | — | Inbox updated |
| `MAIL_SEND_SUCCESS` | — | Mail sent |
| `MAIL_SHOW` | — | Mailbox opened |
| `MAIL_CLOSED` | — | Mailbox closed |
| `TRADE_SHOW` | — | Trade window opened |
| `TRADE_CLOSED` | — | Trade ended |
| `TRADE_ACCEPT_UPDATE` | playerAccept, targetAccept | Accept state |
| `TRADE_MONEY_CHANGED` | — | Gold offer changed |
| `TRADE_PLAYER_ITEM_CHANGED` | slotIndex | Player item changed |
| `TRADE_TARGET_ITEM_CHANGED` | slotIndex | Target item changed |
| `BLACK_MARKET_ITEM_UPDATE` | — | BMAH items updated |
| `BLACK_MARKET_OUTBID` | — | Outbid on BMAH |

---

## Gotchas & Restrictions

1. **Auction House hardware event** — Posting, buying, and bidding require hardware events (user clicks).
2. **Commodity vs. item** — Commodities (stackable) use a different API path than equipment/unique items.
3. **AH throttling** — Searches are rate-limited. Rapid queries get throttled by the server.
4. **Mail COD** — COD mail auto-deducts gold when attachment is taken. Test with `InboxItemCanDelete()`.
5. **GetMoney() returns copper** — Divide by 100 for silver, 10000 for gold.
6. **Currency caps** — Always check `maxQuantity` and `maxWeeklyQuantity` before displaying progress.
7. **WoW Token price is async** — Call `UpdateMarketPrice()` then wait for `TOKEN_MARKET_PRICE_UPDATED`.
8. **ReplicateItems() is slow** — Full AH scan is expensive. Use sparingly and handle results incrementally.


---
Source attribution: JBurlison
Original project: https://github.com/JBurlison/WoWAddonAPIAgents
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Gabriel Moreira

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: JBurlison
Original project: https://github.com/JBurlison/WoWAddonAPIAgents
Attribution basis: Upstream repository explicitly recorded in package mirror path

Fields of work: Data & Analytics, Development & Engineering
Roles: Backend Developer, Data Analyst, Game Developer
Specialties: API
Tools: World Of Warcraft Api
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: e584e718e8db7864551576da8e90e565d88a6c7c1c258b37b91341726acbdedc