Developer API

AstralAuctionHouse exposes its services through the main plugin instance, registers two AstralCore actions, and contributes three placeholder namespaces. There is no shared interface in core-commons for the auction house itself — integrating plugins depend on the auction-house artifact directly.

Maven coordinates

<dependency>
    <groupId>com.astralrealms</groupId>
    <artifactId>auctionhouse</artifactId>
    <version>2.0-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

Repository: https://maven.astralrealms.fr/repository/maven-public/.

Plugin handle

import com.astralrealms.auctionhouse.AstralAuctionHouse;

AstralAuctionHouse plugin = AstralAuctionHouse.getPlugin(AstralAuctionHouse.class);

Services

Getter	Type	Use
`plugin.items()`	`ItemService`	Sell / buy / claim, list cached items.
`plugin.transactions()`	`TransactionService`	Persist and look up sales.
`plugin.average()`	`AverageService`	Cached weighted unit prices.
`plugin.configuration()`	`AHConfiguration`	TTL, sell tax, listing limits, blacklist.
`plugin.categoriesConfiguration()`	`CategoriesConfiguration`	Category registry.
`plugin.menus()`	`MenuContainer`	Menu loader.

`ItemService`

ItemService items = plugin.items();

// All cached items, sorted, for menu rendering
List<AuctionItem> snapshot = items.items();

// Mutations — all return CompletableFuture<…> and emit the standard messages internally
items.sell(player, 1500);                 // List the player's main-hand item
items.buy(player, auctionItem);           // Network-safe purchase
items.claim(player, auctionItem);         // Recover an EXPIRED listing
items.expire(auctionItem);                // Force-expire (admin tooling)

All four mutating methods take the Redis lock (auctionhouse:locks:<itemId>) internally; you do not need to acquire it yourself. Errors are surfaced to the player via AHMessages; the future resolves silently.

`TransactionService`

TransactionService transactions = plugin.transactions();

// Pull the player's history (buyer ∪ seller, last 250)
CompletableFuture<List<AuctionTransaction>> recent = transactions.findPlayerId(player.getUniqueId());

// Run the weighted-average query (used internally; rarely needed by other plugins)
CompletableFuture<Map<String, Integer>> averages = transactions.fetchAllAverages();

`AverageService`

AverageService averages = plugin.average();

Integer price = averages.average("diamond_sword");      // null if no data
averages.setAverage("diamond_sword", 1850);             // write-through (Redis)
averages.refetch();                                     // force refresh

Actions

`[buy-item]`

- "[buy-item] %item_id%"

Calls ItemService.buy(executor, item). The argument is a placeholder that must resolve to an AuctionItem — typically %item_id% while iterating a layout that already provides AuctionItem context.

`[claim-item]`

- "[claim-item] %item_id%"

Calls ItemService.claim(executor, item).

Placeholders

`item_*` (`AuctionItem`)

Placeholder	Type	Description
`%item_id%`	UUID	Primary key.
`%item_item%`	ItemStack	Chain into `_name`, `_lore`, `_material`, …
`%item_owner%`	MinecraftPlayer	Seller (network-aware lookup).
`%item_status%`	ItemStatus	`LISTED`/`EXPIRED`/ etc.
`%item_category%`	String	Category id.
`%item_price%`	int	Raw asking price.
`%item_formatted-price%`	String	Thousands-separated.
`%item_amount%`	int	Stack size.
`%item_time%`	TimePlaceholder	Expiry (createdAt + TTL). Chain `_remaining`, `_format`.
`%item_average%`	Integer	Weighted unit price for the item's `itemKey`.
`%item_averageWeighted%`	int	`average × amount`.

`transaction_*` (`AuctionTransaction`)

Placeholder	Type	Description
`%transaction_id%`	UUID	—
`%transaction_item%`	ItemStack	—
`%transaction_buyer%`	MinecraftPlayer	—
`%transaction_seller%`	MinecraftPlayer	—
`%transaction_price%`	int	Final price.
`%transaction_date%`	TimePlaceholder	When the sale happened.
`%transaction_type%`	String	`"BOUGHT"` or `"SOLD"` — resolved from the viewer's perspective when available.

`category_*` (`AuctionCategory`)

Placeholder	Type	Description
`%category_id%`	String	—
`%category_slot%`	int	Menu slot.
`%category_item%`	ItemStack	The display icon.

Analytics

AstralAuctionHouse pushes two event types through AstralAnalytics:

Event type	Payload
`auctionhouse-listed`	`{item_key, price, amount, category, ...}`
`auctionhouse-purchased`	`{item_key, price, amount, buyer, seller, ...}`

Use them to build retention / market-velocity dashboards in Metabase. See AstralAnalytics for example queries.

Extending the category matcher

There is no extension hook for category matching — the CategoriesConfiguration.find(ItemStack) walks the YAML in order and falls back. To classify a new custom item, add its material (or supplier key) to the relevant category's materials list in categories.yml. See Configuration.

Last modified: 25 July 2026

Developer API

Maven coordinates

Plugin handle

Services

ItemService

TransactionService

AverageService