Vault Economy Bridge Setup Guide: Linking EssentialsX, CMI and Shop Plugins

Vault is one of the most important plugins on any economy server, but it is also one of the most misunderstood. Vault does not provide an economy, permissions system or chat formatting by itself. It is a bridge — an API layer that lets shop plugins, jobs plugins and virtually every plugin that handles money talk to whichever economy plugin you have installed, without being hard-coded to a specific one. This guide explains how Vault works, how to link it to your economy and permissions plugins, and how to diagnose problems when money is not flowing correctly.

What Vault actually does

When ShopGUIPlus needs to charge a player $50, it does not call EssentialsX directly. It calls the Vault economy API: Economy.withdrawPlayer(player, 50.0). Vault then forwards that call to whichever plugin has registered itself as the economy provider. This means:

• You can swap from EssentialsX economy to CMI without reconfiguring ShopGUIPlus, AuctionHouse or Jobs Reborn.
• Plugin developers only need to support the Vault API once, not every economy plugin individually.
• If no economy provider is registered, all economy calls return false and players can buy everything for free.

Vault provides three APIs: Economy, Permission (for checking groups and permissions in code), and Chat (for getting prefixes/suffixes). Most plugins use Economy. Some chat formatters use Chat. Virtually no plugin needs the Permission API directly when LuckPerms is installed.

Installation

Drop Vault into plugins/ and restart. Vault has no configuration file — it just sits there waiting for providers to register. Confirm Vault is running with /vault-info or just check the startup log for:

[Vault] Enabling Vault v1.7.3-b131
[Vault] [Economy] Essentials found: Waiting

Linking EssentialsX as the economy provider

Install EssentialsX (the core jar, not just EssentialsXChat or EssentialsXSpawn). On startup, EssentialsX automatically registers itself with Vault. You should see:

[Vault] [Economy] Essentials Economy hooked

No configuration needed. EssentialsX economy is now the Vault provider. Test it:

/eco give YourName 1000
/balance

If /balance shows the amount, Vault is wired correctly.

Linking CMI as the economy provider

CMI also auto-registers with Vault on startup, but only if you have CMI economy enabled in plugins/CMI/config.yml:

Economy:
  Enabled: true
  StartAmount: 500.0
  MaxBalance: 10000000000.0

Critical: Do not install both EssentialsX economy and CMI economy simultaneously. Both will try to register as the Vault provider, and whichever one loads first wins — leaving the other's commands disconnected from the economy other plugins see. Pick one and disable or remove the other:

• To use CMI economy: remove EssentialsX from the plugins/ folder, or disable EssentialsX economy by removing the EssentialsX jar and using only EssentialsXChat and EssentialsXSpawn.
• To use EssentialsX economy: disable CMI economy in CMI's config.

Checking which provider is active

/vault-info

This command shows the active Economy, Permissions and Chat providers. If Economy shows None, no provider has registered — players can buy items for free from any shop plugin.

Common reasons for no economy provider:

• EssentialsX is not installed (only EssentialsXChat is present).
• CMI economy is disabled in config.
• Both EssentialsX and CMI are installed and conflicting — one loaded but did not register, or registered too late.
• The economy plugin crashed during startup before it could register.

Linking LuckPerms as the permissions provider

LuckPerms automatically registers with Vault's Permissions API on startup. You should see:

[Vault] [Permission] LuckPerms found: Waiting
[Vault] [Permission] LuckPerms hooked.

Some older plugins use Vault's Permission API to check player groups (e.g. Permission.getPrimaryGroup(player)). This will now return the LuckPerms primary group. If you see group checks failing, verify LuckPerms is hooked by checking /vault-info.

Linking LuckPerms as the chat provider

LuckPerms also registers as the Vault Chat provider, exposing prefixes and suffixes set via /lp group meta setprefix. EssentialsXChat and many other chat formatters read prefixes through the Vault Chat API, so the chain is:

LuckPerms prefix → Vault Chat API → EssentialsXChat format → player sees prefix in chat

If chat prefixes are not showing up, verify this chain:

1. /vault-info shows LuckPerms as Chat provider.
2. /lp group vip meta info shows a prefix is set.
3. EssentialsX config.yml has add-prefix-suffix: true.
4. EssentialsXChat is installed (not just the core EssentialsX jar).

Vault with ShopGUIPlus

ShopGUIPlus reads buy and sell prices from its shops.yml and calls Vault for every transaction. If transactions fail silently (players click buy but nothing happens and no money is deducted), the cause is almost always:

• No economy provider registered in Vault.
• The player has insufficient balance (ShopGUIPlus shows an insufficient funds message — if even that is missing, the economy hook is broken).
• ShopGUIPlus is running an outdated version incompatible with the installed Vault version.

In ShopGUIPlus config.yml, confirm:

economy:
  plugin: Vault     # must be "Vault", not "Essentials" or "CMI"

Vault with Jobs Reborn

Jobs Reborn pays players through Vault. Configure income in plugins/Jobs/Jobs/ job config files. The relevant section in each job YAML:

Jobs:
  Miner:
    payment:
      min-income: 0.1
      max-income: 1.0
    Blocks:
      DIAMOND_ORE:
        break:
          income: 8.0

If players are doing jobs but not receiving money, check /vault-info first — this is always the first diagnostic step.

Multiple currency — Vault limitations

Vault's economy API only supports a single currency. If you want a second currency (tokens, gems, shards) alongside the main balance, you have two options:

• Use a plugin like PlayerPoints which manages its own point system entirely outside Vault.
• Use TheNewEconomy (TNE) which provides multi-currency support through an extended Vault API.

ShopGUIPlus, CrazyVouchers and many other plugins have native multi-currency support that bypasses Vault entirely for secondary currencies.

Debugging checklist

1. Run /vault-info — confirm all three providers (Economy, Permission, Chat) show non-null values.
2. Check server startup log — look for "[Vault] [Economy] <Plugin> hooked".
3. Give yourself $0 and try buying from a shop — if nothing happens, the Vault hook is broken.
4. Check for plugin startup errors in the log — a plugin that crashes during init does not register with Vault.
5. Ensure Vault is loading before economy plugins (Vault should generally load first as it has no dependencies; if not, add it to load-before in problematic plugins).

Need hosting with full config access? Astroworld Hosting — Pterodactyl panel, NVMe SSDs, 24/7 support.