API reference

Everything here is on com.zephrynis.zyauctions.api.ZyAuctionsApi. The whole API module is @NullMarked, so a parameter or return type is non-null unless it is annotated @Nullable or wrapped in Optional.

Reading

Safe to call from any thread. All of these serve immutable snapshots out of an in-memory index — no storage access, no blocking.

Optional<Listing> listing(UUID listingId)

One listing by id, or empty if nothing on sale has that id.

List<Listing> listings(ListingQuery query)

Active listings matching a query, already sorted. Returns an immutable list; possibly empty, never null.

List<Listing> endingSoon = auctions.listings(ListingQuery.builder()
        .type(ListingType.AUCTION)
        .sort(SortOrder.ENDING_SOON)
        .build());

List<Listing> listingsOf(UUID seller)

Every active listing belonging to one seller, newest first. Immutable.

int activeListingCount()

How many listings are on sale in total.

List<Collectible> collectibles(UUID owner)

One player's collection bin, oldest first. Immutable. Bins are held in memory for every player, online or not, so this does not hit storage.

Quotes

Safe to call from any thread.

int listingLimit(Player player)

How many listings that player may have at once, taking their permissions into account. Returns Integer.MAX_VALUE for a player with no cap.

double quoteListingFee(Player player, double price)

What creating a listing at that price would cost them up front. 0 if they hold zyauctions.bypass.fee.

double quoteSalesTax(Player seller, double price)

What would be withheld from a sale at that price. 0 if they hold zyauctions.bypass.tax.

String apiVersion()

The API module's semantic version, such as "1.0.0". Useful for refusing to load against an API you were not built for.

Changing things

ListingResult createListing(Player seller, ListingRequest request)

Puts an item up for sale. Fires ListingCreateEvent before anything is charged.

The item comes from the request, not from the seller's inventory — taking it out of wherever it came from is your job, and should happen only once the result is successful.

ListingRequest request = ListingRequest.buyNow(stack, 1200.0)
        .withDuration(Duration.ofHours(12));

ListingResult result = auctions.createListing(player, request);
if (result.successful()) {
    player.getInventory().removeItem(stack);
}

ListingResult carries status(), the created listing() (only on success) and feePaid(). Statuses: SUCCESS, NO_ECONOMY, CANNOT_AFFORD_FEE, LISTING_LIMIT_REACHED, COLLECTION_BIN_FULL, BLACKLISTED_ITEM, NO_ITEM, PRICE_TOO_LOW, PRICE_TOO_HIGH, CANCELLED_BY_PLUGIN, STORAGE_ERROR.

ListingRequest validates in its constructor and throws IllegalArgumentException for an empty item, a non-positive or non-finite price, a negative increment, or a non-positive duration. It takes a copy of the item, so the original is left alone.

PurchaseResult buy(Player buyer, UUID listingId)

Buys a fixed-price listing outright. Fires ListingPurchaseEvent before any money moves.

Charges the buyer, credits the seller after tax, and hands the item over — into the buyer's inventory if there is room, otherwise into their collection bin.

PurchaseResult carries status(), listing(), pricePaid(), sellerReceived() and deliveredToBin(). Statuses: SUCCESS, NOT_FOUND, NOT_ACTIVE, OWN_LISTING, NOT_BUY_NOW, CANNOT_AFFORD, NO_ECONOMY, CANCELLED_BY_PLUGIN, ECONOMY_ERROR.

Two players clicking the same listing in the same tick is handled: exactly one gets SUCCESS, the other gets NOT_ACTIVE. Nothing is charged to the loser.

BidResult bid(Player bidder, UUID listingId, double amount)

Places a bid. Fires ListingBidEvent before any money moves.

The amount is held from the bidder's balance immediately and refunded in full the moment they are outbid. amount must be at least Listing.minimumBid().

BidResult carries status(), listing(), amount() and minimumBid() — the last of which is populated even on failure, so you can tell a player exactly how much more they need. Statuses: SUCCESS, NOT_FOUND, NOT_ACTIVE, OWN_LISTING, NOT_AUCTION, BID_TOO_LOW, ALREADY_WINNING, CANNOT_AFFORD, NO_ECONOMY, CANCELLED_BY_PLUGIN, ECONOMY_ERROR.

If anti-snipe is on and the bid lands near the end, the listing on the result already has its extended expiresAt().

CancelResult cancel(@Nullable UUID actor, UUID listingId, boolean administrative)

Withdraws a listing. Fires ListingCancelEvent before anything moves.

• actor — who is doing it, or null for console and automated removals.
• administrative — true skips the "must be the seller" check and the "auctions with bids may not be withdrawn" rule. Any held bid is refunded either way.

The item always goes to the seller's collection bin, never straight into their inventory, so the outcome does not depend on whether they are online.

Statuses: SUCCESS, NOT_FOUND, NOT_ACTIVE, NOT_ALLOWED, HAS_BIDS, CANCELLED_BY_PLUGIN.

boolean claim(Player player, UUID collectibleId)

Claims one collection bin entry into a player's inventory. Fires CollectibleClaimEvent.

Returns false — leaving the entry where it is — if the entry does not exist, the player has no room, or a plugin cancelled the event. The entry is only dropped once the item is definitely in their inventory.

int claimAll(Player player)

Claims as much of a player's bin as fits, oldest first, and returns how many entries were handed over. Stops at the first one that will not fit.

Collectible deposit(UUID owner, ItemStack item, CollectibleReason reason)

Puts an item into a player's collection bin and returns the stored entry.

Useful outside auctions entirely: the bin survives restarts and does not care whether the player is online, which makes it a reasonable place to put anything you cannot hand over right now.

auctions.deposit(playerId, reward, CollectibleReason.WON);

Takes a copy of the item.

Model types

Listing

An immutable snapshot. id, seller, sellerName, item (a copy), type, category, status, price, bidIncrement, minimumBid, topBidder, topBidderName, bidCount, createdAt, expiresAt, plus remaining(), expired() and isSeller(UUID).

price() means "what it costs to take this right now" — the fixed price for a buy-it-now listing, the current top bid for an auction, or the starting bid if nobody has bid yet.

minimumBid() is the opening bid before anyone has bid, and price + bidIncrement afterwards. It is 0 for buy-it-now listings.

Collectible

id, owner, item (a copy), reason, createdAt.

ListingQuery

Built with ListingQuery.builder(), or ListingQuery.all() for everything. Filters: category, type, seller, search, sort. Every filter is optional; an unset one matches everything. toBuilder() gives you a pre-filled builder for making a variation.

Search matches the item's material name and display name, case-insensitively. The builder trims and lowercases whatever you give it.

ListingRequest

ListingRequest.buyNow(item, price) or ListingRequest.auction(item, startingBid, increment), then optionally .withDuration(duration). Leaving the duration unset uses the server's configured default.

Enums

• ListingType — BUY_NOW, AUCTION
• ListingStatus — ACTIVE, SOLD, EXPIRED, CANCELLED
• Category — WEAPONS, TOOLS, ARMOR, BLOCKS, FOOD, POTIONS, REDSTONE, TRANSPORT, DECORATION, MISC
• SortOrder — NEWEST, OLDEST, PRICE_LOW, PRICE_HIGH, ENDING_SOON
• CollectibleReason — EXPIRED, CANCELLED, REMOVED, WON, PURCHASED

Each has id() for the lowercase form used in storage and translation keys, and Category, SortOrder have byId(String) returning an Optional.

What you will not find here

• Sale history. Nothing records completed sales. Listen to ListingSoldEvent and keep your own if you need one.
• A way to change a live listing's price. Withdraw it and create a new one.
• Anything that returns a mutable collection. Every list is immutable and every ItemStack is a copy.