Loyal Spark

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

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 programscurl -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/confirmcurl -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.gitcd unboxed-loyalty-sparknpm installnpm 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: [email protected]

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.