Architecture Overview
What you're integrating with: the three-chain model, the APIs, the webhooks, and where your program fits.
If you're building against HeartBadge, this is the page to start with. It's the bird's-eye view of what's on the other side of the API call and how the pieces relate.
The three chains
HeartBadge operates across two layers, each handling what it does best. As a developer, you interact with the HeartBadge API — the API fans out calls to the right layer. You don't need to run a node on any of them.
- OP_CAT Layer (identity & proof). Badges live here as CAT-721 tokens under the HeartBadgeRulesContract covenant. C-Protocol attestations also run here — event check-ins, quest completions, co-sign proofs.
- BSV (rewards). MNEE micropayments, balance tracking, and the messagebox surface. High throughput, low fees.
See Three-Chain Overview for the architectural detail.
What you'll build with
- REST APIs for minting, reward distribution, gift codes, and lookups. Authenticated with program credentials.
- Webhooks that fire on protocol events — badge activated, reward delivered, event check-in received. Signed, with delivery guarantees.
- SDKs for TypeScript (the primary), or HTTP directly from any language.
Where your program lives
Each program deploys its own collection on the OP_CAT
Layer via POST /cat721/collection/deploy. Every badge
your program mints is part of this collection. The collection is the
unit of governance — your covenant rules, your operator identity keys,
your reward policies are all scoped to it.
Typical integration flow
- Deploy your collection (once)
- Mint badges as members purchase memberships
- Handle webhook events from member activity
- Distribute rewards from your backend as events happen
- Surface wallet and tier to members through the embeddable components or your own UI
From here, Authentication and Environments get you ready to make your first call, and Mint Your First Badge walks you through the happy path.