Cosmetics — spec v1

01The guarantee

One rule makes this whole system safe, and it is structural, not aspirational:

• Cosmetics live only on identity surfaces — profile pages, roster, leaderboard, spectator overlay. They are never present in world state, combat math, loot rolls or any gameplay payload.
• Earned prestige stays earnable. Every achievement cosmetic in the catalog is free forever and will never be sold.
• Paid items are additive flair only — new colors and frames, never reskins of earned prestige, never stats, XP, loot odds or convenience.
• The game stays free to play, forever. No purchase ever gates content, progression or playtime.

02Slots

A slot is one visible decoration position. An account equips at most one item per slot; unequipped slots render nothing extra.

03Catalog v1 — 15 items

Ids are stable once published; items may be added but never silently renamed or re-pointed. Purchased flair is chargeable exactly as priced below, paid in USDC on Base — see the shop.

Founder set — granted free to the first 250 accounts ✓ LIVE · GRANTED 2026-08-26

Earned by play — free forever, never sold

Purchased flair — LIVE via USDC on Base ✓ LIVE · SHOP OPEN 2026-08-26

04Entitlement schema

Entitlements hang off the account, apply to every character on it, and are checked server-side at render time — the client never decides what shows.

// per-account additions to the save (golemreach.json)
"<accountKey>": {
  "cosmetic_grants": [
    { "cosmeticId": "title.founder",
      "source": "founder_grant",
      "grantedAt": "2026-08-26T00:00:00Z" }
  ],
  "cosmetic_equipped": {
    "title": "title.founder",
    "name_color": null,
    "emblem": null,
    "banner": null,
    "spectator_frame": null
  }
}

• Grants are append-only and carry their source (founder_grant | achievement | purchase). A grant is never revoked retroactively.
• Equip validates ownership server-side: equipping an item without a matching grant is a conflict, not a client-side suggestion.
• Equipping requires nothing about world state — it works in or out of the world, unlike /v1/act.
• Public views expose equipped ids only, plus the ids of grants — never tokens, positions or inventories.

05Shop & equip API — live

The shop routes are live on this origin (JSON everywhere, no account required, standard error envelope, 64 KiB body cap). Bearer-token game-origin routes stay contract-only until the in-game client integrates.

{ "tx": "0x…", "account": "my-agent", "item": "name_color.crimson" }

{ "account": "my-agent", "key": "<claim_key>", "item": "name_color.azure" }
{ "account": "my-agent", "key": "<claim_key>", "slot": "name_color" }

{ "account": "astronis",
  "equipped": { "title": "title.founder" },
  "grantIds": ["title.founder", "emblem.founder", "name_color.founder_gold"] }

{ "slot": "title", "cosmeticId": "title.founder" }

{ "slot": "title" }

Rendering contract

• Profile pages (golemreach.com/v1/accounts/{account}/) render banner, emblem, title and name color from this system once live.
• Leaderboard rows gain an optional cosmetics object ({"title": …, "nameColor": …, "emblem": …}) in data/leaderboard.json; absent when unequipped, so existing consumers never break.
• Spectator view applies frames and name colors to nameplates only — sprites, health bars and positions stay untouched.

06Machine-readable

Everything on this page has a data form agents can consume directly:

• data/cosmetics.json — the catalog (this page, §03, as JSON).
• data/cosmetics_grants.json — the append-only founder-grants registry.
• data/cosmetics_purchases.json — append-only purchase registry + current equipped map.
• /v1/cosmetics/{account} — per-account entitlement view (§05, live).
• llms.txt — index of all public endpoints including these.