> For the complete documentation index, see [llms.txt](https://docs.xandtech.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xandtech.fr/home/xstash/reference/placeholderapi.md).

# PlaceholderAPI

Requires [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) — the expansion registers itself automatically if it's installed, no separate download needed. All placeholders only resolve for an **online** player.

{% hint style="info" %}
This page is about the `%xstash_*%` placeholders XStash exposes to other plugins. Going the other way — XStash *reading* any PlaceholderAPI placeholder as a chest-purchase condition — is `currency: placeholder` in `chest-prices.yml`, see [Economy & Selling](/home/xstash/reference/economy-and-selling.md).
{% endhint %}

## General

| Placeholder        | Returns                     |
| ------------------ | --------------------------- |
| `%xstash_version%` | The running XStash version. |

## Chests

| Placeholder                               | Returns                                                                    |
| ----------------------------------------- | -------------------------------------------------------------------------- |
| `%xstash_chests%` / `%xstash_max_chests%` | How many chests the player currently has access to via permission.         |
| `%xstash_rows%` / `%xstash_max_rows%`     | How many rows per chest the player currently has via permission.           |
| `%xstash_unlocked_<n>%`                   | `true`/`false` — whether chest `<n>` is unlocked (permission or purchase). |
| `%xstash_purchased_<n>%`                  | `true`/`false` — whether chest `<n>` was specifically purchased.           |
| `%xstash_chest_<n>_used%`                 | Occupied slots in chest `<n>`. Empty if not unlocked.                      |
| `%xstash_chest_<n>_free%`                 | Empty slots in chest `<n>`.                                                |
| `%xstash_chest_<n>_total%`                | Total slots in chest `<n>` (rows × 9).                                     |
| `%xstash_chest_<n>_bar%`                  | A 10-character fill bar for that chest, e.g. `&8[&a■■■■■&7■■■■■&8]`.       |

## Sacks

| Placeholder                                 | Returns                                                                           |
| ------------------------------------------- | --------------------------------------------------------------------------------- |
| `%xstash_sackofsacks_slots%`                | How many Sack of Sacks slots the player has unlocked.                             |
| `%xstash_sack_<id>_tier%`                   | The sack's current tier display name, or empty if the player has never owned it.  |
| `%xstash_sack_<id>_owned%`                  | `true`/`false` — whether the player currently owns (or has ever owned) that sack. |
| `%xstash_sack_<id>_item_<itemKey>%`         | `"<amount>/<max>"` for that item in that sack, at the player's current tier.      |
| `%xstash_sack_<id>_item_<itemKey>_amount%`  | Just the stored amount.                                                           |
| `%xstash_sack_<id>_item_<itemKey>_max%`     | Just the current tier's capacity for that item.                                   |
| `%xstash_sack_<id>_item_<itemKey>_percent%` | Fill percentage (0-100).                                                          |

`<id>` is the sack's id from `sacks/sacks.yml` (e.g. `farming`). `<itemKey>` is one of that sack's configured item keys (e.g. `wheat`) — matched case-insensitively, since PlaceholderAPI lowercases the whole placeholder before it reaches XStash.

**Example:** `%xstash_sack_farming_item_wheat%` → `"1234/5000"`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xandtech.fr/home/xstash/reference/placeholderapi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.