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 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 Privy — email, phone/SMS, Google, or external wallets (MetaMask, WalletConnect, Coinbase Wallet). Privy automatically creates an embedded wallet 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 phone number (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 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

• 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

• DEX Trading: Trade loyalty tokens on decentralized exchanges (module frozen in this repo — no new work in marketplace/)

• Round-Up Investment: Automatically invest spare change into DeFi (module frozen in this repo — no new work in roundup/)

• 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 (agents): Free (200 calls/mo, 1.25% mint fee) → Pro ($49/mo, 0.5%) → Enterprise ($129/mo, 0.25%) — see docs/business/MONETIZATION_AND_PRICING.md

• Skills Documentation: 12 structured step-by-step guides (00–11 under /.well-known/skills/) for agent onboarding and operations

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

Merchant dashboard:

1. Go to loyalspark.online/merchant and sign in (email, phone, Google, or wallet via Privy)

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.

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 (1.25% mint 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://api.loyalspark.online/agent-api/mint

API Endpoints (23 authenticated + 1 public)

All routes below require x-api-key: lsk_... except GET /vouchers/status (public).

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 (28) — defined in supabase/functions/loyalty-mcp/index.ts:
get_platform_info, get_my_profile, 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, 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.

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.

REST (all require x-api-key: rwk_… except register): GET /me, GET /balances, GET /balance?token_address=, GET /rewards?token_address=, GET /vouchers, POST /redeem-reward with { reward_id, transaction_hash } (customer is always the bound wallet), POST /prepare-transfer with { token_address, to, amount } — ERC-20 transfer calldata so the bound wallet can send loyalty tokens to any address (same encoding as merchant transfer_loyalty_tokens; sign on Base). 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 (11) — supabase/functions/recipient-loyalty-mcp/index.ts: get_recipient_profile, list_my_loyalty_balances, get_my_loyalty_balance, 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.

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/ — 12 structured Skills (00–11, step-by-step guides)

• /api-docs — Interactive API documentation

Skills for AI Agents

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

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_server_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

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).

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

• Email / Phone / Google (recommended): Click "Sign In" via Privy — an embedded 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

unboxed-loyalty-spark/
├── AGENTS.md                      # Entry map for AI / coding agents
├── docs/                          # Human docs (guides, integrations, pitch notes)
│   ├── development/               # Build & deploy
│   ├── integrations/              # Farcaster, OpenServ, A2A, prompts
│   ├── pitch-deck/                # Investor deck (Markdown sources)
│   └── supabase/                  # DB/edge runbooks
├── 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
│   │   ├── merchant/              # Merchant shell & tabs (Team, Programs, …)
│   │   ├── team/                  # Branches, employees, invite redemption
│   │   └── admin/                 # Platform administration
│   ├── hooks/                     # Data fetching (TanStack Query + Supabase) — keep queries here
│   ├── config/                    # Contract addresses & ABIs
│   ├── contexts/                  # Auth context
│   ├── integrations/supabase/     # Database client & types
│   ├── pages/                     # Routes (e.g. ForAgentsPage → /for-agents, ApiDocsPage → /api-docs)
│   └── lib/                       # Utilities
├── examples/agent-mcp/            # Copy-paste MCP + curl for agents
├── scripts/                       # Optional dev helpers (x402 MCP smoke test, SIWE lsk_ helper) — not bundled in the web app
├── public/
│   ├── .well-known/
│   │   ├── agent.json             # AI agent discovery
│   │   ├── skills/                # Markdown skills for agents (00–11)
│   │   └── farcaster.json         # Farcaster manifest
│   ├── openapi.json               # OpenAPI 3.1 (API + x402 hints)
│   ├── llms.txt / llms-full.txt   # Short / long summaries for LLM crawlers
│   └── media-kit/                 # Brand & press assets
├── capacitor.config.ts            # Native app IDs (see docs/development/)
├── contracts/                     # Solidity contracts
├── supabase/
│   ├── functions/                 # Edge Functions — see supabase/functions/README.md
│   └── migrations/                # Database migrations
└── README.md

Indexes: AGENTS.md (AI agents) · docs/README.md (human guides) · docs/development/PORTALS_AND_TEAM.md (portal UI & team invites) · supabase/functions/README.md (Edge Functions).

Edge Functions

See the supabase/functions/README.md catalogue (grouped by role: API, MCP, auth, payments, jobs). The root README table is intentionally shortened here to avoid duplication.

Security

• Flexible Authentication: Email/phone/Google via Privy (with embedded wallets), or SIWE for Farcaster and crypto-native users

• 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.

For AI Agents

Loyal Spark is a machine-payment-native API. AI agents can discover, authenticate, and pay for API calls without human intervention.

Discovery Endpoints

Payment Gateways (No API Key Needed)

Agents can pay per request using onchain micropayments:

Pricing: $0.001–$0.005 per read · $0.005–$0.05 per write · HTTP 402 challenge/response flow.

Paid MCP (merchant): POST …/x402-gateway/mcp-tools/<tool_name> (JSON-RPC tools/call); after settlement, pass x-api-key: lsk_… like direct MCP. Recipient / holder MCP: POST …/x402-gateway/recipient-mcp-tools/<tool_name> with x-api-key: rwk_…. Tool lists + JSON Schemas: mcp-bazaar-tools.ts · recipient-mcp-bazaar-tools.ts. 402 + Bazaar (discovery) metadata for both families: x402-bazaar-accept.ts (extensions.bazaar, outputSchema.input.type: "mcp"). After successful settle, the CDP facilitator may return EXTENSION-RESPONSES (bazaar.status: success | processing | rejected).

Catalogues & Registries

• mppscan.com — MPP service scanner (indexed via OpenAPI)

• glama.ai — MCP server directory

• mcp.so — MCP server registry

• smithery.ai — MCP marketplace

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

• Privy — Wallet Abstraction & Authentication

• Coinbase CDP — MPC Server Wallets (for AI agents)

• Wagmi — React Hooks for Ethereum

• shadcn/ui — UI Components

• Lovable — Full-Stack Development Platform

• Viem — TypeScript Interface for Ethereum

License

MIT License — see LICENSE file for details.