StockMarket is a Minecraft mod that brings a better way for trading to the game. It enables players to trade items on a virtual stock market, making it ideal for multiplayer servers with active economies. For servers that do not have enough players or even for single player, plugins can be added that simulate a large player base and provide liquidity and price movements to the market.

• Features
• Blocks
• Crafting Recipes
• Matching Engine
  • Market Order
  • Limit Order
• How to use
  • For Players
  • For Admins / Single Player
• Commands
• Plugins
• Changelog
• Discord to help me improve the mod

• Adds a banking system to the game for money and items.
• Adds new blocks to interact with the market or bank account.
• Implementation of a matching engine inspired by the real market.
• Configurable plugins that provide the market with liquidity, volatility and price movements.

• Bank System Mod
• Architectury
• Quilted Fabric API (Only needed for Quilt)
• Mod Utilities (Only needed for Quilt)
• Fabric API (Only needed for Fabric)

CurseForge

Minecraft	Fabric	Forge	Quilt	Neoforge

Stock Market Block Used to get access to the stock market. Interaction using right click. Right click on a Terminal Block using a Trading Software to create this block.

Trading Software	Stock Market Display Block

A matching engine is the core component of a trading system that facilitates the buying and selling of items, stocks, or other assets. Its primary function is to match buy orders and sell orders based on specific rules to execute trades efficiently and fairly.

For simplicity are no special roles implemented. The type of order and the price is all what the matching engine needs to match the orders.

A market order requires only the amount to buy/sell. The trade is executed on the best available price.

Benefits

• The trade is executed immediately

Disadvantages

• When buing/selling, the average buy/sell price is mostly higher/lower than the market price before the trade.
• Creates high volatility for markets with low liquidity, see: Order Book Swipe
• A market order can only be executed when there are enough volume present on the opposite side to fill the order. Otherwise the order may only be filled partially.

A limit order requires an amount and price at which the trade gets executed. A buy order gets mostly placed below the current market price. The order is executed when the market price moves towards the order price.

Benefits

• For a buy order, the price a trader has to pay is at the price level or lower.
• For a sell order, the received amount is at least the price or higher.
• Limit orders are important for a market because it provides the required liquidity for the market to be able to process market orders.

Disadvantages

• The order needs time to be filled by the market.
• When the price never reaches the desired buy/sell price, the order never gets executed and stays pending.

To trade items, the item must have an active market. This is managed by the server admin.
Before trading, deposit the items you want to sell into your bank account using the Bank Terminal Block.
See Bank System Mod to learn how banking works.

Right-click on a Stock Market Terminal Block to open the trading interface.

The trading screen has two main areas:

• Left side — A real-time candlestick chart showing price history, with the order book volume displayed along the right edge of the chart.
• Right side — The trading panel with tabs for placing orders, viewing pending orders, order history, and recent market trades.

At the top of the screen is a favorites bar for quickly switching between markets. Click any market button, or use the market selector popup to browse all available items.

The terminal supports two trading modes, switchable via toggle buttons:

Money Mode — Trade a single item for money. This is the standard mode.
Pair Mode — Trade between two different items directly (e.g. trade iron ingots for diamonds). Select a "have" item and a "want" item using the pair selector.

Select the Market Order or Limit Order tab in the trading panel:

Market Order:

1. Enter the quantity you want to buy or sell (use the quick-add buttons: +1, +10, +32, +64, +128).
2. Click Buy or Sell. The order executes immediately at the best available price.

Limit Order:

1. Enter the quantity and your desired price.
2. Click Buy or Sell. The order is placed on the order book and waits until the market reaches your price.

In Pair Mode, the trading panel switches to show Market Exchange and Limit Exchange tabs, which work the same way but for cross-market trades at the current exchange rate.

• Pending Orders tab shows all your active limit orders. Each order has a cancel button.
• Drag and drop — Limit orders appear as markers on the chart. Drag a marker to change the order price. If you don't have enough funds to move a buy order higher, it will stay in place.
• My History tab shows your completed and cancelled orders.
• Market Trades tab shows the latest trades on the selected market.

Once your buy orders are filled, withdraw the purchased items from your bank account using the Bank Terminal Block.

All market management in v2.0 is done through graphical interfaces. The old command-based bot setup has been replaced by the Management GUI and the Plugin System.

A server operator needs to grant StockMarket admin privileges:
/stockmarket op — Grant admin to yourself
/stockmarket op [username] — Grant admin to another player

Run /stockmarket manage to open the management interface. It has three tabs:

Plugins replace the old bot system. They are modular components that can be added to markets to provide liquidity, simulate price movements, and more.

Open the Plugin Management screen from the Management GUI overview tab:

• Add plugins — Click the add button and choose from available plugin types.
• Configure — Each plugin has its own settings. Simple plugins show settings inline; complex ones open a dedicated configuration screen.
• Subscribe to markets — Plugins can be subscribed to one or more markets. Use the subscribe button to choose which markets a plugin operates on.
• Enable/Disable — Toggle plugins on or off without removing them.
• Reorder — Move plugins up or down to change their execution priority. Plugins are executed from top to bottom.
• Auto-subscribe — Enable to automatically subscribe a plugin to newly created markets.

Since v2.0, the old monolithic StockMarketBot has been replaced by a modular plugin system. Each plugin handles one aspect of market simulation and can be independently configured, enabled, or subscribed to specific markets through the Plugin Management screen.

The mod ships with three built-in plugins:

Simulates realistic price movements using a random walk algorithm. Each market gets independent price fluctuations around its default price, creating the organic-looking charts you see in-game.

Settings:

The market-making bot that drives prices toward a target value. It places market orders to push the price in the desired direction. A PID controller determines the size and direction of each order to smoothly converge on the target price without overshooting.

The target price is influenced by the VolatilityPlugin (random walk noise) and by player trading activity (supply and demand).

Settings:

Automatically fills the order book with a realistic volume distribution so that players always have liquidity to trade against. Without this plugin, market orders would have no counterpart to fill against.

The distribution uses a power-law shape near the current price (tighter spreads close to market) with a Gaussian cluster around the default price and a background liquidity level across all price levels.

Settings:

The three plugins combine to create a functioning market:

1. The VolatilityPlugin generates a wandering target price using random walk noise.
2. The TargetPriceBot places market orders to push the actual price toward the target, using a PID controller for smooth convergence.
3. The DefaultOrderbookVolumeDistributionPlugin keeps the order book filled with liquidity so that both bot orders and player orders can be executed.

If you don't know what a Order Book is, learn the basics first and come back later.
A price can move in two ways:

• market order
• Limit on oposite price A market order is always executed at the current price. Example with a buy market order:

1. A player places a market buy order with a volume of 8.
2. The matching engine will search a sell limit order with the lowest price.
3. The market order gets filled by the sell order.
4. If the buy order is not filled completly, the matching engine searches again for the best sell order
5. The fill-search process gets repeated until the complete market order is filled.
6. If no more sell orders can be found to fill the buy order, the buy order can not be filled completly. No one is selling, so the remainings of the order will get canceled. To avoid this problem, enough liquidity is needed for the market.

Example with a buy limit order:

1. A player places a limit order with a volume of 8 above the current market price.
2. The matching engine will search a sell limit order with the lowest price to fill the buy order, just like the market order. But the engine will not search for higher limit orders than the limit price of the buy order.
3. If the order was not filled completly, the remaining amount will stay at that position as a normal limit buy order.

As you can see in the pictures below, the current price is always that price, where the matching engine has last processed 2 orders.

The Order Book is a list with all limit orders waiting to be processed. A buy order is always on a lower or equal price as the current market price and sell orders above or at the same price. When a buy order is at the same price like a sell order, they will get matched by the matching engine. The spread is the price difference from the last executed sell to the last executed buy price. The smaller the spread the better. Buy/Sell orders which are placed nearer to the current market price will get processed first.

A order book swipe can occure when a market does not provide enough liquidity to fill large market orders. The image above shows that in an example for a large buy order and to less sell limit orders. Since the matching engine try's to fill the market order, the market price can rise extremly high when the market order is large enough and the sell volume is low enough. For the player who executed the buy order, this is bad since all sell orders are on different prices, the average buy price can rise much higher than expected. The same can happen for sell orders, in that case the player will not receive as much money for the selled goods as expected.

The candle stick chart is a common used representation of price history. Each candle has a fixed time width. Candles are available for different time scales. The timescale can't be changed in the mod. A admin can change the time for each candle, default is 1 min. A cancle can be defined with 4 values:

• Open Price The current price the market had when the new candle was created.
• High Price The highest price the market had since the candle was created.
• Low Price The lowest price the market had since the candle was created.
• Close Price The current price the market had when the candle was finished.

Below is a short animation to show how a price movement can be visualized using candle sticks.

A random walk is a way to generate pseudorandom values ​​that depend on the previous values. This value is a great source to create random market prive movements.

Since this is a complex field from control theory, I will not cover this here. PID Controller Wikipedia