API & Developer Guide

This guide is for developers who want to integrate with CryptocurrencyMC or extend its functionality.

Maven/Gradle Dependency

Add CryptocurrencyMC as a dependency to your plugin project.

Maven

<dependencies>
    <dependency>
        <groupId>fr.jachou</groupId>
        <artifactId>cryptocurrency</artifactId>
        <version>1.0-SNAPSHOT</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle

dependencies {
    compileOnly 'fr.jachou:cryptocurrency:1.0-SNAPSHOT'
}

plugin.yml

Add CryptocurrencyMC as a soft dependency:

name: YourPlugin
version: 1.0
main: com.yourname.yourplugin.YourPlugin
softdepend: [Cryptocurrency]

Getting the Plugin Instance

import fr.jachou.cryptocurrency.Cryptocurrency;
import org.bukkit.plugin.Plugin;

public class YourPlugin extends JavaPlugin {
    private Cryptocurrency cryptoPlugin;
    
    @Override
    public void onEnable() {
        Plugin plugin = getServer().getPluginManager().getPlugin("Cryptocurrency");
        if (plugin instanceof Cryptocurrency) {
            cryptoPlugin = (Cryptocurrency) plugin;
            getLogger().info("Hooked into CryptocurrencyMC!");
        } else {
            getLogger().warning("CryptocurrencyMC not found!");
        }
    }
}

Using the Wallet Manager

The WalletManager handles all player wallet operations.

Get Balance

import fr.jachou.cryptocurrency.services.WalletManager;
import java.util.UUID;

WalletManager walletManager = cryptoPlugin.getWalletManager();
UUID playerUuid = player.getUniqueId();

// Get balance for a specific cryptocurrency
double btcBalance = walletManager.get(playerUuid, "BTC");
double ethBalance = walletManager.get(playerUuid, "ETH");

Set Balance

// Set exact amount
walletManager.set(playerUuid, "BTC", 1.5);
walletManager.set(playerUuid, "ETH", 50.0);

Add to Balance

// Add to existing balance
walletManager.add(playerUuid, "BTC", 0.5);
walletManager.add(playerUuid, "DOGE", 100.0);

Remove from Balance

// Remove from balance (returns true if successful)
boolean success = walletManager.remove(playerUuid, "BTC", 0.25);
if (success) {
    player.sendMessage("Removed 0.25 BTC from your wallet");
} else {
    player.sendMessage("Insufficient balance");
}

Get All Balances

import java.util.Map;

// Get all cryptocurrencies and their balances for a player
Map<String, Double> allBalances = walletManager.getAll(playerUuid);
for (Map.Entry<String, Double> entry : allBalances.entrySet()) {
    String symbol = entry.getKey();
    double amount = entry.getValue();
    player.sendMessage(symbol + ": " + amount);
}

Using the Price Service

The PriceService fetches real-time cryptocurrency prices.

Get Current Price

import fr.jachou.cryptocurrency.services.PriceService;
import java.util.concurrent.CompletableFuture;

PriceService priceService = cryptoPlugin.getPriceService();

// Async price fetch (recommended)
priceService.getPrice("BTC").thenAccept(price -> {
    if (price != null) {
        player.sendMessage("BTC Price: $" + price);
    } else {
        player.sendMessage("Failed to fetch price");
    }
});

Get Multiple Prices

import java.util.Arrays;
import java.util.List;

List<String> symbols = Arrays.asList("BTC", "ETH", "SOL");
priceService.getPrices(symbols).thenAccept(prices -> {
    for (Map.Entry<String, Double> entry : prices.entrySet()) {
        String symbol = entry.getKey();
        Double price = entry.getValue();
        if (price != null) {
            player.sendMessage(symbol + ": $" + price);
        }
    }
});

Check API Status

// Get circuit breaker status
String status = priceService.getCircuitBreakerStatus();
player.sendMessage("API Status: " + status);

Transaction Manager

Record transactions for player history.

Record a Transaction

import fr.jachou.cryptocurrency.services.TransactionManager;

TransactionManager txManager = cryptoPlugin.getTransactionManager();

// Record a custom transaction
txManager.record(
    playerUuid,
    "CUSTOM",           // Transaction type
    "Custom Action",    // Description
    player.getName()    // Actor (who performed it)
);

Transaction Types

• BUY - Cryptocurrency purchase
• SELL - Cryptocurrency sale
• TRANSFER - Player-to-player transfer
• CONVERT - Crypto-to-crypto conversion
• ADMIN - Admin wallet modification
• AIRDROP - Mass distribution
• CUSTOM - Custom transaction type

PlaceholderAPI Integration

Use CryptocurrencyMC placeholders in your plugin.

Available Placeholders

Using Placeholders in Code

import me.clip.placeholderapi.PlaceholderAPI;

// Set placeholders in a string
String message = "You have %crypto_balance_BTC% BTC worth $%crypto_balance_usd_BTC%";
String parsed = PlaceholderAPI.setPlaceholders(player, message);
player.sendMessage(parsed);

Events (Future Feature)

CryptocurrencyMC currently doesn't fire custom events, but this is planned for future versions.

Planned Events

• CryptoTradeEvent - Fired when a player buys or sells crypto
• CryptoTransferEvent - Fired when crypto is transferred between players
• CryptoConvertEvent - Fired when crypto is converted
• WalletUpdateEvent - Fired when a wallet balance changes
• PriceUpdateEvent - Fired when prices are updated

Example Event Handler (Future)

// This is planned for a future version
@EventHandler
public void onCryptoTrade(CryptoTradeEvent event) {
    Player player = event.getPlayer();
    String symbol = event.getSymbol();
    double amount = event.getAmount();
    boolean isBuy = event.isBuy();
    
    if (isBuy) {
        // Handle buy event
    } else {
        // Handle sell event
    }
}

Best Practices

Asynchronous Operations

// Good - Async
priceService.getPrice("BTC").thenAccept(price -> {
    // Run on main thread if needed
    Bukkit.getScheduler().runTask(plugin, () -> {
        player.sendMessage("Price: $" + price);
    });
});

// Bad - Would block main thread if sync method existed
// Never do this!

Error Handling

// Always handle null prices
priceService.getPrice("BTC").thenAccept(price -> {
    if (price == null) {
        player.sendMessage("Unable to fetch price");
        return;
    }
    // Use price
}).exceptionally(throwable -> {
    throwable.printStackTrace();
    player.sendMessage("Error fetching price");
    return null;
});

Balance Checks

// Always check balance before removing
double currentBalance = walletManager.get(playerUuid, "BTC");
double removeAmount = 0.5;

if (currentBalance >= removeAmount) {
    walletManager.remove(playerUuid, "BTC", removeAmount);
    player.sendMessage("Transaction successful");
} else {
    player.sendMessage("Insufficient balance");
}

Example Plugin Integration

Complete example of a plugin that rewards players with crypto for mining blocks:

package com.example.cryptorewards;

import fr.jachou.cryptocurrency.Cryptocurrency;
import fr.jachou.cryptocurrency.services.WalletManager;
import fr.jachou.cryptocurrency.services.TransactionManager;
import org.bukkit.Material;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.block.BlockBreakEvent;
import org.bukkit.plugin.Plugin;
import org.bukkit.plugin.java.JavaPlugin;

public class CryptoRewards extends JavaPlugin implements Listener {
    private Cryptocurrency cryptoPlugin;
    private WalletManager walletManager;
    private TransactionManager txManager;
    
    @Override
    public void onEnable() {
        // Hook into CryptocurrencyMC
        Plugin plugin = getServer().getPluginManager().getPlugin("Cryptocurrency");
        if (plugin instanceof Cryptocurrency) {
            cryptoPlugin = (Cryptocurrency) plugin;
            walletManager = cryptoPlugin.getWalletManager();
            txManager = cryptoPlugin.getTransactionManager();
            
            // Register event listener
            getServer().getPluginManager().registerEvents(this, this);
            
            getLogger().info("CryptoRewards enabled!");
        } else {
            getLogger().severe("CryptocurrencyMC not found! Disabling...");
            getServer().getPluginManager().disablePlugin(this);
        }
    }
    
    @EventHandler
    public void onBlockBreak(BlockBreakEvent event) {
        Player player = event.getPlayer();
        Material blockType = event.getBlock().getType();
        
        // Reward crypto based on block type
        if (blockType == Material.DIAMOND_ORE || blockType == Material.DEEPSLATE_DIAMOND_ORE) {
            // Give 0.001 BTC for diamond ore
            walletManager.add(player.getUniqueId(), "BTC", 0.001);
            txManager.record(
                player.getUniqueId(),
                "MINING_REWARD",
                "Mined diamond ore: +0.001 BTC",
                "CryptoRewards"
            );
            player.sendMessage("§6[CryptoRewards] §aYou earned 0.001 BTC!");
        } else if (blockType == Material.GOLD_ORE || blockType == Material.DEEPSLATE_GOLD_ORE) {
            // Give 0.05 DOGE for gold ore
            walletManager.add(player.getUniqueId(), "DOGE", 0.05);
            txManager.record(
                player.getUniqueId(),
                "MINING_REWARD",
                "Mined gold ore: +0.05 DOGE",
                "CryptoRewards"
            );
            player.sendMessage("§6[CryptoRewards] §aYou earned 0.05 DOGE!");
        }
    }
}

API Documentation

Main Classes

Key Methods

WalletManager

• double get(UUID uuid, String symbol) - Get balance
• void set(UUID uuid, String symbol, double amount) - Set balance
• void add(UUID uuid, String symbol, double amount) - Add to balance
• boolean remove(UUID uuid, String symbol, double amount) - Remove from balance
• Map<String, Double> getAll(UUID uuid) - Get all balances
• void saveToFile(File file) - Save wallets to disk
• void loadFromFile(File file) - Load wallets from disk

PriceService

• CompletableFuture<Double> getPrice(String symbol) - Get single price
• CompletableFuture<Map<String, Double>> getPrices(List<String> symbols) - Get multiple prices
• String getCircuitBreakerStatus() - Get API health status

TransactionManager

• void record(UUID uuid, String type, String details, String actor) - Record transaction

Support & Contributing

If you're developing an integration or extension:

• GitHub: MatisseAD/CryptocurrencyMC
• Issues: Report bugs or request features on GitHub Issues
• Pull Requests: Contributions are welcome!