Getting started

This guide walks through the full integration path. If you only have ten minutes, this is the one to read.

1. Sign up and grab an API key

1. Create an account at the Hatched dashboard.
2. Pick a preset — language-learning, fitness, productivity, custom — it seeds your config with sensible defaults.
3. Go to Developers → API keys and create a secret key (prefix hatch_live_ in production, hatch_test_ for sandbox).

2. Install the SDK

pnpm add @hatched/sdk-js
# or
npm install @hatched/sdk-js

import { HatchedClient } from '@hatched/sdk-js';

const hatched = new HatchedClient({
  apiKey: process.env.HATCHED_API_KEY!,
});

The SDK throws on construction if it detects a browser runtime. For browser integrations, mint a widget session token server-side (step 5) or use a publishable key.

3. Create an egg and hatch it

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

const hatchOp = await hatched.eggs.hatch(egg.eggId);
const finished = await hatched.operations.wait(hatchOp.operationId);

console.log('Buddy ready:', finished.result);

Image generation runs asynchronously; operations.wait polls until the buddy's art is ready (usually 5–20 seconds).

4. Send your first event

await hatched.events.send({
  eventId: 'lesson_lsn_1_user_42',
  userId: 'user_42',
  type: 'lesson_completed',
  properties: { lessonId: 'lesson_1', durationMs: 5 * 60 * 1000 },
});

The rule engine evaluates the event against the buddy's pinned config and applies coin, skill, badge, streak, and evolution effects in a single transaction. eventId provides idempotency — re-sending the same id returns the cached effect.

5. Embed the buddy widget

On any page your user visits, mint a widget session token on your server:

const session = await hatched.widgetSessions.create({
  buddyId: 'bdy_abc',
  userId: 'user_42',
  scopes: ['buddy:read', 'buddy:interact'],
  ttlSeconds: 60 * 15,
});

Pass the token to the client and render the widget:

<script src="https://cdn.hatched.com/widget/v1/loader.min.js" defer></script>

<div
  data-hatched-widget="buddy"
  data-hatched-token="{{session.token}}"
></div>

That's it. The widget mounts in a Shadow DOM, pulls buddy state, and reflects new events in real time.

Next steps

• Handle webhooks — react on your backend when a buddy earns a badge or hits a streak milestone.
• Configure rules — tune the coin economy and badge conditions.
• Reference — the full API spec.
• Auth model — secret vs publishable keys.