Integrations

Discord Webhooks

XAuctionHouse can send rich embeds to Discord channels via webhooks. There are two separate webhook configurations:

Sales webhook

Sends notifications for marketplace events. Enable in config.yml:

discord-sales:
  enabled: true
  webhook-url: "https://discord.com/api/webhooks/..."

Events sent to the sales webhook:

Event	Embed Color	Description
New Listing	Blue	A player listed an item for fixed-price sale
New Auction	Purple	A player started an auction
Item Purchased	Green	A fixed-price item was bought
Bid Placed	Yellow	A bid was placed on an auction
Auction Won	Gold	An auction ended with a winner

Admin webhook

Logs administrative actions for audit purposes:

discord-admin:
  enabled: true
  webhook-url: "https://discord.com/api/webhooks/..."

Event	Embed Color	Description
Force Remove	Red	An admin force-removed a player's listing
Purge	Orange	An admin purged expired or sold items

All embeds include a timestamp. When cross-server sync is enabled, the server name is included in the footer.

PlaceholderAPI

If PlaceholderAPI is installed, XAuctionHouse registers the following placeholders:

Placeholder	Description
%xauctionhouse_sell_limit%	Maximum sell slots for the player (based on ah.limit.* permission)
%xauctionhouse_sell_count%	Current number of active listings
%xauctionhouse_expired_count%	Current number of expired listings
%xauctionhouse_active_auctions%	Number of active auction listings by this player
%xauctionhouse_active_bids%	Number of items where this player is the highest bidder

Web Dashboard API

XAuctionHouse registers a web module with the XCore dashboard. It provides 5 pages (Listings, Expired, Sales History, Player Lookup, Statistics) and the following API endpoints.

All endpoints require Authorization: Bearer <token> authentication. Rate limit: 30 requests per IP per minute.

GET endpoints

Endpoint	Description
GET /api/xauctionhouse/listings	Returns the 100 most recent active listings
GET /api/xauctionhouse/sales	Returns the 100 most recent completed sales
GET /api/xauctionhouse/stats	Aggregate stats: active listings count, total sold, total expired
GET /api/xauctionhouse/stats/daily	Last 7 days: daily volume, top 10 sellers, top 10 buyers
GET /api/xauctionhouse/expired?page=1&limit=50	Paginated expired/cancelled listings
GET /api/xauctionhouse/history?page=1&limit=50&search=name	Paginated transaction history with optional player search
GET /api/xauctionhouse/player/{name}	Player's active listings, sold items, bought items, and expired listings
GET /api/xauctionhouse/player/{name}/history	Player's complete buy/sell transaction history

POST endpoints

Endpoint	Body	Description
POST /api/xauctionhouse/listing/cancel	{"id": int}	Cancel a single active listing by ID
POST /api/xauctionhouse/listing/cancel-all	{"player": "name"}	Cancel all active listings by a player
POST /api/xauctionhouse/expired/clear	{"player": "name"} or {}	Delete expired listings (for one player, or all if no player specified)

Response format

All responses are JSON. Listing objects include item details extracted from the serialized ItemStack:

{
  "sellerName": "Steve",
  "price": 500.0,
  "currency": "coins",
  "listingType": "FIXED_PRICE",
  "itemDetails": {
    "material": "DIAMOND_SWORD",
    "amount": 1,
    "displayMaterial": "Diamond Sword",
    "enchantments": [
      {"name": "Sharpness", "level": 5}
    ]
  }
}

For auction listings, additional fields are included: startingBid, currentBid, bidCount, and highBidder.

Cross-Server Sync

When cross-server sync is enabled in XCore, XAuctionHouse registers a sync channel to propagate listing changes across all servers in real-time.

Sync events include:

• ADD — A new listing was created
• REMOVE — A listing was purchased, cancelled, or force-removed
• BID — A bid was placed on an auction

This means players on any server see the same auction house contents. When a listing is bought on Server A, it immediately disappears from the GUI on Server B.