# Marketplace widget

> Browse items, purchase with coins, and equip items on the buddy.

Source: https://docs.hatched.live/docs/reference/widgets/marketplace

## Mount

```html
<script src="https://cdn.hatched.live/widget.js" data-session-token="SESSION_TOKEN" defer></script>

<div data-hatched-mount="marketplace"></div>
```

## Required scopes

- `read` renders catalog, ownership, and affordability.
- `marketplace:browse` documents browse intent for session review, but browse
  itself is read-only.
- `marketplace:purchase` enables purchases.
- `items:equip` enables equip/unequip.

Read-only embed tokens can display state, but buying and equipping require a
widget session token with the mutation scopes above.

## Appearance updates

Equip and unequip actions render a new buddy image. The action can complete from
cache immediately or return an operation id while `buddy.appearance.status` is
`pending`. During that window the marketplace disables further outfit changes
and shows an appearance banner.

Possible statuses:

- `ready` — current `image_url` reflects the rendered outfit.
- `pending` — an image composite is running.
- `awaiting_credits` — Hatched will retry after image credits are available.
- `failed` — the user or operator must retry or rerender the base.

The widget reads `scopes` from `/widget/state`. If the token lacks
`marketplace:purchase` or `items:equip`, the catalog remains visible but
mutating actions are disabled.

## Rerender recovery

When `appearance.status === 'failed'` and `appearance.error.code === 'needs_rerender'`,
the buddy needs a clean bare stage before items can change.
Use a session token with `items:equip` and call:

```http
POST /api/v1/widget/appearance/rerender
Authorization: Bearer WIDGET_SESSION_TOKEN
```

After the rerender operation returns `ready`, re-equip the desired items.
Rerender clears the rendered item set so the UI never claims an item is visible
when the current image is bare.