Hatched Documentation

1 credit = $0.10 = 1 completed AI job.

Every call to Hatched's generative pipeline authorizes one credit up-front, runs, then commits (success) or rolls back (failure). Preset and cache-hit paths cost zero credits.

Job types

Job	Credits
Onboarding chat turn	1
Website scan	1
Plan generation / regeneration	1
Theme synthesis	1
Integration guide	1
Hatch (creature)	1
Equip / composite edit	1
Evolve (generative)	1
Badge icon	1
Skill icon	1
Marketplace item image	1
Stage asset	1
Preset / cache-hit evolution	0
Platform-internal asset prompt drafting	0

Three pools

Credits live in three pools, spent in this order:

promo — time-limited (30-day expiry), spent first.
welcome — 10 one-time credits granted on signup, never expires while the account exists.
paid — top-ups and subscription grants. Persistent while the subscription is active.

A single 1-credit job debits from exactly one pool — no splitting across pools. If the pool with enough balance for the requested cost exists, we use it; otherwise the API returns 402 credit_insufficient.

Monthly subscription grant

Growth grants 50 credits each month on successful invoice.payment_succeeded. Pro grants 250. Granted credits go to the paid pool. Paid credits do not expire until the subscription ends.

Top-up bundles

Bought via the Stripe Customer Portal:

Bundle	Price	Effective per-credit
100	$10	$0.100
500	$50	$0.100
1,000	$99	$0.099

Reading the balance

GET /api/v1/credits/balance
Authorization: Bearer hatch_live_…

{
  "welcome": 7,
  "paid": 43,
  "promo": 0,
  "promo_expires_at": null,
  "total_spendable": 50
}

Every authenticated response also includes:

X-Credits-Remaining
X-Credits-Welcome-Remaining
X-Credits-Paid-Remaining
X-Credits-Promo-Remaining

Ledger

GET /api/v1/credits/ledger?limit=50 returns the 50 most recent AI usage rows (authorize/commit/rollback) — the same rows the dashboard's Billing page displays.

Onboarding cap

During the very first publish, Hatched generates at most 4 images (creature, one stage preview, one badge, one item). Remaining badge/item icons stay in pending and surface as "Generate now" actions in the dashboard — the operator pays 1 credit per asset they actually need.

Credits