# Currencies API

### Overview

The currency system supports multiple custom currencies with configurable properties like maximum values, starting amounts, and display names. All currency operations use BigDecimal for precise handling of large numbers and decimal values.

***

### Balance Operations

#### Balance Retrieval

**`BigDecimal getCurrency(UUID uuid, String currency)`**

* **Description:** Gets a player's current balance for a specific currency
* **Parameters:**
  * `uuid` - Player's unique identifier
  * `currency` - Currency identifier (e.g., "money", "gems", "tokens")
* **Returns:** Current balance as BigDecimal
* **Usage:** Check player funds, display balances, transaction validation

#### Balance Modification

**`void setCurrency(UUID uuid, String currency, BigDecimal amount)`**

* **Description:** Sets a player's balance to a specific amount
* **Parameters:**
  * `uuid` - Player's unique identifier
  * `currency` - Currency identifier
  * `amount` - New balance amount
* **Usage:** Administrative balance setting, account resets, initialization

**`void addCurrency(UUID uuid, String currency, BigDecimal amount)`**

* **Description:** Adds currency to a player's balance
* **Parameters:**
  * `uuid` - Player's unique identifier
  * `currency` - Currency identifier
  * `amount` - Amount to add (positive values)
* **Usage:** Reward distribution, earning money, balance increases

**`void removeCurrency(UUID uuid, String currency, BigDecimal amount)`**

* **Description:** Removes currency from a player's balance
* **Parameters:**
  * `uuid` - Player's unique identifier
  * `currency` - Currency identifier
  * `amount` - Amount to remove (positive values)
* **Usage:** Purchases, penalties, transaction costs

***

### Currency Validation

**`void isCurrency(String currency)`**

* **Description:** Validates if a currency identifier exists in the system
* **Parameters:** `currency` - Currency identifier to validate
* **Usage:** Input validation, configuration checking
* **Note:** Method name suggests boolean return, but signature shows void - check implementation

***

### Currency Configuration

#### Limits and Constraints

**`double getMaxCurrencyValue(String currency)`**

* **Description:** Gets the maximum allowed value for a currency
* **Parameters:** `currency` - Currency identifier
* **Returns:** Maximum value (0.0 for unlimited)
* **Usage:** Validate transactions, prevent overflow, display limits

**`double getStartingCurrencyValue(String currency)`**

* **Description:** Gets the default starting amount for new players
* **Parameters:** `currency` - Currency identifier
* **Returns:** Starting balance amount
* **Usage:** Initialize new player accounts, reset balances

#### Display Information

**`String getCurrencyName(String currency)`**

* **Description:** Gets the display name for a currency
* **Parameters:** `currency` - Currency identifier
* **Returns:** Human-readable currency name
* **Usage:** User interfaces, transaction messages, display formatting

***

### Usage Examples

#### Basic Balance Operations

```java
EdDungeonsCurrencyAPI currencyAPI = EdDungeonsAPI.getInstance().getCurrencyAPI();
UUID playerUUID = player.getUniqueId();

// Check player's money balance
BigDecimal balance = currencyAPI.getCurrency(playerUUID, "money");
player.sendMessage("§6Balance: §f" + balance + " " + 
    currencyAPI.getCurrencyName("money"));

// Add money reward
BigDecimal reward = new BigDecimal("1000");
currencyAPI.addCurrency(playerUUID, "money", reward);
player.sendMessage("§a+1000 money!");

// Check if player can afford something
BigDecimal cost = new BigDecimal("500");
BigDecimal currentBalance = currencyAPI.getCurrency(playerUUID, "money");
if (currentBalance.compareTo(cost) >= 0) {
    currencyAPI.removeCurrency(playerUUID, "money", cost);
    player.sendMessage("§aPurchase successful!");
} else {
    player.sendMessage("§cInsufficient funds!");
}
```