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) │          │
│  └──────────┘          └──────────────┘          │
└─────────────────────────────────────────────────┘

Related MCP server: Free USDC Transfer MCP Server

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

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.

Network: Base Mainnet (Chain ID: 8453)

Program creation (summary)

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.

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

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.

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:

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

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

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
│   │   ├── marketplace/           # Token trading (frozen)
│   │   ├── 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–12)
│   │   └── 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: Google/email via Coinbase (gas-sponsored smart 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 (pay per call — no subscription)

Agents can pay per request with onchain micropayments instead of a monthly plan. Write actions still need a free lsk_ or rwk_ key for identity and scopes; x402/MPP cover the per-call USDC/pathUSD fee only.

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

• Official MCP Registry — io.github.aspekt19/loyal-spark (remote Streamable HTTP → api.loyalspark.online/loyalty-mcp; see root server.json)

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

• glama.ai — MCP server directory

• mcp.so — MCP server registry

• smithery.ai — MCP marketplace (loyalspark/loyalty-protocol)

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 Developer Platform — Embedded Wallets, Paymaster & 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.