Marketplace widget

Mount

<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:

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.