# Badges

> One-shot rewards that mark a specific achievement — the "you did it" moment.

Source: https://docs.hatched.live/docs/concepts/badges

Where [skills](/docs/concepts/skills) draw a curve and
[coins](/docs/concepts/coins) drip over time, a badge **freezes a moment**.
"7-day streak". "First 10 lessons". "Helped 5 classmates".

## What badges can key off

- **Milestone events** — "complete your 100th lesson"
- **Streaks** — "7-day streak"
- **Skill levels** — "reach Pronunciation level 5"
- **Collections** — "earn all sports-themed items"
- **Evolution stages** — "reach stage 3"
- **Coin thresholds** — "earn 1,000 coins"
- **Custom** — any combination via the rule engine

## Auto vs manual award

Badges can be **auto-awarded** (the rule engine evaluates the condition and
awards immediately) or **manual** (the dashboard operator or an external
workflow awards them after review).

Manual badges emit `badge.ready` webhooks — subscribe a moderation queue if
you want humans in the loop.

## Example

> **Week Warrior** — auto-awarded on 7-day streak, plays a shine animation
> in the widget, fires `badge.awarded`. Also grants +50 coins as a side
> effect.

## How to set it up

1. Name, icon, and description.
2. Pick a condition type (milestone, streak, skill, coin, custom).
3. Decide auto vs. manual award.
4. Optionally attach a coin or token reward.

## Gotchas

- Custom conditions read the event payload — renaming properties silently
  breaks the rule. Version your event schemas.
- Manual badges fire `badge.ready`, not `badge.awarded`. Make sure your
  workflow calls `POST /badges/:id/award` when the human says yes.

## Related

- [Streaks](/docs/concepts/streaks) — the most common badge trigger.
- [Skills](/docs/concepts/skills) and [Coins](/docs/concepts/coins) — other things badges can key off.
- [Configure rules](/docs/guides/configure-rules) — defining badge conditions.