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

Real stock quotes via Tencent Finance (no API key required).
A-share, HK, and US markets with 60 pre-configured stocks.
Local virtual markets with configurable random-walk simulation.
Bull/bear/neutral market regimes for local markets.
Chest GUI trading with pagination, confirmation dialogs, and price sparklines.
Commands for buy, sell, short, quote, portfolio, rankings, and more.
Limit orders, stop-loss, and take-profit automated orders.
Short selling with margin requirements and forced liquidation.
Investment competitions with virtual capital, seasons, and Vault rewards.
IPO offerings with subscription, proportional allocation, and refunds.
Stock certificates as tradeable in-game items.
BossBar real-time stock price pinning.
Market composite index and periodic market reports.
Admin GUI panel and audit log queries.
Vault economy integration (EssentialsX Economy compatible).
PlaceholderAPI support.
SQLite storage for all holdings, trades, orders, and audit data.
13 built-in language files.
Winner and loser leaderboards by unrealized P&L.
Configurable loss penalty system with tiered charges.
Circuit breaker and quote anomaly protection.
Market hours restrictions (optional).
Config migration and startup validation.

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:

Minecraft 1.21.x Paper / Purpur
Java 21
Vault
EssentialsX + EssentialsX Economy
PlaceholderAPI (for scoreboards, menus, chat displays)

Installation

Install Vault.
Install EssentialsX Economy or another Vault-compatible economy plugin.
Optionally install PlaceholderAPI.
Drop SuperStocks.jar into your server's plugins folder.
Start the server to generate default configuration files.
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:

Confirm Vault economy is working.
Keep default language:

language: zh_CN

Keep default quote provider:

stock-provider:
  active: tencent

High-risk features are already disabled by default — no changes needed.
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 <symbol> <above	below> <price>`
`/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:

Start with 10-30 stocks per market.
Too many stocks increase sync time and API load.
Avoid removing symbols that players already hold — orphaned holdings won't appear in rankings or valuations.

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:

Local markets are great for server-made companies, town economies, event stocks, or lore-driven economies.
Give a small positive drift-percent-per-tick (e.g. 0.02) for stocks you want to trend upward long-term.
For high-risk stocks, raise volatility-percent but keep min-price and max-price as guardrails.
Don't set drift-percent-per-tick too high or prices will quickly leave the intended range.

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

Keep min-price at 0.01.
Set max-price to match your economy scale to prevent misconfiguration damage.

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:

Limit buy orders reserve the estimated cost upfront; funds are returned if the order expires or is cancelled.
Sell/stop/take-profit orders check available holdings to prevent over-selling.
Orders are checked every automation.check-seconds.
orders.max-open-per-player caps how many open orders each player can have.

Recommendations:

Normal servers: max-open-per-player: 5 - 10.
Investment-focused servers: 10 - 20.
Don't set automation.check-seconds below 10 to avoid excessive database scanning.

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:

transaction-tax-percent: 0.2 - 1.0 for normal servers.
Large trade extra tax discourages high-frequency whale trades.
Raise min-shares to match your economy scale.

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:

Keep never-negative-balance: true on normal servers.
Don't enable heavy penalties on a public survival server from day one.
Start with notify-only, observe player losses, then gradually enable withdrawals.

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:

Opening a short freezes the margin deposit; it's returned when you close.
If the stock price rises to the liquidation threshold, the position is force-closed and the margin is lost.
Default daily interest is 0% — no silent money drain.
Partial covers are supported.

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:

Competitions use separate virtual portfolios — real holdings are untouched.
Ending a competition auto-valuates all entries at current market prices, ranks them, and distributes rewards.
Adjust reward amounts to match your server's economy scale.

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:

IPO subscriptions pre-withdraw Vault funds. After allocation, excess is refunded.
Oversubscribed IPOs scale down proportionally; unallocated funds are returned.
Allocated shares go directly into player portfolios.

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:

Back up stocks.db regularly.
Do not edit the database directly while the server is running.
Deleting the database will wipe all player holdings and trade history.

Reloading

/stocks reload

Reloads:

config.yml
Current language file
Real market lists
Local custom market files
Quote provider parameters
Gameplay volatility settings
Loss penalty configuration
Trading fees and minimum trade amounts

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:

Vault is installed.
A Vault economy plugin (e.g. EssentialsX Economy) is installed.
Vault recognizes the economy provider.
No economy plugin loading errors in console.

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.

SuperStocks

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details

SuperStocks

Features

Requirements

Installation

Quick Start

Commands

Player Commands

Admin Commands

Permissions

GUI Overview

Quote Provider

Real Stock Markets

Local Custom Markets

Global Switch

Market File Example

Local Stock Parameters

Gameplay Volatility Enhancement

Price Multiplier

Random Adjustment

Safety Bounds

Recommended Combinations

Automated Orders, Stop-Loss & Take-Profit

Price Alerts & Watchlist

Quote Safety & Circuit Breaker

Fees, Short-Term Tax & Dividends

Loss Penalty

Loss Calculation

Tier Configuration

Vault Withdrawal

Console Commands

Player Notification

Short Selling

Investment Competitions

IPO Offerings

Stock Certificates

BossBar, Index & Reports

Admin Panel & Audit Log

Leaderboards

Languages

PlaceholderAPI

Data Storage

Reloading

Recommended Configurations

Stable Survival Server

Normal Economy Server

High-Risk Investment Server

Market Hours (Optional)

Market Events (Optional)

FAQ

Can't trade a stock?

Leaderboard shows no data?

Vault or EssentialsX Economy not working?

Language didn't change after switching?

Prices seem too volatile?

Do local markets affect real stock quotes?

Disclaimer