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 Server that have not enough players or even for single player, a market bot can be added that simulates a large player base and provides liquidity to the market.

• Features
• Blocks
• Items
• Matching Engine
  • market-order
  • Limit Order
• How to use
  • For server player / single player
  • For admins / single player
• Commands
• Stock Market Bot
• 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 bot which provides the market with liquidity and volatility

• 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 Used to programm the Terminal Block to be a Stock Market Terminal Block 1 Empty Software 1 Emerald

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 sell items the item must be available on the market. This is managed by the server admin.
Assuming the item can be traded on the market, you first have to deposit the item to your bank account. This can be done using the Bank Terminal Block.
See Bank System Mod to learn how.

Now open the Stock Market Terminal Block using right click.
This opens the trading window.
On the left side you can see the Candle stick chart
On the left edge of the chart is the price axis.
On the right edge of the chart is the Order Book volume displayed.
On the right side of the window is the interaction panel. There you can select the desired item to be traded. Just click on the button and a list of all tradable items will appear.
Type the amount of items you want to buy/sell.
Decide whether you want to execute a market-order or a limit order.
If you want to create a limt order, you have to type in the desired price.
Click on the sell button for market or limit order to execute the trade.
A market-order is executet directly but the limit order will be listed on the left side until it is filled or gets canceled.

To buy a item you have to get some money first. You can do that by selling other items or receiving money from other players.
A server admin can also provide you money...
Assuming you have money, open the Stock Market Terminal Block
Select the item you want to trade by pressing the button on the top right with the Label "Price: XX".
Type the amount you want to buy, type a limit price if you want to execute a limit order.
Click on the buy button.
A market-order gets executed directly but a limit order may take some time until it gets filled by the market.

Once you have received the items, you can go to the Bank Terminal Block receive the bought items.

A limit order can be changed by clicking on the marker on the position of the order. There is a small botton on the left sinde of
the market. Drag and drop the order to the new price level.
If you do not have enough money to move a buy order higher, the order will not be moved to that location.

When you first join a server/save using this mod, some default markets are getting created by the mod. Each player receives its bank account with 0 balance.

Change bot settings

Just type the command /StockMarket BotSettingsGUI
This opens a gui that lets you change all settings from a bot.
- Change Item to select a market.
- Save Settings to save the current settings which are listed below.
- Market Open Open/Close the market for players to trade in order to safely change settings without players exploiting the market movements.
Players can not place new orders when a market is closed. Already placed orders will still get processed when the market is closed.
- Destroy Bot/Create Bot to delete or create a bot for that item.
- Bot Setup Opens a setup guide, that asks questions about desired market behavior in order to find the correct bot settings.
- Bot Bank to access the bank account of the bot to set its balance.

1) Close the market so players can't exploit the market when you change settings. Click Save
2) Click on Bot Setup and follow the instructions.
3) You can now ajust the settings from the setup guide to make more individual changes if you want.
4) Click on Save Settings to apply the settings to the bot and watch the market ajusts for the new settigns.
5) Once you are happy with the result, Open the market again to enable trading for players.

Some Informations about ajusting settings manually:

⚠️ Warning: Do not set the item balance to 0 since this will break the bot.
The bot must always have some items and money, otherwise it can't place orders.

⚠️ Be aware, when changing settings to other values, depending on the scale it can lead to large market change.
I reccoment to try it on a single player to get a feeling for it. There are so many differend possibilities the bot can react to it.
🚧A detaild explanation for each setting will come soon.

The StockMarketBot has multiple purposes.

• Providing the market with liquidity
• Changing price depending on supply and demand
• Source for capital for players (if they start with 0 money)

Liquidity is a very important part of every market. For example if player A wants to buy wood, someone has to sell the same amount. Without the counterpart, a trade can't be made. Since it is unlikely that a server creates enough sell/buy orders to create this liquidity, the bot is used to provide both buy and sell orders. The bot will buy if a player wants to sell, and he will sell if a player wants to buy. The bot can only sell so many items it has and he also can only buy as long as he has money. The bot always needs some balance of items and money. Without that its function will break.

The bot is responsible for the most price movements you see on the chart. The bot is always buying and selling to it self. Using a combination of limit and market -orders will create movements in price.
To create a random price chart that also stays in its realistic bounds, multiple stages are needed.

1. Defining parameters

   • target stock balance
   • target price range
   • Others...

2. Defining a target price the market should move to Depending on how many items the bot holds and what its target item balance is, it will try to rise or lower the price. For example if the bot holds 1000 items, wants to hold 500, the bot will lower the target price, making it attractive to players to buy. In the case the bot has more items than the target stock balance, the target price fall linear and also can reach a price of 0. In the case the bot holds less than he wants, the target price will rise quadraticly, producing a even larger price increase. The reason for that is, that the bot is dependend on enough supplies to work correct, a larger price increase makes it lucrative for players to sell to the bot.

   Additionaly some random noise is used to create the volatility. This noise is added to the target price and is generated using a Random Walk generator.

3. Move the market to the target price To change the price the bot creates market- sell/buy -orders. The market oder will fill the previously placed limit orders from the bot or a player. Click here to learn why a price moves. The size of the market-order defines how fast the price will change. A PID-Controller is used to generate the buy/sell market-orders. The PID-Controller will make sure to generate the right amount of orders until the target price is reached.

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