# Tokens widget

> The buddy's wallet — the spendable primary balance plus every progression token, each with progress toward its gate.

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

## Mount

```html
<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](/docs/concepts/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.