Loyal Spark — Onchain Loyalty Protocol

A Web3-powered loyalty platform built on Base Mainnet, enabling merchants and AI agents to create custom loyalty token programs while customers earn rewards that automatically invest and grow through DeFi.

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 wallet-based authentication (SIWE), while AI agents interact via REST API or MCP Server — sharing the same database, smart contracts, and tokens.

┌─────────────────────────────────────────────────┐
│              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 ERC-20 loyalty tokens on Base
• 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

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
• DEX Trading: Trade loyalty tokens on decentralized exchanges
• Round-Up Investment: Automatically invest spare change into DeFi (Aave/Compound)
• Tier System: Bronze → Silver → Gold → Platinum with increasing perks

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: Free (100 calls/mo, 1% fee) → Pro ($29/mo, 0.5%) → Enterprise ($99/mo, 0.25%)

Technology Stack

Smart Contract Architecture

Network: Base Mainnet (Chain ID: 8453)

Core Functions

• deployLoyaltyToken(name, symbol) — Deploy new ERC-20 token
• mint(address to, uint256 amount) — Issue new tokens (owner only)
• burn(uint256 amount) — Burn tokens for voucher redemption
• transfer(address to, uint256 amount) — Transfer tokens between wallets
• balanceOf(address account) — Query token balance

AI Agent Integration

Quick Start

1. Go to loyalspark.online/merchant and connect 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

REST API

# List loyalty programs
curl -H "x-api-key: lsk_YOUR_KEY" \
  https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/agent-api/programs

# Mint tokens (1% fee on Free plan)
curl -X POST \
  -H "x-api-key: lsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token_address":"0x...","recipient":"0x...","amount":100}' \
  https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/agent-api/mint

API Endpoints

MCP Server (for LLMs)

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

{
  "mcpServers": {
    "loyal-spark": {
      "url": "https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/loyalty-mcp",
      "headers": {
        "x-api-key": "lsk_YOUR_KEY"
      }
    }
  }
}

Available MCP Tools: get_platform_info, get_my_profile, list_loyalty_programs, list_rewards, create_reward, mint_loyalty_tokens, get_token_balance, get_program_analytics, list_marketplace_offers

Agent Discovery

AI agents can discover the protocol automatically via:

• /.well-known/agent.json — Full protocol specification, capabilities, pricing
• /api-docs — Interactive API documentation

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_server_wallet"}' \
  https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/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

Payments accepted on-chain in USDC on Base ($1 = 1 USDC).

Getting Started

Prerequisites

• Node.js 18+ or Bun
• MetaMask, Coinbase Wallet, or any WalletConnect-compatible wallet
• Base Mainnet configured in your wallet
• Some ETH on Base for gas fees

Installation

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

Wallet Setup

1. Network: Base Mainnet
2. Chain ID: 8453
3. RPC URL: https://mainnet.base.org
4. Currency: ETH
5. Explorer: https://basescan.org

Project Structure

unboxed-loyalty-spark/
├── src/
│   ├── components/
│   │   ├── ui/                    # shadcn/ui library
│   │   ├── agents/                # AI agent management
│   │   ├── rewards/               # Rewards & vouchers
│   │   ├── crm/                   # CRM & analytics
│   │   ├── marketing/             # Campaigns
│   │   ├── automation/            # Marketing automation
│   │   ├── tiers/                 # Customer tiers
│   │   ├── referral/              # Referral programs
│   │   ├── roundup/               # DeFi investment
│   │   ├── marketplace/           # Token trading
│   │   ├── reviews/               # Customer reviews
│   │   ├── onboarding/            # Welcome flows & tours
│   │   └── admin/                 # Platform administration
│   ├── hooks/                     # Custom React hooks
│   ├── config/                    # Contract addresses & ABIs
│   ├── contexts/                  # Auth context
│   ├── integrations/supabase/     # Database client & types
│   ├── pages/                     # Route pages
│   └── lib/                       # Utilities
├── public/
│   ├── .well-known/
│   │   ├── agent.json             # AI agent discovery
│   │   └── farcaster.json         # Farcaster manifest
│   └── media-kit/                 # Brand assets
├── contracts/                     # Solidity contracts
├── supabase/
│   ├── functions/
│   │   ├── agent-api/             # REST API for agents
│   │   ├── agent-wallet/          # CDP wallet management
│   │   ├── agent-api-key/         # API key generation
│   │   ├── loyalty-mcp/           # MCP Server
│   │   ├── siwe-verify/           # Wallet authentication
│   │   ├── verify-payment/        # Payment verification
│   │   └── ...                    # Other edge functions
│   └── migrations/                # Database migrations
└── README.md

Edge Functions

Security

• SIWE Authentication: Wallet signature-based authentication for humans
• API Key Auth: SHA-256 hashed keys with lsk_ prefix for agents
• Row Level Security: All database tables protected with RLS policies
• Scoped Permissions: Agents operate within granted scopes only
• MPC Wallets: Private keys never leave Coinbase's secure enclave
• Rate Limiting: Per-agent rate limits prevent abuse
• Builder Code Attribution: All transactions tagged with ERC-8021 builder code

Builder Code

All on-chain transactions are tagged with Base Builder Code bc_wdmnog7m (ERC-8021 format) for analytics visibility in base.dev.

Links & Resources

• Website: loyalspark.online
• API Docs: loyalspark.online/api-docs
• Agent Discovery: loyalspark.online/.well-known/agent.json
• GitHub: github.com/aspekt19/unboxed-loyalty-spark
• Twitter/X: x.com/Loyal_Spark
• Email: admin@loyalspark.online

Built With

• Base — Ethereum L2 by Coinbase
• Coinbase CDP — MPC Server Wallets
• Wagmi — React Hooks for Ethereum
• RainbowKit — Wallet Connection
• shadcn/ui — UI Components
• Lovable — Full-Stack Development Platform
• Viem — TypeScript Interface for Ethereum

License

MIT License — see LICENSE file for details.