> For the complete documentation index, see [llms.txt](https://docs.ohalee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ohalee.com/products/networkeconomy/currencies.md).

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

```yaml
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
```

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

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

{% hint style="warning" %}
Non-default currencies are reachable only through NetworkEconomy's own commands and API. A Vault-based shop plugin cannot charge in `gems`.
{% endhint %}

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

{% hint style="danger" %}
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.
{% endhint %}

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

{% hint style="danger" %}
**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.
{% endhint %}