GroupeZ Docs
AddonszAuctionHouseStats

zAuctionHouseStats

Sales statistics, leaderboards, item price history and player stats for zAuctionHouse V4

zAuctionHouseStats is the official statistics addon for zAuctionHouse V4. It records every listing, sale and purchase made on your auction house, then turns that data into leaderboards, per-player statistics, item price references, zMenu GUIs and PlaceholderAPI placeholders.

It is built so that it never slows your server down. Every display (commands, menus, placeholders) is served from a cache, and all database work runs on one dedicated background thread. It is also safe to run on a network: several servers can share one MySQL/MariaDB database without counting a sale twice.

What it does

Leaderboards

Rank your players on 6 metrics, each available for 4 periods and filterable by economy:

MetricRanks players by
TOP_SELLERS_MONEYMoney actually received as a seller, after taxes
TOP_BUYERS_MONEYMoney actually paid as a buyer, taxes included
TOP_SELLERS_COUNTNumber of completed sales
TOP_BUYERS_COUNTNumber of completed purchases
TOP_TAX_PAIDTotal taxes paid (purchase tax share and listing tax)
BIGGEST_SALEHighest single sale received as a seller
PeriodWindow
DAYToday, since midnight
WEEKThis week, since Monday
MONTHThis month, since the 1st
ALLAll time

Periods are calendar windows, computed in the timezone set in statistics.timezone (or the server timezone). Money leaderboards are always calculated per economy: amounts from different economies are never added together.

Player statistics

Each player gets a full profile: items listed, sold, bought, expired and removed, money earned and spent, taxes paid, biggest sale, and the dates of their first and last sale and purchase. Players can view their own profile, and staff can look up any player, including offline ones.

Item price history

The addon records the material (and custom model data) of every item sold, so it can show the number of sales, average price and median price of any item. Players can check the item in their hand with /ah price, or browse the most sold items in the price explorer menu.

Server-wide statistics

Global counters for the whole auction house: items listed, sold, expired and removed, total money volume, taxes collected, number of times the auction house was opened, and the biggest sale ever made.

Ready-to-use GUIs

Five zMenu inventories are included and fully customizable: a statistics hub with a top 3 podium, the leaderboards, the player statistics profile, the item price explorer, and an admin status menu. They are generated in English, French, Spanish or Italian.

Placeholders

Every statistic is available as a %zahstats_...% placeholder (top_, player_, global_ and material_ families). Placeholders never query the database when they are displayed: they show a loading text until the value is ready, then read it from the cache.

V1 compatibility

Coming from the old zAuctionHouseStats V1? The V1 placeholder names keep working through a compatibility layer (it can be turned off with placeholders.enable-v1-aliases), and your V1 history can be imported with /zahstats import v1. Existing zAuctionHouse V4 history can also be imported from its logs with /zahstats import v4logs.

Key features

FeatureDescription
6 leaderboards x 4 periodsDaily, weekly, monthly and all-time rankings, per economy
Player profiles13 statistics per player, viewable in chat, GUI or placeholders
Item pricesNumber of sales, average and median price per item
Integrated commands/zahstats plus /ah stats and /ah price added to the zAuctionHouse command
zMenu GUIs5 inventories, 11 custom button types, 2 patterns
PlaceholderAPI%zahstats_*% placeholders, plus the V1 placeholder names
Zero-lag designCached reads, batched writes on a dedicated thread, no SQL on the main or region threads
Multi-server safeCounters are written as atomic increments, so several servers can share one database
Own databaseSeparate SQLite, MySQL or MariaDB storage (tables prefixed with zahstats_ by default), never the zAuctionHouse tables
History importImport from zAuctionHouseStats V1 or from the zAuctionHouse V4 logs
RetentionOptional daily purge of old sale and listing rows, while daily rollups, leaderboards and all-time totals are kept
FoliaFully supported
Public APIA StatsManager service for other plugins

Requirements

RequirementVersion
Java21 or higher
Minecraft1.21+
zAuctionHouseV4, 4.0.1.5 or newer recommended
zMenuRequired (the addon disables itself if zMenu is not working)
PlaceholderAPIOptional, only needed for %zahstats_*% placeholders in other plugins (they always work inside the addon's zMenu inventories)

Supported server software

SoftwareStatus
PaperRecommended
FoliaFully supported
Paper forks (Purpur, Pufferfish, ...)Supported
SpigotNot supported (the addon uses the Paper API)

zAuctionHouse V4 only

This addon does not work with zAuctionHouse V3. If zAuctionHouse is missing, disabled, or is not V4, the addon shuts itself down at startup and explains why in the console.

How data is collected

zAuctionHouseStats supports two ways of collecting data. Only one of them is active on a server at any time, so a sale can never be counted twice.

SourceWhen it is usedAccuracy
zAuctionHouse events (default)zAuctionHouse 4.0.1.5 or newerExact: real amounts paid and received, taxes, item details
Logs polling (fallback)Older zAuctionHouse V4 builds, only if collection.polling.enabled is trueApproximate prices
  • Events mode: the addon listens to the events zAuctionHouse fires after a listing, purchase, money claim or auction house opening, as well as to item expirations and removals. Events are queued in memory and written to the database in batches (every 2 seconds by default, or sooner during busy moments).
  • Logs polling mode: if the installed zAuctionHouse does not fire these events, the addon can read the zAuctionHouse logs table at a regular interval instead. This mode is never enabled by default. On a network, enable it on one server only.

The source is selected with collection.mode (AUTO, EVENTS or LOGS_POLLING). With the default AUTO, the addon uses the events when they exist. If they don't and polling is not allowed, the addon disables itself and asks you to update zAuctionHouse.

Running a network?

Use MYSQL or MARIADB storage and point every server to the same database. If the addon detects zAuctionHouseRedis while using SQLite, it warns you that each server will only see its own statistics. See also the zAuctionHouse Redis addon page.

Next steps

Installing zAuctionHouse

How to download, install and configure zAuctionHouse on your Minecraft server

Installing zAuctionHouseStats

How to install zAuctionHouseStats, configure its database and verify that statistics are collected

On this page

What it doesLeaderboardsPlayer statisticsItem price historyServer-wide statisticsReady-to-use GUIsPlaceholdersV1 compatibilityKey featuresRequirementsSupported server softwareHow data is collectedNext steps
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.