Buddy & hatch

A buddy is the persistent companion a user gets when they join your Hatched programme. Everything else — skills, coins, streaks, badges — hangs off the buddy.

Egg and hatch

Before a buddy exists, there is an egg. Creating an egg is the first write you make to the Hatched API:

const egg = await hatched.eggs.create({
  externalUserId: 'user_42',
  presetId: 'language-learning-v1',
});

The egg is pinned to the current config version and carries any audience tags you passed. It doesn't render a visible buddy yet — it's a placeholder with pending image generation.

Hatch is the ceremony that turns an egg into a buddy:

const op = await hatched.eggs.hatch(egg.id);
const buddy = await hatched.operations.wait(op.id);

Hatching is asynchronous because image generation takes 5–20 seconds. You get an operation id back; poll it with operations.wait or listen for the buddy.hatched webhook.

One user, possibly several buddies

By default there is one buddy per (customer, external_user_id) pair. When audiences are in play, a single user can have one buddy per audience — useful when the same person plays two roles (student and teacher, for instance).

What a buddy carries

A buddy is not just a picture. It holds:

• a config_version_id — which rulebook it lives under
• a skills map — each skill with value and level
• coins and any token balances
• a list of awarded badges
• a set of streak counters
• an evolution stage and the image for that stage
• equipped marketplace items
• an audience tag (if configured)

The widget reads this shape directly; your backend can mirror it via webhooks if you need your own source of truth for UX.

Lifecycle

Buddies are long-lived. They don't expire on their own — they evolve. When you update the rule set, existing buddies stay pinned to their old config version; you migrate them explicitly when you're ready.