Loyal Spark — Onchain Loyalty Protocol

A Web3-powered loyalty platform built on Base Mainnet: merchants and AI agents create onchain loyalty programs (B20 by default), mint points, manage rewards/vouchers, and automate the loop via REST, MCP, and pay-per-call gateways (x402 / MPP).

Overview

Loyal Spark revolutionizes traditional loyalty programs by bringing them onchain. It operates as a dual-mode platform: humans interact via the web UI with flexible authentication (email, phone, social login, or wallet), while AI agents interact via REST API or MCP Server — sharing the same database, smart contracts, and tokens.

Wallet Abstraction: Users and merchants sign in via Coinbase Embedded Wallets — Google, email code, or external wallets (MetaMask, Coinbase Wallet, Base App). Coinbase automatically creates a gas-sponsored smart account on Base — no crypto experience needed. Farcaster miniapp and SIWE for crypto-native users are also fully supported. Merchants can send tokens to customers by email or QR code (resolved to wallet address automatically).

┌─────────────────────────────────────────────────┐
│              Loyal Spark Platform                │
│                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │  Web UI   │    │ REST API │    │MCP Server│   │
│  │ (humans)  │    │ (agents) │    │ (agents) │   │
│  └─────┬─────┘    └─────┬────┘    └─────┬────┘   │
│        │                │               │        │
│        ▼                ▼               ▼        │
│  ┌──────────────────────────────────────────┐    │
│  │        Backend (Edge Functions)           │    │
│  │    Auth · RLS · DB · Realtime             │    │
│  └─────────────────┬────────────────────────┘    │
│                    │                             │
│        ┌───────────┴───────────┐                 │
│        ▼                       ▼                 │
│  ┌──────────┐          ┌──────────────┐          │
│  │ Base L2  │          │ CDP Server   │          │
│  │ Contracts│          │ Wallet (MPC) │          │
│  └──────────┘          └──────────────┘          │
└─────────────────────────────────────────────────┘

Features

For Merchants (Web UI)

• Deploy Loyalty Tokens: Create custom loyalty tokens on Base (B20 default; legacy ERC-20 via API)
• Mint Tokens: Issue loyalty points to customers via wallet addresses or QR scan
• Create Rewards: Design voucher rewards with token costs
• CRM & Analytics: Customer profiles, RFM segmentation, tier management
• Marketing Automation: Automated campaigns, personalized offers
• Referral Programs: Generate referral codes with bonuses
• Voucher Management: Track redemptions with QR code verification
• AI Agent Management: Register agents, manage API keys, monitor activity
• Team & branches: Invite cashiers/managers by wallet or one-time invite code (redeem on Merchant → Team); requires Postgres RPC accept_merchant_invite — see docs/development/PORTALS_AND_TEAM.md

For Customers (Web UI)

• Multi-Token Dashboard: View all loyalty tokens from different merchants
• Browse Rewards: Explore available vouchers across all programs
• Redeem Vouchers: Burn tokens to claim exclusive rewards with QR codes
• Tier System: Bronze → Silver → Gold → Platinum with increasing perks
• Frozen module (not a product promise): marketplace/ (DEX) remains in the tree but is explicitly frozen — no active development

For AI Agents (REST API + MCP)

• Full CRUD via API: Create programs, mint tokens, manage rewards, view analytics
• MCP Server: Connect Claude, GPT, Cursor, or any MCP-compatible LLM directly
• Server Wallets: Coinbase CDP MPC wallets for autonomous onchain operations
• Scoped Permissions: Granular access control (read, mint, manage_rewards, trade)
• Activity Logging: Full audit trail of all agent operations
• Tiered Pricing (agents): Free (200 calls/mo, 1 agent, 1,000 tokens minted/mo, 1.25% mint fee) → Pro ($49/mo, 0.5%) → Enterprise ($129/mo, 0.25%) — subscriptions in USDC, mint fee in loyalty tokens (off-chain obligation, not enforced by the token contract); see docs/business/MONETIZATION_AND_PRICING.md
• Skills Documentation: 16 structured step-by-step guides (00–15 under /.well-known/skills/) for agent onboarding, B20 semantics, and payment rails

Technology Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui (Radix)
Animations	Framer Motion
Blockchain	Wagmi v2, Viem, RainbowKit, Coinbase CDP (@coinbase/cdp-hooks + @coinbase/cdp-wagmi)
Network	Base Mainnet (Chain ID: 8453)
Smart Contracts	Base-native B20 Asset precompile + legacy ERC-20 factory
Backend	Supabase (PostgreSQL, RLS, Deno Edge Functions, Realtime)
Native apps	Capacitor 8 (iOS / Android) — see docs/development/NATIVE_BUILD_GUIDE.md
Agent Wallets	Coinbase CDP MPC (Server Wallets)
State	TanStack Query v5
Routing	React Router DOM v6
Forms	React Hook Form + Zod validation
Builder Attribution	Base Builder Code (ERC-8021)

Smart Contract Architecture

New loyalty programs (default) deploy via Base’s native B20 factory precompile — one transaction, active immediately after register-program. Legacy programs use the Loyal Spark ERC-20 factory below (token_standard: "erc20" in API only). Full flows: docs/development/LOYALTY_PROGRAM_CONTRACTS.md.

Role	Address	When
B20 Factory (Base precompile)	0xB20f000000000000000000000000000000000000	Default — createB20 → token 0xB200…
LoyaltyTokenFactory (legacy)	0x5F3DdBa12580CFdc6016258774cCc19C4250dA80	Opt-in erc20 — createLoyaltyToken + activation
LoyalSparkERC20 (implementation)	0xe6BA426C9c51281B929a17444De02c65815E27C3	Logic for legacy proxy tokens
LoyaltyTokenEscrow (P2P)	0xA569C95AfC1BCF381c48BcF336ED9D2c014bcdDF	Marketplace swaps

Network: Base Mainnet (Chain ID: 8453)

Program creation (summary)

Path	Deploy	Activate	Portal
B20 (default)	1× createB20 on 0xB20f…	Not required	Yes
Legacy ERC-20	1× createLoyaltyToken on 0x5F3DdB…	unpauseUtility + enableMinting	API only

Token operations (both standards)

B20 tokens are ERC-20–compatible for balances, transfers, mint, and escrow:

• mint(address to, uint256 amount) — issue points (role-gated)
• transfer / transferFrom — move tokens between wallets
• balanceOf(address) — query balance

AI Agent Integration

Quick Start

Merchant dashboard:

1. Go to loyalspark.online/merchant and sign in (Google, email via Coinbase, or a wallet)
2. Open AI Agents tab → Register an agent → Copy your API key (lsk_...)
3. Use the key in x-api-key header for REST or MCP calls

Without the web app (autonomous agents): free lsk_ via wallet signature — Edge Function agent-register-siwe + nonce from siwe-nonce. See docs/agents/AUTONOMOUS_AGENT_REGISTRATION.md and docs/agents/QUICKSTART.md.

Optional repo scripts (development / agent onboarding)

These directories are not imported by the web app; they are optional helpers for developers and agents reproducing flows locally. Secrets stay in environment variables only.

Folder	Purpose
scripts/x402-paid-mcp-test/	Smoke test: paid MCP via x402 (USDC on Base, @x402/fetch).
scripts/x402-paid-agent-api/	Same stack, paid agent-api routes (GET/POST to x402-gateway/<resource>).
scripts/agent-register-siwe/	Helper: build SIWE message + sign + call agent-register-siwe (same as production).

Schemas for paid MCP: merchant mcp-tools/<name> — mcp-bazaar-tools.ts; recipient recipient-mcp-tools/<name> — recipient-mcp-bazaar-tools.ts. HTTP 402 accepts + Coinbase x402 Bazaar discovery metadata for all paid routes are built in x402-bazaar-accept.ts. These scripts are not linked from the marketing homepage; primary onboarding remains /for-agents and the merchant portal.

REST API

# List loyalty programs
curl -H "x-api-key: lsk_YOUR_KEY" \
  https://api.loyalspark.online/agent-api/programs

# Mint tokens — returns a fee-first calls[] bundle (1.25% fee on Free plan,
# minted in your own loyalty tokens); settle it via POST /agent-api/mint/confirm
curl -X POST \
  -H "x-api-key: lsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token_address":"0x...","recipient_address":"0x...","amount":100}' \
  https://api.loyalspark.online/agent-api/mint

API Endpoints (28 authenticated + 1 public)

All routes below require x-api-key: lsk_... except GET /vouchers/status (public). Canonical catalogue: public/.well-known/agent.json (must match supabase/functions/agent-api/index.ts).

Method	Path	Scope	Description
GET	/me	authenticated	Agent profile & permissions
GET	/workflow/program-status	read	Autonomous planner: lifecycle step + next_actions[]
GET	/programs	read	List loyalty programs
POST	/workflow/generate-program-defaults	read, mint, or create_program	Propose program name, symbol, economics, and starter rewards from business context
POST	/programs	mint or create_program	Calldata to deploy loyalty token (B20 default, or legacy ERC-20 with token_standard: "erc20")
POST	/register-program	mint or create_program	Register deployed token (optional cashback_rate, points_per_dollar)
POST	/update-program-config	mint or create_program	Update cashback_rate / points_per_dollar for a program
POST	/activate-program	mint or create_program	Legacy ERC-20 activation only (no-op for B20)
POST	/program-status	mint or create_program	Update program status
GET	/rewards	read	List rewards
POST	/rewards	manage_rewards	Create reward
POST	/mint	mint	Fee-first mint calls[] + fee_obligation_id
POST	/mint/confirm	mint	Settle protocol fee after mint/earn (obligation_id + fee_tx_hash)
POST	/earn	mint	Cashback: mint from purchase amount × rate (same fee-first + confirm)
POST	/transfer	mint	Transfer tokens
GET	/balance	read	Token balance & tier
GET	/customers	read	Customer list
GET	/vouchers	read	List vouchers
GET	/vouchers/status	public	Check voucher status (no API key)
POST	/redeem-reward	read	Redeem reward → create voucher
POST	/vouchers/use	manage_rewards	Mark voucher as used
GET	/analytics	read	Program analytics
GET	/offers	read	Marketplace offers
POST	/offers	trade	Create P2P offer
POST	/accept-offer	trade	Accept P2P offer
POST	/cancel-offer	trade	Cancel P2P offer
GET	/tx-receipt	authenticated	Extract token_address from deploy tx
GET	/merchant-profile	read	Read merchant profile
POST	/merchant-profile	manage_rewards	Create or update merchant profile (PUT also accepted)

MCP Server (for LLMs)

Connect Claude, GPT, or any MCP-compatible agent:

{
  "mcpServers": {
    "loyal-spark": {
      "url": "https://api.loyalspark.online/loyalty-mcp",
      "headers": {
        "x-api-key": "lsk_YOUR_KEY"
      }
    }
  }
}

MCP tools (39) — defined in supabase/functions/loyalty-mcp/index.ts:
get_platform_info, get_my_profile, generate_program_defaults, get_program_workflow_status, list_loyalty_programs, create_loyalty_program, register_loyalty_program, activate_loyalty_program, update_program_status, update_program_config, list_rewards, create_reward, mint_loyalty_tokens, transfer_loyalty_tokens, earn_points, confirm_mint_fee, get_token_balance, get_program_analytics, list_marketplace_offers, redeem_reward, use_voucher, check_voucher_status, get_platform_stats, cancel_stale_offers, create_personalized_offer, update_reward_status, export_customers, send_report, list_my_reports, update_report_status, delete_report, create_gift_certificate, list_gift_certificates, revoke_gift_certificate, mark_gift_certificate_minted, bazaar_discover_resources, bazaar_discover_mcp_servers, bazaar_probe_x402, bazaar_pay_and_call (confirm_mint_fee = lsk_-only fee settlement, not x402-priced; last four = Bazaar side-car).

Base MCP custom plugin (send_calls-ready calldata)

For AI users already connected to Base MCP (mcp.base.org), Loyal Spark ships GET-friendly calldata endpoints at https://api.loyalspark.online/agent-prepare/*. Each response returns a send_calls-compatible transaction batch with Builder Code bc_wdmnog7m already appended (ERC-8021). Base Account signs and broadcasts.

Actions: create-program, activate-program, mint, transfer (merchant, lsk_) · recipient-transfer, recipient-approve (holder, rwk_).

# Prepare a mint (returns { transactions: [{to,data,value}], … } for send_calls)
curl -H "x-api-key: lsk_YOUR_KEY" \
  "https://api.loyalspark.online/agent-prepare/mint?token=0xTOKEN&to=0xCUSTOMER&amount=100"

Plugin spec: skills/loyal-spark/plugins/loyal-spark.md.

Recipient agents (wallet holders, rwk_)

For AI agents that only hold a wallet which receives loyalty tokens (not merchant operators). Humans are unchanged; this is an optional machine path.

Piece	URL / path
REST	https://api.loyalspark.online/recipient-api
MCP	https://api.loyalspark.online/recipient-loyalty-mcp
Register key	POST …/recipient-api/register with SIWE { message, signature } (nonce from siwe-nonce) — returns rwk_… once. Pass Supabase apikey (anon/publishable) header like other public functions.

REST (14 routes; all require x-api-key: rwk_… except register): GET /me, GET /balances, GET /balance?token_address=, GET /rewards?token_address=, GET /vouchers, GET /workflow/reward-status, POST /register (SIWE), POST /redeem-reward with { reward_id, transaction_hash } (customer is always the bound wallet), POST /prepare-transfer with { token_address, to, amount }, POST /workflow/prepare-reward-redemption. P2P: GET /offers?token_address=, POST /offers, POST /accept-offer, POST /cancel-offer (same bodies as merchant agent-api marketplace; creator_address is the bound wallet).

MCP tools (20) — supabase/functions/recipient-loyalty-mcp/index.ts: get_recipient_profile, list_my_loyalty_balances, get_my_loyalty_balance, get_reward_workflow_status, prepare_reward_redemption, prepare_loyalty_token_transfer, list_rewards_for_program, list_my_vouchers, redeem_my_reward, list_p2p_offers, create_p2p_offer, accept_p2p_offer, cancel_p2p_offer, lookup_gift_certificate, claim_gift_certificate, list_my_gift_certificates, bazaar_discover_resources, bazaar_discover_mcp_servers, bazaar_probe_x402, bazaar_pay_and_call (last four = Bazaar side-car; bazaar_pay_and_call requires opt-in delegated CDP wallet).

Pay-per-call (recipient, MPP / x402): Autonomous agents that should pay USDC per request use the same gateways as merchants: mpp-gateway/recipient-api/… (Tempo MPP) or x402-gateway/recipient-api/… and x402-gateway/recipient-mcp-tools/<tool> (x402). USD prices match the merchant corridor (reads ~$0.001, writes ~$0.005–0.01; prepare-transfer / prepare_loyalty_token_transfer $0.005). Canonical tables: docs/business/MONETIZATION_AND_PRICING.md §4.1 · source constants: supabase/functions/_shared/recipient-paid-routes.ts, recipient-mcp-bazaar-tools.ts. Direct functions/v1/recipient-api / recipient-loyalty-mcp calls use rwk_ + rate limits only (no per-request USDC in the gateway layer).

Example MCP fragment: examples/recipient-agent-mcp/cursor-mcp.json.

Agent Discovery

AI agents can discover the protocol automatically via:

• /.well-known/agent.json — Full protocol specification, capabilities, pricing
• /.well-known/skills/ — 16 structured Skills (00–15, step-by-step guides)
• /api-docs — Interactive API documentation

Skills for AI Agents

Structured Markdown guides that teach agents how to use the protocol:

#	Skill	Description
00	Getting Started	Register agent (merchant UI or SIWE), get lsk_, first request
01	Create Loyalty Program	Deploy B20 loyalty token on Base (legacy ERC-20 optional)
02	Mint Tokens	Mint tokens to customer wallets
03	Transfer Tokens	Transfer tokens between wallets
04	Manage Rewards	Create redeemable rewards catalog
05	Balance & Tiers	Check balances and tier status
06	Marketplace Trading	P2P token trading with atomic escrow
07	Analytics & CRM	Program analytics and CRM data
08	Referrals	Referral programs for organic growth
09	Vouchers	Voucher lifecycle management
10	Server Wallets	CDP MPC wallets for autonomous transactions
11	Earn Points (Cashback)	Mint from purchase amount × cashback rate
12	Gift Certificates	Issue, claim, and mint LOYAL-XXXXXX certificates
13	Endpoint Workflows	Multi-step REST/MCP flows and prerequisites
14	B20 Native Spec	Base Beryl B20 Asset semantics for loyalty tokens
15	Payment Scenarios	x402 exact, MPP, subscriptions, spend policies

Installable skill bundle (CLI): npx skills add aspekt19/unboxed-loyalty-spark --skill loyal-spark — source in skills/loyal-spark/.

Skills index: https://loyalspark.online/.well-known/skills/index.md

Server Wallets (CDP MPC)

Agents can create their own Coinbase MPC wallets on Base for autonomous transactions:

curl -X POST \
  -H "x-api-key: lsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"create_wallet"}' \
  https://api.loyalspark.online/agent-wallet

Benefits:

• No private key management — keys are in Coinbase's secure enclave
• Server-side transaction signing
• Automatic Builder Code attribution (ERC-8021)

Pricing

Plan	Monthly	API Calls	Agents	Mint fee	Mint cap
Free	$0	200	1	1.25%	1,000 tokens/mo
Pro	$49 USDC	10,000	5	0.5%	Unlimited
Enterprise	$129 USDC	Unlimited	Unlimited	0.25%	Unlimited

Merchant SaaS (portal): Starter $39 / Growth $79 / Scale $149 per month (annual discount 15–20% optional) — details in docs/business/MONETIZATION_AND_PRICING.md.

Payments for agent plans on-chain in USDC on Base ($1 = 1 USDC). Plan limits (API calls, agent seats, Free-tier mint cap) are enforced server-side in Edge Functions — see MONETIZATION_AND_PRICING.md.

Mint fee is not USDC. It is charged in the merchant's own loyalty tokens — a second mint(address,uint256) to the platform fee wallet on the same token contract, returned first in the calls[] bundle. The token contract has no mintWithFee, so settlement is tracked off-chain: each prepared mint creates a fee obligation, and 5+ obligations unpaid for over 60 minutes block further mints with HTTP 402. Confirm with POST /agent-api/mint/confirm.

Getting Started

Prerequisites

• Node.js 18+ or Bun
• An email, phone number, Google account, or Web3 wallet (MetaMask, Coinbase Wallet, WalletConnect)
• Some ETH on Base for gas fees (merchants only)

Installation

git clone https://github.com/aspekt19/unboxed-loyalty-spark.git
cd unboxed-loyalty-spark
npm install
npm run dev

Sign In Options

• Google / Email (recommended): Click "Sign In" — a Coinbase smart wallet is created automatically, no crypto knowledge needed
• MetaMask / Coinbase Wallet / WalletConnect: Traditional Web3 wallet connection
• Farcaster: Auto-connects inside Warpcast miniapp

On Merchant and Customer portals, use the header Sign In / wallet control until a session exists; the Profile control appears only after you are signed in. See docs/development/PORTALS_AND_TEAM.md.

Network: Base Mainnet (Chain ID: 8453) | RPC: https://mainnet.base.org | Explorer: https://basescan.org

Project Structure