Home›Java›Mods›SuperStocks
SuperStocks
ModsJava

SuperStocks

A virtual stock investment plugin for Paper/Purpur Minecraft servers

⬇ Download on Modrinth
Open in MCModsHubGet it on Google Play →

SuperStocks

A Minecraft virtual stock investment plugin for Paper/Purpur servers. Sync real stock quotes into your server or create fully simulated local markets. Players trade through chest GUIs or commands, with all transactions settled via Vault economy.

Designed for servers looking to add long-term economy gameplay, investment systems, leaderboard competition, virtual finance events, or high-risk/high-reward mechanics. It does not alter real stock data but can scale prices and volatility to fit your server's economy scale.

SuperStocks is for entertainment purposes only and does not constitute investment advice.

Features

Requirements

Item Requirement
Server Paper / Purpur compatible
Java Java 21
Required Vault + a Vault economy plugin
Recommended EssentialsX Economy
Optional PlaceholderAPI
Database SQLite (auto-created)
Network Required for real stock quotes (Tencent API)

Recommended environment:

Installation

  1. Install Vault.
  2. Install EssentialsX Economy or another Vault-compatible economy plugin.
  3. Optionally install PlaceholderAPI.
  4. Drop SuperStocks.jar into your server's plugins folder.
  5. Start the server to generate default configuration files.
  6. Modify as needed (then /stocks reload):
plugins/SuperStocks/config.yml
plugins/SuperStocks/Language/
plugins/SuperStocks/CustomMarkets/

After first startup you should see:

plugins/SuperStocks/config.yml
plugins/SuperStocks/stocks.db
plugins/SuperStocks/Language/zh_CN.yml
plugins/SuperStocks/CustomMarkets/example.yml

Quick Start

If you just want the plugin running:

  1. Confirm Vault economy is working.
  2. Keep default language:
language: zh_CN
  1. Keep default quote provider:
stock-provider:
  active: tencent

  1. High-risk features are already disabled by default — no changes needed.

  2. In-game:

/stocks sync
/stocks

If you see stock quotes in the GUI and can buy/sell, the basic setup is working. You can then gradually enable volatility enhancement, local markets, and loss penalties.

Commands

Player Commands

Command Description
/stocks Open the stock trading GUI
/stocks help Show help
/stocks open Open the stock GUI
/stocks quote <symbol> View stock quote
/stocks buy <symbol> <shares> Buy shares
/stocks sell <symbol> <shares> Sell shares
/stocks short <symbol> <shares> Open a short position
/stocks cover <id> [shares] Close (cover) a short position
/stocks portfolio View text-based portfolio
/stocks history <symbol> View 24h price history
/stocks stats View personal investment statistics
/stocks watch add <symbol> Add to watchlist
/stocks watch remove <symbol> Remove from watchlist
/stocks watch list View watchlist
`/stocks alert <above below> `
/stocks order buy <symbol> <shares> <price> [seconds] Create limit buy order
/stocks order sell <symbol> <shares> <price> [seconds] Create limit sell order
/stocks order stop-loss <symbol> <shares> <price> [seconds] Create stop-loss order
/stocks order take-profit <symbol> <shares> <price> [seconds] Create take-profit order
/stocks order list View open orders
/stocks order cancel <id> Cancel an order
/stocks rank winners View top investors
/stocks rank losers View bottom investors
/stocks index View market indices
/stocks pin <symbol> Pin stock price to BossBar
/stocks unpin Remove BossBar pin
/stocks report View market report
/stocks competition list List competitions
/stocks competition join <id> Join a competition
/stocks competition buy <id> <symbol> <shares> Buy in competition
/stocks competition sell <id> <symbol> <shares> Sell in competition
/stocks certificate issue <symbol> <shares> Convert holdings to certificate item
/stocks certificate list List your certificates
/stocks ipo list List IPO offerings
/stocks ipo subscribe <id> <shares> Subscribe to an IPO

Examples:

/stocks quote sh600519
/stocks buy sh600519 10
/stocks sell sh600519 5
/stocks short usTSLA 5
/stocks cover 1
/stocks portfolio
/stocks rank winners

Admin Commands

Command Permission Description
/stocks sync superstocks.admin Force quote sync
/stocks status superstocks.admin View system status
/stocks pause superstocks.admin Pause all trading
/stocks resume superstocks.admin Resume trading
/stocks penalty history <player> superstocks.admin View player penalty history
/stocks admin portfolio <player> superstocks.admin View player portfolio
/stocks admin give <player> <symbol> <shares> superstocks.admin Grant holdings to player
/stocks admin remove <player> <symbol> <shares> superstocks.admin Remove holdings from player
/stocks admin clear <player> superstocks.admin Clear all player holdings
/stocks admin panel superstocks.admin Open admin GUI
/stocks admin audit [player] [action] superstocks.admin Query audit log
/stocks competition create <name> <days> <capital> superstocks.admin Create a competition
/stocks competition end <id> superstocks.admin End competition & distribute rewards
/stocks ipo create <symbol> <name> <market> <price> <total> <max> superstocks.admin Create an IPO
/stocks ipo cancel <id> superstocks.admin Cancel an IPO
/stocks reload superstocks.admin Reload config, language, markets, services

Permissions

Permission Default Description
superstocks.use Everyone Use GUI and player commands
superstocks.admin OP Use admin commands
superstocks.penalty.exempt OP Exempt from loss penalties

GUI Overview

Main screen — Market entries, portfolio button, winners/losers leaderboards, watchlist, system stats.

Market screen — Stock list showing name, symbol, current price, change amount, change %, and last update time. Supports pagination for markets with many stocks.

Stock detail page — Quick-buy and quick-sell buttons (3 preset amounts), 24h price trend sparkline, and price history summary.

Trade confirmation dialog — Appears when the estimated trade gross exceeds the configured threshold (default 1000), preventing accidental large trades.

Watchlist — A personal page showing only the stocks the player has added via /stocks watch add.

Portfolio — Shows all current holdings with cost basis, market value, and unrealized profit.

Admin panel — Overview of total holdings, active players, total trades, last sync time, trading pause status, and Vault status.

All GUI sizes, materials, and slot layouts are configurable in config.yml. The preset trade amounts default to [1, 10, 100] and can be adjusted to fit your economy scale — for high-currency servers, consider [10, 100, 1000].

Quote Provider

Default: Tencent Finance (no API key needed).

stock-provider:
  active: tencent
  refresh-seconds: 300
  timeout-seconds: 8
  log-success: true

Recommendations:

Setting Recommended Notes
refresh-seconds 300 - 600 Don't set too low — avoid API rate limiting
timeout-seconds 8 - 15 Increase if network is unstable
log-success true Useful for monitoring sync health

The default endpoint:

sources:
  tencent:
    display-name: "Tencent Finance"
    endpoint: "https://qt.gtimg.cn/q={symbols}"
    encoding: "GBK"
    symbol-separator: ","
    max-symbols-per-request: 80
    user-agent: "SuperStocks/1.0"

Placeholder entries exist for Eastmoney, THS, Xueqiu, and Sina. The built-in parser only handles Tencent's v_symbol="...~..." format. If switching sources, use a compatible proxy that outputs the same format.

Real Stock Markets

Configured under markets in config.yml.

Example:

markets:
  cn:
    display-name: "A-Share"
    icon: EMERALD
    symbols:
      - "sh600519"
      - "sz000001"

  hk:
    display-name: "HK Stocks"
    icon: GOLD_INGOT
    symbols:
      - "hk00700"

  us:
    display-name: "US Stocks"
    icon: DIAMOND
    symbols:
      - "usAAPL"

Tencent symbol format:

Market Format Example
Shanghai A-Share sh + code sh600519
Shenzhen A-Share sz + code sz000001
Hong Kong hk + code hk00700
US us + ticker usAAPL

Recommendations:

Local Custom Markets

SuperStocks reads .yml files from:

plugins/SuperStocks/CustomMarkets/

Each file defines one local virtual market. An example file is generated on first startup:

plugins/SuperStocks/CustomMarkets/example.yml

Local markets don't call external APIs. They use a random-walk model close to real market behavior:

new price = old price × (1 + drift% + random volatility%)

Local prices also pass through gameplay-volatility, so local and real markets share the same in-game volatility rules.

Global Switch

custom-markets:
  enabled: true
  global-tick-seconds: 300

Guidance:

Playstyle global-tick-seconds
Stable 600 - 1800
Normal 300 - 600
Fast-paced 60 - 180

Market File Example

market:
  id: local_tech
  display-name: "Local Tech Stocks"
  icon: AMETHYST_SHARD
  enabled: true

simulation:
  tick-seconds: 300
  tick-limit-percent: 15
  regimes:
    enabled: true
    duration-seconds: 3600

stocks:
  local_chip:
    symbol: "lcCHIP"
    name: "Block Chip Inc."
    enabled: true
    initial-price: 120.0
    min-price: 10.0
    max-price: 1000.0
    drift-percent-per-tick: 0.03
    volatility-percent: 2.0

Local Stock Parameters

Setting Description Guidance
symbol Stock code Use a prefix to avoid conflicts, e.g. lcCHIP
name Display name Shown in GUI
initial-price Starting price Match your server's economy scale
min-price Price floor Keep above 0
max-price Price ceiling Prevents runaway prices
drift-percent-per-tick Long-term trend Typically -0.2 to 0.2
volatility-percent Random swing strength Stable 0.5-1.5, normal 1.5-3.0, risky 3.0-8.0

Tips:

Gameplay Volatility Enhancement

Real stocks often have small daily moves that feel insignificant in Minecraft economies. gameplay-volatility transforms base prices into more dramatic in-game prices.

Processing order:

Base quote → Price multiplier → Random offset → In-game display & trading price

Configuration:

gameplay-volatility:
  price-multiplier:
    enabled: false
    multiplier: 1.0

  random-adjustment:
    enabled: false
    min-percent: -3.0
    max-percent: 3.0
    refresh-seconds: 300

  safety:
    min-price: 0.01
    max-price: 1000000000.0

Price Multiplier

price-multiplier:
  enabled: true
  multiplier: 5.0

In-game price = base price × multiplier.

Server Type multiplier
Vanilla-scale economy 1.0 - 5.0
Normal economy 5.0 - 20.0
High-inflation economy 20.0 - 100.0

If unsure, keep disabled initially, observe the trading experience, then enable.

Random Adjustment

random-adjustment:
  enabled: true
  min-percent: -5.0
  max-percent: 5.0
  refresh-seconds: 300

Each stock gets an independent random offset (e.g. -5% to +5%), regenerated every refresh-seconds.

Style min-percent max-percent refresh-seconds
Stable -2.0 2.0 600 - 1800
Normal -5.0 5.0 300 - 600
Aggressive -10.0 10.0 60 - 180

Safety Bounds

safety:
  min-price: 0.01
  max-price: 1000000000.0

Recommended Combinations

Normal survival economy server:

gameplay-volatility:
  price-multiplier:
    enabled: true
    multiplier: 5.0
  random-adjustment:
    enabled: true
    min-percent: -5.0
    max-percent: 5.0
    refresh-seconds: 300

Fast-paced investment server:

gameplay-volatility:
  price-multiplier:
    enabled: true
    multiplier: 20.0
  random-adjustment:
    enabled: true
    min-percent: -10.0
    max-percent: 10.0
    refresh-seconds: 120

Automated Orders, Stop-Loss & Take-Profit

SuperStocks supports automated orders so players can set buy/sell conditions in advance.

orders:
  enabled: true
  max-open-per-player: 10

automation:
  check-seconds: 30

Order types:

Type Command Description
Limit Buy /stocks order buy <symbol> <shares> <price> [seconds] Auto-buy when price reaches trigger
Limit Sell /stocks order sell <symbol> <shares> <price> [seconds] Auto-sell when price reaches trigger
Stop-Loss /stocks order stop-loss <symbol> <shares> <price> [seconds] Auto-sell when price drops to limit losses
Take-Profit /stocks order take-profit <symbol> <shares> <price> [seconds] Auto-sell when price rises to lock in gains

Utility commands:

/stocks order list
/stocks order cancel <id>

Mechanics:

Recommendations:

Price Alerts & Watchlist

Players can track stocks of interest and receive notifications when price targets are hit.

Watchlist commands:

/stocks watch add <symbol>
/stocks watch remove <symbol>
/stocks watch list

Alert commands:

/stocks alert <symbol> above <price>
/stocks alert <symbol> below <price>

Configuration:

alerts:
  enabled: true

The main GUI also has a watchlist entrance. Watchlists help players track key stocks; alerts pair well with limit/stop/take-profit orders.

Quote Safety & Circuit Breaker

Public servers should keep these enabled to protect the economy from API anomalies, player spam, or misconfiguration.

Quote anomaly protection:

quote-safety:
  reject-stale-quotes: true
  max-quote-age-seconds: 900
  reject-abnormal-change: true
  max-change-percent-per-sync: 25.0
  circuit-breaker:
    enabled: true
    stock-max-change-percent: 15.0
    freeze-seconds: 600
Setting Description Guidance
reject-stale-quotes Block trading with expired quotes Enable for public servers
max-quote-age-seconds Quote expiry threshold 2-3× your refresh interval
reject-abnormal-change Reject single-sync price spikes Enable
max-change-percent-per-sync Max allowed change per sync 20 - 30 for normal servers
circuit-breaker.enabled Freeze trading on abnormal in-game price swings Enable
freeze-seconds Freeze duration 300 - 900

Trading rate limits:

trading:
  paused: false
  cooldown-milliseconds: 1000
  max-trades-per-minute: 20
  max-shares-per-trade: 10000
  max-position-value: 0.0
Setting Description Guidance
paused Global trading pause Toggle during maintenance
cooldown-milliseconds Minimum interval between player trades 500 - 2000
max-trades-per-minute Max manual trades per minute per player 10 - 30
max-shares-per-trade Max shares per single trade Match your economy scale
max-position-value Max market value per stock per player (0 = unlimited) Prevents monopolization

Admin commands:

/stocks pause
/stocks resume
/stocks status

Fees, Short-Term Tax & Dividends

Base transaction fees:

economy:
  transaction-tax-percent: 0.5
  min-shares: 1
  large-trade-threshold-shares: 1000
  large-trade-extra-tax-percent: 0.2

Guidance:

Short-term tax:

economy:
  short-term-tax:
    enabled: false
    minimum-holding-hours: 24
    percent: 1.0

Charges an extra fee when selling positions held for less than the minimum duration. Encourages long-term holding.

Dividends:

dividends:
  enabled: false
  interval-hours: 168
  yield-percent: 0.5
  minimum-holding-hours: 24
Setting Description Guidance
interval-hours Payout interval 168 = weekly
yield-percent % of market value paid out 0.1 - 1.0
minimum-holding-hours Minimum holding period to qualify Prevents last-minute buying

⚠️ Dividends continuously inject money into the economy. Disabled by default.

Loss Penalty

loss-penalty triggers consequences when a player's portfolio is losing money. Penalties are selected by loss-percentage tier, then applied as Vault withdrawals or console commands.

Disabled by default:

loss-penalty:
  enabled: false

Loss Calculation

Uses current in-game prices:

Cost basis = shares × average cost
Market value = shares × current price
Loss amount = max(0, cost basis - market value)
Loss % = loss amount ÷ cost basis × 100%

Tier Configuration

loss-penalty:
  check-interval-seconds: 600
  player-cooldown-seconds: 3600

  tiers:
    light:
      enabled: true
      min-loss-percent: 5.0
      max-loss-percent: 10.0
      fixed-amount: 0.0
      percent-of-loss: 0.5
      percent-of-portfolio-value: 0.0
      max-amount: 1000.0

The plugin selects the highest min-loss-percent tier that matches the current loss percentage.

Penalty formula:

Charge = fixed-amount + loss × percent-of-loss% + portfolio value × percent-of-portfolio-value%

Tier guidance:

Tier Loss % percent-of-loss percent-of-portfolio-value max-amount
light 5% - 10% 0.5 - 1.0 0 - 0.2 0.5-1× daily player income
normal 10% - 20% 1.0 - 3.0 0 - 0.5 1-2× daily player income
severe 20%+ 2.0 - 6.0 0.2 - 1.0 2-5× daily player income

Vault Withdrawal

loss-penalty:
  actions:
    vault-withdraw:
      enabled: false
      never-negative-balance: true

Recommendations:

Console Commands

loss-penalty:
  actions:
    commands:
      enabled: false
      list:
        - "effect give {player} minecraft:slowness 30 0"

Available variables:

Variable Description
{player} Player name
{uuid} Player UUID
{tier} Triggered tier ID
{loss} Current loss amount
{loss_percent} Current loss percentage
{portfolio_value} Current portfolio market value
{cost} Current cost basis
{vault_penalty} This round's Vault charge

Player Notification

loss-penalty:
  actions:
    notify:
      enabled: true
      message: "&cYour portfolio is down {loss} ({loss_percent}%), triggering {tier} tier penalty. Charge: {vault_penalty}."

This message lives in config.yml so you can edit it directly for your server's style and language.

Short Selling

Players borrow shares to sell high, then buy back lower to return them. Short positions require a margin deposit and are subject to forced liquidation if the price rises too much.

short-selling:
  enabled: true
  max-shares-per-position: 10000
  check-seconds: 120
  interest-percent-per-day: 0.0        # 0 = no interest
  margin:
    required-percent: 50                # Margin = position value × rate
    liquidation-percent: 50             # Auto-close when loss reaches margin × rate

Commands:

/stocks short <symbol> <shares>       # Open a short
/stocks cover <id> [shares]           # Close all or part of a short

Mechanics:

Investment Competitions

Create seasonal competitions where participants pay an entry fee for equal virtual capital, compete on returns, and win Vault rewards.

competition:
  enabled: true
  rewards:
    - "1: 5000"     # 1st place reward
    - "2: 2000"     # 2nd place
    - "3: 1000"     # 3rd place

Player commands:

/stocks competition list
/stocks competition join <id>
/stocks competition buy <id> <symbol> <shares>
/stocks competition sell <id> <symbol> <shares>

Admin commands:

/stocks competition create <name> <days> <start-capital>
/stocks competition end <id>

Mechanics:

IPO Offerings

Admins can create IPOs for local market stocks. Players subscribe during the offering window; shares are allocated proportionally when it closes.

Player commands:

/stocks ipo list
/stocks ipo subscribe <id> <shares>

Admin commands:

/stocks ipo create <symbol> <name> <market> <price> <total-shares> <max-per-player>
/stocks ipo cancel <id>

Mechanics:

Stock Certificates

Players can convert holdings into tradeable certificate items, enabling peer-to-peer trading, chest shops, or auctions.

/stocks certificate issue <symbol> <shares>    # Convert to item
/stocks certificate list                       # View your certificates

Right-click the certificate item in the air to redeem it back into your portfolio. Certificates can be freely traded between players.

BossBar, Index & Reports

BossBar pinning — Pin a stock's real-time price to the top of your screen:

/stocks pin <symbol>       # Pin
/stocks unpin              # Remove

The bar color follows price direction (green up, red down) and the progress bar reflects intraday volatility.

Market index — View average price per market:

/stocks index

Market report — Generate a text-based summary:

/stocks report

Admin Panel & Audit Log

Admin GUI — Visual overview of total holdings, active players, trades, sync status, trading pause state, and Vault health:

/stocks admin panel

Audit log — Query the operation history:

/stocks admin audit [player] [action]

Audit action types include: BUY, SELL, ORDER_CREATED, ORDER_EXECUTED, ADMIN_GIVE, ADMIN_REMOVE, ADMIN_CLEAR, SHORT_OPEN, SHORT_COVER, SHORT_LIQUIDATED, COMPETITION_CREATE, COMPETITION_JOIN, IPO_CREATE, IPO_ALLOCATED, CERT_REDEEM, and more.

Leaderboards

Two leaderboards:

Board Command Description
Winners /stocks rank winners Ranked by unrealized profit (highest first)
Losers /stocks rank losers Ranked by unrealized loss (highest first)

Leaderboards depend on cached quotes. Stocks without successful syncs are excluded from that cycle's valuation.

Languages

Set in config.yml:

language: zh_CN

Language files live in:

plugins/SuperStocks/Language/

Built-in languages:

Code Language
zh_CN 简体中文
zh_HK 繁體中文（香港）
zh_MO 繁體中文（澳門）
zh_TW 繁體中文（台灣）
en_US English
ja_JP 日本語
ko_KR 한국어
ar_SA العربية
de_DE Deutsch
es_ES Español
fr_FR Français
pt_BR Português do Brasil
ru_RU Русский

Missing keys fall back to en_US at runtime. To add a custom language, copy any existing file, rename it, edit the text, set it in config.yml, and run /stocks reload.

PlaceholderAPI

Placeholder Description
%superstocks_cash% Vault balance
%superstocks_portfolio_value% Current portfolio market value
%superstocks_total_value% Cash + portfolio value
%superstocks_profit% Unrealized profit/loss
%superstocks_profit_percent% Unrealized return percentage
%superstocks_shares_<symbol>% Shares held of a specific stock

Examples:

%superstocks_profit_percent%
%superstocks_shares_usAAPL%

Data Storage

SuperStocks uses SQLite to store holdings and trade data.

database:
  file: "stocks.db"

Default location:

plugins/SuperStocks/stocks.db

Recommendations:

Reloading

/stocks reload

Reloads:

Database file path changes require a full server restart.

Recommended Configurations

Stable Survival Server

For normal survival economy — stocks as a side activity.

gameplay-volatility:
  price-multiplier:
    enabled: false
  random-adjustment:
    enabled: true
    min-percent: -2.0
    max-percent: 2.0
    refresh-seconds: 900

loss-penalty:
  enabled: false

Normal Economy Server

For servers where stocks are a core feature.

gameplay-volatility:
  price-multiplier:
    enabled: true
    multiplier: 5.0
  random-adjustment:
    enabled: true
    min-percent: -5.0
    max-percent: 5.0
    refresh-seconds: 300

loss-penalty:
  enabled: false

High-Risk Investment Server

For servers built around trading, rankings, and risk mechanics.

gameplay-volatility:
  price-multiplier:
    enabled: true
    multiplier: 20.0
  random-adjustment:
    enabled: true
    min-percent: -10.0
    max-percent: 10.0
    refresh-seconds: 120

loss-penalty:
  enabled: true
  check-interval-seconds: 300
  player-cooldown-seconds: 3600

High-risk configurations should be paired with clear announcements, rules, or tutorials so players understand the penalty mechanics.

Market Hours (Optional)

Restrict trading to real market hours. Disabled by default (24/7 trading).

market-hours:
  cn:
    enabled: false
    timezone: "Asia/Shanghai"
    open: "09:30"
    close: "15:00"
    weekends: false
    closed-action: "DENY"

closed-action: DENY (block all trading) or SELL_ONLY (allow selling only during closed hours).

Market Events (Optional)

Random "breaking news" events that cause price jumps in local markets. Disabled by default.

market-events:
  enabled: false
  chance-percent-per-tick: 2.0
  min-impact-percent: -5.0
  max-impact-percent: 5.0
  announce-threshold-percent: 3.0

When an event's impact exceeds the threshold, a server-wide announcement is broadcast.

FAQ

Can't trade a stock?

The stock likely hasn't synced quotes yet. Try:

/stocks sync
/stocks quote <symbol>

If still no data, check your server's network access to the quote API and verify the symbol is correct.

Leaderboard shows no data?

Leaderboards require players to hold positions with cached quotes. Local stocks need at least one simulation tick; real stocks need a successful sync first.

Vault or EssentialsX Economy not working?

Confirm:

Language didn't change after switching?

Verify the language code in config.yml, e.g.:

language: en_US

Then run:

/stocks reload

Prices seem too volatile?

This is expected if random-adjustment is enabled. To reduce it, narrow min-percent / max-percent or increase refresh-seconds.

Do local markets affect real stock quotes?

No. Local markets use independent configs in CustomMarkets/ and never call external APIs. They pass through the same gameplay-volatility processing as real quotes.

Disclaimer

SuperStocks is a virtual investment entertainment plugin for Minecraft servers. It does not provide, constitute, or imply any real-world investment advice. Real stock quote APIs may be subject to third-party stability, access restrictions, or field changes. Set reasonable sync intervals and comply with applicable terms of service.

Verified by MCModsHub

These come from our own check of the pack file, not from the source page.

Explore more

All Mods for JavaAll Minecraft Java modsJava mods for 1.21Java mods for 26