# Hatched

> Hatched is the gamification layer for B2B products: a typed SDK (@hatched/sdk-js), embeddable widgets, and an HTTP API. Send product events, grow buddies, award coins / tokens / badges / streaks, run marketplaces, and embed it all with a few lines of HTML.

This file follows the [llms.txt](https://llmstxt.org) convention. For the full text of every page in one document, fetch [https://docs.hatched.live/llms-full.txt](https://docs.hatched.live/llms-full.txt). Any single page is also available as Markdown at `https://docs.hatched.live/llm/<path>` (e.g. https://docs.hatched.live/llm/guides/getting-started).

Integrating Hatched? Start with the SDK quickstart and the auth model:

- [Get Hatched into your product in 10 minutes](https://docs.hatched.live/docs/guides/getting-started)
- [Which key / token do I use?](https://docs.hatched.live/docs/concepts/auth-model)
- [Drop-in instructions for your coding assistant](https://docs.hatched.live/AGENTS.md)

## Start here

- [Hatched documentation](https://docs.hatched.live/docs): Drop a buddy into your product in under 10 minutes. Server-only SDK, scoped browser tokens, auto-retries, idempotency built in.
- [Use Hatched with AI coding assistants](https://docs.hatched.live/docs/ai-assistants): These docs are machine-readable. Point Cursor, Claude Code, Copilot, or any LLM at the right files and drop a ready-made instruction file into your repo.

## Guides — task-oriented walkthroughs

- [Getting started](https://docs.hatched.live/docs/guides/getting-started): Ten minutes from zero to a buddy in your product — create an egg, send your first event, embed a widget.
- [First user bootstrap](https://docs.hatched.live/docs/guides/first-user-bootstrap): The complete first-run path — from a published config to a mounted widget — in both the SDK and raw HTTP. The one flow you can't skip steps in.
- [SDK quickstart](https://docs.hatched.live/docs/guides/sdk-quickstart): Install @hatched/sdk-js, authenticate, and make your first calls from Node or TypeScript.
- [Widget integration](https://docs.hatched.live/docs/guides/widget-integration): Drop Hatched widgets into any page with one loader script and stable data-hatched-mount attributes.
- [React Native integration](https://docs.hatched.live/docs/guides/react-native-integration): Embed Hatched gamification in Expo and bare React Native apps with @hatched/react-native — native widgets, a WebView fallback, and one provider.
- [Pinning a widget version](https://docs.hatched.live/docs/guides/widget-versioning): Pin a frozen loader release with `cdn.hatched.live/v/<version>/widget.js` so your embed surface stays byte-for-byte stable across deploys.
- [Send events](https://docs.hatched.live/docs/guides/send-events): What to send, when to send it, and how Hatched turns events into effects.
- [Customise the buddy](https://docs.hatched.live/docs/guides/customize-buddy): Style the widget, swap the art style, and tune evolution stages to match your brand.
- [Configure rules](https://docs.hatched.live/docs/guides/configure-rules): Tune the coin economy, skill progression, badge conditions, and streak milestones in the dashboard.
- [Handle webhooks](https://docs.hatched.live/docs/guides/handle-webhooks): Verify the HMAC signature, respect the replay window, and respond before Hatched retries.
- [Verify webhooks end-to-end](https://docs.hatched.live/docs/guides/verify-webhooks): Copy-paste handlers that capture the raw body, verify the HMAC signature, and acknowledge fast — for Express, Fastify, Hono, Next.js App Router, Next.js Pages Router, and Cloudflare Workers.
- [Content Security Policy](https://docs.hatched.live/docs/guides/widget-csp): The minimum CSP directives a partner site needs to host Hatched widgets, plus variations for custom domains and staging hosts.
- [Unlock gates](https://docs.hatched.live/docs/guides/unlock-gates): Spend primary tokens to unlock features — the non-cosmetic half of the token economy.
- [Next.js integration](https://docs.hatched.live/docs/guides/nextjs-integration): Wire Hatched into a Next.js App Router app — server components, route handlers, widgets, and webhooks.
- [Express integration](https://docs.hatched.live/docs/guides/express-integration): Use @hatched/sdk-js from an Express app — handlers, raw-body webhook middleware, and error mapping.
- [Edge runtimes](https://docs.hatched.live/docs/guides/edge-runtimes): Run @hatched/sdk-js on Cloudflare Workers, Vercel Edge, Deno, and Bun — fetch overrides, AbortSignal, and the crypto caveat.
- [Browser usage (publishable keys)](https://docs.hatched.live/docs/guides/browser-usage): Use @hatched/sdk-js in the browser with a publishable key — read buddies, mint read-only embed tokens, no server round-trip.
- [Best practices](https://docs.hatched.live/docs/guides/best-practices): Patterns for a Hatched integration that scales — designing the economy, sending events safely, handling webhooks reliably, and staying multi-tenant clean.
- [Troubleshooting](https://docs.hatched.live/docs/guides/troubleshooting): Reproduce common failures and the exact fix for each — 401, 429, validation errors, image errors, and widget mount issues.

## Concepts — the vocabulary of gamification on Hatched

- [Overview](https://docs.hatched.live/docs/concepts/overview): The fourteen primitives that make up every Hatched gamification programme, and how they fit together.
- [Buddy & hatch](https://docs.hatched.live/docs/concepts/buddy-and-hatch): The avatar at the heart of Hatched;how it's created, what hatch means, and how it grows.
- [Skills](https://docs.hatched.live/docs/concepts/skills): The dimensions along which a buddy grows — Pronunciation, Grammar, Stamina, whatever matters for your product.
- [Skill decay](https://docs.hatched.live/docs/concepts/skill-decay): Subtract skill points on a schedule so users who go inactive feel the loss — a loss-aversion engagement loop for power users who already capped out.
- [Coins](https://docs.hatched.live/docs/concepts/coins): The primary currency — earned from events, spent in the marketplace, tuned with coin rules.
- [Tokens](https://docs.hatched.live/docs/concepts/tokens): Two-tier token model — one primary spendable, one progression accumulator. Customers pick the names.
- [Token economy](https://docs.hatched.live/docs/concepts/token-economy): How the two-tier token model, gates, and marketplace pricing fit together.
- [Streaks](https://docs.hatched.live/docs/concepts/streaks): Consistent-daily-activity counters that reward habit, not volume.
- [Badges](https://docs.hatched.live/docs/concepts/badges): One-shot rewards that mark a specific achievement — the "you did it" moment.
- [Paths](https://docs.hatched.live/docs/concepts/paths): Multi-step guided journeys — onboarding, learning modules, activation checklists, certification tracks.
- [Marketplace](https://docs.hatched.live/docs/concepts/marketplace): Where users spend coins to dress up the buddy — items, costumes, backgrounds, boosters.
- [Compositing & stages](https://docs.hatched.live/docs/concepts/compositing-and-stages): How equipped items layer onto the buddy, and how evolution preserves them atomically.
- [Leaderboard](https://docs.hatched.live/docs/concepts/leaderboard): Rank-based competition, scoped by time window and audience.
- [Evolution](https://docs.hatched.live/docs/concepts/evolution): Stages the buddy grows through over time — the Tamagotchi arc.
- [Audiences](https://docs.hatched.live/docs/concepts/audiences): Segment one customer into multiple user groups — each with its own rules, capabilities, and leaderboards.
- [Config versions](https://docs.hatched.live/docs/concepts/config-versions): Immutable snapshots of every rule, skill, coin payout, and item. Buddies pin to a snapshot so their world never shifts unexpectedly.
- [Rule engine](https://docs.hatched.live/docs/concepts/rule-engine): The deterministic two-phase pipeline that converts events into effects.
- [Webhooks](https://docs.hatched.live/docs/concepts/webhooks): Signed HTTP callbacks when something happens in the buddy's world — HMAC-signed, 3 retries, 5-minute replay window.
- [Webhook delivery](https://docs.hatched.live/docs/concepts/webhook-delivery): How Hatched enqueues, signs, retries, and dedupes webhook deliveries — what the platform promises and what it expects from your handler.
- [Auth model](https://docs.hatched.live/docs/concepts/auth-model): Secret keys, publishable keys, widget session tokens, and embed tokens — which one to use, when, and why.
- [Idempotency](https://docs.hatched.live/docs/concepts/idempotency): How retry-safe mutations work in the Hatched API — the Idempotency-Key contract, what the platform caches, and how the SDK uses it automatically.
- [Pagination](https://docs.hatched.live/docs/concepts/pagination): Hatched ships two pagination envelopes — cursor (canonical for new endpoints) and offset (legacy). This page documents both shapes, the SDK helpers that walk them, and how to add cursor pagination to a server-side route.

## Reference — the complete technical spec

- [HTTP API](https://docs.hatched.live/docs/reference/http-api): Lean API contract and state machines — V1 scope, endpoints, authentication, and the business processes behind each operation.
- [SDK (JavaScript / TypeScript)](https://docs.hatched.live/docs/reference/sdk-js): Complete method reference for @hatched/sdk-js — HatchedClient, resources, error classes.
- [SDK (React Native)](https://docs.hatched.live/docs/reference/react-native): Component and hook reference for @hatched/react-native — HatchedProvider, the native widgets, HatchedWebView, and hooks.
- [Theme tokens](https://docs.hatched.live/docs/reference/theme-tokens): Every CSS variable the widget loader honors — what it does, default value in light and dark mode, and how to override it from the script tag or at runtime.
- [Webhook payloads](https://docs.hatched.live/docs/reference/webhook-payloads): Common event payloads Hatched emits, with the shape of the body you'll receive.
- [Error codes](https://docs.hatched.live/docs/reference/error-codes): Every stable error code Hatched raises — HTTP status, SDK class, and how to fix.
- [Rate limits](https://docs.hatched.live/docs/reference/rate-limits): Per-principal plan-tier quotas, the 429 response shape, and how to back off gracefully.
- [Plan capabilities](https://docs.hatched.live/docs/reference/plan-capabilities): Which Hatched widgets, capabilities, and quotas land on which subscription tier. Auto-generated from packages/shared/src/pricing.ts.
- [Health & version probes](https://docs.hatched.live/docs/reference/health-version): Bare-path liveness, readiness, and build-fingerprint endpoints for Kubernetes, Fly.io, and uptime monitoring.
- [Changelog](https://docs.hatched.live/docs/reference/changelog): Release notes for @hatched/sdk-js — mirrored from the package's CHANGELOG.md.

## Widget reference — mount points, data attributes, scopes

- [Buddy widget](https://docs.hatched.live/docs/reference/widgets/buddy): Animated companion with stage, coins, equipped items, and live event effects.
- [Badges widget](https://docs.hatched.live/docs/reference/widgets/badges): A shelf of the buddy's earned and locked badges.
- [Streak widget](https://docs.hatched.live/docs/reference/widgets/streak): A compact streak counter with milestones and current progress.
- [Path widget](https://docs.hatched.live/docs/reference/widgets/path): A guided journey of steps and sub-steps, rendered as a straight column, a zigzag quest, or a horizontal stepper.
- [Tokens widget](https://docs.hatched.live/docs/reference/widgets/tokens): The buddy's wallet — the spendable primary balance plus every progression token, each with progress toward its gate.
- [Leaderboard widget](https://docs.hatched.live/docs/reference/widgets/leaderboard): Ranked list surface for the buddy's audience.
- [Marketplace widget](https://docs.hatched.live/docs/reference/widgets/marketplace): Browse items, purchase with coins, and equip items on the buddy.
- [Kudos widget](https://docs.hatched.live/docs/reference/widgets/kudos): Tenant-defined peer recognition — send and receive kudos with a configurable taxonomy.
- [Group Quest widget](https://docs.hatched.live/docs/reference/widgets/group-quest): Cooperative team goal with a shared progress bar — join, contribute, and win together.
- [Feed widget](https://docs.hatched.live/docs/reference/widgets/feed): Passive team activity feed (SeeSaw Bump) — celebrate teammates' milestones with a clap.
- [Mystery Box widget](https://docs.hatched.live/docs/reference/widgets/mystery-box): Once-a-day surprise reward — a weighted-random coin drop with a deterministic daily seed.
- [League widget](https://docs.hatched.live/docs/reference/widgets/league): Seasonal tier standing — live cohort board, promotion target, and Boss Fight progress.
- [Council widget](https://docs.hatched.live/docs/reference/widgets/council): Elite-circle surface — Council members co-author user-facing narrative copy.
- [Hexad Survey widget](https://docs.hatched.live/docs/reference/widgets/hexad-survey): Marczewski Hexad player-type survey — 24 questions that derive a player's primary type.
- [Login widget](https://docs.hatched.live/docs/reference/widgets/login): Historical note for the retired login widget.
- [Celebrate host](https://docs.hatched.live/docs/reference/widgets/celebrate): One-shot celebration overlay for badges, evolutions, and streak milestones.

## Pricing & billing

- [Pricing](https://docs.hatched.live/docs/billing/pricing): Fixed platform fee + metered AI credits. Four plans (Free, Growth, Pro, Enterprise).
- [Credits](https://docs.hatched.live/docs/billing/credits): How the credit pool works, which jobs cost credits, and the spend order.
- [Stripe portal](https://docs.hatched.live/docs/billing/stripe-portal): Subscription management, invoices, and top-up purchases.
- [Handling 402 responses](https://docs.hatched.live/docs/billing/handling-402): credit_insufficient, event_quota_exceeded — what they mean and how to recover.