Let's Get Started!

Before using the plugin: Make sure you have Menu Blur disabled in your game video settings (NeoForge/Fabric clients only).

EasyTrading is a lightweight economy plugin for Paper, Bukkit, Spigot, Folia servers. It introduces a virtual currency, a player-to-player marketplace, a server-side bank with dynamic pricing, direct money transfers, and a full GUI-based item trade system.

1. Core Concepts

Currency. Every player has a single balance stored on the server. It is a whole number (no decimal places). The currency has no official name by default — the Vault integration calls it "coins."

Starting balance. New players begin with 0. The primary way to earn money early on is selling resources to the bank via /market sellto.

Persistence. Balances survive restarts. Data is auto-saved every 5 minutes and also saved on clean plugin shutdown.

2. Balance & HUD

Your balance is always visible as a yellow BossBar at the top of the screen, updated every 3 seconds in real time.

Command	Effect
`/market balance`	Print your balance in chat
`/market hide`	Hide the BossBar
`/market show`	Show the BossBar again
`/market team [name]`	Show the combined balance of your scoreboard team (or any named team for admins)

The HUD preference (hidden/visible) is session-based — it resets when you reconnect.

3. Market — Player-to-Player Trading

The market is a shared board where any player can list items for sale and any other player can buy them.

Opening the Market

/market

Opens a 6-row chest GUI. The top 5 rows (45 slots) display all active listings. The bottom row is the navigation bar:

Slot	Item	Function
1	Arrow (left)	Previous page
2	Hopper	Toggle sort order
3	Player head	Show only your listings
4	Barrier	Clear active filters
5	Paper	Current page / total listings
6	Compass	Filter by item name
7	Name tag	Filter by seller name
8	Gold Ingot	View bank exchange rates
9	Arrow (right)	Next page

Each page shows up to 45 listings. Item tooltips display the price, average price per unit, and the seller's name.

Sorting

Click the hopper (slot 2 of the nav row) to cycle through sort modes:

Newest first (default)
Cheapest first
Most expensive first
Oldest first

Filtering

By seller — in GUI: Click the name tag slot in the nav row, then type a seller's name in chat. Type clear to remove the filter, or cancel to abort without changing anything.

By item — in GUI: Click the compass slot, then type any part of the item name in chat. Type clear to remove the filter.

Via commands:

/market my                    — show only your own listings (sorted newest first)
/market seller <player>       — filter by a specific seller's name (partial names accepted if unambiguous)
/market search <item name>    — filter by item name keyword

Listing an Item for Sale

/market sell <price>

Hold the item you want to sell in your main hand.
Run the command, e.g. /market sell 500.
A 3-row confirmation screen appears showing the item, price, and listing fee.
Click the green pane (slot 12) to confirm, or the red pane (slot 16) to cancel.
On confirmation, the item is removed from your hand and the fee is deducted from your balance. The listing goes live immediately.

Price limits: The price must be between the server-configured minimum (default: 10) and maximum (default: 5,000,000). The exact range is enforced at submission time.

Listing fee structure:

The first 2 listings (free slots) incur only a base fee calculated as a percentage of the listing price.
Listings beyond the free slots but within the soft cap (default: 8) use the base fee percentage.
Listings beyond the soft cap (up to the hard cap, default: 28) add a progressive surcharge on top of the base fee.
The fee is always clamped between a minimum and maximum coin value (defaults: 1 and 250,000).
If you do not have enough balance to cover the fee, the listing is rejected.

Bank resource restriction: Items that can be traded at the bank (coal, iron, gold, etc.) cannot be listed on the player market. The plugin will reject the command and tell you to use /market sellto instead.

Confirmation timeout: If you do not respond to the confirmation screen within 5 minutes, the pending sale is automatically cancelled and the item stays in your inventory.

Buying an Item

Simply click on any listing in the market GUI. A confirmation screen will appear showing the item details, the seller, and the total cost. Confirm with the green pane.

If you do not have enough balance, or if your inventory is full, the purchase is rejected and the listing is returned to the market untouched.

If the seller is online at the time of purchase, they receive an in-game notification and the money is credited to their balance immediately.

Buying your own listing: Clicking on your own listing triggers a different flow — the item is returned to your inventory instead of a purchase being made.

Managing Your Listings

View your listings:

/market my

Relist (refresh timestamp or change price):

/market relist <listingId> [newPrice]

If newPrice is omitted, the listing is refreshed at the same price (moves it to "newest" in the sort).
You can only relist your own listings.
Tab-complete suggests your active listing IDs.

Cancel all your listings at once:

/market cancelall

All your listings are removed and all items are returned to your inventory (or dropped at your feet if your inventory is full).

Individual listing cancellation is not currently available via command — ask an admin or use /market cancelall.

4. Bank — Server Shop

The bank is a built-in server shop that buys and sells a fixed set of resources at prices that change dynamically based on supply and demand (see Section 11 for details).

Supported Resources

Display Name	Command Alias
Coal	`coal`
Redstone	`redstone`
Lapis Lazuli	`lapis`
Copper Ingot	`copper`
Iron Ingot	`iron`
Gold Ingot	`gold`
Diamond	`diamond`
Emerald	`emerald`
Netherite Ingot	`netherite`

Selling to the Bank

/market sellto <amount>

Hold the resource in your main hand.
Run the command, e.g. /market sellto 64.
A confirmation screen shows how many will be accepted, the price per unit (after tax deduction), and the total payout.
Confirm with the green pane.

Automatic adjustment: If you request more than you hold, or more than your remaining daily limit, the amount is silently reduced to the maximum possible. You will see the adjusted quantity on the confirmation screen before committing.

Tax: The sell price shown is already net of tax. If the base price for iron is 100, and the tax is 12%, you receive floor(100 × 0.88) = 88 per unit.

Daily sell limit: Each resource has a per-player daily sell limit. Once reached, the command is rejected with an error. Limits reset at midnight (server time).

Buying from the Bank

/market buyfrom <resource> <amount>

Examples:

/market buyfrom diamond 10
/market buyfrom iron 32
/market buyfrom netherite 1

A confirmation screen shows the price per unit (with tax added on top), the total amount that will be issued, and the total cost.

Automatic adjustment: If your inventory cannot fit the full requested amount, the accepted quantity is reduced to what fits. If you cannot afford the full amount, it is reduced to what you can buy.

Tax on purchases: The buy price is the base price with tax added. If the base price is 100 and the tax is 12%, you pay ceil(100 × 1.12) = 112 per unit.

Daily buy limit: There is also a daily limit on how much you can buy per resource. The buy limit is configurable independently of the sell limit (via buy_limit_multiplier).

Inventory safety: If your inventory is completely full when a purchase is confirmed, the plugin will reject the transaction rather than losing items.

Viewing Bank Rates

Open the market (/market) and click the gold ingot in the navigation row. It displays the current tax percentage and the buy/sell price for every available resource.

Viewing Your Daily Limits

/market limits

Shows how many units of each resource you have sold and bought today, and how much of each limit remains.

5. Direct Item Trades

EasyTrading includes a full GUI-based item trade system for direct exchanges between two online players.

Initiating a Trade

/market trade <playerName>

The target player receives a clickable chat message with [Accept] and [Decline] buttons.
Trade requests expire after 60 seconds if not responded to. The sender receives a notification when this happens.
You cannot trade with yourself, and neither player can be already in an active trade.

Auto-accept: If both players send a trade request to each other before either accepts, the trade opens automatically.

Accepting / Declining

/market trade accept
/market trade decline

Or click the buttons in the chat message.

The Trade GUI

When a trade starts, both players see the same 6-row chest inventory titled Trade: Player1 ↔ Player2.

Layout:

Row 1-4:  [ P1 items: 16 slots ] | separator | [ P2 items: 16 slots ]
Row 5:    [ P1 money info ] [+10] [-10] | sep | [-10] [+10] [ P2 money info ]
Row 6:    [P1 Confirm] [P1 Cancel] ... [Status] ... [P2 Cancel] [P2 Confirm]

Each player can only interact with their own side (left side for Player 1, right side for Player 2). Clicking the opponent's slots, separator slots, or other control slots is blocked.

Offering items: Drag items from your inventory into your offer slots (left or right, depending on which player you are). You can pick items back up from your own offer slots.

Offering money: Click the +10 or -10 buttons to adjust your money offer in increments of 10. The money is taken from your balance — you cannot offer more than you currently have.

Confirming: Click your Confirm button. The status indicator in the center updates to show who has confirmed. If both players confirm, a short countdown begins. If either player changes their items or money offer after confirming, both confirmations are reset and must be redone.

Cancelling: Click your Cancel button at any time. All items placed in the trade are immediately returned to their owners.

What is exchanged: When both players confirm and the countdown completes, Player 1's offered items go to Player 2, Player 2's offered items go to Player 1, and the offered money amounts are transferred between them net. If either player lacks sufficient funds at the moment of completion, the trade is cancelled and items are returned.

Disconnection / Death: If either player disconnects or dies during a trade, the trade is cancelled and all items are returned.

Trade History

Completed trades are recorded in each player's transaction history with the counterpart's name, item counts, and net money change.

6. Money Transfers

/market send <player> <amount>

Example: /market send Steve 500

Rules:

The recipient must be online.
You cannot send money to yourself.
You must have sufficient balance.
Both players receive a chat notification confirming the transfer.
The transfer is logged server-side to plugins/EasyTrading/logs/easytrading-transfers.log with timestamps, player names, and UUIDs.
Both players' transaction histories are updated.

7. Transaction History

/market history

Shows your last 10 transactions in chat. The plugin stores up to 100 entries per player.

Recorded transaction types:

Type	Description
`BUY`	You purchased something from the player market
`SELL_INCOME`	Someone bought your market listing
`SEND`	Money transfer sent or received
`BANK_BUY`	You bought from the bank
`BANK_SELL`	You sold to the bank
`FEE`	Market listing fee deducted
`TRADE`	Completed direct player trade

Each entry shows the date/time (dd.MM HH:mm), item name, quantity, and money amount.

8. Notifications

When you join the server, you may see:

"New items appeared on the market."

This means at least one new item was listed while you were offline. The plugin tracks a market "version number" that increments every time a new listing is added. Your last-seen version is recorded on login, and the message is shown if the current version is higher.

9. All Commands

Player Commands

Command	Description
`/market`	Open the market GUI
`/market help`	Show the command list in chat
`/market my`	Open market filtered to your own listings
`/market seller <player>`	Filter market by a specific seller
`/market search <query>`	Filter market by item name
`/market sell <price>`	List the item in your main hand
`/market relist <id> [price]`	Refresh your listing, optionally changing the price
`/market cancelall`	Remove all your listings and return items
`/market sellto <amount>`	Sell the resource in your hand to the bank
`/market buyfrom <resource> <amount>`	Buy a resource from the bank
`/market trade <player>`	Send a trade request
`/market trade accept`	Accept a pending trade request
`/market trade decline`	Decline a pending trade request
`/market send <player> <amount>`	Send money to an online player
`/market balance`	Show your balance in chat
`/market team [name]`	Show your team's combined balance
`/market history`	Show your last 10 transactions
`/market limits`	Show your remaining daily bank limits
`/market hide`	Hide the balance BossBar
`/market show`	Show the balance BossBar

Admin / OP Commands

These require the easytrading.admin permission (or OP).

Command	Description
`/market bankreload`	Reload bank config from disk without restarting
`/market clearlimits`	Reset all players' daily bank limits
`/market change <percent>`	Set the bank tax percentage (0–100)
`/market add <player> <amount>`	Add coins to a player's balance
`/market take <player> <amount>`	Remove coins from a player's balance
`/market team <name>`	Show the balance of any named team
`/checkbalance <player>`	Check any online player's balance

10. Configuration Files

All config files live in plugins/EasyTrading/. They are auto-created on first run with sensible defaults.

`market-config.json` — Marketplace Settings

Key	Default	Description
`free_listing_slots`	`2`	How many listings per player have no progressive surcharge
`soft_listing_cap`	`8`	Listings beyond this count apply progressive fee
`hard_listing_cap`	`28`	Maximum listings per player (hard block)
`base_fee_percent`	`4`	Base listing fee as % of price
`progressive_fee_percent`	`2`	Extra fee % added per listing beyond the soft cap
`fee_min`	`1`	Minimum listing fee (coins)
`fee_max`	`250000`	Maximum listing fee (coins)
`min_price`	`10`	Minimum allowed listing price
`max_price`	`5000000`	Maximum allowed listing price

The config is hot-reloaded — the plugin checks file modification time and reloads automatically. No restart or /market bankreload needed for market config changes.

`bank-config.json` — Bank Settings

Key	Default	Description
`tax_percent`	`12`	Tax applied to all bank transactions (buy and sell)
`price_elasticity`	`0.60`	How strongly price responds to stock changes
`min_factor`	`0.55`	Minimum price = `base × min_factor`
`max_factor`	`2.10`	Maximum price = `base × max_factor`
`max_step_percent`	`12`	Max price change per rebalance step (% of current price)
`daily_stock_recovery_percent`	`18`	How much stock drifts back toward target each day (%)
`buy_limit_multiplier`	`1`	Multiplier on top of the base `limit` for buy transactions
`last_rebalance_date`	auto	Tracks when the last daily rebalance ran (do not edit manually)

Each resource entry under "resources" has:

Key	Description
`limit`	Daily sell limit per player
`base`	Base reference price for elasticity calculations
`target`	Target stock level (normal equilibrium)
`min`	Hard minimum price
`max`	Hard maximum price
`stock`	Current stock level (updated live, do not set manually unless resetting)
`price`	Current computed price (updated live)

To reload the bank config at runtime without a restart: /market bankreload (admin).

11. Bank Price System (Advanced)

The bank uses a stock-based elasticity model — prices are not fixed but adjust dynamically based on how much of a resource the bank has in stock compared to its target level.

Price Formula

The base equilibrium price is computed as:

equilibrium = base × (target / stock) ^ elasticity

When stock == target, the price equals base.
When stock is low (players have been buying a lot), the ratio target/stock exceeds 1, so the price rises.
When stock is high (players have been selling a lot), the ratio falls below 1, so the price drops.
The result is bounded by [min, max] which are derived from base × min_factor and base × max_factor.

Smooth Price Change

To prevent sudden jumps, each price update is limited to max_step_percent of the current price per step. For example, with max_step_percent = 12, a price of 100 can only move to at most 112 or 88 in a single step.

Daily Rebalance

Once per day (at the first server action after midnight), the plugin runs a stock recovery step:

For each resource, daily_stock_recovery_percent of the gap between current stock and target stock is recovered.
With the default of 18%, if stock is 0 and target is 100, stock becomes 18 after day 1, 32 after day 2, etc.
After rebalancing stock, prices are recomputed.

This means that even if players have drained a resource completely, prices and supply naturally recover over time without admin intervention.

Tax Direction

Selling to bank: Tax is deducted from the base price. You receive floor(price × (1 − tax/100)).
Buying from bank: Tax is added to the base price. You pay ceil(price × (1 + tax/100)).

The spread between buy and sell prices widens as tax increases.

12. Data & Storage

File	Contents
`economy.json`	Player UUID → balance
`market.json`	All active market listings (items serialized as Base64 YAML for full NBT support)
`market-config.json`	Marketplace configuration
`bank-config.json`	Bank config + live stock/price state
`bank-state.json`	Daily sell/buy counters per player per resource, with date tracking
`history.json`	Transaction history (up to 100 entries per player)
`market-notify.json`	Market version counter + per-player last-seen version
`logs/easytrading-bank.log`	Detailed log of every bank transaction attempt (accepted, rejected, partial)
`logs/easytrading-transfers.log`	Log of all `/market send` transfers with timestamps, player names, and UUIDs

All data files are auto-saved every 5 minutes and on clean shutdown. The bank log and transfer log are append-only and never overwritten.

13. Vault Integration

EasyTrading registers itself as a Vault Economy provider if the Vault plugin is installed on the server. This allows other economy-aware plugins (e.g., Towny, LuckPerms reward systems, shop plugins) to read and modify EasyTrading balances through the standard Vault API.

Currency is identified as "coins" / "coin".
Bank accounts (Vault feature) are not supported — only player accounts.
If Vault is not found, a warning is logged and cross-plugin economy integration is unavailable, but EasyTrading itself works normally.

14. FAQ

Q: Why can't I list diamonds on the market with /market sell? A: Resources accepted by the bank (coal, redstone, lapis, copper, iron, gold, diamond, emerald, netherite) are reserved for bank trading only. This prevents players from bypassing the bank's dynamic pricing. Use /market sellto to sell them to the bank.

Q: Why does the confirmation show fewer items than I requested? A: The bank automatically reduces the amount to the maximum allowed — limited by what you're holding, your remaining daily limit, your inventory space (for buyfrom), or your balance (for buyfrom).

Q: My daily limit is reached. When does it reset? A: Limits reset every calendar day at midnight server time. Use /market limits to see exactly how much remains.

Q: I accidentally listed an item. Can I cancel it? A: Use /market cancelall to retrieve all your listings at once. Individual cancellation via command is not available — ask an admin if you need to remove a specific listing without cancelling others.

Q: How do I refresh a listing that has been buried by newer ones? A: Use /market relist <id> (without a new price) to bump the listing's timestamp so it appears first in "Newest first" sort. Tab-complete will suggest your listing IDs.

Q: What happens if I disconnect mid-trade? A: The trade is immediately cancelled and all items are returned to their owners. Your opponent receives a notification.

Q: How do I find a specific item on the market? A: Use /market search <item name> or click the compass icon in the market GUI and type the item name in chat.

Q: Prices at the bank keep changing. Why? A: The bank uses dynamic pricing based on stock. When many players buy a resource, stock drops and prices rise. When many players sell, stock rises and prices fall. Prices recover toward normal each day automatically. Check current rates by opening /market and clicking the gold ingot.

Q: How do I hide the yellow bar at the top? A: Type /market hide. To bring it back: /market show. Note that this preference resets when you reconnect.

Q: Can I trade with a player who is offline? A: No. Both the /market trade system and /market send require the other player to be online.

Q: Does EasyTrading work with other economy plugins like Towny? A: Yes, if Vault is installed. EasyTrading registers as a Vault economy provider, so Towny and other Vault-compatible plugins can read and modify balances.

Q: Where is my balance stored? Can I lose it? A: Your balance is stored in economy.json on the server and auto-saved every 5 minutes. It persists between sessions, restarts, and reconnects. It is not tied to your inventory or any in-game item.