# Currencies

# Currencies

Each shop names one currency in its `currencyId` field (and optionally a different payout currency in `sellCurrencyId`). Currencies come from other KS mods, from an economy plugin, or from items in the player's inventory.

## Currency Types

### Quest Tokens

| Property | Value |
|----------|-------|
| Currency ID | `quest_tokens` |
| Provided by | Quest mod |
| Earned through | Completing quests (awarded as quest rewards) |

Quest tokens are the main progression currency. Players earn them by completing quests and spend them in shops that accept `quest_tokens`.

```json title="Example quest reward"
{
  "type": "quest_tokens",
  "amount": 5
}
```

### Achievement Points

| Property | Value |
|----------|-------|
| Currency ID | `achievement_points` |
| Provided by | Achievement mod |
| Earned through | Unlocking achievements |

Achievement points are earned as players complete achievements. They work well for shops that reward long-term play.

```json title="Shop using achievement points"
{
  "id": "rare_collector",
  "currencyId": "achievement_points",
  "items": [ ... ]
}
```

### Season Tokens

| Property | Value |
|----------|-------|
| Currency ID | `season_tokens` |
| Provided by | Season Pass mod |

When the Season Pass mod is installed, its season tokens can also be used as an NPC shop currency.

### Server Economy

| Property | Value |
|----------|-------|
| Currency ID | `economy` |
| Provided by | An economy plugin through Core's economy bridge |

Core connects to an economy plugin through **VaultUnlocked** (any economy that registers there, for example Ecotale) or EliteEssentials. The bridge also finds an economy plugin that starts after Core. Use `"currencyId": "economy"` to sell for the server's money.

:::info
A failed balance read is never treated as a balance of 0, and the payment itself always decides whether a purchase goes through.
:::

### Item-Based Currencies

| Property | Value |
|----------|-------|
| Currency ID | `item:<ItemId>` |
| Provided by | Core (automatic) |
| Earned through | Gathering, crafting, looting |

Any Hytale item can be used as a currency. The shop counts the items in the player's inventory and removes them on purchase. No setup is needed — Core creates the currency the first time it sees an `item:` ID.

```json title="Shop using gold bars as currency"
{
  "id": "example_shop",
  "currencyId": "item:Ingredient_Bar_Gold",
  "items": [ ... ]
}
```

Common item currencies:

| Currency ID | Item |
|-------------|------|
| `item:Ingredient_Bar_Gold` | Gold Bars |
| `item:Ingredient_Bar_Iron` | Iron Bars |
| `item:Ore_Gold` | Gold Ore |

:::tip
You can use any valid Hytale item ID after the `item:` prefix. The shop window shows the game's translated item name as the currency name.
:::

## How Currencies Work in Shops

When a player opens a shop, Core looks up the currency for the shop's `currencyId`. The currency handles three things:

1. **Balance** — How many tokens, points, coins or items does the player have?
2. **Spend** — Take the price when a purchase is made.
3. **Refund** — Give it back if the purchase could not be delivered.

### Purchase Flow

When a player buys an entry, the checks run in this order:

1. **Permission** — Does the player have the entry's permission (if set)?
2. **Purchase limit** — Would this purchase exceed `maxPurchases` for today?
3. **Balance** — Can the player pay?
4. **Space** — Does the item fit into the inventory? If not, nothing is charged.
5. **Payment** — The price is taken.
6. **Delivery** — The item is added all at once. If that fails, the full price is refunded and the purchase is not counted.

For command entries, step 4 is replaced by a check that the command exists and may run; a command that fails while running is refunded.

:::info
Purchase counts reset daily. A player who bought 3 of 3 allowed pickaxes today can buy again tomorrow.
:::

### Named currencies in rewards

Rewards that pay a named currency (for example "gems") are paid in exactly that currency or reported as failed — they are no longer paid silently in the main currency. Common names such as "gold", "money" or "coins" still pay the server economy.

## Setting Up a Shop with Currencies

To create a shop that uses quest tokens:

```json title="shops/quest_rewards.json"
{
  "id": "quest_rewards",
  "title": "Quest Reward Shop",
  "currencyId": "quest_tokens",
  "settings": {
    "itemsPerPage": 9,
    "dailyShopSize": 0,
    "showSoldOut": true,
    "allowBuyMultiple": false
  },
  "items": [
    {
      "itemId": "Potion_Health_Greater",
      "quantity": 3,
      "cost": 5,
      "description": "3x Greater Health Potions",
      "category": "potions"
    },
    {
      "itemId": "Weapon_Sword_Adamantite",
      "quantity": 1,
      "cost": 50,
      "description": "The finest blade",
      "category": "weapons",
      "maxPurchases": 1
    }
  ]
}
```

:::caution
If the currency for a shop's `currencyId` is not available (for example the shop uses `quest_tokens` but the Quest mod is not installed), the shop cannot sell. The shop editor warns about unknown currencies before you save.
:::