Design principles

Seven rules the rest of the architecture follows. Each one exists because the alternative caused a concrete problem.

One financial logic, many channels

The Partner application, WhatsApp, a white-label portal or any future channel never implement financial rules of their own. A channel collects the intent, shows the quote, obtains confirmation and presents state.

Idempotency, limits, fees, authorization, signing, execution, ledger and reconciliation are resolved once, in the B2B core. A rule implemented twice is a rule that will eventually disagree with itself, and the disagreement will be about money.

The Partner controls the real deployment

The reference profile for an external Partner is self-hosted. When a deployment moves real funds, the runtime executes inside cloud infrastructure the Partner controls, along with service identities, networking, secrets, key material, policies, operating funds, deployments and release promotion.

ChatterPay publishes versioned artefacts; the Partner decides when to promote them. See Reference deployment topology.

The Sandbox is the first reference Partner

The Sandbox on this site is not a special interface that skips internal components. It is treated as a complete Partner integration and travels the same public boundaries an external Partner uses:

Browser
→ Sandbox Partner BFF
→ SDK
→ B2B API
→ Recipient Resolver
→ Operations / Workers
→ Partner Signer Gateway
→ chain adapter
→ blockchain or simulator
→ reconciliation and events
→ signed webhook back to the Sandbox Partner BFF

Even in the Mock profile, where there is no real transaction to sign, the signing boundary is not skipped: a deterministic synthetic authorization digest goes through the real Partner Signer Gateway before any simulated result is returned.

The API and the SDK are the integration contract

The recommended path is Partner app → Partner backend → SDK → API.

The SDK is a typed client for the API: it carries authentication, idempotency, serialization, errors, polling, event cursors and webhook verification. It never hands over private keys, and it does not expose arbitrary blockchain primitives.

Operations are durable and asynchronous

An HTTP call does not stay open for the length of a blockchain operation. The API validates and persists an Operation, returns an identifier, and processing continues through workers and events.

Critical state lives in durable storage, never in the memory of a process, because a process restart in the middle of a transfer must not lose what happened.

Intent is separate from execution mechanism

The financial intent states what the user wants: asset, amount, recipient, network, quote, limits and expiry. Each network's adapter turns that intent into a technical payload.

Switching between a direct relayer, ERC-4337, Bitcoin, Cardano or an external route provider therefore changes the payload, not the business semantics.

Security evolves without changing the financial API

The initial profile prioritizes a clear signing boundary, secrets outside the API, explicit authorization, audit, limits and operable recovery.

The same signing port evolves to independent per-wallet keys, KMS or HSM, or MPC, without touching the financial contract. See Security and signing.