> 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/xplayercurrencies/features/shop.md).

# Shop

NPC-style shop menus (Hypixel/RoyaleEconomy style) where players buy and sell items for a currency. The master toggle and dynamic-pricing tuning live in `currencies/<id>.yml`; the actual catalog (which items, at what price) lives in `shops/<id>/*.yml` - a currency can have several shops.

```yaml
shop:
  enabled: true
  commands: ["shop"]     # e.g. "/shop" on top of "/currencies shop coins" / "/coins shop"
  dynamic-pricing:
    step-percent: 1.0
    min-multiplier: 0.5
    max-multiplier: 2.0
```

| Key                 | Description                                                                                                                                                                                                                                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `commands`          | Extra top-level command(s) that open this currency's shop directly. First entry is the primary name, rest are aliases.                                                                                                                                                                                                         |
| `admin-commands`    | Extra top-level command(s) that jump straight to this currency's shop management menu for an admin.                                                                                                                                                                                                                            |
| `dynamic-pricing.*` | Only matters for an item with its own dynamic pricing turned on in the shop editor - shared per currency so admins tune "how aggressively supply/demand moves prices" once rather than per item. `step-percent` is how much the price moves per sale, clamped between `min-multiplier` and `max-multiplier` of the base price. |

Enabled here with a one-item demo auto-created the first time it loads with an empty `shops/coins/` folder, so a fresh install already has a working example.

## What a shop offers

Configured per item in the in-game editor (`/currencies admin editshop <currency>`) or by hand in `shops/<id>/*.yml`:

* Buy price, sell price (either can be left unset to disable that direction for an item)
* Stock with restock timers, and dynamic pricing that shifts with supply/demand
* Per-player purchase limits and cooldowns
* A sell confirmation prompt for high-value sales
* A full transaction history per shop

## Sounds

```yaml
shop:
  sounds:
    enabled: true
    open:         { sound: UI_TOAST_IN, volume: 0.7, pitch: 1.0 }
    click:        { sound: UI_BUTTON_CLICK, volume: 0.5, pitch: 1.2 }
    buy-success:  { sound: ENTITY_EXPERIENCE_ORB_PICKUP, volume: 1.0, pitch: 1.0 }
    sell-success: { sound: ENTITY_EXPERIENCE_ORB_PICKUP, volume: 1.0, pitch: 1.5 }
    error:        { sound: ENTITY_VILLAGER_NO, volume: 1.0, pitch: 1.0 }
```

`enabled` is a single master switch - to silence one sound, set its own `volume` to `0` instead. `open` only plays when genuinely entering the shop system, not on every internal refresh.

## Commands

| Command                                 | Description                                                                                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/currencies shop <currency> [shopId]`  | Opens a shop. With no `shopId` and only one shop, opens it directly; otherwise shows the shop list.                                              |
| `/currencies sellall <currency> [shop]` | Sells every matching item in your inventory at once - see [Sell Sticks & /sellall](/home/xplayercurrencies/features/sell-sticks-and-sellall.md). |

Requires `xplayercurrencies.shop` (default: `true`) to buy/sell, `xplayercurrencies.sellall` for `/sellall`.

## Admin

```
/currencies admin editshop <currency>
```

Opens the in-game shop editor (`xplayercurrencies.admin`) - add/edit/remove items, catalogs, and tune stock/dynamic pricing/limits/cooldowns without touching YAML.

## Citizens integration

Bind a Citizens NPC to a shop so right-clicking it opens the shop directly - see [Citizens](/home/xplayercurrencies/integrations/citizens.md).

Next: [Sell Sticks & /sellall](/home/xplayercurrencies/features/sell-sticks-and-sellall.md).


---

# 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/xplayercurrencies/features/shop.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.