NexaAuctions Documentation

What is NexaAuctions?#

A configurable auction platform for servers that need safe sales, bid handling, mailbox recovery and operator tooling.

Who is it for?#

SMP, Lifesteal, Prison, SkyBlock and network owners who need a premium market layer with clear admin recovery paths.

Truthful scope#

Redis currently handles heartbeat, cache invalidation and lock helpers. SQL remains the authoritative source of auction state.

Main features#

• BIN, normal bid and bulk BIN listing models.
• Mailbox claim flow for purchases, cancels, expirations and recovery returns.
• Transaction locks, idempotency records, optimistic state transitions and payout retry queue.
• SQL storage with auctions, transactions, bids, mailbox, logs, notifications and payouts.
• Twenty-four YAML menus covering market, creation, confirmations, history, statistics and admin panels.
• YAML fees, currencies, limits, categories, item rules, webhooks, messages and network settings.
• Admin integrity, cleanup, logs, suspicious transaction, performance, player view and migration commands.

Dependencies#

• Java 25 and Paper or Purpur 1.21.x-26.1.x.
• Vault and an economy plugin recommended for money currency.
• PlaceholderAPI, PlayerPoints, Discord webhook and custom item plugins are optional.
• MySQL/MariaDB and Redis are recommended for network mode testing.

Listing types#

• BIN: fixed-price purchase flow.
• Normal bid: competitive bidding and settlement path.
• Bulk BIN: amount-aware fixed-price selling for stacked items.

Input parsers#

• Price shorthand: 1k, 2.5m, 1b, 1t.
• Duration input: seconds, minutes, hours, days and weeks.
• Command shortcuts for fast BIN and explicit auction type creation.

Item snapshot#

• Material and amount.
• Display name and lore.
• Custom model data.
• Serialized item payload and hash metadata.

State model#

• Listed listings are visible to players.
• Purchase and bid pending states isolate in-progress operations.
• Sold, cancelled and expired flows route items or payouts to the correct owner.

Category matching#

Categories can be matched from item data and used by browsing, limits, fee rules and search filters.

API validation#

Lifecycle events let external plugins cancel or react before final item and money movement happens.

Idempotency#

Transaction idempotency records reduce the chance of duplicate processing when commands, menu clicks or network retries overlap.

Locks#

Transaction and auction locks guard purchase, bid, cancel, expire and claim flows. Redis lock helpers can be used in network mode.

Optimistic state#

Listings must move from the expected current state into the next state. Invalid movement is rejected instead of silently overwriting state.

Mailbox#

Purchases, cancellations, expirations and recovery returns can move through mailbox records that are claimed with /ah claim.

Payout retry#

Seller deposits that cannot be completed immediately can be queued and retried when the economy provider is available again.

Integrity scanner#

Admin integrity checks surface pending auctions and stale transactions before they turn into unresolved support cases.

Main market#

• Open from /ah.
• Browse active auctions.
• Open create, search, history and personal auction pages.

Create flow#

• Hold item.
• Choose command or GUI path.
• Validate price, duration, currency, limits and item rules.
• Charge listing fee after final approval.

Purchase flow#

• Open detail page.
• Confirm expensive purchases where configured.
• Move item to buyer mailbox and payout/tax to seller path.

Bid flow#

• Place bid on normal auctions.
• Record bid history.
• Settle winning bid on expiration.

History#

• My listings.
• My bids.
• Purchases.
• Sold items.
• Expired items.
• Transaction history.

Claiming#

/ah claim is the player recovery path for purchased, returned, expired and staff-recovered items.

Player cancellation#

1. Open /ah profile and choose My Listings.
2. Click the listing item to open the cancellation confirmation menu.
3. Review the item and remaining amount, then select Confirm Cancellation.
4. The item is queued through the seller mailbox and can be claimed with /ah claim.

Admin delist#

• /ahadmin cancel <auctionId> safely force-cancels an active listing.
• /ahadmin delete <auctionId> <reason> records a moderation reason.
• Both operations preserve the listing snapshot and route the remaining item to the seller.
• Use recovery tools for already-pending or historical records instead of bypassing transaction state.

Refund delivery#

• Online players may receive the item immediately when inventory space is available.
• Offline players, full inventories and delivery retries remain in the mailbox.
• Delivery records are idempotent per auction removal.
• The listing is not treated as fully removed until a durable delivery record exists.

Health checks#

• /ahadmin menu
• /ahadmin hooks
• /ahadmin storage
• /ahadmin network
• /ahadmin performance

Investigation#

• /ahadmin logs [limit]
• /ahadmin suspicious [limit]
• /ahadmin view <player|uuid>
• /ahadmin integrity

Intervention#

• /ahadmin cancel <auctionId>
• /ahadmin delete <auctionId> <reason>
• /ahadmin recover <auctionId> <player>
• /ahadmin cleanup

Export#

/ahadmin logs export <csv|json> gives staff a review artifact for chargebacks, duping reports and support tickets.

Migration#

Scan, preview and start commands are separated so data can be inspected before any import writes NexaAuctions listings.

Admin menus#

Admin overview, logs, suspicious, recovery, player listings, network and performance menus give visual staff entry points.

Setup checklist#

1. Set a real LicenseGate key.
2. Choose SQLite for single server or MySQL/MariaDB for network mode.
3. Install Vault and confirm the default currency is available.
4. Tune fees, limits and blocked item rules.
5. Open the main menu, create a test listing, buy it and claim the item.
6. Run admin integrity and storage checks.

Production notes#

• Give permissions through LuckPerms or your permission manager.
• Back up YAML files and SQL databases before updates.
• Use a staging server before enabling Redis/network mode.
• Do not advertise full Folia support until the exact stack is region-thread tested.

How to edit messages#

Edit the generated messages.yml in the plugin folder, preserve keys and placeholders, then run /ahadmin reload or restart for startup-level changes.

Formatting#

<green>Listed <white><item></white></green>
<gradient:#22d3ee:#a855f7>NexaAuctions</gradient>
&cLegacy color fallback

Main#

Main player market menu.

• Title: NexaAuctions | Market
• Size: 54
• Actions: browse, sell, search, my auctions, history, close

Create Auction#

Listing creation preview and command handoff menu.

• Title: NexaAuctions | Create
• Size: 54
• Focus: item slot and back action

Auction Action#

Shared view and buy entry for a listed auction.

• Title: NexaAuctions | Auction
• Size: 45
• Actions: confirm purchase for BIN, bid hint for auctions, back

Confirm Purchase / Bid / Cancel#

Safety screens before purchase, bid or listing removal.

• Purchase and bid: configurable confirmation menus
• Cancel: runtime five-row confirmation menu from My Listings
• Purpose: avoid accidental money movement or item removal

Player History#

Player-oriented lists for bids, listings, purchases, sold and expired items.

• Menus: my-listings, my-bids, purchases, sold-items, expired-items
• Size: 54

Admin Menus#

Operator menus for overview, logs, suspicious transactions, recovery, network and performance.

• Admin overview size: 54
• Network/performance size: 45

Text search#

Free text can match item summary, seller name and category id.

/ah search diamond sword
/ah search spawner

Structured filters#

• seller:<name|uuid>
• material:<material>
• category:<id> or cat:<id>
• currency:<id> or cur:<id>
• type:<bin|normal|bulk>

Item filters#

• enchant:<id>
• model:<custom model data>
• custom:<provider item id>
• min:<price>
• max:<price>

Sort modes#

• sort:newest
• sort:oldest
• sort:highest / sort:price_desc
• sort:lowest / sort:price_asc
• sort:ending_soon
• sort:most_bids
• sort:random

Examples#

/ah search seller:Steve sort:newest
/ah search material:DIAMOND_SWORD max:500k
/ah search category:weapons type:normal sort:most_bids
/ah search custom:mythic_blade currency:vault

Menu relationship#

The search command can route into menu views, while category and browse menus keep casual navigation simple for players who do not use filters.

Currency providers#

• Vault provider
• PlayerPoints provider
• YAML fallback provider
• Unavailable placeholders for several economy plugins

Fee types#

• Listing fee
• Sale tax
• Purchase tax
• Bid fee
• Cancel fee
• Duration fee
• Range/category/currency tax

Payout handling#

Seller payouts that cannot be deposited immediately can be queued and retried. This protects offline or temporarily unavailable economy flows.

Runtime guards#

• TPS guard
• Ping guard
• Create cooldown
• Transaction timeout
• Ghost cleanup

Player limits#

• Active auction limit
• Active bid limit
• Min/max price
• Min/max duration
• Per-category active limit

Item rules#

• Blacklist mode
• Shulker content inspection
• Blocked bedrock and command blocks
• Name/lore/enchant/PDC match support

Storage recommendation#

Use SQLite with WAL for a small single server. Use MySQL or MariaDB before enabling network mode, Redis locks or multi-server cache invalidation.

Backup checklist#

• Stop the server before copying live SQLite files.
• Export SQL databases before updates.
• Keep plugin, server and schema version in backup notes.
• Test migration on a copy first.

Redis heartbeat#

Publishes server heartbeat data so admins can inspect known network members.

Cache invalidation#

Publishes listing changes so other servers can invalidate cached auction views.

Distributed locks#

Claim and expiration guards can use Redis lock helpers with token-based release.

Global placeholders#

%nexaauctions_active_listings%
%nexaauctions_total_listings%
%nexaauctions_transactions%
%nexaauctions_storage%
%nexaauctions_network_mode%

Player placeholders#

%nexaauctions_player_active%
%nexaauctions_player_sold%
%nexaauctions_player_bought%

Example scoreboard lines#

<gray>Market: <white>%nexaauctions_active_listings% active
<gray>Sold: <green>%nexaauctions_player_sold%
<gray>Bought: <aqua>%nexaauctions_player_bought%

Operational use#

Show %nexaauctions_storage% and %nexaauctions_network_mode% only to staff or debug panels. Player-facing boards usually only need active listings and personal stats.

Migration sources#

zAuctionHouse, AuctionMaster, DeluxeAuctions, CrazyAuctions, ExcellentAuction, JSON, SQL and CSV providers are registered as migration surfaces.

Recovery flow#

Admin delete and recover commands can move item data into a player's mailbox, then the player claims it with /ah claim.

Audit flow#

Logs, suspicious reports, player views, performance status and integrity scans help staff investigate support cases.

Public API#

• Create, purchase, bid, cancel and claim methods.
• Auction query and immutable view models.
• Economy provider registry access.
• Custom item resolver registration.

Events#

• AuctionCreateEvent
• AuctionCancelEvent
• AuctionPurchaseEvent
• AuctionBidEvent
• AuctionExpireEvent
• AuctionClaimEvent
• AuctionRecoverEvent
• AuctionPriceCalculateEvent
• AuctionItemValidateEvent
• AuctionPreviewEvent

SMP Economy Setup#

Use SQLite, Vault currency, conservative fees, default limits and clear item blacklist rules for community survival servers.

Prison Marketplace Setup#

Use higher listing limits for rank groups, PlayerPoints currency if needed and strict suspicious price thresholds.

Network Auction Setup#

Use MySQL/MariaDB, Redis cache invalidation, unique server ids and staged duplicate purchase/claim testing.

Automated tests#

• Plugin bootstrap with MockBukkit.
• Command registration and basic command behavior.
• Listing creation with a mocked economy path.
• Blocked item rule behavior.
• Cancelled create event fee/item safety.
• SQL schema migrator behavior.

Manual player flow#

1. Create a BIN listing.
2. Open My Listings and cancel a test listing from the confirmation menu.
3. Claim the returned mailbox item.
4. Purchase another listing with a second player.
5. Create a bid auction and place a bid.
6. Open listings, bids, purchases, sold, expired and history views.
7. Search by seller, material, category and price.

Manual admin flow#

1. Run license, hooks, storage and network checks.
2. Inspect logs and suspicious output.
3. Run integrity check.
4. Delete and recover a test listing.
5. Export logs in CSV or JSON.
6. Test reload after editing menus and messages.

Network staging#

Before enabling network mode on production, run two test servers against the same MySQL/MariaDB database and Redis instance. Test duplicate purchase, duplicate claim, expiration and cache invalidation behavior.

Economy staging#

Test with the same Vault economy or PlayerPoints version used on production. Verify failed payout retry behavior by temporarily disabling the provider on a staging server.

Menu QA#

Open every menu file, verify titles fit, check invalid materials in console, confirm all command/open/sound actions work and capture the showcase screenshots after the final layout is stable.

Send this with reports#

• Plugin version and server software/version.
• First console error, not only repeated follow-up lines.
• Edited YAML files or a config diff.
• Exact command, player permissions and reproduction steps.

Useful admin commands#

/ahadmin menu
/ahadmin hooks
/ahadmin storage
/ahadmin network
/ahadmin integrity
/ahadmin logs 20
/ahadmin suspicious 20