Frequently Asked Questions

Find answers to common questions about CryptocurrencyMC.

General Questions

What is CryptocurrencyMC?

CryptocurrencyMC is a Minecraft plugin that brings real-world cryptocurrency trading to your server. Players can buy, sell, and trade popular cryptocurrencies using your server's economy system, with prices fetched in real-time from CoinGecko API.

Is this real cryptocurrency trading?

No! This is a virtual economy system within Minecraft. Players use in-game currency (via Vault) to trade virtual representations of cryptocurrencies. No real money or actual cryptocurrencies are involved. It's purely for entertainment and education within the game.

Do I need an API key?

No API key is required! The plugin uses CoinGecko's free public API to fetch cryptocurrency prices. However, be aware of rate limits on the free tier.

What Minecraft versions are supported?

CryptocurrencyMC is designed for Minecraft 1.21+ (Paper or Spigot) with Java 21+. It may work on older versions but is not officially supported.

Is the plugin free?

Yes! CryptocurrencyMC is completely free and open-source under the MIT license.

Installation & Setup

What plugins are required?

Required:

Optional:

The plugin won't load. What should I check?

  1. Ensure you're running Java 21 or higher
  2. Verify you're using Paper or Spigot 1.21+
  3. Make sure Vault is installed and loaded
  4. Verify an economy plugin is installed
  5. Check the console for specific error messages

Can I use this on older Minecraft versions?

The plugin is built for 1.21+ and uses features specific to newer versions. While it might work on 1.20, we recommend using the supported version for the best experience.

Do I need to restart after installation?

Yes, you should restart your server after installing the plugin for the first time. After that, you can use /crypto reload to apply config changes without restarting.

Features & Functionality

Which cryptocurrencies are supported?

Any cryptocurrency available on CoinGecko can be added! Popular ones include:

Configure them in config.yml under market.enabled_symbols.

How often are prices updated?

Prices are cached for 60 seconds by default to respect API rate limits. When a player requests a price, if the cached price is older than 60 seconds, a new price is fetched from CoinGecko.

Can players trade directly with each other?

Yes! Players can transfer cryptocurrencies to each other using the /crypto transfer command. They can also convert between different cryptocurrencies using /crypto convert.

Are player balances saved?

Yes! All player wallets are automatically saved to plugins/Cryptocurrency/wallets.yml when the server shuts down and loaded when it starts. Balances persist across restarts.

What happens if the API goes down?

The plugin has a built-in circuit breaker. If the API fails repeatedly, it temporarily stops making requests to prevent server lag. After a cooldown period, it automatically tries again. You can check API health with /crypto api status.

Can players lose cryptocurrency?

Players can only lose crypto through:

Cryptocurrency values fluctuate with real market prices, so the USD value can go up or down.

Economy & Trading

How is the exchange rate calculated?

The plugin uses real-time prices from CoinGecko (in USD) and converts them to your server currency at a 1:1 ratio. For example, if BTC costs $30,000 USD, players pay $30,000 server currency to buy 1 BTC.

Can I change the exchange rate?

Currently, the exchange rate is fixed at 1:1 (USD to server currency). Custom multipliers are planned for a future version.

Is there a fee for trading?

No trading fees are applied by default. However, you could implement custom fees by modifying the plugin or using another plugin to tax transactions.

Can players go negative in their wallet?

No, all trading commands check that players have sufficient balance before allowing transactions.

What if a player doesn't have enough server currency?

The buy command checks the player's Vault balance before executing. If they don't have enough money, the transaction is cancelled with an error message.

How do conversions work?

When converting from one crypto to another (e.g., BTC to ETH), the plugin:

  1. Fetches the current price of both cryptocurrencies
  2. Converts the source amount to USD value
  3. Converts the USD value to the target cryptocurrency
  4. Updates both balances atomically

Administration

How do I give cryptocurrency to a player?

Use the admin commands:

/crypto add [player] [symbol] [amount]    # Add to existing balance
/crypto set [player] [symbol] [amount]    # Set exact amount

How do I remove cryptocurrency from a player?

/crypto remove [player] [symbol] [amount]

Can I do a server-wide airdrop?

Yes! Use the giveall command to distribute crypto to all online players:

/crypto giveall [symbol] [amount]

How do I reset a player's wallet?

Set all their balances to 0 using the set command for each cryptocurrency, or edit wallets.yml directly (requires server restart).

Can I see all player balances?

Use the top command to see a leaderboard of top investors:

/crypto top

For specific players, use:

/crypto balance [player]

How do I backup player data?

Simply backup the file plugins/Cryptocurrency/wallets.yml. You can also backup the entire plugins/Cryptocurrency/ folder to preserve configuration.

Troubleshooting

Prices aren't updating

Possible causes:

Solutions:

Players get "insufficient balance" errors

This means they don't have enough of that cryptocurrency in their wallet. Check their balance with /crypto balance [player].

Market GUI doesn't open

Check:

Commands don't work

Check:

Wallets reset after restart

This means wallets aren't being saved properly. Check:

Performance issues / Server lag

Optimization tips:

Advanced Topics

Can I integrate this with other plugins?

Yes! See the API & Developer Guide for information on integrating with CryptocurrencyMC. You can also use PlaceholderAPI placeholders in other plugins.

Can I add custom cryptocurrencies?

You can only add cryptocurrencies that are available on CoinGecko. The plugin fetches real market data, so custom/fictional currencies aren't supported.

Can I change the currency format?

Yes! Edit the placeholder formats in config.yml:

placeholders:
  format:
    money: "#,##0.00"      # USD format
    quantity: "#,##0.####"  # Crypto amount format

Can I use this plugin offline?

No, an internet connection is required to fetch real-time cryptocurrency prices from CoinGecko. Without internet, price fetching will fail and trading will not work.

Is there a limit to how much crypto a player can own?

No hard limit is enforced by the plugin. However, be aware that very large numbers may have floating-point precision issues (values are stored as doubles).

Can I run multiple servers with shared wallets?

No, wallet data is stored locally in each server's wallets.yml file. Shared wallet support (via MySQL) could be added in a future version.

Security & Privacy

Is my server data sent anywhere?

The plugin only sends HTTP requests to CoinGecko's public API to fetch cryptocurrency prices. No player data, server information, or wallet balances are transmitted.

Are there any security risks?

As with any plugin, risks exist if:

Follow standard Minecraft server security practices.

Can players exploit the economy?

The plugin includes checks to prevent common exploits:

However, always monitor your economy and review transaction logs.

Support & Contribution

I found a bug. Where do I report it?

Please report bugs on the GitHub repository:

Include:

Can I request a feature?

Yes! Open a feature request on GitHub Issues. Popular requests will be considered for future versions.

Can I contribute to the project?

Absolutely! The project is open-source. You can:

Where can I get help?

Is there a Discord server?

Check the GitHub repository for the latest community links and support channels.

Future Plans

Features planned for future versions:

💡 Want to see a specific feature? Request it on GitHub Issues!