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

# Black Market

A rotating shop of rare/exclusive items, separate from the normal [shop](/home/xplayercurrencies/features/shop.md). Every `refresh-interval-hours`, a random **weighted** subset of the configured `pool` becomes buyable, each with its own limited stock for that rotation - once sold out, that item is gone until the next refresh (or an admin's forced one).

```yaml
black-market:
  enabled: true
  refresh-interval-hours: 6
  rotation-size: 3
  permission: ""
  border-material: BLACK_STAINED_GLASS_PANE
  pool:
    - id: netherite_scrap
      material: NETHERITE_SCRAP
      name: "&5&lNetherite Scrap"
      lore:
        - "&7A rare find, straight off"
        - "&7the black market."
      price: 5000
      stock-per-rotation: 3
      amount: 1
      weight: 3
      permission: ""
    - id: elytra
      material: ELYTRA
      name: "&5&lElytra"
      price: 50000
      stock-per-rotation: 1
      amount: 1
      weight: 1
```

| Key                      | Description                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `refresh-interval-hours` | How often a new rotation is picked.                                                                     |
| `rotation-size`          | How many pool entries are active at once.                                                               |
| `permission`             | Blank = anyone with `xplayercurrencies.blackmarket` can open the market at all.                         |
| `border-material`        | The glass framing the menu - any `*_STAINED_GLASS_PANE` color.                                          |
| `pool`                   | Every possible item, only ever picked **into** an active rotation - never directly buyable outside one. |

Pool entry fields:

| Key                  | Description                                                                                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stock-per-rotation` | How many times it can be bought (in units of `amount`) before it's sold out for that rotation.                                                                   |
| `amount`             | How many of `material` one purchase gives.                                                                                                                       |
| `weight`             | Relative odds of being picked into a rotation - a weight-2 entry is roughly twice as likely as a weight-1 one. Doesn't affect anything once already in rotation. |
| `permission`         | Blank = anyone who can open the market can buy it. Set to gate one specific rare entry further, on top of the market's own `permission`.                         |

{% hint style="info" %}
Everything above (settings and the pool) is also editable in-game via `/currencies admin gui` -> a currency -> Features -> Black Market - no need to hand-edit YAML.
{% endhint %}

## Commands

| Command                                                        | Description                                                  |
| -------------------------------------------------------------- | ------------------------------------------------------------ |
| `/currencies blackmarket <currency>` (or `/coins blackmarket`) | Opens the current rotation.                                  |
| `/currencies admin blackmarket refresh <currency>`             | Forces a new rotation right now, regardless of the schedule. |

Requires `xplayercurrencies.blackmarket` (default: `true`) for players, `xplayercurrencies.admin` to force-refresh.

Next: [Fraud Detection](/home/xplayercurrencies/features/fraud-detection.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/black-market.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.