# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tne.gitbook.io/tne-docs/developers/creating-custom-balance-handlers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.