> 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/readme.md).

# Introduction

XStash is a Paper plugin that gives every player their own set of **virtual chests** plus a Hypixel SkyBlock-style **sacks** system — automatic resource collectors with upgradeable capacity tiers. Both modules are independent (either can be disabled without touching the other), fully permission-driven, and configurable down to individual menu items through YAML.

## What's in here

* [**Chests Module**](/home/xstash/chests-module/chests.md) — up to 30 virtual chests per player, unlocked by rank permission and/or individual purchase, with a utility bar (sort, auto-smelt, compact, sell-all), per-chest customization, search, and a travel backpack shortcut.
* [**Sacks Module**](/home/xstash/sacks-module/sacks.md) — a configurable catalog of sacks, each a single physical item whose storage capacity is upgraded in place through tiers, with auto-collect and a "Sack of Sacks" menu to carry every sack at once.
* **Admin tools for both** — `/xstash view <player>` and `/sacks view <player>` open a live-editable management view of any player's chests/sacks, including offline players. Both sides (the admin's view and the player's own, if open at the same time) refresh automatically within about a second of any change, in either direction. `/xstash export` dumps the chest transaction log to CSV/YAML/JSON.
* **Economy** — Vault (money) and PlayerPoints (points) for every purchase and sale, an optional PlaceholderAPI-driven condition (not a spend) as a third chest-purchase option, an optional fallback to an installed shop plugin's own prices, and a permission-driven sell price boost.
* **Integrations** — PlaceholderAPI, ExecutableItems, and a public Java API (`XStashAPI`) for other plugins to read/modify a player's chests and Sack of Sacks slots.

## Requirements

* Paper (or a Paper fork) `1.21.x` or newer — API version `26.2`.
* Java 21+.

Everything else is optional:

| Plugin                                                                                  | Needed for                                                                                               |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [Vault](https://www.spigotmc.org/resources/vault.34315/) + any Vault-compatible economy | Money-based chest purchases, sells, and sack upgrade costs                                               |
| [PlayerPoints](https://www.spigotmc.org/resources/playerpoints.80745/)                  | Points-based purchases/sells                                                                             |
| [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)               | The `%xstash_*%` placeholders, plus `currency: placeholder` condition-based chest purchases              |
| [ExecutableItems](https://www.spigotmc.org/resources/executableitems.100480/)           | Custom `ei:<id>` items in sack contents/crafting                                                         |
| EssentialsX, ShopGUIPlus, EconomyShopGUI, GUIShop, or RoyaleEconomy                     | Shop-plugin sell price fallback (see [Economy & Selling](/home/xstash/reference/economy-and-selling.md)) |

None of these are required to run XStash — each integration only activates if the corresponding plugin is actually installed.

## Where to start

New to XStash? Read [Installation & Setup](/home/xstash/getting-started/getting-started.md) first, then jump into whichever module you're setting up: [Chests](/home/xstash/chests-module/chests.md) or [Sacks](/home/xstash/sacks-module/sacks.md). Server admins managing existing players should also check [Admin Tools](/home/xstash/chests-module/admin-tools.md) and the [Permissions](/home/xstash/reference/permissions.md) reference.


---

# 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/readme.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.