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
Server Sale	Gold	A server listing was bought (money sink)

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
Auction Ban	Red	An admin banned a player from the auction house

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

These placeholders work in scoreboards, tab lists, holograms, and anywhere PlaceholderAPI is supported. Use them to show players their auction house stats.

Web Dashboard API

XAuctionHouse registers a web module with the XCore dashboard. It provides 6 pages (Listings, Expired, Sales History, Player Lookup, Bans, 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
`GET /api/xauctionhouse/bans`	All auction-house bans with a computed Active/Expired status

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)
`POST /api/xauctionhouse/bans/add`	`{"player", "duration", "reason"}`	Ban a player (`def` or empty duration = permanent); resolves offline players
`POST /api/xauctionhouse/bans/remove`	`{"player": "name"}`	Lift a player's auction-house ban

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.

POST endpoints that modify listings automatically publish cross-server sync messages, so changes are reflected on all servers immediately.

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.

Auction bans use their own sync channel (BAN / UNBAN events), so banning a scammer on one server applies everywhere instantly.

For instant sync, configure Redis in XCore. Without Redis, sync falls back to database polling with a configurable delay.