Docs/Getting started/Overview

Loyfin documentation

Add Loyfin to your existing loyalty system. Customers can convert eligible points into wallet tokens, send them to other people, and convert valid tokens back into points in your program.

Start with the working quickstart to create a checkout, or compare signing options for an existing issuer wallet.

Loyfin connects your existing points system to customer wallets. Add to wallet converts eligible points into tokens. Add from wallet burns those tokens so your backend can restore the matching points to the customer’s account. You keep your customer accounts, earning rules, points database, and support tools.

01

Define the program

Map an existing loyalty program to a Loyalty Token identity, artwork, issuer wallet, expiry policy, and Add from wallet policy.

02

Sign tokenization actions

Your issuer signs the amount, program, expiry, and reference for each conversion. A separate customer signature authorizes the recipient or holder wallet.

03

Customer submits

The customer authorizes the conversion in Loyfin Checkout and pays the action fee plus network gas. Your backend uses finalized completion receipts to update its records.

Add to walletView API

Tokenization layer#

Keep your existing loyalty system.

Your database remains the record of points in each brand account. Customers choose how many eligible points to convert into wallet tokens. They can send those tokens to someone else or convert valid tokens back into points in your program.

  • Your existing app remains the place for customer authentication, earning rules, fraud checks, support, and fulfillment.
  • issue is Add to wallet: it converts eligible points into tokens held in the customer’s wallet.
  • redeem is Add from wallet: it burns wallet tokens so your backend can credit the matching points to a brand account.
  • operationHash connects each Loyfin action to the brand's internal database row.

Brand checklist#

A non-technical team can gather these before an engineer touches the API.

Program name and short symbolProgram artworkAssigned or external issuer walletFirst customer or seed walletReward amount rulesExpiry policyAdd from wallet policy

Choose your path#

Start with the task closest to what you are shipping.

Mainnet launchPlan a small trial, wallet custody, balance reconciliation, and customer instructions.Add to walletConvert eligible points into tokens in a customer’s wallet.Add from walletBurn wallet tokens and credit matching points to the customer’s brand account.Customer-paid checkoutHave the customer authorize and submit the action while paying the action fee and network gas.

Admin controls#

Brand identity and admin control are separate.

The issuer is the immutable brand identity for a Loyalty Token and signs issue and redeem actions forever. The owner is the admin for mutable settings: metadata and royalty settings. New programs have no pause controls.

  • transferOwnership moves admin control only; it does not change the issuer or brand identity.
  • renounceOwnership freezes owner-controlled settings, while issuer-signed issue and redeem actions can continue subject to signature and expiry checks.
  • Brands that need signer rotation should use a multisig as issuer and rotate signers inside that multisig.

Fees and brand revenue#

Earn fees on completed wallet conversions.

Customers pay a 0.1 USD action fee when converting points to or from their wallets. The contract splits this fee between the issuer and Loyfin. Customers also pay network fees in USD through Privy.

The brand can also receive royalties when customers sell tokenized points through marketplaces that honor the program’s royalty settings. A sale and its royalty depend on the marketplace; Loyfin does not guarantee a buyer.

Glossary#

The words used across the guides.

Brand wallet

The wallet or approved contract wallet that signs reward actions.

Program

A brand loyalty program with its own identity, balances, metadata, and controls.

Reward action

A signed issuance or redemption prepared by the brand.

Nonce

A unique per-issuer value that prevents replaying the same signed action.

Expiry bucket

The reward bucket selected by expiresAt. Use 0 for no expiry.

Action deadline

The latest time a signed issuance or redemption can be submitted. Use 0 for no deadline.

Submitting wallet

The customer wallet that authorizes a prepared action and pays the exact action fee plus network gas.

Marketplace royalties

Program-level royalties that compatible marketplaces can honor on secondary activity.