EzEconomy

EzEconomy is a professional-grade Vault economy provider for Minecraft servers. Choose from YML, MySQL, SQLite, MongoDB, or custom storage with multi-currency support, async caching, and thorough permission controls.

Runtime Compatibility Matrix

Quick Pick

Your runtime	Download this Bukkit jar	Notes
Java 17 + MC `1.17.x`-`1.20.x`	`ezeconomy-bukkit-<version>-legacy.jar`	Uses Adventure `4.26.1`, Paper API `26.1.x`
Java 21+ + MC `1.21.x`	`ezeconomy-bukkit-<version>-modern.jar`	Uses Adventure `5.2.0`, Paper API `26.2.x`

Keep only one EzEconomy Bukkit jar in your plugins/ folder.

Java 17 runtime: Minecraft 1.17.x through 1.20.x
Java 21+ runtime: Minecraft 1.21.x (1.21.11 currently validated in CI)
Paper API branches validated by lane:
- Java 17 artifact lane (-legacy jar): 26.1.x
- Java 21+ artifact lane (-modern jar): 26.2.x
Note: legacy/modern labels apply to runtime artifact lanes, not to Paper API age.
Bukkit release artifacts:
- ezeconomy-bukkit-<version>-legacy.jar for Java 17 / MC 1.17.x through 1.20.x
- ezeconomy-bukkit-<version>-modern.jar for Java 21+ / MC 1.21.x
Both artifacts are published in each GitHub Release.

Documentation

Overview: General introduction and architecture
Commands: Command usage and permissions
Configuration: All configuration options
Developer API: API usage for plugin developers
Permissions: Permission nodes and details
Placeholders: PlaceholderAPI integration
Storage: Storage backends and setup
Features - Multi-currency: Configure multiple currencies
Features - Banking: In-plugin bank accounts and permissions
Features - Money formatting: Presentation options, locales, compact formats, and placeholders
Cross-server messaging: Velocity, BungeeCord, and Redis cross-server transports
Caching strategy: LOCAL, REDIS, BUNGEECORD, DATABASE options
Locking strategy and options: How to choose LOCAL vs REDIS and what each means
Velocity integration: Velocity proxy setup for cross-server messaging
BungeeCord integration: BungeeCord proxy locking and messaging
Proxy & Redis notes: Redis and proxy operational notes

Do you get the message "Missing message: ..."? Please check the latest available translations: https://github.com/ez-plugins/EzEconomy/tree/main/src/main/resources/languages

Key Features

EzEconomy is designed for performance, reliability, and operational clarity. Highlights include:

Vault API compatible: Works with any Vault-based plugin
YML, MySQL, SQLite, MongoDB, or custom storage: Flexible, production-ready storage options
Thread-safe: Robust error handling and concurrency controls
Multi-currency support: Optional, per-player, fully configurable
Cross-server messaging: Payment notifications and player lists via Velocity, BungeeCord, or Redis pub/sub
Distributed locking: LOCAL, REDIS, or BUNGEECORD lock strategies for multi-server safety
Async caching: Optimised for large servers
Comprehensive commands: /balance, /eco, /baltop, /bank, /pay, /currency
Granular permissions: Per-command and per-bank action

Commands

/balance: View your balance
/balance : View another player's balance (ezeconomy.balance.others)
/eco gui: Open the /eco administrative GUI (if enabled). Permission: ezeconomy.eco.gui (default: allowed for everyone).
/eco give [currency]: Add funds to a player. Optional currency (multi-currency). Permission: ezeconomy.eco.give (or the umbrella ezeconomy.eco).
/eco take [currency]: Remove funds from a player. Optional currency (multi-currency). Permission: ezeconomy.eco.take (or the umbrella ezeconomy.eco).
/eco set [currency]: Set a player's balance. Optional currency (multi-currency). Permission: ezeconomy.eco.set (or the umbrella ezeconomy.eco).
/baltop [amount]: Show top balances
/bank <create|delete|balance|deposit|withdraw|addmember|removemember|info> ...: Bank management (ezeconomy.bank)
/pay : Send funds to another player (ezeconomy.pay)
/pay * : Send funds to all online players (requires ezeconomy.payall; configurable via pay.pay_all in config.yml). See Commands for details.
/currency [currency]: Set or view your preferred currency

Permissions

ezeconomy.balance.others: View other players' balances
ezeconomy.eco: Use /eco admin command
ezeconomy.pay: Use /pay command
ezeconomy.currency: Use /currency command
ezeconomy.eco: Legacy umbrella admin permission (still supported)
ezeconomy.eco.give: Permission for /eco give
ezeconomy.eco.take: Permission for /eco take
ezeconomy.eco.set: Permission for /eco set
ezeconomy.eco.gui: Permission to open the /eco GUI (default: allowed for everyone)
ezeconomy.pay: Use /pay command
ezeconomy.currency: Use /currency command
Bank Permissions:
- ezeconomy.bank.create: Create a new bank
- ezeconomy.bank.delete: Delete a bank
- ezeconomy.bank.balance: View bank balance
- ezeconomy.bank.deposit: Deposit to a bank
- ezeconomy.bank.withdraw: Withdraw from a bank
- ezeconomy.bank.addmember: Add a member to a bank
- ezeconomy.bank.removemember: Remove a member from a bank
- ezeconomy.bank.info: View bank info
- ezeconomy.bank.admin: All bank admin actions

Security Notes for Server Owners

Limit admin permissions: Only grant ezeconomy.eco and ezeconomy.bank.admin to trusted staff.
Use a permissions plugin: Manage access with groups/roles so players cannot self-assign economy powers.
Lock down database access: Use a dedicated database user with minimal privileges and keep credentials private.
Back up economy data: Schedule regular backups of your storage files or database to recover from mistakes or exploits.
Review bank permissions: Consider limiting bank creation/withdraw permissions to prevent abuse on public servers.

Dupe Prevention Safeguards

Thread-safe balance updates: Economy operations are designed to avoid race conditions during concurrent deposits, withdrawals, and transfers.
Server-side validation: Commands and transactions validate amounts to prevent invalid or malformed requests.
Storage integrity: Backends use consistent write patterns to reduce the risk of partial or conflicting balance writes.

Configuration Example

`config.yml` (Only global settings):

storage: yml
multi-currency:
  enabled: false
  default: "dollar"
  currencies:
    dollar:
      display: "Dollar"
      symbol: "$"
      decimals: 2
    euro:
      display: "Euro"
      symbol: ""
      decimals: 2
    gem:
      display: "Gem"
      symbol: ""
      decimals: 0
  conversion:
    dollar:
      euro: 0.95
      gem: 0.01
    euro:
      dollar: 1.05
      gem: 0.012
    gem:
      dollar: 100
      euro: 80

`config-yml.yml` (YML storage settings):

yml:
  file: balances.yml
  per-player-file-naming: uuid
  data-folder: data

`config-mysql.yml` (MySQL storage settings):

mysql:
  host: localhost
  port: 3306
  database: ezeconomy
  username: root
  password: password
  table: balances

`config-sqlite.yml` (SQLite storage settings):

sqlite:
  file: ezeconomy.db
  table: balances
  banksTable: banks

`config-mongodb.yml` (MongoDB storage settings):

mongodb:
  uri: mongodb://localhost:27017
  database: ezeconomy
  collection: balances
  banksCollection: banks

Installation

Place the correct Bukkit artifact in your plugins folder and rename if desired:

Java 17 servers: ezeconomy-bukkit-<version>-legacy.jar
Java 21+ servers: ezeconomy-bukkit-<version>-modern.jar
Keep only one EzEconomy Bukkit jar on a server at a time.

Configure config.yml and the appropriate config-*.yml file for your storage type
Restart your server

- Integration

EzEconomy automatically registers as a Vault provider
No extra setup required for Vault-compatible plugins
PlaceholderAPI support:
- Use placeholders in chat, scoreboard, and other plugins:
  - %ezeconomy_balance% Your balance
  - %ezeconomy_balance_<currency>% Your balance in a specific currency (e.g., %ezeconomy_balance_euro%)
  - %ezeconomy_bank_<bank>% Balance of a specific bank
  - %ezeconomy_top_1% Top 1 player balance (replace 1 with rank)
  - %ezeconomy_currency% Your preferred currency
- Works with all PlaceholderAPI-compatible plugins

Developer: Custom Storage Providers

EzEconomy supports custom storage backends (YML, MySQL, SQLite, MongoDB, or your own). You can implement your own provider for any database or storage system.

How to add a custom provider:

Implement the StorageProvider interface in your plugin or module.

Register your provider before EzEconomy loads:

EzEconomy.registerStorageProvider(new YourProvider(...));

Only one provider can be registered. If set, EzEconomy will use it instead of YML/MySQL.
See the JavaDoc in StorageProvider.java for required methods.

This allows you to use SQLite, MongoDB, Redis, or any other system for player balances and banks.

Name		Name	Last commit message	Last commit date
.github		.github
com/github/ezframework/jaloquent/model		com/github/ezframework/jaloquent/model
docs		docs
ezeconomy-bukkit		ezeconomy-bukkit
ezeconomy-bungeecord-proxy		ezeconomy-bungeecord-proxy
ezeconomy-bungeecord		ezeconomy-bungeecord
ezeconomy-papi		ezeconomy-papi
ezeconomy-redis		ezeconomy-redis
ezeconomy-velocity		ezeconomy-velocity
src		src
tools/economy-benchmark-harness		tools/economy-benchmark-harness
.gitignore		.gitignore
.markdownlint.yml		.markdownlint.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pom.xml		pom.xml

Navigation Menu

Repository files navigation

EzEconomy

Runtime Compatibility Matrix

Quick Pick

Documentation

Key Features

Commands

Permissions

Security Notes for Server Owners

Dupe Prevention Safeguards

Configuration Example

`config.yml` (Only global settings):

`config-yml.yml` (YML storage settings):

`config-mysql.yml` (MySQL storage settings):

`config-sqlite.yml` (SQLite storage settings):

`config-mongodb.yml` (MongoDB storage settings):

Installation

- Integration

Developer: Custom Storage Providers

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

EzEconomy

Runtime Compatibility Matrix

Quick Pick

Documentation

Key Features

Commands

Permissions

Security Notes for Server Owners

Dupe Prevention Safeguards

Configuration Example

config.yml (Only global settings):

config-yml.yml (YML storage settings):

config-mysql.yml (MySQL storage settings):

config-sqlite.yml (SQLite storage settings):

config-mongodb.yml (MongoDB storage settings):

Installation

- Integration

Developer: Custom Storage Providers

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`config.yml` (Only global settings):

`config-yml.yml` (YML storage settings):

`config-mysql.yml` (MySQL storage settings):

`config-sqlite.yml` (SQLite storage settings):

`config-mongodb.yml` (MongoDB storage settings):