API interface for interacting with EssentialsC's economy system. The economy
is backed by SQLite and maintains an in-memory cache of recently accessed balances.
All methods that touch the database return CompletableFuture —
do not block the main thread waiting on them.
Retrieve an instance via EssentialsCAPI.getEconomyApi().
EconomyApi eco = APIProvider.getAPI().getEconomyApi();
eco.getBalance(player.getUniqueId()).thenAccept(balance -> {
player.sendMessage("Balance: " + eco.format(balance));
});
eco.withdraw(player.getUniqueId(), BigDecimal.valueOf(100))
.thenAccept(success -> {
if (!success) player.sendMessage("Insufficient funds.");
});
Accounts
| CompletableFuture<Boolean> |
hasAccount(UUID uuid) Returns whether an economy account exists for the given player. |
| CompletableFuture<Boolean> |
createAccount(UUID uuid, String name) Creates an account for the given player if one does not already exist. |
Balances
| CompletableFuture<BigDecimal> |
getBalance(UUID uuid) Returns the current balance of the given player. |
| CompletableFuture<Boolean> |
has(UUID uuid, BigDecimal amount) Returns whether the player has at least the specified amount. |
| CompletableFuture<Boolean> |
withdraw(UUID uuid, BigDecimal amount) Withdraws the given amount from the player's account. |
| CompletableFuture<Boolean> |
deposit(UUID uuid, BigDecimal amount) Deposits the given amount into the player's account. |
| CompletableFuture<Boolean> |
setBalance(UUID uuid, BigDecimal amount) Sets the player's balance to exactly the given amount. |
| CompletableFuture<Map<UUID,BigDecimal>> |
getTopBalances(int limit) Returns the top balances across all players, ordered descending. |
Formatting
| String |
format(BigDecimal amount) Formats an amount as a full currency string including the currency name. |
| String |
formatPlain(BigDecimal amount) Formats an amount as a plain number string with no currency name. |
| String |
currencyNameSingular() Returns the singular form of the configured currency name. |
| String |
currencyNamePlural() Returns the plural form of the configured currency name. |
Limits
| BigDecimal |
getMinTransaction() Returns the minimum amount allowed in a single transaction. |
| BigDecimal |
getMaxBalance() Returns the maximum balance a player may hold, or null if uncapped. |
| boolean |
hasMaxBalance() Returns whether a maximum balance cap is configured. |
| BigDecimal |
getStartingBalance() Returns the starting balance given to newly created accounts. |
Vault
| boolean |
isVaultHooked() Returns whether EssentialsC is registered as the active Vault economy provider. |
Returns whether an economy account exists for the given player.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player to check; must not be null |
| CompletableFuture<Boolean> | true if an account exists |
Creates an economy account for the given player if one does not already exist.
The account is initialised with the configured starting balance. If an account already exists this is a no-op and the future resolves false.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| name | the player's current name, used for display purposes; must not be null |
| CompletableFuture<Boolean> | true if the account was newly created, false if it already existed |
Returns the current balance of the given player. Results are served from an in-memory cache when available. Returns BigDecimal.ZERO if no account exists for the UUID.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| CompletableFuture<BigDecimal> | the player's balance; never null |
Returns whether the given player has at least the specified amount.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| amount | the amount to check against; must not be null |
| CompletableFuture<Boolean> | true if the player's balance is greater than or equal to amount |
Withdraws the given amount from the player's account. The future resolves false if the amount is below the minimum transaction threshold, the player does not have sufficient funds, or no account exists for the UUID.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| amount | the amount to withdraw; must be positive |
| CompletableFuture<Boolean> | true on success |
Deposits the given amount into the player's account. The future resolves false if the amount is below the minimum transaction threshold, or the deposit would exceed the configured maximum balance. If no account exists for the UUID, one is created automatically.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| amount | the amount to deposit; must be positive |
| CompletableFuture<Boolean> | true on success |
Sets the player's balance to exactly the given amount. The future resolves false if the amount is negative, exceeds the configured maximum balance, or no account exists for the UUID.
Do not block the main thread waiting on this future.
Parameters:| uuid | the UUID of the player; must not be null |
| amount | the exact balance to set; must be zero or positive |
| CompletableFuture<Boolean> | true on success |
Returns the top balances across all players, ordered descending. The returned map preserves insertion order (highest balance first). Keys are player UUIDs, values are their balances.
Do not block the main thread waiting on this future.
Parameters:| limit | the maximum number of entries to return; must be positive |
| CompletableFuture<Map<UUID,BigDecimal>> | a linked map of UUID to balance, highest first; never null, may be empty |
Formats the given amount as a full currency string including the currency name (e.g. "1,234.56 Dollars" or "1.00 Dollar"). Singular vs. plural is chosen automatically based on the amount.
| amount | the amount to format; must not be null |
| String | the formatted currency string; never null |
Formats the given amount as a plain number string with no currency name appended (e.g. "1,234.56").
| amount | the amount to format; must not be null |
| String | the formatted number string; never null |
Returns the singular form of the configured currency name (e.g. "Dollar").
| String | the singular currency name; never null |
Returns the plural form of the configured currency name (e.g. "Dollars").
| String | the plural currency name; never null |
Returns the minimum amount allowed in a single transaction. Withdraw and deposit calls with an amount below this threshold resolve false without touching the database.
| BigDecimal | the minimum transaction amount; never null, always positive |
Returns the maximum balance a player may hold, or null if there is no cap.
| BigDecimal | the maximum balance, or null if uncapped |
Returns whether a maximum balance cap is configured. Equivalent to getMaxBalance() != null.
| boolean | true if a maximum balance limit is active |
Returns the starting balance given to newly created accounts.
Returns:| BigDecimal | the starting balance; never null, always non-negative |
Returns whether EssentialsC has successfully registered itself as a Vault economy provider.
When true, other plugins using the Vault API will route economy calls through EssentialsC's economy. When false, Vault is either not installed or the hook failed to register.
| boolean | true if the Vault economy hook is active |