Configuration Guide

The configuration file is located at plugins/Cryptocurrency/config.yml. This guide explains all available options and how to customize them.

💡 Tip: After making changes to the config file, use /crypto reload to apply them without restarting the server.

Market Settings

Configure the market GUI and available cryptocurrencies.

enabled_symbols

market:
  enabled_symbols: ["BTC", "ETH", "SOL", "DOGE"]

Option	Description
Type	List of strings
Default	["BTC", "ETH", "SOL", "DOGE"]
Description	List of cryptocurrency symbols available on your server. Players can only trade these symbols.

Available Symbols: BTC, ETH, BNB, SOL, ADA, DOGE, XRP, DOT, MATIC, LINK, UNI, AVAX, ATOM, LTC, BCH, XLM, ALGO, VET, FIL, THETA, and many more supported by CoinGecko.

⚠️ Important: Only add symbols that are available on CoinGecko API. Invalid symbols will cause price fetch errors.

page_size

market:
  page_size: 21

Option	Description
Type	Integer
Default	21
Description	Number of items per page in the market GUI
Valid Range	1-54 (limited by Minecraft chest inventory size)

gui_title

market:
  gui_title: "&6Crypto Market"

Option	Description
Type	String (with color codes)
Default	&6Crypto Market
Description	Title displayed at the top of the market GUI. Supports Minecraft color codes (& format).

refresh_seconds

market:
  refresh_seconds: 15

Option	Description
Type	Integer
Default	15
Description	How often (in seconds) the market GUI automatically refreshes prices
Recommended	10-60 seconds

Chart Settings

Configure price history tracking and chart visualization.

retention_points

chart:
  retention_points: 360

Option	Description
Type	Integer
Default	360
Description	Maximum number of historical price points to keep per cryptocurrency
Impact	Higher values = more detailed history but more memory usage

sample_seconds

chart:
  sample_seconds: 60

Option	Description
Type	Integer
Default	60
Description	How often (in seconds) to sample and store price data
Recommended	30-300 seconds

Example: With 360 retention_points and 60 sample_seconds, you store 6 hours of price history.

default_points

chart:
  default_points: 24

Option	Description
Type	Integer
Default	24
Description	Default number of data points to show in charts when not specified

sparkline_chars

chart:
  sparkline_chars: "▁▂▃▄▅▆▇█"

Option	Description
Type	String
Default	▁▂▃▄▅▆▇█
Description	Characters used to render sparkline charts, from lowest to highest value

PlaceholderAPI Settings

Configure placeholder formatting and behavior.

enabled

placeholders:
  enabled: true

Option	Description
Type	Boolean
Default	true
Description	Enable or disable PlaceholderAPI integration

format

placeholders:
  format:
    money: "#,##0.00"
    quantity: "#,##0.####"

Option	Description
money	Number format for USD values (default: #,##0.00)
quantity	Number format for cryptocurrency amounts (default: #,##0.####)

Format Syntax:

# = optional digit
0 = required digit
, = thousands separator
. = decimal point

API Settings

Configure CoinGecko API connection and circuit breaker behavior.

timeout_ms

api:
  timeout_ms: 4000

Option	Description
Type	Integer
Default	4000 (4 seconds)
Description	Maximum time to wait for API response in milliseconds
Recommended	2000-10000 ms

retry

api:
  retry: 1

Option	Description
Type	Integer
Default	1
Description	Number of retry attempts if API request fails
Recommended	0-3

Circuit Breaker

api:
  circuit_breaker:
    error_threshold: 5
    open_seconds: 30

Option	Description
error_threshold	Number of consecutive errors before circuit opens (default: 5)
open_seconds	How long to keep circuit open before trying again (default: 30)

💡 What is a Circuit Breaker? When the API fails repeatedly, the circuit breaker temporarily stops making requests to prevent server lag. After the timeout period, it tries again.

Message Customization

All player-facing messages can be customized in the config. Messages support Minecraft color codes.

Color Codes

Code	Color	Code	Format
&0	Black	&l	Bold
&1	Dark Blue	&m	~~Strikethrough~~
&2	Dark Green	&n	Underline
&3	Dark Aqua	&o	Italic
&4	Dark Red	&r	Reset
&5	Dark Purple	&k	Obfuscated
&6	Gold
&7	Gray
&8	Dark Gray
&9	Blue
&a	Green
&b	Aqua
&c	Red
&d	Light Purple
&e	Yellow
&f	White

Message Placeholders

Many messages support placeholders that are replaced with actual values:

Placeholder	Description
{symbol}	Cryptocurrency symbol (BTC, ETH, etc.)
{amount}	Cryptocurrency amount
{player}	Player name
{usd}	USD value
{price}	Price per unit
{error}	Error message
{label}	Command label used
{count}	Count/number

Example Custom Messages

messages:
  prefix: "&8[&6₿ &eCrypto&8] &r"
  
  trade:
    buy:
      success: "&a✓ Bought &f{amount} {symbol} &afor &f${usd}"
      nomoney: "&c✗ Insufficient funds! Need: &f${usd}"
    
    sell:
      success: "&a✓ Sold &f{amount} {symbol} &afor &f${usd}"
      notenough: "&c✗ Not enough {symbol}!"
  
  transfer:
    success: "&a✓ Sent &f{amount} {symbol} &ato &f{player}"

Example Configurations

High-Performance Server

Optimized for servers with many players:

market:
  enabled_symbols: ["BTC", "ETH", "BNB", "SOL"]
  refresh_seconds: 30
  
chart:
  retention_points: 180
  sample_seconds: 120
  
api:
  timeout_ms: 3000
  retry: 0
  circuit_breaker:
    error_threshold: 3
    open_seconds: 60

Feature-Rich Server

Maximum features and cryptocurrencies:

market:
  enabled_symbols: ["BTC", "ETH", "BNB", "SOL", "ADA", "DOGE", 
                    "XRP", "DOT", "MATIC", "LINK", "UNI", "AVAX"]
  refresh_seconds: 15
  
chart:
  retention_points: 720
  sample_seconds: 30
  
api:
  timeout_ms: 5000
  retry: 2
  circuit_breaker:
    error_threshold: 10
    open_seconds: 30

Low-Resource Server

Minimal resource usage:

market:
  enabled_symbols: ["BTC", "ETH"]
  refresh_seconds: 60
  
chart:
  retention_points: 60
  sample_seconds: 300
  
api:
  timeout_ms: 3000
  retry: 0
  circuit_breaker:
    error_threshold: 3
    open_seconds: 60

Advanced Configuration

Multi-Language Support

While the plugin doesn't have built-in multi-language support, you can create language-specific messages:

# French Example
messages:
  prefix: "&6[&eCrypto&6] &r"
  trade:
    buy:
      success: "&aAchat : &f{amount} {symbol} &7(-${usd})"
      nomoney: "&cPas assez d'argent. Requis : ${usd}"
    sell:
      success: "&aVente : &f{amount} {symbol} &7(+${usd})"
      notenough: "&cVous n'avez pas assez de {symbol}"

Backup Configuration

⚠️ Important: Always backup your config file before making major changes!

# On Linux/Mac
cp plugins/Cryptocurrency/config.yml plugins/Cryptocurrency/config.yml.backup

# On Windows
copy plugins\Cryptocurrency\config.yml plugins\Cryptocurrency\config.yml.backup

Validation

After editing the config, validate it's still valid YAML:

Use an online YAML validator
Check the server console for config errors on startup
Use /crypto reload to test changes

Troubleshooting

Config Not Loading

Symptoms: Changes don't apply or server won't start.

Solutions:

Check for YAML syntax errors (indentation, colons, quotes)
Ensure you're using spaces, not tabs for indentation
Validate YAML syntax with an online validator
Check console for specific error messages
Restore from backup if corrupted

Prices Not Updating

Symptoms: Prices are stale or not updating.

Solutions:

Check if symbols are valid CoinGecko symbols
Increase api.timeout_ms if on slow connection
Check circuit breaker status with /crypto api status
Verify internet connection

Performance Issues

Symptoms: Server lag when many players trade.

Solutions:

Reduce number of enabled_symbols
Increase market.refresh_seconds
Reduce chart.retention_points
Increase chart.sample_seconds
Set api.retry to 0