# API

## API

Read and change balances in any currency from your own plugin, online or offline.

## Maven Repository

```xml
<repositories>
    <repository>
        <id>phoenixplugins</id>
        <url>https://repo.phoenixplugins.com/</url>
    </repository>
</repositories>
```

## Dependency

```xml
<dependency>
    <groupId>com.phoenixplugins.phoenixcurrencies</groupId>
    <artifactId>api</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

## Getting started

Add PhoenixCurrencies to your **plugin.yml** so your plugin loads after it.

```yaml
depend: [PhoenixCurrencies]
```

Use `softdepend` instead if your plugin should still work without it, and check `PhoenixCurrenciesAPI.isAvailable()` before calling anything.

```java
if (!PhoenixCurrenciesAPI.isAvailable()) {
    return;
}

CurrenciesService currencies = PhoenixCurrenciesAPI.get();
```

The same service is registered in Bukkit's services manager, for plugins that look services up there:

```java
CurrenciesService currencies = Bukkit.getServicesManager().load(CurrenciesService.class);
```

| Method | Returns |
| ------ | ------- |
| `getCurrencies()` | Every currency |
| `getCurrency(String id)` | One currency by its id, as an `Optional` |
| `getBalanceExact(UUID player, String currency)` | The player's balance |
| `deposit(UUID player, String currency, BigDecimal amount, String reason)` | Adds to the balance |
| `withdraw(UUID player, String currency, BigDecimal amount, String reason)` | Takes from the balance |
| `setBalance(UUID player, String currency, BigDecimal amount, String reason)` | Sets the balance |
| `transfer(UUID from, UUID to, String currency, BigDecimal amount, String reason)` | Moves an amount from one player to another |
| `has(UUID player, String currency, BigDecimal amount)` | Whether the player has at least that much |
| `findPlayer(String name)` | The UUID of a player who has joined before, as an `Optional` |
| `getCachedBalanceExact(UUID player, String currency)` | The balance if the plugin already has it in memory, without waiting |
| `getTop(String currency, int limit)` | The [leaderboard](../main-features/leaderboards.md), as entries with the rank, UUID, name and balance |
| `getRank(UUID player, String currency)` | The player's place on the leaderboard |
| `isUsableBy(Player player, String currency)` | Whether the player may use the currency where they are |

Every call works on offline players. Calls return a `CompletableFuture` so they never block the main thread: for a player who is online on this server the future is already complete when the call returns, for an offline player it completes once the database answers. The `reason` is shown in the [transaction log](../features/transaction-log.md).

Amounts are exact `BigDecimal`s, cut (never rounded up) to the currency's decimals. Each method also has a `double` version (`getBalance`, `getCachedBalance`, and the same names taking a `double`), kept for older plugins. A `double` loses precision on balances above about 100 billion, so prefer the `BigDecimal` ones.

```java
currencies.withdraw(player.getUniqueId(), "gems", BigDecimal.valueOf(50), "Bought a kit").thenAccept(result -> {
    if (result.isSuccess()) {
        giveKit(player);
    }
});
```

For an offline player the future completes off the main thread. Go back to it with the Bukkit scheduler before touching the world or the player, or on Folia with the player's own scheduler (`player.getScheduler()`). Calling `join()` on a tick thread is instant for online players but waits for the database for offline ones.

## Results

| `TransactionResult` | Means |
| ------------------- | ----- |
| `SUCCESS` | The change went through. |
| `NOT_ENOUGH_MONEY` | The player cannot pay that much. |
| `MAX_BALANCE` | The change would go past the currency's maximum balance. |
| `INVALID_AMOUNT` | The amount is not a positive number. |
| `UNKNOWN_CURRENCY` | No currency has that id. |
| `CANCELLED` | A listener cancelled the change, see [Events](events.md). |
| `FAILED` | The database refused the change. The console has the details. |

## The Currency

| Method | Returns |
| ------ | ------- |
| `getId()`, `getDisplayName()`, `getSymbol()` | The currency's names |
| `getDisplayName(BigDecimal amount)` | The singular name for exactly 1, the plural name otherwise, the display name when either is empty |
| `getDecimals()`, `getStartingBalanceExact()`, `getMaxBalanceExact()` | Its limits. A maximum of -1 is unlimited. |
| `isTransferable()` | Whether players can pay it to each other |
| `format(BigDecimal amount)`, `formatCompact(BigDecimal amount)` | The amount written the currency's way, in full or short |

Leaderboard entries give the balance with `getBalanceExact()`. `getStartingBalance()`, `getMaxBalance()`, `getBalance()` and `format(double)` remain as `double` versions.

## Labelling Transactions

Money your plugin moves can say why it moved. The label shows in the [transaction log](../features/transaction-log.md#reasons-and-details) and in the player's balance history as a reason, a Detail line and your plugin's name under **By**.

```java
PhoenixCurrenciesAPI.labelled("MyPlugin", "kit-purchase", "Kit: Starter", () -> {
    economy.withdrawPlayer(player, price);
});
```

| Method | Does |
| ------ | ---- |
| `PhoenixCurrenciesAPI.labelled(plugin, reason, detail, Runnable)` | Runs the block with the label set. |
| `PhoenixCurrenciesAPI.labelled(plugin, reason, detail, Supplier)` | The same, and returns what the supplier returns. |
| `PhoenixCurrenciesAPI.currentLabel()` | The label active on this thread. |
| `TransactionLabel` | The label itself: the plugin, the reason and the detail. |
| `deposit(UUID player, String currency, BigDecimal amount, String plugin, String reason, String detail)` | Adds to the balance with a label. `CurrenciesService.withdraw` has the same overload, and both also take a `double`. |

The label applies to money calls made on the same thread, inside the block. When the money call happens in a later callback, such as a `thenAccept` or a scheduled task, put `labelled(...)` inside that callback, not around the code that schedules it. Nesting is fine: the innermost label wins, and the outer one comes back when it ends. The label is cleared when the block ends, even when it throws.

The reason is cut to 32 characters and the detail to 128. A reason such as `shop-purchase` or `crate-open` shows as a translated name like Shop Purchase or Crate Opening, and any other reason shows as a readable title. The older four-argument `deposit` and `withdraw` still work and log the reason `api`.

Money moved through Vault with no label shows the calling plugin's name under **By**, with the reason Vault.

Source: https://www.phoenixplugins.com/docs/phoenix-currencies/api