# Marketplace

> Where users spend coins to dress up the buddy — items, costumes, backgrounds, boosters.

Source: https://docs.hatched.live/docs/concepts/marketplace

The marketplace is the **consumption side** of the coin economy. Without it,
coins become an empty metric. It's also where users feel "this buddy is mine".

## Anatomy of an item

Each item carries:

- **name**, **description**, **image**
- **category** (`background`, `body`, `feet`, `hand`, `neck`, `face`, `head`, `accessory`)
- **price** — in coins, tokens, or mixed
- **rarity** (common, uncommon, rare, epic, legendary)
- **visibility rule** — "stage 2+", "holds badge X", "audience = premium"
- **equip slot** — the category also drives compositing order and conflicts

## Example

> **"Cowboy Hat"** — 50 coins, rare, unlocked for Stage 2+ buddies. Once
> equipped, the widget renders the buddy wearing it.

## Equip lifecycle

Equipping is an appearance update, not just a metadata flip. Hatched validates
ownership, enforces [category bounds](/docs/concepts/compositing-and-stages),
sets the desired `equipped_items`, and then renders a new image against the
buddy's `base_image_url`.

The response can be instant when a cached composite exists. Otherwise it returns
an operation id and the buddy reports `appearance.status: 'pending'` until the
render lands. If the image provider is out of credits the status becomes
`awaiting_credits` and Hatched retries after credits are available. If the
base image must be regenerated, the status is `failed` with
`error.code: 'needs_rerender'`; call `buddies.rerenderAppearance(...)`, wait
for `ready`, then re-equip.

## How to set it up

1. Create a marketplace (pricing mode: coin / free / mixed).
2. For each item, set an image, price, and unlock type.
3. Add visibility rules (Stage 2+, holds badge X, etc.).
4. Mount the [marketplace widget](/docs/reference/widgets/marketplace) on
   the page where users shop.

## Gotchas

- Oversized images slow the marketplace widget — cap thumbnails at 512×512.
- Tune prices against the coin economy. An unsold item is usually invisible,
  not expensive.
- A buddy can equip at most 4 items. Non-`accessory` categories are exclusive,
  so two `head` items conflict.
- Equipped items persist across evolution stages. When a stage changes, Hatched
  renders the same desired item set against the new `base_image_url` and exposes
  any delayed composite through `buddy.appearance`.

## Related

- [Coins](/docs/concepts/coins) — what items are priced in.
- [Compositing & stages](/docs/concepts/compositing-and-stages) — equip slots, layer order, and the `appearance` state machine.
- [Customize buddy](/docs/guides/customize-buddy) — walking an equip flow.
- [Marketplace widget](/docs/reference/widgets/marketplace) — the shopping surface.