Tokens widget

Mount

<script
  src="https://cdn.hatched.live/widget.js"
  data-embed-token="EMBED_OR_SESSION_TOKEN"
  defer
></script>

<div data-hatched-mount="tokens"></div>

The loader mounts every data-hatched-mount="tokens" element. Each mount hits /widget/tokens once on init. There are no per-mount attributes — the wallet is scoped to the buddy carried by the token.

What it renders

• Primary balance — the spendable currency (coins, or whatever the customer renamed it to in the dashboard), shown as the headline number.
• Progression tokens — one row per active progression token (the earn-only gate currency, XP-like). Each row shows the token's label, a glyph, the current balance, and — when the token defines a max_balance — a progress bar toward it (7 / 10 Mastery Stars). Tokens without a cap render the balance alone.

Customers without a progression token get a clean single-balance card. See Tokens for the two-tier model behind this.

Liveness

The primary number stays live: it is read from the shared /widget/state snapshot (buddy.coins), so hatched.track() round-trips update it without re-fetching /widget/tokens.

Progression balances update from effects.tokens returned by track() (format token_key:amount), so earning a progression token reflects in the wallet immediately. A token that did not exist in the wallet at mount time appears after the next remount.

Required capability and scopes

• Capability: tokens must be enabled for the customer. If it is off the endpoint returns 403 and the widget renders the error state.
• Scope: read — to load the wallet. No write scope is needed; the tokens widget is read-only (spending happens through gates, not here).

Theming

The widget honours the customer brand theme. The eight-axis personality system from the workspace theme (surface, geometry, motion profile, reward voice, iconography, typography) is forwarded as data-* attributes on the size wrapper, exactly like the other widgets.