> For the complete documentation index, see [llms.txt](https://tne.gitbook.io/tne-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tne.gitbook.io/tne-docs/developers/creating-custom-balance-handlers.md).

# Creating Custom Balance Handlers

## Creating a Custom HoldingsHandler for TheNewEconomy

TheNewEconomy allows developers to extend its functionality by creating custom `HoldingsHandler` implementations. These handlers enable the integration of various storage sources for player holdings, such as virtual wallets, inventory, experience levels, or external systems like banks.

***

### What is a HoldingsHandler?

A `HoldingsHandler` is an interface that provides methods to:

1. Set holdings for a player or account.
2. Retrieve holdings from a specific source.
3. Determine whether the handler supports specific currencies or accounts.

***

### Steps to Create a Custom HoldingsHandler

#### 1. **Implement the HoldingsHandler Interface**

Your custom class must implement the `HoldingsHandler` interface. Below is a template example:

```java
import net.tnemc.core.account.Account;
import net.tnemc.core.account.holdings.HoldingsEntry;
import net.tnemc.core.account.holdings.HoldingsHandler;
import net.tnemc.core.currency.Currency;
import net.tnemc.core.currency.CurrencyType;
import net.tnemc.core.utils.Identifier;

import java.math.BigDecimal;

public class CustomHandler implements HoldingsHandler {

  @Override
  public Identifier identifier() {
    return new Identifier("custom_handler"); // Unique identifier for this handler
  }

  @Override
  public boolean supports(Currency currency, CurrencyType type) {
    // Define the logic for supported currencies or types
    return true;
  }

  @Override
  public boolean setHoldings(Account account, String region, Currency currency, CurrencyType type, BigDecimal amount) {
    // Define how holdings are stored for the account
    return true;
  }

  @Override
  public HoldingsEntry getHoldings(Account account, String region, Currency currency, CurrencyType type) {
    // Define how holdings are retrieved for the account
    return new HoldingsEntry(region, currency.getUid(), BigDecimal.ZERO, identifier());
  }
}
```

***

#### 2. **Register the Handler with TNE**

After implementing the `HoldingsHandler` interface, register your custom handler with TNE:

```java
TNECore.eco().addHandler(new CustomHandler());
```

This ensures that TNE uses your handler when interacting with supported currencies or account types.

***

### Example Implementations

#### EnderChestHandler

The `EnderChestHandler` manages holdings stored in a player's Ender Chest:

```java
@Override
public boolean setHoldings(Account account, String region, Currency currency, CurrencyType type, BigDecimal amount) {
  account.getWallet().setHoldings(new HoldingsEntry(region, currency.getUid(), amount, identifier()));
  // Logic to update items in Ender Chest
  return true;
}
```

#### ExperienceHandler

The `ExperienceHandler` handles player holdings based on their experience points:

```java
@Override
public boolean setHoldings(Account account, String region, Currency currency, CurrencyType type, BigDecimal amount) {
  if(account instanceof PlayerAccount player && player.isOnline()) {
    Experience.setExperience(player.getPlayer().get(), amount.intValueExact());
  }
  return true;
}
```

***

### Key Points

1. **Identifier**: Each handler must have a unique identifier returned by the `identifier()` method.
2. **Compatibility**: Use the `supports()` method to restrict the handler to specific currencies or types.
3. **Data Handling**: Decide whether holdings should be saved in TNE's database or managed externally via the `database()` method.
4. **Integration**: Handlers can interact with specific storage systems, such as inventory or external databases.

***

### Notes

* Use existing handlers like `VirtualHandler`, `InventoryHandler`, or `ExperienceHandler` as references.
* Always register your custom handler with `TNECore.eco().addHandler()` to make it active in TNE.

***

By creating a custom `HoldingsHandler`, you can expand TheNewEconomy to integrate with diverse systems and provide unique gameplay experiences.