Astral Realms Documentation Help

Commands

Base aliases: /ah, /auctionhouse, /hdv.

Command

Aliases

Permission

Description

/ah

—

auctionhouse.use

Open the listing menu.

/ah open <player>

—

auctionhouse.use

Open another player's listings (also gated by the menu's own requirements).

/ah sell <price> [tag]

—

—

List the item in your main hand. See below.

/ah average

/ah avg

—

Show the weighted average unit price of the item in your main hand.

/ah transactions

—

—

Open your transaction-history menu (buys & sells, last 250).

/ah refresh

—

auctionhouse.admin

Force AverageService.refetch() — recomputes every average from the transactions table.

/ah reload

—

auctionhouse.reload

Reload config.yml, messages.yml, categories.yml, and the menu container.

/ah sell

/ah sell <price> [tag]

tag is a free-form trailing argument captured by the command parser; it is not currently consumed by the service and is reserved for future labelling.

The flow validates in this order:

  1. Player is on a server whose group is in commands-enabled-groups (otherwise DISABLED_WORLD).

  2. Main hand is not empty (EMPTY_HAND).

  3. Price is 1 ≤ price ≤ 1_000_000_000 (INVALID_PRICE).

  4. Item material isn't blacklisted (BLACKLISTED_ITEM).

  5. Number of currently active listings is below maximumListings(player) (SELL_FAILED_LISTING_LIMIT).

  6. Seller has at least price * sell-tax Polaris in their balance (SELL_FAILED_INSUFFICIENT_FUNDS).

Then:

  • Item is removed from the main hand.

  • The sell tax is withdrawn from the seller via EconomyService.withdraw.

  • A new AuctionItem row is written.

  • ItemUpdatedPacket(uuid) is broadcast on the auctionhouse.items exchange so peer servers refresh their caches.

  • The seller receives SELL_SUCCESS.

  • An auctionhouse-listed event is emitted to AstralAnalytics.

If any step after the inventory removal fails, the tax is refunded and the item is not returned to the inventory automatically — the row may still have been written; the cleanup task and the operator are expected to resolve the situation.

See Selling, Buying & Claiming for the full flow including the buy and claim paths.

/ah average

Reads the cached weighted unit price for the held item's itemKey. Returns:

Outcome

Message

Item has no itemKey (e.g. unidentifiable custom item)

NOT_AVERAGABLE

AverageService has no entry for that key (fewer than 3 sales in the last 90 days)

NO_AVERAGE_AVAILABLE

Otherwise

AVERAGE with the unit price.

See Averaging for how the cache is built and refreshed.

/ah transactions

Opens the transactions menu populated by TransactionRepository.findByPlayerId(player.uuid) — up to 250 rows where the player is either buyer or seller, ordered by created_at descending. Each row resolves the transaction placeholder namespace (see Developer API).

/ah refresh and /ah reload

  • /ah refresh runs AverageService.refetch() which:

    1. Recomputes every weighted average from the transactions table with the standard query (90-day window, minimum 3 sales).

    2. Pushes the results to the auctionhouse:average Redis hash.

    3. Invalidates the local Caffeine cache.

    Use it after a manual database edit or when you suspect the periodic refresh missed.

  • /ah reload runs the full configuration reload (AHConfiguration, CategoriesConfiguration, AHMessages, all menu YAMLs). Running listings keep their state — only the YAML is reread.

Last modified: 25 July 2026
messages.yml ReferenceSelling, Buying & Claiming