diff --git a/README.md b/README.md
index c4319fb7..31f14516 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
| [Class](docs/API.md#class) | `FillLocalizedClassList` |
| [Combat](docs/API.md#combat) | `InCombatLockdown` |
| [CVar](docs/API.md#cvar) | `C_CVar.GetCVarBool` |
-| [Container](docs/API.md#container) | `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` |
+| [Container](docs/API.md#container) | `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` |
| EncodingUtil | `C_EncodingUtil.CompressString`, `C_EncodingUtil.DecompressString`, `C_EncodingUtil.EncodeBase64`, `C_EncodingUtil.DecodeBase64`, `C_EncodingUtil.EncodeHex`, `C_EncodingUtil.DecodeHex`, `C_EncodingUtil.SerializeJSON`, `C_EncodingUtil.DeserializeJSON`, `C_EncodingUtil.SerializeCBOR`, `C_EncodingUtil.DeserializeCBOR` |
| [EquipmentSet](docs/API.md#equipmentset) | `C_EquipmentSet.CanUseEquipmentSets`, `C_EquipmentSet.ClearIgnoredSlotsForSave`, `C_EquipmentSet.CreateEquipmentSet`, `C_EquipmentSet.DeleteEquipmentSet`, `C_EquipmentSet.EquipmentSetContainsLockedItems`, `C_EquipmentSet.GetEquipmentSetID`, `C_EquipmentSet.GetEquipmentSetIDs`, `C_EquipmentSet.GetEquipmentSetInfo`, `C_EquipmentSet.GetIgnoredSlots`, `C_EquipmentSet.GetItemIDs`, `C_EquipmentSet.GetItemLocations`, `C_EquipmentSet.GetNumEquipmentSets`, `C_EquipmentSet.IgnoreSlotForSave`, `C_EquipmentSet.IsSlotIgnoredForSave`, `C_EquipmentSet.ModifyEquipmentSet`, `C_EquipmentSet.SaveEquipmentSet`, `C_EquipmentSet.UnignoreSlotForSave`, `C_EquipmentSet.UseEquipmentSet` (sets persist to `WTF\Account\...\ClassicAPI_EquipmentSets.txt`) |
| [Events](docs/API.md#events) | `C_EventUtils.IsEventValid` |
diff --git a/docs/API.md b/docs/API.md
index 2f921ede..47be53bc 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -34,6 +34,7 @@ build instructions.
- [`GetItemCooldown(itemInfo)` / `C_Container.GetItemCooldown(itemID)`](#getitemcooldowniteminfo--c_containergetitemcooldownitemid)
- [`C_Container.GetContainerItemDurability(containerIndex, slotIndex)`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex)
- [`C_Container.GetContainerItemRepairCost(containerIndex, slotIndex)`](#c_containergetcontaineritemrepaircostcontainerindex-slotindex)
+ - [`C_Container.GetContainerItemCharges(containerIndex, slotIndex)`](#c_containergetcontaineritemchargescontainerindex-slotindex)
- [`C_Container.GetContainerNumFreeSlots(bagID)`](#c_containergetcontainernumfreeslotsbagid)
- [`C_Container.PlayerHasHearthstone()`](#c_containerplayerhashearthstone)
- [`C_Container.UseHearthstone()`](#c_containerusehearthstone)
@@ -770,6 +771,62 @@ Useful for "repair only items above N copper" smart-repair logic
without scanning tooltips. ClassicAPI addition; modern WoW has no
direct equivalent.
+### `C_Container.GetContainerItemCharges(containerIndex, slotIndex)`
+
+Per-slot equivalent of
+[`C_Item.GetItemCount`](#c_itemgetitemcountitem-includebank-includecharges)'s
+`includeCharges=true` mode — returns the total uses available in
+*this single slot*, where `GetItemCount` totals the same value
+across every matching slot.
+
+```
+uses = C_Container.GetContainerItemCharges(containerIndex, slotIndex)
+```
+
+`containerIndex` accepts the same values as
+[`C_Container.GetContainerItemDurability`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex)
+(`0` = backpack, `1..4` = equipped bags, `-1`/`5..11` = bank, etc.).
+`slotIndex` is 1-based.
+
+Math is `stack * usesPerItem`, where `usesPerItem` is
+`abs(SPELL_CHARGES[0])` for items with a negative charges field
+(consume-on-use: wands, healthstones, mana gems, sapper charges)
+and `1` for everything else. Worked examples:
+
+| Slot contents | Stack | Raw charges | Returns |
+|---|---:|---:|---:|
+| Wand of Decay at 50 charges | 1 | -50 | **50** |
+| Wand at 1 charge | 1 | -1 | **1** |
+| Healthstone | 1 | -1 | **1** |
+| Stack of 20 water | 20 | -1 | **20** |
+| Stack of 5 mana potions | 5 | -1 | **5** |
+| Hearthstone (cooldown-only) | 1 | 0 | **1** |
+| Any other item in the slot | 1 | 0 | **1** |
+
+Returns `nil` only when the slot is empty.
+
+```lua
+-- "how many charges does my wand have left?"
+local charges = C_Container.GetContainerItemCharges(0, 1)
+print("Wand charges remaining: " .. charges)
+
+-- "how many drinks across the bags?" — same as GetItemCount(water, false, true)
+local total = 0
+for bag = 0, 4 do
+ for slot = 1, GetContainerNumSlots(bag) do
+ if C_Container.GetContainerItemID(bag, slot) == waterID then
+ total = total + C_Container.GetContainerItemCharges(bag, slot)
+ end
+ end
+end
+```
+
+ClassicAPI addition; modern WoW has no direct equivalent (modern
+addons read charges off tooltip text). Useful when you need a
+per-slot number rather than `GetItemCount`'s rollup — e.g. to
+display "X charges" on the slot UI for a wand without re-walking
+every other matching item.
+
### `C_Container.GetContainerNumFreeSlots(bagID)`
Returns the number of empty slots in the given bag, plus the bag's
diff --git a/src/container/Charges.cpp b/src/container/Charges.cpp
new file mode 100644
index 00000000..6ca14a33
--- /dev/null
+++ b/src/container/Charges.cpp
@@ -0,0 +1,55 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU Lesser General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along with
+// ClassicAPI. If not, see .
+
+// `C_Container.GetContainerItemCharges(containerIndex, slotIndex)` —
+// returns the `abs(SPELL_CHARGES[0])` value of the item in the
+// specified bag slot, or `nil` for empty slots and items that don't
+// carry a charge concept. Wands return their remaining cast count
+// (e.g. 50 → 49 → …); single-use items (Healthstone, Mana Gem,
+// Goblin Sapper Charge) return `1`.
+//
+// Modern equivalent: none — modern WoW exposes charges only through
+// tooltip text scanning. `C_Item.GetItemCount(includeBank, includeCharges)`
+// totals charges across every matching stack; this is the per-slot
+// reader.
+
+#include "Game.h"
+#include "item/Charges.h"
+#include "item/Location.h"
+
+namespace Container::Charges {
+
+namespace {
+
+int __fastcall Script_C_Container_GetContainerItemCharges(void *L) {
+ if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2)) {
+ Game::Lua::Error(L,
+ "Usage: C_Container.GetContainerItemCharges(containerIndex, slotIndex)");
+ return 0;
+ }
+ const int bagID = static_cast(Game::Lua::ToNumber(L, 1));
+ const int slotIndex = static_cast(Game::Lua::ToNumber(L, 2));
+ return Item::Charges::PushChargesForItem(
+ L, Item::Location::ResolveBag(L, bagID, slotIndex));
+}
+
+void RegisterLuaFunctions() {
+ Game::Lua::RegisterTableFunction("C_Container", "GetContainerItemCharges",
+ &Script_C_Container_GetContainerItemCharges);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Container::Charges
diff --git a/src/item/Charges.cpp b/src/item/Charges.cpp
new file mode 100644
index 00000000..49b691bd
--- /dev/null
+++ b/src/item/Charges.cpp
@@ -0,0 +1,39 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU Lesser General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along with
+// ClassicAPI. If not, see .
+
+#include "Charges.h"
+
+#include "../Game.h"
+#include "../Offsets.h"
+
+#include
+
+namespace Item::Charges {
+
+int PushChargesForItem(void *L, const uint8_t *item) {
+ if (item == nullptr)
+ return 0;
+ auto *descriptor = *reinterpret_cast(
+ item + Offsets::OFF_ITEM_DESCRIPTOR);
+ if (descriptor == nullptr)
+ return 0;
+ const int32_t stack = static_cast(*reinterpret_cast(
+ descriptor + Offsets::OFF_DESCRIPTOR_STACK_COUNT));
+ const int32_t rawCharges = *reinterpret_cast(
+ descriptor + Offsets::OFF_DESCRIPTOR_SPELL_CHARGES_0);
+ const int32_t usesPerItem = (rawCharges < 0) ? -rawCharges : 1;
+ Game::Lua::PushNumber(L, static_cast(stack * usesPerItem));
+ return 1;
+}
+
+} // namespace Item::Charges
diff --git a/src/item/Charges.h b/src/item/Charges.h
new file mode 100644
index 00000000..d75fc51f
--- /dev/null
+++ b/src/item/Charges.h
@@ -0,0 +1,44 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU Lesser General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along with
+// ClassicAPI. If not, see .
+
+#pragma once
+
+#include
+
+namespace Item::Charges {
+
+// Pushes the total uses available in this single slot — the
+// per-slot equivalent of `GetItemCount(_, _, includeCharges=true)`.
+// Returns `1` (pushed one value) on success, `0` (pushes nothing,
+// caller surfaces as `nil`) when the item is missing or the
+// descriptor is null.
+//
+// Math is `stack * usesPerItem` where `usesPerItem` follows
+// `Item::Count::GetUsesPerItem`:
+// - `SPELL_CHARGES[0] >= 0` → `1` (no destroy-on-zero behavior;
+// stack count alone reflects "how many uses").
+// - `SPELL_CHARGES[0] < 0` → `abs(value)` (consume-on-use items;
+// wand at 50 has `-50` so each item contributes 50).
+//
+// Worked examples:
+// - Wand at 50 charges (stack=1, raw=-50): `1 * 50 = 50`
+// - Hearthstone (stack=1, raw=0): `1 * 1 = 1` (cooldown-
+// only, no charges concept; we still surface "1 use").
+// - Water stack of 20 (stack=20, raw=-1): `20 * 1 = 20`
+// - Equipped sword (stack=1, raw=0): `1 * 1 = 1`
+//
+// Caller can `return PushChargesForItem(L, item);` to forward the
+// count directly.
+int PushChargesForItem(void *L, const uint8_t *item);
+
+} // namespace Item::Charges