Wallet-Lite

🌍 Overview

Wallet-Lite transforms your Minecraft economy by letting players trade real-world financial assets with live market prices — all through a clean, inventory-based GUI. No websites, no external apps, no commands to memorise. Just open your wallet and trade.

Prices are fetched live from CoinGecko (crypto) and Yahoo Finance (stocks & ETFs) — completely free, no API key required.

✨ Features

Trading

• Fractional shares & crypto — buy as little as 0.001 BTC
• Dollar presets when buying crypto: $10 / $100 / $1,000 / $5,000 / $10,000
• Percentage presets when selling: 25% / 50% / 75% / 100%
• Free-text input for any custom amount via chat
• Full P/L tracking: average entry price, unrealized and realized profit/loss
• Fee display on every buy and sell confirmation

Wallet System

• Separate trading wallet — keeps trading money clean from server economy
• Deposit & withdraw via Vault/Essentials integration
• Full transaction history with filters (Wallet / Crypto / Stocks)
• Weekend fee discount: 0.01% vs 0.1% on weekdays
• Stock market hours enforced: Mon–Sat 06:00–23:00 (CET, configurable)
• Crypto trades 24/7 — never closed

GUI & UX

• 100% inventory-based — everything via left-click / right-click
• MiniMessage gradient titles for all GUI windows
• Inventory locked while GUI is open — no accidental item moves
• Colour-coded P/L: 🟢 green = profit, 🔴 red = loss
• Clean market overview with price change indicators

Admin Tools

• /walletadmin info <player> — view any player's full portfolio
• /walletadmin freeze <player> — freeze/unfreeze a wallet (blocks all trades)
• Freeze notification sent to the player if online

📋 Requirements

Java 17 or higher is required.

🚀 Quick Start

1. Download WalletLite-1.0.jar
2. Place it in /plugins/
3. Start the server
4. Edit plugins/WalletLite/config.yml
5. Type /wallet in-game

🎮 Commands

Aliases: /w · /crypto · /geldbörse · /wreload

⚙️ Config

currency:
  symbol: "$"
  code:   "USD"

market:
  price_currency: "EUR"   # CoinGecko quote currency
  fx_eur_to_usd:  1.10    # Conversion rate for in-game trading

time:
  zone: "Europe/Berlin"   # Stock market hours use this timezone

trading:
  fee_percent:         0.001   # 0.1%  weekdays
  weekend_fee_percent: 0.0001  # 0.01% weekends
  min_total_usd:       1.0     # Minimum trade size

history:
  enabled:     true
  max_entries: 250

ℹ️ The API update interval is fixed at 15 minutes in Lite Edition.

💱 How Trading Works

Buying:

Total Cost = Trade Amount + Fee
Example: $1,000 of BTC + 0.1% fee = $1,001.00 deducted from wallet

Selling:

You Receive = Sale Value − Fee
Example: Sell $500 of ETH − 0.1% fee = $499.50 added to wallet

P/L Display:

Unrealized P/L = (Current Price − Avg Entry Price) × Holdings
Realized P/L   = Sale Revenue − Cost Basis

🔐 Permissions

wallet.use         → Open /wallet          (default: everyone)
wallet.trade       → Buy and sell          (default: everyone)
wallet.deposit     → Deposit / withdraw    (default: everyone)
coinwallet.admin   → Admin commands        (default: op)
coinwallet.reload  → Reload config         (default: op)
wallet.*           → All permissions       (default: op)

❓ FAQ

Q: Do I need an API key?
No. CoinGecko and Yahoo Finance both offer free public endpoints. Wallet-Lite handles all rate limiting automatically.

Q: Prices say "Lädt..." — what do I do?
Wait ~30 seconds after server start. The initial fetch runs 5 seconds after plugin load. Check console for [WalletLite] Crypto-Preise aktualisiert!

Q: Can I add more stocks or crypto?
Not in Lite Edition — the asset list is fixed. This keeps things simple and well-tested.

Q: ETF tab shows nothing?
Delete stocks.yml from the plugin folder and restart — it will regenerate with correct type: ETF entries.

Q: What if Yahoo Finance rate-limits us?
The plugin will automatically wait and retry with exponential backoff. A warning is logged to console.