> ## Documentation Index
> Fetch the complete documentation index at: https://pumpkings.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# NxShards PlaceholderAPI Variables for Balance and Leaderboard

> Full reference for the %shards_*% PlaceholderAPI placeholders — balance, leaderboard names, and leaderboard amounts for any position.

With PlaceholderAPI installed, NxShards exposes a small set of `%shards_*%` placeholders that work inside any PAPI-compatible plugin: scoreboards, tab lists, holograms, chat formatters, and more.

## Available Placeholders

| Placeholder                              | Description                                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `%shards_balance%`                       | The current Shards balance of the player viewing the placeholder.                                             |
| `%shards_leaderboard_name_<position>%`   | Name of the player at the given leaderboard position (e.g. `%shards_leaderboard_name_1%` for the top player). |
| `%shards_leaderboard_amount_<position>%` | Shards balance of the player at the given leaderboard position (e.g. `%shards_leaderboard_amount_1%`).        |

## Examples

**Scoreboard line (using FeatherBoard / TAB / etc.):**

```text theme={null}
&7Balance: &6%shards_balance%
```

**Top 3 leaderboard hologram:**

```text theme={null}
&e&l— Top Shards —
&f1. &6%shards_leaderboard_name_1% &7— &e%shards_leaderboard_amount_1%
&f2. &6%shards_leaderboard_name_2% &7— &e%shards_leaderboard_amount_2%
&f3. &6%shards_leaderboard_name_3% &7— &e%shards_leaderboard_amount_3%
```

**Chat format prefix (DeluxeChat, EssentialsXChat):**

```text theme={null}
&8[&6%shards_balance%&8] {DISPLAYNAME}: {MESSAGE}
```

## Requirements

* PlaceholderAPI must be installed in `plugins/`.
* NxShards registers its expansion automatically on startup — there is no need to download anything from the PAPI eCloud.

<Note>
  If `%shards_leaderboard_name_5%` is requested but only four players have a balance, NxShards returns an empty string so your scoreboard does not break.
</Note>