# hShards<\/p>\n
**A lightweight virtual economy plugin that runs alongside your main economy, or replaces it entirely.**<\/p>\n
—<\/p>\n
## What is hShards?<\/p>\n
hShards adds a second currency to your server called Shards (fully renameable). It’s designed to sit next to your existing Vault economy, players keep their regular money for the normal stuff, and Shards become a separate progression currency that they can earn by selling items, receiving them as rewards, trading with other players, or passively through an interest system.<\/p>\n
It can also run in PRIMARY mode and act as your main Vault economy provider if you want, replacing plugins like EssentialsX economy entirely.<\/p>\n
I built this to pair with hShop, but the API is public so other plugins can hook into it to.<\/p>\n
—<\/p>\n
## Features<\/p>\n
– **Dual mode** – run as a secondary currency alongside Vault, or take over as the primary Vault provider
\n– **Player-to-player payments** – `\/pay` command with optional tax and cooldown
\n– **Item selling** – define a shard price for any item and players can sell it via `\/hshards sell` or `\/sellall`
\n– **Leaderboard** – paginated top balance list with a configurable refresh interval and cache size
\n– **Interest system** – automatically give online players a percentage of their balance on a timer
\n– **Max balance cap** – optionally prevent players from holding more then a set amount
\n– **Payment tax** – take a configurable percentage cut from every player-to-player payment
\n– **Transaction logging** – every deposit, withdraw, payment and sell is written to a log file
\n– **YAML or SQLite storage** – choose whichever fits your server size, switchable in config
\n– **PlaceholderAPI support** – full set of placeholders for balances, ranks, leaderboard and more
\n– **Public API** – `HShardsAPI` class lets any plugin get\/set\/deposit\/withdraw shard balances
\n– **Title notifications** – optional screen title when a player receives or loses shards
\n– **Fully customizable messages** – every single message is in `messages.yml` with color code support<\/p>\n
—<\/p>\n
## Requirements<\/p>\n
| Dependency | Required? |
\n|—|—|
\n| Paper 1.21+ | \u2705 Required |
\n| Vault | \u2b50 Soft (required for PRIMARY mode or hShop integration) |
\n| PlaceholderAPI | \u2b50 Soft |
\n| hShop | \u2b50 Soft (required if running in SECONDARY mode) |<\/p>\n
—<\/p>\n
## Modes<\/p>\n
**SECONDARY** *(default)* – hShards doesn’t touch Vault at all. It runs as a completely separate currency on the side. Requires hShop (or another integration) to actually be useful, since Vault-only plugins won’t know about shards. This is the mode you want 99% of the time.<\/p>\n
**PRIMARY** – hShards registers itself as the Vault economy provider. Every plugin that calls `economy.getBalance()` will be reading from hShards. Good if you want a fully custom economy without EssentialsX or CMI handling it.<\/p>\n
Set this in `config.yml`:
\n“`yaml
\nmode:
\n type: SECONDARY # or PRIMARY
\n“`<\/p>\n
—<\/p>\n
## Commands<\/p>\n
| Command | Description | Permission | —<\/p>\n ## Bypass Permissions<\/p>\n | Permission | Effect | —<\/p>\n ## PlaceholderAPI Placeholders<\/p>\n | Placeholder | Description | Supports any rank number for `top_name` and `top_balance` \u2014 not just top 10.<\/p>\n —<\/p>\n ## Sellable Items<\/p>\n Define which items players can sell for shards in `plugins\/hShards\/sellable-items.yml`:<\/p>\n “`yaml netherite_ingot: —<\/p>\n ## Developer API<\/p>\n Other plugins can interact with hShards balances through the static API class:<\/p>\n “`java \/\/ Formatting \/\/ Leaderboard Add hShards as a soft dependency in your `plugin.yml` and the API will be available whenever hShards is loaded.<\/p>\n —<\/p>\n ## Interest System<\/p>\n The interest system gives online players a percentage of their balance at a regular interval. Its completely optional and disabled by default.<\/p>\n “`yaml —<\/p>\n ## Storage<\/p>\n hShards supports two storage backends:<\/p>\n – **YAML** – default, no setup required, good for small servers “`yaml —<\/p>\n ## Works great with hShop<\/p>\n hShards pairs perfectly with hShop. Players earn shards through selling items, then spend them on special items in the shop that uses `HSHARDS` as their currency. The two plugins are aware of each other – hShop hooks into hShards automatically when both are present.<\/p>\n —<\/p>\n *Made by hPlugins by hodakazy*<\/p>\n","protected":false},"excerpt":{"rendered":" A cool secondary virtual economy.<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"_minecraft_slug":"hshards","_minecraft_project_id":"BQ3UzNXt","_minecraft_author":"hodakazy","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":13,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"hshards.zip","_minecraft_size_bytes":89124,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:56:50.019263Z","_minecraft_date_created":"2026-04-02T21:22:56.069100Z","_minecraft_date_modified":"2026-04-12T09:10:17.062648Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/hshards","_minecraft_icon_attachment_id":0,"_minecraft_imported_at":"2026-06-04T17:32:49+00:00","_minecraft_import_hash":"b597e4595514425d98a830a4e80d0d6d","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,127,128,129],"mod_loader":[130,132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-82464","mod","type-mod","status-publish","hentry","mod_category-bukkit","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_loader-bukkit","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n|—|—|—|
\n| `\/hshards balance` | Check your shard balance | `hshards.balance` |
\n| `\/shardbal [player]` | Check your own or another players balance | `hshards.balance` |
\n| `\/pay
\n| `\/shardstop [page]` | View the shards leaderboard | `hshards.top` |
\n| `\/hshards sell` | Sell item in hand for shards | `hshards.use` |
\n| `\/hshards sellall` | Sell all eligible items | `hshards.use` |
\n| `\/hshards rank` | View your leaderboard position | `hshards.top` |
\n| `\/hshardsadmin give
\n| `\/hshardsadmin take
\n| `\/hshardsadmin set
\n| `\/hshardsadmin reset
\n| `\/hshardsadmin resetall confirm` | Reset every player’s balance | `hshards.admin.reset` |
\n| `\/hshardsadmin balance
\n| `\/hshardsadmin reload` | Reload the plugin | `hshards.admin.reload` |
\n| `\/hshardsadmin lb-refresh` | Force a leaderboard cache refresh | `hshards.admin` |<\/p>\n
\n|—|—|
\n| `hshards.bypass.pay-tax` | Skip the payment tax |
\n| `hshards.bypass.pay-cooldown` | Skip the payment cooldown |
\n| `hshards.bypass.max-balance` | Exceed the max balance cap |<\/p>\n
\n|—|—|
\n| `%hshards_balance%` | Player’s raw balance |
\n| `%hshards_balance_formatted%` | Balance with currency symbol |
\n| `%hshards_rank%` | Player’s leaderboard rank |
\n| `%hshards_top_name_
\n| `%hshards_top_balance_
\n| `%hshards_top_balance_formatted_
\n| `%hshards_currency_name%` | Plural currency name |
\n| `%hshards_currency_symbol%` | Currency symbol |
\n| `%hshards_total_players%` | Total players with recorded balances |<\/p>\n
\nitems:
\n diamond:
\n material: DIAMOND
\n price: 50.0
\n enabled: true
\n name: “&bDiamond”
\n permission: “” # leave empty for no requirement<\/p>\n
\n material: NETHERITE_INGOT
\n price: 200.0
\n enabled: true
\n name: “&8&lNetherite Ingot”
\n permission: “hshards.sell.netherite”
\n“`<\/p>\n
\n\/\/ Check if hShards is available before calling anything
\nif (HShardsAPI.isAvailable()) {
\n double balance – HShardsAPI.getBalance(player);
\n HShardsAPI.deposit(player, 100);
\n boolean success – HShardsAPI.withdraw(player, 50);
\n HShardsAPI.setBalance(player, 500);<\/p>\n
\n String formatted – HShardsAPI.format(balance); \/\/ e.g. “\u2726 500.00”
\n String name – HShardsAPI.getCurrencyName(); \/\/ e.g. “Shards”<\/p>\n
\n int rank – HShardsAPI.getRank(player);
\n String topName – HShardsAPI.getLeaderboardName(1);
\n double topBalance – HShardsAPI.getLeaderboardBalance(1);
\n}
\n“`<\/p>\n
\ninterest:
\n enabled: true
\n interval: 60 # every 60 minutes
\n percent: 1.0 # 1% of their balance
\n max-eligible: 5000 # only the first 5000 shards count toward interest
\n permission: “” # require a permission node, or leave empty for everyone
\n“`<\/p>\n
\n– **SQLite** – recommended for larger servers, writes are async so it won’t affect performance<\/p>\n
\nstorage:
\n type: SQLITE
\n sqlite-file: “hshards.db”
\n“`<\/p>\n