🪙Currencies

NetworkEconomy supports any number of currencies. Each one is an independent balance per player, stored as its own row in the balances table, with its own formatting and rules.

Declaring a currency

Every entry under currencies: is a currency, and the config key is its id — the lowercase name used in commands and in the API.

currencies:
  coins:
    display-name: "Coin"
    display-name-plural: "Coins"
    symbol: "$"
    symbol-before: true
    decimals: 2
    starting-balance: 100.0
    payable: true
    default: true
  gems:
    display-name: "Gem"
    display-name-plural: "Gems"
    symbol: "♦"
    symbol-before: false
    decimals: 0
    starting-balance: 0.0
    payable: false
    default: false

Key	Description
display-name	Singular human-readable name
display-name-plural	Plural name. Used in messages like "You do not have enough Coins". Defaults to display-name
symbol	Symbol used when formatting amounts
symbol-before	true renders $1,250.00; false renders 1,250 ♦
decimals	Fractional digits kept. 0 makes the currency whole-number only. Amounts are rounded half-up to this precision
starting-balance	Balance given to a brand-new account, and the value /eco reset restores
payable	Whether players may send it with /pay
default	Marks this as the default currency — the one used when no currency argument is given, and the only one exposed to Vault

The default currency

Exactly one currency is the default: the first one flagged default: true, or simply the first entry if none is flagged.

The default currency is special in two ways:

• It is what every command uses when you omit the currency argument.

• It is the only currency visible through the Vault Economy API. Vault has no concept of multiple currencies, so third-party Vault plugins — shops, jobs, crates — always operate on this one.

Non-default currencies are reachable only through NetworkEconomy's own commands and API. A Vault-based shop plugin cannot charge in gems.

Precision and rounding

Balances are stored as DECIMAL(20,4) in the database and handled as BigDecimal in Java, so arithmetic is exact — no floating-point drift. Amounts are normalised (rounded half-up) to the currency's decimals before being applied.

Because storage keeps 4 decimal places, decimals is a presentation and input precision, not a storage limit. Setting decimals: 0 makes a currency behave as whole units: /pay Notch 2.7 gems becomes 3.

Lowering decimals on a live currency does not rewrite stored balances — existing fractional amounts stay in the database and simply stop being displayed. Decide precision before going live.

Using a currency in commands

Every player-facing command takes an optional currency id as its last argument:

/balance                    # default currency, yourself
/balance gems               # gems, yourself
/balance Notch gems         # gems, another player
/pay Notch 250 coins        # explicit currency
/baltop 2 gems              # page 2 of the gems ranking
/eco give Notch 10 gems     # admin, explicit currency

Tab completion offers currency ids in each of those positions, and /pay only suggests currencies that are payable.

Adding a currency later

Adding a new entry under currencies: is safe at any time. Balance rows are created on demand, so:

• Existing players get the new currency's starting-balance the first time it is touched.

• Nothing is migrated or rewritten.

• Remember to add the currency to the config on every server — a server that does not know an id will fall back to the default currency when resolving command arguments.

Removing a currency from the config does not delete its rows, but it makes those balances unreachable in game. If you also change which currency is default, every Vault plugin on the network silently starts reading and writing a different balance — announce that kind of change carefully.