Loyal Spark
io.github.aspekt19v1.0.3更新于 Sep 29, 2026
Base MCP (39 tools) on Base: programs, mint, rewards. lsk_ key; plan limits enforced. /for-agents
安装
在 SourceWeft 中
- 打开 控制台中的 Loyal Spark，将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。
其他 MCP 客户端
把它添加到你客户端的 mcpServers 配置中。
{
"mcpServers": {
"loyal-spark": {
"type": "http",
"url": "https://api.loyalspark.online/loyalty-mcp"
}
}
}README
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 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).
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 modules (not product promises):
marketplace/(DEX) androundup/(DeFi) remain in the tree but are 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–15under/.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 walletsbalanceOf(address)— query balance
AI Agent Integration
Quick Start
Merchant dashboard:
- Go to loyalspark.online/merchant and sign in (email, phone, Google, or wallet via Privy)
- Open AI Agents tab → Register an agent → Copy your API key (
lsk_...) - Use the key in
x-api-keyheader 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
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:
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_).
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:
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
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
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 (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 rootserver.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
- 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.
来源：README.md，提交 eb164c0
工具
0版本历史
1- v1.0.3最新Sep 16, 2026