{
  "markdown": "# Loyal Spark — Onchain Loyalty Protocol\n\nA 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).\n\n## Overview\n\nLoyal 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.\n\n**Wallet Abstraction**: Users and merchants sign in via [Privy](https://privy.io) — 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).\n\n```\n┌─────────────────────────────────────────────────┐\n│              Loyal Spark Platform                │\n│                                                  │\n│  ┌──────────┐    ┌──────────┐    ┌──────────┐   │\n│  │  Web UI   │    │ REST API │    │MCP Server│   │\n│  │ (humans)  │    │ (agents) │    │ (agents) │   │\n│  └─────┬─────┘    └─────┬────┘    └─────┬────┘   │\n│        │                │               │        │\n│        ▼                ▼               ▼        │\n│  ┌──────────────────────────────────────────┐    │\n│  │        Backend (Edge Functions)           │    │\n│  │    Auth · RLS · DB · Realtime             │    │\n│  └─────────────────┬────────────────────────┘    │\n│                    │                             │\n│        ┌───────────┴───────────┐                 │\n│        ▼                       ▼                 │\n│  ┌──────────┐          ┌──────────────┐          │\n│  │ Base L2  │          │ CDP Server   │          │\n│  │ Contracts│          │ Wallet (MPC) │          │\n│  └──────────┘          └──────────────┘          │\n└─────────────────────────────────────────────────┘\n```\n\n## Features\n\n### For Merchants (Web UI)\n- **Deploy Loyalty Tokens**: Create custom loyalty tokens on Base (**B20 default**; legacy ERC-20 via API)\n- **Mint Tokens**: Issue loyalty points to customers via wallet addresses or QR scan\n- **Create Rewards**: Design voucher rewards with token costs\n- **CRM & Analytics**: Customer profiles, RFM segmentation, tier management\n- **Marketing Automation**: Automated campaigns, personalized offers\n- **Referral Programs**: Generate referral codes with bonuses\n- **Voucher Management**: Track redemptions with QR code verification\n- **AI Agent Management**: Register agents, manage API keys, monitor activity\n- **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](./docs/development/PORTALS_AND_TEAM.md)\n\n### For Customers (Web UI)\n- **Multi-Token Dashboard**: View all loyalty tokens from different merchants\n- **Browse Rewards**: Explore available vouchers across all programs\n- **Redeem Vouchers**: Burn tokens to claim exclusive rewards with QR codes\n- **Tier System**: Bronze → Silver → Gold → Platinum with increasing perks\n- **Frozen modules (not product promises):** `marketplace/` (DEX) and `roundup/` (DeFi) remain in the tree but are explicitly frozen — no active development\n\n### For AI Agents (REST API + MCP)\n- **Full CRUD via API**: Create programs, mint tokens, manage rewards, view analytics\n- **MCP Server**: Connect Claude, GPT, Cursor, or any MCP-compatible LLM directly\n- **Server Wallets**: Coinbase CDP MPC wallets for autonomous onchain operations\n- **Scoped Permissions**: Granular access control (read, mint, manage_rewards, trade)\n- **Activity Logging**: Full audit trail of all agent operations\n- **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; see [docs/business/MONETIZATION_AND_PRICING.md](./docs/business/MONETIZATION_AND_PRICING.md)\n- **Skills Documentation**: 16 structured step-by-step guides (`00`–`15` under `/.well-known/skills/`) for agent onboarding, B20 semantics, and payment rails\n\n## Technology Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Frontend | React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui (Radix) |\n| Animations | Framer Motion |\n| Blockchain | Wagmi v2, Viem, RainbowKit, Privy (`@privy-io/react-auth` + `@privy-io/wagmi`) |\n| Network | Base Mainnet (Chain ID: 8453) |\n| Smart Contracts | Base-native B20 Asset precompile + legacy ERC-20 factory |\n| Backend | Supabase (PostgreSQL, RLS, Deno Edge Functions, Realtime) |\n| Native apps | Capacitor 8 (iOS / Android) — see `docs/development/NATIVE_BUILD_GUIDE.md` |\n| Agent Wallets | Coinbase CDP MPC (Server Wallets) |\n| State | TanStack Query v5 |\n| Routing | React Router DOM v6 |\n| Forms | React Hook Form + Zod validation |\n| Builder Attribution | Base Builder Code (ERC-8021) |\n\n## Smart Contract Architecture\n\n**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](./docs/development/LOYALTY_PROGRAM_CONTRACTS.md)**.\n\n| Role | Address | When |\n|------|---------|------|\n| **B20 Factory** (Base precompile) | `0xB20f000000000000000000000000000000000000` | **Default** — `createB20` → token `0xB200…` |\n| **LoyaltyTokenFactory** (legacy) | `0x5F3DdBa12580CFdc6016258774cCc19C4250dA80` | Opt-in `erc20` — `createLoyaltyToken` + activation |\n| **LoyalSparkERC20 (implementation)** | `0xe6BA426C9c51281B929a17444De02c65815E27C3` | Logic for legacy proxy tokens |\n| **LoyaltyTokenEscrow** (P2P) | `0xA569C95AfC1BCF381c48BcF336ED9D2c014bcdDF` | Marketplace swaps |\n\n**Network**: Base Mainnet (Chain ID: 8453)\n\n### Program creation (summary)\n\n| Path | Deploy | Activate | Portal |\n|------|--------|----------|--------|\n| **B20** (default) | 1× `createB20` on `0xB20f…` | Not required | Yes |\n| **Legacy ERC-20** | 1× `createLoyaltyToken` on `0x5F3DdB…` | `unpauseUtility` + `enableMinting` | API only |\n\n### Token operations (both standards)\n\nB20 tokens are ERC-20–compatible for balances, transfers, mint, and escrow:\n\n- `mint(address to, uint256 amount)` — issue points (role-gated)\n- `transfer` / `transferFrom` — move tokens between wallets\n- `balanceOf(address)` — query balance\n\n## AI Agent Integration\n\n### Quick Start\n\n**Merchant dashboard:**  \n1. Go to [loyalspark.online/merchant](https://loyalspark.online/merchant) and sign in (email, phone, Google, or wallet via Privy)  \n2. Open **AI Agents** tab → Register an agent → Copy your API key (`lsk_...`)  \n3. Use the key in `x-api-key` header for REST or MCP calls  \n\n**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](./docs/agents/AUTONOMOUS_AGENT_REGISTRATION.md)** and **[docs/agents/QUICKSTART.md](./docs/agents/QUICKSTART.md)**.\n\n### Optional repo scripts (development / agent onboarding)\n\nThese 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.\n\n| Folder | Purpose |\n|--------|---------|\n| [`scripts/x402-paid-mcp-test/`](./scripts/x402-paid-mcp-test/) | Smoke test: paid MCP via **x402** (USDC on Base, `@x402/fetch`). |\n| [`scripts/x402-paid-agent-api/`](./scripts/x402-paid-agent-api/) | Same stack, paid **agent-api** routes (`GET/POST` to `x402-gateway/<resource>`). |\n| [`scripts/traffic-bot-x402-bridge.py`](./scripts/traffic-bot-x402-bridge.py) | Example **Python → Node** subprocess hook for bots that already send loyalty txs on Base. |\n| [`scripts/agent-register-siwe/`](./scripts/agent-register-siwe/) | Helper: build SIWE message + sign + call **`agent-register-siwe`** (same as production). |\n\nSchemas for paid MCP: merchant **`mcp-tools/<name>`** — **[mcp-bazaar-tools.ts](./supabase/functions/_shared/mcp-bazaar-tools.ts)**; recipient **`recipient-mcp-tools/<name>`** — **[recipient-mcp-bazaar-tools.ts](./supabase/functions/_shared/recipient-mcp-bazaar-tools.ts)**. HTTP **402** `accepts` + Coinbase **x402 Bazaar** discovery metadata for all paid routes are built in **[x402-bazaar-accept.ts](./supabase/functions/_shared/x402-bazaar-accept.ts)**. These scripts are **not** linked from the marketing homepage; primary onboarding remains [/for-agents](https://loyalspark.online/for-agents) and the merchant portal.\n\n### REST API\n\n```bash\n# List loyalty programs\ncurl -H \"x-api-key: lsk_YOUR_KEY\" \\\n  https://api.loyalspark.online/agent-api/programs\n\n# Mint tokens — returns a fee-first calls[] bundle (1.25% fee on Free plan,\n# minted in your own loyalty tokens); settle it via POST /agent-api/mint/confirm\ncurl -X POST \\\n  -H \"x-api-key: lsk_YOUR_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"token_address\":\"0x...\",\"recipient_address\":\"0x...\",\"amount\":100}' \\\n  https://api.loyalspark.online/agent-api/mint\n```\n\n### API Endpoints (28 authenticated + 1 public)\n\nAll 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`).\n\n| Method | Path | Scope | Description |\n|--------|------|-------|-------------|\n| GET | `/me` | authenticated | Agent profile & permissions |\n| GET | `/workflow/program-status` | read | Autonomous planner: lifecycle step + `next_actions[]` |\n| GET | `/programs` | read | List loyalty programs |\n| POST | `/workflow/generate-program-defaults` | read, mint, or `create_program` | Propose program name, symbol, economics, and starter rewards from business context |\n| POST | `/programs` | mint or `create_program` | Calldata to deploy loyalty token (**B20 default**, or legacy ERC-20 with `token_standard: \"erc20\"`) |\n| POST | `/register-program` | mint or `create_program` | Register deployed token (optional `cashback_rate`, `points_per_dollar`) |\n| POST | `/update-program-config` | mint or `create_program` | Update `cashback_rate` / `points_per_dollar` for a program |\n| POST | `/activate-program` | mint or `create_program` | Legacy ERC-20 activation only (no-op for B20) |\n| POST | `/program-status` | mint or `create_program` | Update program status |\n| GET | `/rewards` | read | List rewards |\n| POST | `/rewards` | manage_rewards | Create reward |\n| POST | `/mint` | mint | Fee-first mint `calls[]` + `fee_obligation_id` |\n| POST | `/mint/confirm` | mint | Settle protocol fee after mint/earn (obligation_id + fee_tx_hash) |\n| POST | `/earn` | mint | Cashback: mint from purchase amount × rate (same fee-first + confirm) |\n| POST | `/transfer` | mint | Transfer tokens |\n| GET | `/balance` | read | Token balance & tier |\n| GET | `/customers` | read | Customer list |\n| GET | `/vouchers` | read | List vouchers |\n| GET | `/vouchers/status` | public | Check voucher status (no API key) |\n| POST | `/redeem-reward` | read | Redeem reward → create voucher |\n| POST | `/vouchers/use` | manage_rewards | Mark voucher as used |\n| GET | `/analytics` | read | Program analytics |\n| GET | `/offers` | read | Marketplace offers |\n| POST | `/offers` | trade | Create P2P offer |\n| POST | `/accept-offer` | trade | Accept P2P offer |\n| POST | `/cancel-offer` | trade | Cancel P2P offer |\n| GET | `/tx-receipt` | authenticated | Extract token_address from deploy tx |\n| GET | `/merchant-profile` | read | Read merchant profile |\n| POST | `/merchant-profile` | manage_rewards | Create or update merchant profile (`PUT` also accepted) |\n\n### MCP Server (for LLMs)\n\nConnect Claude, GPT, or any MCP-compatible agent:\n\n```json\n{\n  \"mcpServers\": {\n    \"loyal-spark\": {\n      \"url\": \"https://api.loyalspark.online/loyalty-mcp\",\n      \"headers\": {\n        \"x-api-key\": \"lsk_YOUR_KEY\"\n      }\n    }\n  }\n}\n```\n\n**MCP tools (39)** — defined in `supabase/functions/loyalty-mcp/index.ts`:  \n`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).\n\n### Base MCP custom plugin (`send_calls`-ready calldata)\n\nFor 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.\n\nActions: `create-program`, `activate-program`, `mint`, `transfer` (merchant, `lsk_`) · `recipient-transfer`, `recipient-approve` (holder, `rwk_`).\n\n```bash\n# Prepare a mint (returns { transactions: [{to,data,value}], … } for send_calls)\ncurl -H \"x-api-key: lsk_YOUR_KEY\" \\\n  \"https://api.loyalspark.online/agent-prepare/mint?token=0xTOKEN&to=0xCUSTOMER&amount=100\"\n```\n\nPlugin spec: [`skills/loyal-spark/plugins/loyal-spark.md`](./skills/loyal-spark/plugins/loyal-spark.md).\n\n### Recipient agents (wallet holders, `rwk_`)\n\nFor **AI agents that only hold a wallet** which receives loyalty tokens (not merchant operators). Humans are unchanged; this is an optional machine path.\n\n| Piece | URL / path |\n|-------|----------------|\n| REST | `https://api.loyalspark.online/recipient-api` |\n| MCP | `https://api.loyalspark.online/recipient-loyalty-mcp` |\n| Register key | `POST …/recipient-api/register` with SIWE `{ message, signature }` (nonce from `siwe-nonce`) — returns `rwk_…` once. Pass Supabase `apikey` (anon/publishable) header like other public functions. |\n\n**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).\n\n**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).\n\n**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`](./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).\n\nExample MCP fragment: [`examples/recipient-agent-mcp/cursor-mcp.json`](./examples/recipient-agent-mcp/cursor-mcp.json).\n\n### Agent Discovery\n\nAI agents can discover the protocol automatically via:\n- `/.well-known/agent.json` — Full protocol specification, capabilities, pricing\n- `/.well-known/skills/` — 16 structured Skills (`00`–`15`, step-by-step guides)\n- `/api-docs` — Interactive API documentation\n\n### Skills for AI Agents\n\nStructured Markdown guides that teach agents how to use the protocol:\n\n| # | Skill | Description |\n|---|-------|-------------|\n| 00 | Getting Started | Register agent (merchant UI or SIWE), get `lsk_`, first request |\n| 01 | Create Loyalty Program | Deploy B20 loyalty token on Base (legacy ERC-20 optional) |\n| 02 | Mint Tokens | Mint tokens to customer wallets |\n| 03 | Transfer Tokens | Transfer tokens between wallets |\n| 04 | Manage Rewards | Create redeemable rewards catalog |\n| 05 | Balance & Tiers | Check balances and tier status |\n| 06 | Marketplace Trading | P2P token trading with atomic escrow |\n| 07 | Analytics & CRM | Program analytics and CRM data |\n| 08 | Referrals | Referral programs for organic growth |\n| 09 | Vouchers | Voucher lifecycle management |\n| 10 | Server Wallets | CDP MPC wallets for autonomous transactions |\n| 11 | Earn Points (Cashback) | Mint from purchase amount × cashback rate |\n| 12 | Gift Certificates | Issue, claim, and mint `LOYAL-XXXXXX` certificates |\n| 13 | Endpoint Workflows | Multi-step REST/MCP flows and prerequisites |\n| 14 | B20 Native Spec | Base Beryl B20 Asset semantics for loyalty tokens |\n| 15 | Payment Scenarios | x402 exact, MPP, subscriptions, spend policies |\n\nInstallable skill bundle (CLI): `npx skills add aspekt19/unboxed-loyalty-spark --skill loyal-spark` — source in [`skills/loyal-spark/`](./skills/loyal-spark/).\n\nSkills index: `https://loyalspark.online/.well-known/skills/index.md`\n\n### Server Wallets (CDP MPC)\n\nAgents can create their own Coinbase MPC wallets on Base for autonomous transactions:\n\n```bash\ncurl -X POST \\\n  -H \"x-api-key: lsk_YOUR_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"action\":\"create_wallet\"}' \\\n  https://api.loyalspark.online/agent-wallet\n```\n\nBenefits:\n- No private key management — keys are in Coinbase's secure enclave\n- Server-side transaction signing\n- Automatic Builder Code attribution (ERC-8021)\n\n### Pricing\n\n| Plan | Monthly | API Calls | Agents | Mint fee |\n|------|---------|-----------|--------|----------|\n| Free | $0 | 200 | 1 | 1.25% |\n| Pro | $49 USDC | 10,000 | 5 | 0.5% |\n| Enterprise | $129 USDC | Unlimited | Unlimited | 0.25% |\n\n**Merchant SaaS (portal):** Starter **$39** / Growth **$79** / Scale **$149** per month (annual discount 15–20% optional) — details in [docs/business/MONETIZATION_AND_PRICING.md](./docs/business/MONETIZATION_AND_PRICING.md).\n\nPayments 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](./docs/business/MONETIZATION_AND_PRICING.md).\n\n**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`.\n\n## Getting Started\n\n### Prerequisites\n- Node.js 18+ or Bun\n- An email, phone number, Google account, or Web3 wallet (MetaMask, Coinbase Wallet, WalletConnect)\n- Some ETH on Base for gas fees (merchants only)\n\n### Installation\n\n```bash\ngit clone https://github.com/aspekt19/unboxed-loyalty-spark.git\ncd unboxed-loyalty-spark\nnpm install\nnpm run dev\n```\n\n### Sign In Options\n\n- **Email / Phone / Google** (recommended): Click \"Sign In\" via Privy — an embedded wallet is created automatically, no crypto knowledge needed\n- **MetaMask / Coinbase Wallet / WalletConnect**: Traditional Web3 wallet connection\n- **Farcaster**: Auto-connects inside Warpcast miniapp\n\nOn **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](./docs/development/PORTALS_AND_TEAM.md).\n\n**Network**: Base Mainnet (Chain ID: 8453) | **RPC**: https://mainnet.base.org | **Explorer**: https://basescan.org\n\n## Project Structure\n\n```\nunboxed-loyalty-spark/\n├── AGENTS.md                      # Entry map for AI / coding agents\n├── docs/                          # Human docs (guides, integrations, pitch notes)\n│   ├── development/               # Build & deploy\n│   ├── integrations/              # Farcaster, OpenServ, A2A, prompts\n│   ├── pitch-deck/                # Investor deck (Markdown sources)\n│   └── supabase/                  # DB/edge runbooks\n├── src/\n│   ├── components/\n│   │   ├── ui/                    # shadcn/ui library\n│   │   ├── agents/                # AI agent management\n│   │   ├── rewards/               # Rewards & vouchers\n│   │   ├── crm/                   # CRM & analytics\n│   │   ├── marketing/             # Campaigns\n│   │   ├── automation/            # Marketing automation\n│   │   ├── tiers/                 # Customer tiers\n│   │   ├── referral/              # Referral programs\n│   │   ├── roundup/               # DeFi investment (frozen)\n│   │   ├── marketplace/           # Token trading (frozen)\n│   │   ├── reviews/               # Customer reviews\n│   │   ├── onboarding/            # Welcome flows & tours\n│   │   ├── merchant/              # Merchant shell & tabs (Team, Programs, …)\n│   │   ├── team/                  # Branches, employees, invite redemption\n│   │   └── admin/                 # Platform administration\n│   ├── hooks/                     # Data fetching (TanStack Query + Supabase) — keep queries here\n│   ├── config/                    # Contract addresses & ABIs\n│   ├── contexts/                  # Auth context\n│   ├── integrations/supabase/     # Database client & types\n│   ├── pages/                     # Routes (e.g. ForAgentsPage → /for-agents, ApiDocsPage → /api-docs)\n│   └── lib/                       # Utilities\n├── examples/agent-mcp/            # Copy-paste MCP + curl for agents\n├── scripts/                       # Optional dev helpers (x402 MCP smoke test, SIWE lsk_ helper) — not bundled in the web app\n├── public/\n│   ├── .well-known/\n│   │   ├── agent.json             # AI agent discovery\n│   │   ├── skills/                # Markdown skills for agents (00–12)\n│   │   └── farcaster.json         # Farcaster manifest\n│   ├── openapi.json               # OpenAPI 3.1 (API + x402 hints)\n│   ├── llms.txt / llms-full.txt   # Short / long summaries for LLM crawlers\n│   └── media-kit/                 # Brand & press assets\n├── capacitor.config.ts            # Native app IDs (see docs/development/)\n├── contracts/                     # Solidity contracts\n├── supabase/\n│   ├── functions/                 # Edge Functions — see supabase/functions/README.md\n│   └── migrations/                # Database migrations\n└── README.md\n```\n\n**Indexes:** [AGENTS.md](./AGENTS.md) (AI agents) · [docs/README.md](./docs/README.md) (human guides) · [docs/development/PORTALS_AND_TEAM.md](./docs/development/PORTALS_AND_TEAM.md) (portal UI & team invites) · [supabase/functions/README.md](./supabase/functions/README.md) (Edge Functions).\n\n## Edge Functions\n\nSee the **[supabase/functions/README.md](./supabase/functions/README.md)** catalogue (grouped by role: API, MCP, auth, payments, jobs). The root README table is intentionally shortened here to avoid duplication.\n\n## Security\n\n- **Flexible Authentication**: Email/phone/Google via Privy (with embedded wallets), or SIWE for Farcaster and crypto-native users\n- **API Key Auth**: SHA-256 hashed keys with `lsk_` prefix for agents\n- **Row Level Security**: All database tables protected with RLS policies\n- **Scoped Permissions**: Agents operate within granted scopes only\n- **MPC Wallets**: Private keys never leave Coinbase's secure enclave\n- **Rate Limiting**: Per-agent rate limits prevent abuse\n- **Builder Code Attribution**: All transactions tagged with ERC-8021 builder code\n\n## Builder Code\n\nAll on-chain transactions are tagged with Base Builder Code `bc_wdmnog7m` (ERC-8021 format) for analytics visibility in [base.dev](https://base.dev).\n\n## For AI Agents\n\nLoyal Spark is a **machine-payment-native** API. AI agents can discover, authenticate, and pay for API calls without human intervention.\n\n### Discovery Endpoints\n\n| Resource | URL | Purpose |\n|----------|-----|---------|\n| **Agent onboarding (web)** | [/for-agents](https://loyalspark.online/for-agents) | Keys, REST, MCP, gateways, discovery — one page for builders |\n| Agent Manifest | [/.well-known/agent.json](https://loyalspark.online/.well-known/agent.json) | Full protocol spec, capabilities, pricing |\n| MPP Manifest | [/.well-known/mpp.json](https://loyalspark.online/.well-known/mpp.json) | Machine Payment Protocol manifest |\n| OpenAPI Spec | [/openapi.json](https://loyalspark.online/openapi.json) | OpenAPI 3.1.0 with x-payment-info |\n| Skills Library | [/.well-known/skills/](https://loyalspark.online/.well-known/skills/index.md) | 16 step-by-step guides for agents (`00`–`15`) |\n| LLMs.txt | [/llms.txt](https://loyalspark.online/llms.txt) | Protocol summary for LLM crawlers |\n| Prompt Guide | [PROMPT_GUIDE.md](./docs/integrations/PROMPT_GUIDE.md) | Ready-to-use system prompts |\n| Copy-paste MCP / curl | [examples/agent-mcp/](./examples/agent-mcp/) | Starter configs in the repo |\n| Repo quickstart (keys, SIWE, x402) | [docs/agents/QUICKSTART.md](./docs/agents/QUICKSTART.md) | Short paths for coding agents |\n\n### Payment Gateways (pay per call — no subscription)\n\nAgents 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.\n\n| Protocol | Network | Asset | Gateway |\n|----------|---------|-------|---------|\n| **x402 exact** | Base | USDC | `https://api.loyalspark.online/x402-gateway` |\n| **MPP** | Tempo | pathUSD / USDC | `https://api.loyalspark.online/mpp-gateway` |\n\nPricing: **$0.001–$0.005** per read · **$0.005–$0.05** per write · HTTP 402 challenge/response flow.\n\n**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).\n\n### Catalogues & Registries\n\n- **[Official MCP Registry](https://registry.modelcontextprotocol.io)** — `io.github.aspekt19/loyal-spark` (remote Streamable HTTP → `api.loyalspark.online/loyalty-mcp`; see root `server.json`)\n- **[mppscan.com](https://mppscan.com)** — MPP service scanner (indexed via OpenAPI)\n- **[glama.ai](https://glama.ai)** — MCP server directory\n- **[mcp.so](https://mcp.so)** — MCP server registry\n- **[smithery.ai](https://smithery.ai)** — MCP marketplace (`loyalspark/loyalty-protocol`)\n\n## Links & Resources\n\n- **Website**: [loyalspark.online](https://loyalspark.online)\n- **API Docs**: [loyalspark.online/api-docs](https://loyalspark.online/api-docs)\n- **Agent Discovery**: [loyalspark.online/.well-known/agent.json](https://loyalspark.online/.well-known/agent.json)\n- **GitHub**: [github.com/aspekt19/unboxed-loyalty-spark](https://github.com/aspekt19/unboxed-loyalty-spark)\n- **Twitter/X**: [x.com/Loyal_Spark](https://x.com/Loyal_Spark)\n- **Email**: admin@loyalspark.online\n\n## Built With\n\n- [Base](https://base.org) — Ethereum L2 by Coinbase\n- [Privy](https://privy.io) — Wallet Abstraction & Authentication\n- [Coinbase CDP](https://docs.cdp.coinbase.com) — MPC Server Wallets (for AI agents)\n- [Wagmi](https://wagmi.sh) — React Hooks for Ethereum\n- [shadcn/ui](https://ui.shadcn.com) — UI Components\n- [Lovable](https://lovable.dev) — Full-Stack Development Platform\n- [Viem](https://viem.sh) — TypeScript Interface for Ethereum\n\n## License\n\nMIT License — see LICENSE file for details.\n",
  "bytes": 29636,
  "sha": "6c9914243bba6b330d65f19c9c96f97adf1aa068779da1ea9b0e347c30854782",
  "repo_slug": "aspekt19/unboxed-loyalty-spark",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aspekt19_loyal_spark_339db436/readme"
}