On-chain Loyalty

Keyban's On-chain Loyalty turns engagement programs into programmable, verifiable assets. Instead of points trapped in a private database, every issuance, transfer and redemption is recorded on a blockchain — readable by your customer, auditable by you, portable across the apps you operate. This page walks through how a program is shaped, how points reach a wallet, and how a reward gets claimed.

Pick a granularity first

A loyalty program at Keyban sits at one of three scopes. The scope determines who issues points, who can redeem them, and whether the program federates across applications.

Scope	Use case	Issued by	Redeemable across
single-app	One brand, one app — e.g. a coffee chain mobile app	The application owning the program	That single application
cross-program	An ecosystem of partner brands sharing a points currency	Each partner application, against shared rules	All applications enrolled in the program
resale-aware	Programs that recognise second-hand transfers (paired with a DPP)	Application + DPP claim trigger	Original owner and resale recipient

Most teams start with single-app and graduate to cross-program once a second brand or a partner POS (e.g. Zelty) is onboarded. resale-aware typically sits on top of a Digital Product Passport so that a resale event can mint or transfer points to the secondary buyer.

The four-step lifecycle

1. 1

   Step 1: Define

   Configure rules, currency, ratios and rewards in the admin console.

3. 2

   Step 2: Issue

   Backend events trigger on-chain mints to user wallets.

5. 3

   Step 3: Claim

   The user picks a reward and signs the claim through the embedded wallet.

7. 4

   Step 4: Track

   Issuance and redemption history is queryable on-chain and through the API.

A four-step lifecycle: define the program, issue points to wallets, claim rewards, then track and redeem on-chain.

Steps 1, 2 and 4 are partner-side and are driven from the Keyban Dashboard or the backend API with an X-Api-Key. Step 3 is consumer-side and runs through a Keyban end-user app or your own SDK integration.

1. Define the program

A program is configured once per application. From the admin console you set:

• Currency context — the off-chain unit a customer recognises (€, £, points, coffees).
• Earning ratio — how an event in your business converts to points (e.g. 10 points per €1 spent, or 1 point per scan).
• Redemption table — which rewards exist, and how many points each costs (e.g. 100 points = €1 discount, 500 points = a free coffee).
• Eligibility rules — minimum balances, time windows, tier multipliers.

The configuration lives on the application record server-side; the same program can be exposed through the admin UI, the embedded wallet, or a partner POS without re-entering rules.

2. Issue points to wallets

Points are issued through your backend whenever an in-business event qualifies — a purchase, a check-in, a survey response, a DPP claim. Each issuance:

• Calls POST /v1/loyalty/points (or the matching SDK helper) with the recipient and the amount.
• Resolves the recipient's wallet from their email, phone or account UUID — the embedded wallet is provisioned on the fly if the user has not signed in yet.
• Mints the points on-chain so that the recipient sees them appear in any wallet UI they trust.

Issuance is asynchronous: the API returns immediately with a job id, and the on-chain mint is settled in the background. You can poll the job or subscribe to the corresponding event to confirm settlement.

3. Claim a reward

When a customer wants to use their points, they pick a reward in your app or in a Keyban-powered front-end:

• The front-end fetches the redemption table for the program and checks the user's balance.
• The user selects a reward and confirms the claim.
• The embedded wallet co-signs the redemption with Keyban's MPC infrastructure — no seed phrase, no extension to install.
• The corresponding amount is burned from the wallet and the reward voucher (digital code, free product, discount) is delivered through your fulfilment channel.

Because the burn is on-chain, the reward is non-replayable: the same points cannot be claimed twice even if the front-end is reused on another device.

4. Track issuance and redemption

Both the issuance and the redemption emit on-chain events. You can:

• Query the program's history through GET /v1/loyalty/transactions for backend reconciliation.
• Read the same data on-chain to power dashboards or third-party audits.
• Surface a customer-facing transaction history in your app, sourced from the API or the wallet directly.

This dual readability — server-side for your back office, on-chain for your customer — is the structural difference between Keyban's program and a database-only loyalty system.

Programmable incentives

Programs at Keyban are not limited to "spend, earn, redeem". Common patterns we see in production:

• Action-based rewards: scan a QR code on a product, claim a Digital Product Passport, leave a review — each can mint points.
• Tiered multipliers: silver members earn 1×, gold 1.5×, platinum 2× — encoded at the program level, evaluated at issuance time.
• Resale bonuses: when a resale-aware program detects an on-chain DPP transfer, points can be minted to the secondary buyer or split between buyer and seller.
• Time-bound campaigns: issuance rules with a start and end date, or stacked with a base ratio for a holiday season.

Each pattern is configured through the admin console without writing code; the SDK exposes the same surface for fully custom front-ends.

Cross-app compatibility

A cross-program configuration lets several applications share the same point currency. Practical implications:

• A customer who earned points at the e-commerce app can spend them at the partner POS app.
• Settlement between partners is handled at the program level — each application sees the same on-chain balance.
• The Zelty integration is the reference example for restaurant chains: points earned in-store flow to the customer's wallet and become spendable in the brand's mobile app.

This is what "on-chain" structurally enables: the same wallet address is the same identity across apps, no inter-database sync needed.

API and SDK reference

• Endpoint reference (request/response schemas, error shapes): Loyalty API reference.
• React hooks (issuance, balance, redemption history): WAAS React SDK.
• JavaScript SDK for non-React clients: WAAS JavaScript SDK.

Where to go next

• Loyalty assets guide — sizing, formats and brand requirements for reward visuals: Assets guide.
• Zelty integration — connect a restaurant POS to a loyalty program: Zelty integration.
• Digital Product Passport — pair a passport with a loyalty event for resale-aware programs: DPP introduction.