Each currency has a stable ID, scale, native mapping, and transfer gateway. Changing an active currency’s scale or provider requires migration and reconciliation; it is not a normal rename. There is no automatic currency exchange.
Player interfaces use display names such as “Coins” or “Points” without appending internal IDs. Customize each locale’s
currency-names.<currency-id> or an explicit shared/bilingual currencies.<currency-id>.display-name. Labels do not change balances or economy identity; see the configuration guide for precedence and reload behavior.
Amount input and actual limits
The currency page queries both the market wallet and the local economy backend’s actual balance. Amount input offers increments, presets, a maximum button and custom chat input. The maximum is the minimum of these limits, calculated in the currency’s minor units:
Reserved funds cannot be withdrawn. When a backend cannot quote its receive capacity, the quote uses other known limits and the backend still validates execution; this does not mean it can receive unlimited funds. Failed balance queries report the reason and block transfers without inventing a zero balance or maximum amount.
Opening amount input, entering confirmation and executing the transfer query again. If changed funds or receive capacity make the amount too large, choose it again. After depositing funds, refresh and reconfirm the original trade as well. Only the compatible local gateway handles external balances; changing nodes does not silently call another server.
Gateway node
Assign agateway to each currency, matching the target node’s network.node-id. Players must switch to that node to deposit or withdraw. There is no automatic remote RPC forwarding. Another node returns GATEWAY_NODE; market funds and internal trading remain shared.
A Folia node without a certified economy backend can still participate in internal trading, while a compatible Paper node on the same Minecraft version handles transfers. Gateway downtime pauses transfers for that currency; other nodes must not start debiting it directly.
Enabling an adapter
certified-versions must contain the target plugin versions you have actually validated. An empty list blocks transfers. For vault, list the Vault version itself, pin the actual Economy service name with vault-provider, and independently test that economy implementation. This is an operator allowlist; entering a version does not create official KiteMC certification. Folia providers are blocked by default unless verified; do not set certified-folia: true merely to bypass checks.
Test deposits, withdrawals, insufficient funds, precision and amount limits, backend cancellation/failure, disconnects, restarts, and concurrent external changes. See the configuration example and certification matrix.
Failure and UNKNOWN
A rejected external call is handled according to its operation state, including release of reservations where appropriate. An uncertain result becomesUNKNOWN and must not be called again automatically. Administrators need external evidence and market operation records; the player’s current balance alone does not prove a historical transfer.
Some backends update memory before asynchronously persisting it. API success is not a cross-system commit. Internal market transactions do not guarantee automatic recovery of external transfers across every process crash. Keep untested backend combinations disabled.