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, 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 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 — what items are priced in.
• Compositing & stages — equip slots, layer order, and the appearance state machine.
• Customize buddy — walking an equip flow.
• Marketplace widget — the shopping surface.