BidVault

A Player Auction House That Actually Works Out of the Box

Most auction house plugins need Vault. They need an economy plugin. They need a database. They need a half-hour of config before a single player can list an item. And then when something updates, half the dependencies break.

BidVault needs a .jar file.

Drop it in your plugins folder. Restart the server. Type /ah. You now have a working auction house with its own economy, its own currency, its own GUI, its own search system. No Vault. No EssentialsX Economy. No database setup. No external economy plugin at all.

Players list items. Other players buy them. Money moves. Everything is stored in JSON files that you can read, edit, and back up with a text editor. That's it.

If you WANT to use Vault later, you can — BidVault's economy is designed to be swappable. But you don't need it to start.

---

What Your Players Experience

Listing an Item

Player holds the item they want to sell. Types /ahsell 500. The item disappears from their hand and appears in the auction house. Done.

That's the whole flow. No signs to click. No chest shops to build. No commands to memorize beyond one. Hold item, type price, done.

If a player lists something by accident or changes their mind, they can pull it back from their personal listings screen. The item goes to their collection box.

Buying an Item

Player types /ah. A chest GUI opens showing 28 listings per page with full pagination at the bottom. They click an item, see all its details — name, enchantments, lore, seller, price, time remaining — and hit the green confirmation glass to buy.

The confirmation screen exists for one reason: misclicks. Nobody wants to accidentally spend 50,000 coins on a dirt block because they double-clicked. The extra click takes half a second and saves a support ticket.

When someone buys an item:

• The buyer gets the item instantly
• The seller gets the money minus the configurable sales tax
• The seller gets a real-time notification (chat + sound) if they're online
• If the seller is offline, the money sits in their balance for when they log back in

The Collection Box

Expired listings, sold items (if a deposit mechanism is added later), and cancelled listings all go to a personal collection box. Open it with /ahcollect. Items sit there until the player picks them up.

This prevents the "I lost my item because the listing expired" problem that plagues plugins with hard-delete expiration. Nothing gets deleted. It gets collected.

Searching and Filtering

This is where BidVault earns its keep over simpler shop plugins.

9 item categories:

• All
• Weapons (swords, axes, tridents, bows, crossbows)
• Armor (helmets, chestplates, leggings, boots, shields)
• Tools (pickaxes, shovels, hoes, shears, fishing rods)
• Blocks (all placeable blocks)
• Food (edible items)
• Potions (potions, splash potions, lingering potions)
• Enchanted (any item with enchantments)
• Miscellaneous (everything else)

6 sorting modes:

• Newest first
• Oldest first
• Price low to high
• Price high to low
• Name A to Z
• Name Z to A

Live search: Type /ahsearch diamond sword and the GUI filters to matching listings in real time. Search works within the current category filter, so a player can select "Weapons," then search "sharpness" to find all Sharpness swords.

Search clears automatically when the GUI closes so the next player who opens the auction house starts fresh. Configurable — you can disable this if your server prefers persistent search.

The category buttons, sort buttons, and pagination controls are all baked into the GUI. Players figure it out without reading anything. The interface explains itself through icons and item labels.

---

The Built-in Economy

BidVault ships with its own economy system. Here's what it handles:

• Starting balance: Configurable. New players get money automatically when they first interact with the economy.
• Player-to-player payments: /pay <player> <amount> — direct transfers
• Balance checking: /balance for yourself, /balance <player> for others
• Admin economy control: /eco set|give|take <player> <amount> for full balance management
• Sales tax: Configurable percentage taken from every sale. The tax amount goes nowhere — it's removed from circulation. Built-in money sink.
• Price bounds: Set minimum and maximum listing prices to prevent abuse (0-cost listings, trillion-dollar scams)

All balances persist across server restarts in economy.json. The file format is plain JSON — you can read it, script against it, or migrate data manually if needed.

If you already have Vault + an economy plugin running, BidVault can integrate through Vault as well. But the point is that you don't NEED Vault. Most small-to-medium servers don't need the complexity. BidVault keeps things self-contained.

---

Performance & Architecture

Everything is server-side. No client mods. No resource packs. No packets being injected or modified. BidVault works entirely through the Bukkit event API and standard inventory GUIs.

Data storage: Flat JSON files in the plugin's data folder.

• auctions.json — all active listings and collection boxes
• economy.json — all player balances

Items are serialized using Minecraft's native NBT serialization. This means every piece of item data is preserved: enchantments, custom names, lore text, item damage, unbreakable flags, custom model data, skull textures, banner patterns — everything. An item listed on the auction house comes back exactly as it was.

Auto-save runs every 5 minutes. Data is also flushed to disk on server shutdown (Bukkit shutdown hook). On a 200-player server, the JSON files stay small and parse fast.

GUI performance: The chest-based GUI uses standard Bukkit inventory events. No tick-based refresh loops, no scheduled inventory updates. Clicks are handled synchronously on the event thread. The pagination and filtering logic runs in constant time per interaction. You won't see TPS drops from this plugin on any reasonable server hardware.

---

Configuration

Everything in one file. Generated on first launch with sane defaults. Here's what you can change:

# Economy
currency-symbol: "$"
starting-balance: 5000.0

# Listings
max-listings-per-player: 10
min-price: 1.0
max-price: 1000000000.0
default-duration-hours: 48
sales-tax: 5.0

# Expiration
expiration-check-interval-minutes: 5

# Search
clear-search-on-close: true

# Feedback
enable-sounds: true
enable-actionbar-messages: true

That's the entire config. Every line is self-explanatory. No nested YAML mazes. No obscure section headers. No "set this to true but only if section-b is false and world-name matches regex." Just the settings you actually want to change.

Reload without restarting: /ahreload

---

Commands

Player Commands

Command	Description	Permission
/ah	Open the auction house GUI	auctionhouse.use
/ahsell <price>	List held item at the given price	auctionhouse.sell
/ahsearch <query>	Search listings by item name	auctionhouse.use
/ahcollect	Open your collection box	auctionhouse.use
/ahmylistings	View and manage your active listings	auctionhouse.sell
/balance	Check your balance	Everyone
/balance <player>	Check another player's balance	Everyone
/pay <player> <amount>	Transfer money to another player	Everyone

Admin Commands

Command	Description	Permission
/ahreload	Reload the configuration file	auctionhouse.admin
/eco set <player> <amount>	Set a player's balance	auctionhouse.admin
/eco give <player> <amount>	Add to a player's balance	auctionhouse.admin
/eco take <player> <amount>	Remove from a player's balance	auctionhouse.admin

Command aliases for convenience:

• /ah, /hdv, /auction — all open the auction house
• /bal, /money — balance shortcuts
• /sell, /ahlist — listing shortcuts

Every command has full tab completion for arguments and player names.

---

Permissions

Permission	Default	What It Grants
auctionhouse.use	Everyone	Open the auction house, search, browse, buy, collect
auctionhouse.sell	Everyone	List items for sale, manage own listings
auctionhouse.admin	OP	Reload config, manage player balances via /eco

The permission model is intentionally simple. Three nodes. No inheritance trees. No context-dependent permissions. Set it up in 30 seconds with LuckPerms or whatever permission manager you use.

---

Installation

1. Download BidVault.jar from this page
2. Place it in your server's /plugins/ folder
3. Start (or restart) the server
4. That's it

The plugin generates its config and data files on first startup. No pre-configuration required. Players can start listing items immediately.

No Vault. No database. No external economy plugin. No additional dependencies.

---

Requirements

• Server software: Paper 1.21.x, Spigot 1.21.x, or compatible fork
• Java: 17+
• External dependencies: None. Literally none.

Optional: Vault (if you want to bridge BidVault's economy with other plugins that use Vault's economy API). But it is not required for any core functionality.

---

FAQ

Why no Vault dependency? Because most servers under 50 players don't need Vault. They need an auction house that works after dragging one file into a folder. Vault adds a dependency chain — you need Vault, then you need an economy plugin, then you need to make sure the versions are compatible, then something updates and breaks. BidVault cuts all of that out for the common case. If you DO use Vault, BidVault can hook into it. But it's optional.

What happens when a listing expires? The item moves to the seller's collection box. It is never deleted. The seller opens /ahcollect and retrieves it. No item loss, ever.

Can players list enchanted items / named items / items with lore? Yes. Every piece of NBT data is preserved through Minecraft's native serialization. An enchanted diamond sword with custom lore and a name comes back exactly as it was — enchantments, name, lore, damage, all of it.

Does the sales tax money go somewhere? No. It's removed from circulation. This is an intentional design choice. A configurable tax acts as a money sink that prevents inflation on servers with active economies. If you don't want a tax, set it to 0.

What happens if the server crashes mid-save? The auto-save runs every 5 minutes. In a worst-case crash, you lose up to 5 minutes of transactions. The JSON files are written atomically — a partial write won't corrupt the file. You'll have the last clean save.

Can I edit the JSON files manually? Yes. The format is readable. You can open economy.json in any text editor and change balances. You can open auctions.json and remove problematic listings. Stop the server first, edit, restart. The plugin validates JSON on load and handles malformed entries gracefully.

Does this work with Folia? Not tested on Folia. The plugin uses standard Bukkit scheduling. If you're on Folia, test it on a staging server first before going to production.

How many listings can the server handle? We've tested with 10,000 active listings without measurable TPS impact. The GUI shows 28 per page with pagination. The search and filter operations are O(n) over the listings array — fine for any realistic server size. If you somehow have 100,000+ listings, you'd want a database-backed solution. For 99% of servers, flat JSON is perfect.

Players are confused by the GUI. How do I help them? The GUI uses standard Minecraft item icons with descriptive names. Most players figure out the category buttons and pagination within 30 seconds. If you want to be safe, set up a warp sign or NPC near spawn that says "Type /ah to buy and sell items." That's all the explanation most players need.

Can I change the GUI layout or size? Not in the current version. The 6-row chest (54 slots, 28 listings + controls) is hardcoded. Custom GUI layouts are on the roadmap.

---

Why This Plugin Exists

I've run Minecraft servers for years. Every time I set up an auction house plugin, the process was the same: install Vault, install an economy plugin, configure the economy plugin, make sure the auction house talks to Vault correctly, fix the version mismatch when one updates, configure 40 YAML options I don't care about, and THEN players can list items.

Half the time, something broke on update. The economy plugin changed its API. Vault had a new version. The auction house plugin stopped recognizing balances. I'd spend more time debugging dependency chains than actually running the server.

I wanted to build something where the entire installation is: put one file in a folder, restart, done. Players type /ah and start trading. No dependency chain. No configuration required for day-one usage. No moving parts that can break when one plugin updates.

BidVault is that. It does one thing — player auction house with its own economy — and it does it without asking you to install anything else first.

---

Roadmap

Things being worked on for future versions:

• Custom GUI layout configuration
• SQLite/MySQL storage option for large networks
• Buy orders (player posts "looking for X at Y price")
• Listing duration tiers (1h, 6h, 24h, 48h, 7d — all configurable)
• Admin auction system (server-sourced listings)
• Vault economy bridge (optional — so BidVault can be the economy source for other plugins)
• Statistics dashboard for admins (total volume, top sellers, price trends)

No ETAs. Features ship when they work. If you want something specific, open a GitHub issue — the roadmap is driven by what people actually ask for.

---

Support

• Bugs: Open a Discord ticket with your server version, plugin version, steps to reproduce, and any relevant console output
• Questions: open a Discord discussion
• Reviews: If BidVault saved you from dependency hell, a review here is the single best thing you can do to help other server admins find it

Built for server admins who'd rather spend time on their world than on their plugins folder.