Skip to main content

​
Main non-admin routes

  • GET /api/packs
  • GET /api/packs/[id]
  • POST /api/packs/[id]/purchase
  • POST /api/packs/[id]/open
  • GET /api/packs/[id]/odds
  • GET /api/user/packs
  • GET /api/user/packs/opened
  • GET /api/user/collectibles
  • GET/PUT /api/user/featured-collectibles
  • GET/POST /api/binders, GET/PATCH/DELETE /api/binders/[id]
  • POST /api/binders/[id]/verify-pin
  • GET /api/v1/cards/[id]/provenance

​
Runtime behavior highlights

  • Pack browse routes expose currently available packs and pack metadata.
  • POST /api/packs/[id]/purchase starts a purchase. PUT on the same path always returns 410 GONE. Confirmation moved to POST /api/checkout/crypto/verify.
  • Purchase start records pack purchase state for the user. Free packs are limited to 3 purchases per user per UTC day.
  • Open route resolves collectible outcomes and updates user ownership/inventory state.
  • GET /api/user/packs status is authoritative (pending | processing | opened | completed). Template isOpenable is not per-purchase state.
  • User collectible and pack routes expose owned content for client rendering.
  • Featured collectibles expose a public showcase; authenticated replace is capped at 12 slots.
  • Binder routes (/api/binders*) are in the generated OpenAPI. Cover upload is POST /api/upload/binder-cover.
  • PIN binders require x-binder-pin-token from verify-pin. Without it, GET /api/binders/[id] returns 403 PIN_REQUIRED and metadata only.
  • GET /api/v1/cards/[id]/provenance is public and returns { card, currentOwners, transfers, mints }.

​
Side effects and dependencies

  • Purchase/open flows may integrate with checkout, wallet, and minting subsystems.
  • Historical fix/backfill scripts exist for pack purchase and rarity correction scenarios.

​
Known caveats

  • Deterministic guarantees depend on pack configuration integrity and weighted content setup.
  • Open and purchase flow state transitions can require reconciliation in rare partial-failure cases.

​
Exclusions

  • Admin collectible/pack creation and stock management flows are excluded.