Hatched documentation

Hatched is a gamification layer for B2B products. Events go in, buddies grow. These docs are organised by customer task — pick the one that matches your mode.

Thirty-second taste

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

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

// 1. create a buddy
const egg = await hatched.eggs.create({ userId: 'user_42' });
await hatched.eggs.updateStatus(egg.eggId, 'ready');
const op = await hatched.eggs.hatch(egg.eggId);
const finished = await hatched.operations.wait(op.operationId);

// 2. teach the buddy about your product
await hatched.events.send({
  eventId: 'lesson_1_user_42',
  userId: 'user_42',
  type: 'lesson_completed',
  properties: { score: 94 },
});

// 3. mint a browser token and embed the widget
const session = await hatched.widgetSessions.create({
  buddyId: finished.result.buddyId,
  userId: 'user_42',
  scopes: ['read', 'events:track'],
  ttlSeconds: 900,
});

Full walkthrough: Getting started.

Pick your track

• Concepts — buddies, skills, coins, streaks, badges, paths, marketplace, evolution, rule engine, auth model.
• Guides — getting started, SDK quickstart, widgets, events, webhooks, Next.js / Express / edge runtimes, troubleshooting.
• Reference — HTTP endpoints, full SDK method surface, widget props, webhook payloads, error codes, rate limits, changelog.
• Billing — plans, credits, Stripe billing portal, 402 handling, and credit top-ups.

Building with an AI assistant?

These docs are machine-readable. Drop our AGENTS.md into your repo, point your assistant at /llms-full.txt, and grab any page as Markdown with the buttons under its title — full walkthrough in Use Hatched with AI coding assistants.

Popular pages

• Getting started (10 min)
• Widget integration
• Handle webhooks
• Auth model — secret vs publishable keys
• Use Hatched with AI coding assistants
• Error codes
• Troubleshooting

What's new

Always see the latest SDK release notes at Changelog — mirrored from the package itself, produced on every merge.