API interface for interacting with EssentialsC's Auction House system.
Retrieve an instance via EssentialsCAPI.getAuctionApi().
AuctionApi ah = APIProvider.getAPI().getAuctionApi();
// list all active auctions
List<Auction> auctions = ah.getActiveAuctions();
// programmatically create a listing
ah.createAuction(player, item, BigDecimal.valueOf(500), 86400000L)
.thenAccept(success -> {
if (success) player.sendMessage("Listed!");
});
Methods that interact with the economy or database return a
CompletableFuture and must not be awaited
on the main server thread.
Method Summary
| List<Auction> |
getActiveAuctions() Returns a snapshot of all currently active auctions. |
| List<Auction> |
getPlayerAuctions(UUID uuid) Returns all active auctions listed by the given player. |
| Optional<Auction> |
getAuction(int id) Looks up a single active auction by its database ID. |
| List<ItemStack> |
getExpiredItems(UUID uuid) Returns the cached list of unclaimed expired items for the given player. |
| boolean |
hasExpiredItems(UUID uuid) Returns whether the given player has any unclaimed expired items. |
| List<SellHistoryEntry> |
getSellHistory(UUID uuid) Returns the sell history for the given player, most recent first. |
| List<BuyHistoryEntry> |
getBuyHistory(UUID uuid) Returns the buy history for the given player, most recent first. |
| CompletableFuture<Boolean> |
createAuction(Player seller, ItemStack item, BigDecimal price, long duration) Creates a new auction listing on behalf of the given player. |
| CompletableFuture<Boolean> |
buyAuction(Player buyer, int id) Processes the purchase of an auction by the given player. |
| CompletableFuture<Boolean> |
cancelAuction(Player player, int id) Cancels an active auction and returns the item to the seller's expired-items queue. |
| boolean |
claimExpiredItems(Player player) Claims all expired items for the given player, delivering them to their inventory. |
Returns a snapshot of all currently active (non-expired, non-claimed) auctions.
The returned list is not backed by the internal auction map — modifications to it have no effect on the Auction House. The order of entries is not guaranteed.
Returns:| List<Auction> | a list of active auctions; never null, may be empty |
Returns all active auctions listed by the given player.
Returns an empty list if the player has no active listings. The returned list is not backed by internal state.
Parameters:| uuid | the UUID of the seller; must not be null |
| List<Auction> | the player's active listings; never null, may be empty |
Looks up a single active auction by its database ID.
Parameters:| id | the auction ID to look up |
| Optional<Auction> | an Optional containing the auction if found and still active, or Optional.empty() if the ID is unknown or the auction has already been claimed or expired |
Returns the cached list of unclaimed expired items for the given player.
Items appear here when an auction expires without a buyer or is cancelled. The list is loaded from the database on player join and kept in memory until the player claims their items or disconnects. The returned list is a copy.
Only items for currently online players are guaranteed to be cached. For offline players the list will typically be empty even if unclaimed items exist in the database.
Parameters:| uuid | the UUID of the player; must not be null |
| List<ItemStack> | items awaiting claim; never null, may be empty |
Returns whether the given player has any unclaimed expired items waiting.
Equivalent to checking !getExpiredItems(uuid).isEmpty() but avoids
allocating the list copy. Subject to the same online-only caching caveat as
getExpiredItems(UUID).
| uuid | the UUID of the player; must not be null |
| boolean | true if the player has at least one item awaiting claim; false if the cache is empty or the player is offline |
Returns the sell history for the given player, most recent entry first.
The history is kept in memory and automatically capped at 100 entries per player. Returns an empty list if no sales have been recorded yet for this player, or if the player has never been online since the server started.
Parameters:| uuid | the UUID of the seller; must not be null |
| List<SellHistoryEntry> | sell history records; never null, may be empty |
Returns the buy history for the given player, most recent entry first.
The history is kept in memory and automatically capped at 100 entries per player. Returns an empty list if no purchases have been recorded yet for this player, or if the player has never been online since the server started.
Parameters:| uuid | the UUID of the buyer; must not be null |
| List<BuyHistoryEntry> | buy history records; never null, may be empty |
Creates a new auction listing on behalf of the given player.
Before inserting into the database, the following check is performed:
- The seller's current active listing count is compared against the configured
maximum. This check is bypassed if the player holds the
essentialsc.ah.bypass.limitpermission.
The provided ItemStack is cloned internally — you may safely modify
or discard the original after this call.
Do not block the main thread waiting on this future.
Parameters:| seller | the player creating the listing; must not be null |
| item | the item to list; must not be null |
| price | the buy-now price; must be positive, must not be null |
| duration | the auction duration in milliseconds; must be positive |
| CompletableFuture<Boolean> | true if the auction was created successfully, false if the player is at their listing limit or the database insert failed |
Processes the purchase of an auction by the given player.
The future resolves to false and no action is taken if any of the following conditions are met:
- The auction ID does not exist or is already claimed/expired.
- The buyer is the seller of the auction.
- The buyer does not have sufficient funds.
- The auction is already being processed by a concurrent request.
On success: the buyer is charged, the item is delivered to their inventory (dropped at their feet if the inventory is full), the seller receives payment, and the auction is marked as claimed and removed from active listings.
Do not block the main thread waiting on this future.
Parameters:| buyer | the player purchasing the auction; must not be null |
| id | the ID of the auction to buy |
| CompletableFuture<Boolean> | true on a successful purchase, false otherwise |
Cancels an active auction and returns the item to the seller's expired-items queue.
The future resolves to false and no action is taken if any of the following conditions are met:
- The auction ID does not exist in the active listings.
- The requesting player is not the seller and does not have the
essentialsc.ah.adminpermission. - The auction is already being processed by a concurrent request.
On success, the cancelled item is placed in the seller's expired-items queue
and persisted to the database. The seller can retrieve it via
claimExpiredItems(Player).
Do not block the main thread waiting on this future.
Parameters:| player | the player requesting cancellation; must not be null |
| id | the ID of the auction to cancel |
| CompletableFuture<Boolean> | true if the auction was cancelled, false otherwise |
Claims all expired items for the given player, delivering them to their inventory.
Items that do not fit in the player's inventory are dropped naturally at their
current location. If a claim operation is already in progress for this player
(concurrent guard), this method returns false immediately without
delivering anything.
This method is synchronous and safe to call on the main thread.
Parameters:| player | the player claiming their expired items; must not be null |
| boolean | true if at least one item was found and delivered, false if the player had no expired items or a claim was already in progress |