Skip to main content
This page covers currencies in config.yml. For a first installation, follow installation and configuration, then configure the actual source of each currency.

Configuration example

For example, an integer PlayerPoints currency:

Providers and safe ranges

External economy providers are vault, playerpoints, coinsengine, and excellenteconomy. Native experience and item currencies are covered below. Vault requires vault-provider to match the actual Economy service name; the latter two need their native currency ID. Do not copy unverified version numbers or expose the same external currency twice. maximum is in minor units and must fit the backend’s safe range. For external adapters, keep certified-versions empty until you have tested a specific version in isolation; an empty list disables transfers. This allowlist is not an official certification report. See wallets for gateway and recovery behavior.

Native experience and item configuration

Native providers do not require a third-party economy plugin. All three require scale: 0, and the gateway must still match an actual node: Experience-points example:
Merge this under the existing currencies key and select the actual gateway node. For levels, use experience-level and set maximum within the actual safe level range, removing the points mode. Points and levels do not have a linear exchange rate. An item currency’s item-sample must be a Bukkit-serialized real ItemStack retaining its name, Lore, enchantments and other properties. A material name or item-sample: EMERALD cannot replace that sample. denomination must be a positive integer no greater than the currency’s maximum. The plugin derives native-id from the complete sample fingerprint and denomination; do not invent a fingerprint. With denomination: 10, one matching sample represents ten minor units. Eight items deposit 80 and withdrawing 30 returns three items. Deposits and withdrawals must both be multiples of the denomination. Same-material items with different properties do not count, and withdrawals respect normal stack limits and actual inventory space. Native gateways have no third-party economy-plugin version to list. Check actual transfers on the target server. Offline or dead players, missing samples, changed identities and insufficient space block affected operations without switching providers.
Active currency IDs, providers, precision, samples and denominations are not interchangeable configuration labels. Plan migration and reconciliation before replacing an identity that existing funds depend on. Display names can be customized separately.

Fees and permitted currencies

fees.rules selects fees by currency, trade type, permission and declarative item conditions. Fixed amounts use the currency’s minor units: 100 means 1.00 with scale: 2 and 100 with scale: 0. Display formatting does not change this meaning. policy.limits can restrict currencies, quantity, prices, duration, order count and cooldown by permission. GUI, commands and restricted developer requests share these checks; hiding a currency in a theme is not a trading restriction.

Fees, restrictions and funds

See fee snapshots, partial-fill allocation, permission rules and fresh confirmation after top-up.

Currency display names

Display names are separate from internal currency IDs. Language files provide currency-names.coins, currency-names.points and labels for custom IDs under currency-names.<currency-id>; edit each language file and run /km reload. You may instead explicitly configure:
Merge this into the existing points configuration without replacing its economy settings. display-name accepts a shared string or bilingual map and takes precedence over language-file names. An omitted locale uses its language-file label, then the internal ID if no label is defined. Listings, confirmations and wallets use the display name without appending the internal ID.

Reloads and restarts

Names do not change wallets, precision, native currencies or network identity. Changes under currencies still require a full restart. Prefer language files for label-only edits.