MCTrade

Item-to-Item Trading Market

MCTrade is a commercial, asynchronous item-to-item trading market for Minecraft servers, supporting the SpigotMC, PaperMC, and FoliaMC platforms. Players list an item they are giving away and the item they want in return; anyone can fulfil the offer through a chest GUI, with the proceeds held safely in a secure vault until the merchant claims them.

Commercial Software

MCTrade is published by MCHaagenti and is distributed for commercial sale. See the LICENSE file distributed with MCTrade for terms.

Note: In the future I might add some features that only the paid tier can use, but the core system features will be free to use. For example, AI integration like making the AI "find a merchant who offers {item name} that I can exchange with {item name}".

How it works

A trade is a one-for-the-other exchange:

Merchant offers N × Item A, and needs M × Item B in return.

Listing. A merchant runs /trade create and chooses both trade items from the whitelist — Choose Item to Offer and Choose Item to Receive each open a category, then that category's item page. The amount for each side is set to any quantity by left/right-clicking its display (±1, or ±10 with shift). Clicking Confirm takes the full offer amount from the merchant's inventory and lists the offer — if they do not actually hold that many, it reports an insufficient amount and nothing is taken. Both amounts can be any number.
Browsing. Anyone runs /trade to open the market — a paginated chest GUI of all active global offers, one offer per row (four offers per page). Each row reads left to right as four columns:
- Offered item — the item the merchant gives; hover to see the amount.
- Needed item — the item you pay; hover to see the amount.
- Merchant head — the head of the player who created the offer.
- Trade button — click it to accept the trade.
The top row carries filter and sort controls so you can focus the view:
- Filter by Offered Item (slot 0) and Filter by Requested Item (slot 1) — click to choose a specific item (category, then item, from the whitelist); the market then shows only the offers that give (or want) that exact item. Right-click the control to clear that filter. The two filters combine, so you can narrow to offers giving item A and asking for item B.
- Sort: Highest Requested (slot 7) and Sort: Lowest Requested (slot 8) — order the offers by the requested ("need") quantity, highest or lowest first. Clicking the active sort again clears it back to the default most-recent order.
Filters persist as you page through the market and after completing a trade, so the chosen items and sort stay applied.
Affordability at a glance. The trade button is coloured from the viewer's perspective:
- 🟩 Green — you hold the required "need" items; click to accept.
- 🟨 Yellow — this is your own offer (you cannot trade with yourself).
- 🟥 Red — you are missing the required items (the offer is still visible).
Accepting. Clicking a green trade button re-checks your inventory, atomically claims the offer (so it can never be sold twice), removes your "need" items, and gives you the offered items.
Vault. The "need" items are never dropped or force-added to the merchant's inventory. They are deposited into the merchant's secure vault (persisted in the database), and the merchant claims them at their leisure with /trade vault, withdrawing as much as their inventory can hold at a time. Online merchants are told a sale landed in their vault; offline merchants are reminded the next time they join. Nothing is ever lost to a full inventory, a restart, an item-clearing plugin, or theft.

Item whitelist

Only items whose base type is on the trade item whitelist may be offered or requested. The whitelist lives in the trade_item_whitelist table, where the Base64 base item is the primary key and each row carries a category (quantities are never part of the whitelist). Storing the item as the key means checking whether something is tradeable is a single key lookup rather than a scan.

The whitelist is grouped into categories (configured under whitelist.categories in config.yml). Both browsing and administration start by choosing a category; items are then shown most-recently-added first, paginated across as many pages as needed. Administrators manage the whitelist in-game via /trade admin:

Choose a category — the first screen lists every configured category and how many items it holds; click one to open its editor.
Add — inside a category, hold an item on your cursor and click the green Add Item button; it is whitelisted under that category.
Remove — left-click any whitelisted item.
Navigate — Back is slot 45 (returns to the category list), Previous Page is slot 48 (hidden on the first page), and Next Page is slot 50 (hidden on the last page), in a 54-slot chest.

Commands

/trade — open the market of all active offers. Permission mctrade.trade (default: all players).
/trade create — open the creation menu to list a new offer. Permission mctrade.trade (default: all players).
/trade vault — open your secure vault to claim trade proceeds. Permission mctrade.trade (default: all players).
/trade admin — open the whitelist editor. Permission mctrade.admin (default: operators).

All actions are driven through chest GUIs, so the commands must be run by a player.

Permissions

mctrade.trade (default: true) — grants opening the market and creating offers.
mctrade.admin (default: op) — grants editing the trade item whitelist.

Architecture

MCTrade follows the MCHaagenti sub-module architecture; the storage core is pure Java and never touches the Bukkit API, and all storage operations are asynchronous and return a CompletableFuture.

api — interfaces and immutable models only (ITradeDatabase, TradeOffer, WhitelistEntry, VaultItem).
common — storage implementations: a shared AbstractSqlTradeDatabase plus the SQLite, MySQL, and PostgreSQL backends, a native MongoDB backend, and the MCTradeProvider entry point.
bukkit — SpigotMC-API-only core: the chest GUIs, the TradeService orchestrator, item Base64 (de)serialization and inventory helpers, the whitelist/offer/vault flows, the /trade command, listeners, the cancellable TradeCreateEvent, and a SyncExecutor scheduling abstraction.
platforms — thin entry points per platform:
- spigotmc, papermc — use the regular server scheduler.
- foliamc — uses a region/entity-aware scheduler so all Bukkit access respects Folia's threading model.

Thread-safety

Database work runs off the server thread. Any result that touches the Bukkit API is scheduled back through a platform-specific SyncExecutor — the main thread on SpigotMC/PaperMC, or the owning region/entity thread on FoliaMC — so inventory mutations always happen on a thread that may legally perform them. Concurrent accepts of the same offer are made safe by an atomic claim (claimOffer): only the caller that actually deletes the row proceeds, preventing a double-spend.

Database

The storage backend is selected via database.type in config.yml. Supported values are sqlite (default, zero-configuration), mysql, postgresql, and mongodb. For SQLite, the database file name is set under database.sqlite.file (default mctrade.db). The JDBC drivers and the MongoDB driver are declared as libraries in plugin.yml and downloaded by the server at runtime, so no shading of drivers is required.

Three tables (or collections) are created automatically on first start: trade_item_whitelist, trade_offers, and trade_vaults.

Building

This project uses Gradle with the Java 25 toolchain; building the project with the shadowJar task produces a shaded plugin jar per platform (MCTradeSpigotMC, MCTradePaperMC, MCTradeFoliaMC).

Getting started

Build the plugin (or drop the jar for your platform into plugins/).
Start the server once to generate plugins/MCTrade/config.yml, then set enable: true (and pick a database.type if not using SQLite).
As an operator, run /trade admin and whitelist the items you want to be tradeable.
Players can now run /trade create to list offers and /trade to browse and accept them.