{
  "name": "Loyal Spark",
  "description": "Onchain loyalty protocol on Base L2. AI agents can autonomously create loyalty programs, mint ERC-20 loyalty tokens, manage rewards, trade on marketplace, and get their own MPC wallets — all via REST API, MCP Server, or MPP (Machine Payments Protocol).",
  "url": "https://loyalspark.online",
  "version": "2.1.0",
  "protocol": "a2a-loyalty",
  "capabilities": [
    "create_loyalty_program",
    "mint_tokens",
    "manage_rewards",
    "marketplace_trading",
    "customer_analytics",
    "tier_management",
    "referral_programs",
    "voucher_management",
    "server_wallet_creation",
    "autonomous_transactions"
  ],
  "authentication": {
    "type": "api_key",
    "header": "x-api-key",
    "prefix": "lsk_",
    "registration_url": "https://loyalspark.online/merchant",
    "registration_note": "Sign in with email/passkey or Web3 wallet to register an agent",
    "docs_url": "https://loyalspark.online/api-docs"
  },
  "api": {
    "base_url": "https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/agent-api",
    "endpoints": [
      {
        "method": "GET",
        "path": "/me",
        "scope": "read",
        "description": "Get agent profile, permissions, plan, and wallet info"
      },
      {
        "method": "GET",
        "path": "/programs",
        "scope": "read",
        "description": "List all active loyalty programs"
      },
      {
        "method": "POST",
        "path": "/programs",
        "scope": "mint",
        "description": "Get calldata to deploy a new ERC-20 loyalty token via factory contract",
        "body": { "name": "Coffee Rewards", "symbol": "COFFEE", "expiration_days": 365 }
      },
      {
        "method": "POST",
        "path": "/register-program",
        "scope": "mint",
        "description": "Register a deployed token as a loyalty program in the database",
        "body": { "name": "Coffee Rewards", "symbol": "COFFEE", "token_address": "0x...", "expiration_days": 365 }
      },
      {
        "method": "POST",
        "path": "/activate-program",
        "scope": "mint",
        "description": "Get activation calldata (unpauseUtility + enableMinting). Returns 2 transactions to execute.",
        "body": { "token_address": "0x..." }
      },
      {
        "method": "POST",
        "path": "/program-status",
        "scope": "mint",
        "description": "Update program status in database after on-chain activation/pause",
        "body": { "token_address": "0x...", "status": "active" }
      },
      {
        "method": "GET",
        "path": "/rewards",
        "scope": "read",
        "description": "List rewards for a loyalty program"
      },
      {
        "method": "POST",
        "path": "/rewards",
        "scope": "manage_rewards",
        "description": "Create a new reward redeemable with loyalty tokens"
      },
      {
        "method": "POST",
        "path": "/mint",
        "scope": "mint",
        "description": "Mint loyalty tokens to a wallet address (1% fee on Free, 0.5% Pro, 0.25% Enterprise)"
      },
      {
        "method": "POST",
        "path": "/transfer",
        "scope": "mint",
        "description": "Transfer loyalty tokens between wallets. Returns calldata with Builder Code for onchain execution.",
        "body": {
          "token_address": "0x...",
          "to": "0x...",
          "amount": 100
        }
      },
      {
        "method": "GET",
        "path": "/balance",
        "scope": "read",
        "description": "Check token balance for a wallet"
      },
      {
        "method": "GET",
        "path": "/customers",
        "scope": "read",
        "description": "List customers with token balances and activity"
      },
      {
        "method": "GET",
        "path": "/analytics",
        "scope": "read",
        "description": "Get program analytics and performance metrics"
      },
      {
        "method": "GET",
        "path": "/vouchers",
        "scope": "read",
        "description": "List vouchers with optional filters (token_address, status, limit)"
      },
      {
        "method": "GET",
        "path": "/vouchers/status",
        "scope": "none (public)",
        "description": "Check voucher status by code or ID. No API key required.",
        "query_params": { "code": "LOYAL-XXXX-XXXX-XXXX-XXXX" }
      },
      {
        "method": "POST",
        "path": "/redeem-reward",
        "scope": "read",
        "description": "Redeem a reward: verify on-chain token transfer tx and create a voucher",
        "body": { "reward_id": "uuid", "customer_address": "0x...", "transaction_hash": "0x..." }
      },
      {
        "method": "POST",
        "path": "/vouchers/use",
        "scope": "manage_rewards",
        "description": "Mark a voucher as used (redeemed by customer). Merchant-only.",
        "body": { "voucher_code": "LOYAL-XXXX-XXXX-XXXX-XXXX" }
      },
      {
        "method": "GET",
        "path": "/tx-receipt",
        "scope": "any",
        "description": "Extract token_address from a deploy transaction hash",
        "query_params": { "tx_hash": "0x..." }
      },
      {
        "method": "GET",
        "path": "/offers",
        "scope": "trade",
        "description": "List active P2P escrow offers for token trading"
      },
      {
        "method": "POST",
        "path": "/offers",
        "scope": "trade",
        "description": "Create a new P2P escrow offer. Returns escrow contract calldata for atomic swap.",
        "body": {
          "offer_token_address": "0x...",
          "offer_amount": 100,
          "request_token_address": "0x...",
          "request_amount": 50
        }
      },
      {
        "method": "POST",
        "path": "/accept-offer",
        "scope": "trade",
        "description": "Accept a P2P offer. Returns escrow contract calldata for fillOffer.",
        "body": { "offer_id": "uuid" }
      },
      {
        "method": "POST",
        "path": "/cancel-offer",
        "scope": "trade",
        "description": "Cancel your own P2P offer. Returns escrow contract calldata for cancelOffer.",
        "body": { "offer_id": "uuid" }
      }
    ]
  },
  "escrow": {
    "description": "P2P token exchange is protected by a smart contract escrow. Atomic swap — both transfers happen in one transaction, or neither does.",
    "contract_address": "0xA569C95AfC1BCF381c48BcF336ED9D2c014bcdDF",
    "contract_name": "LoyaltyTokenEscrow",
    "chain": "Base (8453)",
    "explorer": "https://basescan.org/address/0xA569C95AfC1BCF381c48BcF336ED9D2c014bcdDF",
    "fee": "0.5% protocol fee on completed swaps",
    "fee_recipient": "0x40a8CdD6a10EC1a8cB3dFb2834675e7a2CF4ad8b",
    "flow": [
      "1. Creator approves escrow contract for offer tokens",
      "2. Creator calls createOffer() — tokens locked in escrow",
      "3. Accepter approves escrow contract for request tokens",
      "4. Accepter calls fillOffer() — atomic swap executes",
      "Alternative: Creator calls cancelOffer() — tokens returned"
    ]
  },
  "wallets": {
    "type": "cdp_mpc",
    "description": "Coinbase CDP MPC wallets on Base — agents get their own server wallet for autonomous onchain operations. No private keys to manage.",
    "create_endpoint": "POST /agent-api (action: create_server_wallet)",
    "chain": "Base (8453)",
    "features": [
      "Automatic wallet creation",
      "Server-side transaction signing",
      "MPC key management by Coinbase",
      "No private key exposure"
    ]
  },
  "pricing": {
    "model": "freemium",
    "currency": "USDC on Base ($1 = 1 USDC)",
    "plans": [
      {
        "name": "Free",
        "price": 0,
        "limits": {
          "api_calls_monthly": 100,
          "agents": 1,
          "transaction_fee": "1%"
        }
      },
      {
        "name": "Pro",
        "price_usdc_monthly": 29,
        "limits": {
          "api_calls_monthly": 10000,
          "agents": 5,
          "transaction_fee": "0.5%"
        }
      },
      {
        "name": "Enterprise",
        "price_usdc_monthly": 99,
        "limits": {
          "api_calls_monthly": "unlimited",
          "agents": "unlimited",
          "transaction_fee": "0.25%"
        }
      }
    ],
    "payment": "On-chain USDC transfer to platform wallet, verified automatically",
    "pay_per_request": {
      "protocol": "MPP (Machine Payments Protocol)",
      "gateway_url": "https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/mpp-gateway",
      "currency": "pathUSD on Tempo",
      "description": "Pay per API call without a subscription. Uses HTTP 402 Payment Required flow.",
      "prices_usd": {
        "GET /me": "free",
        "GET /programs": "0.001",
        "GET /rewards": "0.001",
        "GET /balance": "0.001",
        "GET /customers": "0.002",
        "GET /vouchers": "0.001",
        "GET /vouchers/status": "0 (free, public)",
        "GET /analytics": "0.005",
        "GET /offers": "0.001",
        "POST /programs": "0.05",
        "POST /register-program": "0.01",
        "POST /activate-program": "0.01",
        "POST /program-status": "0.005",
        "POST /rewards": "0.01",
        "POST /mint": "0.01",
        "POST /transfer": "0.005",
        "POST /redeem-reward": "0.01",
        "POST /vouchers/use": "0.005",
        "POST /offers": "0.01",
        "POST /accept-offer": "0.01",
        "POST /cancel-offer": "0.005"
      }
    }
  },
  "chain": {
    "name": "Base",
    "chain_id": 8453,
    "token_standard": "ERC-20",
    "explorer": "https://basescan.org",
    "builder_code": "bc_wdmnog7m"
  },
  "mcp": {
    "url": "https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/loyalty-mcp",
    "transport": "streamable-http",
    "authentication": {
      "type": "api_key",
      "header": "x-api-key",
      "prefix": "lsk_"
    },
    "tools": [
      "get_platform_info",
      "get_my_profile",
      "list_loyalty_programs",
      "create_loyalty_program",
      "register_loyalty_program",
      "activate_loyalty_program",
      "update_program_status",
      "list_rewards",
      "create_reward",
      "mint_loyalty_tokens",
      "transfer_loyalty_tokens",
      "get_token_balance",
      "get_program_analytics",
      "get_platform_stats",
      "list_marketplace_offers",
      "cancel_stale_offers",
      "redeem_reward",
      "use_voucher",
      "check_voucher_status",
      "create_personalized_offer",
      "update_reward_status",
      "export_customers",
      "send_report",
      "list_my_reports",
      "update_report_status",
      "delete_report"
    ]
  },
  "mpp": {
    "description": "Machine Payments Protocol — pay per API request with HTTP 402 flow. No subscription needed.",
    "gateway_url": "https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/mpp-gateway",
    "currency": "pathUSD on Tempo",
    "protocol_spec": "https://mpp.dev",
    "llms_txt": "https://loyalspark.online/llms.txt",
    "how_to_use": [
      "1. Install mppx: npm install -g mppx",
      "2. Create account: mppx account create",
      "3. Make paid request: mppx https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/mpp-gateway/programs -H 'x-api-key: lsk_YOUR_KEY'",
      "4. Payment is handled automatically via 402 challenge/credential flow"
    ]
  },
  "x402": {
    "description": "Coinbase x402 Payment Protocol — pay per API request with USDC on Base. Native HTTP 402 flow with on-chain settlement.",
    "gateway_url": "https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/x402-gateway",
    "currency": "USDC on Base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "network": "base",
    "chain_id": 8453,
    "facilitator": "https://facilitator.x402.org",
    "protocol_spec": "https://github.com/coinbase/x402",
    "how_to_use": [
      "1. Install x402 client: npm install @x402/fetch @x402/evm",
      "2. Make request to x402-gateway — get 402 with PAYMENT-REQUIRED header",
      "3. Sign USDC payment on Base using x402 client SDK",
      "4. Retry request with X-PAYMENT header containing signed payload",
      "5. Gateway verifies via Coinbase facilitator, settles USDC, returns data"
    ],
    "prices_usd": {
      "GET /me": "free",
      "GET /programs": "0.001",
      "GET /rewards": "0.001",
      "GET /balance": "0.001",
      "GET /customers": "0.002",
      "GET /vouchers": "0.001",
      "GET /vouchers/status": "0 (free, public)",
      "GET /analytics": "0.005",
      "GET /offers": "0.001",
      "POST /programs": "0.05",
      "POST /register-program": "0.01",
      "POST /activate-program": "0.01",
      "POST /program-status": "0.005",
      "POST /rewards": "0.01",
      "POST /mint": "0.01",
      "POST /transfer": "0.005",
      "POST /redeem-reward": "0.01",
      "POST /vouchers/use": "0.005",
      "POST /offers": "0.01",
      "POST /accept-offer": "0.01",
      "POST /cancel-offer": "0.005"
    }
  },
  "skills": {
    "url": "https://loyalspark.online/.well-known/skills/index.md",
    "format": "markdown",
    "list": [
      {"id": "getting-started", "file": "00-getting-started.md", "description": "Register agent, get API key, first request"},
      {"id": "create-program", "file": "01-create-loyalty-program.md", "description": "Deploy ERC-20 loyalty token on Base"},
      {"id": "mint-tokens", "file": "02-mint-tokens.md", "description": "Mint loyalty tokens to customer wallets"},
      {"id": "transfer-tokens", "file": "03-transfer-tokens.md", "description": "Transfer tokens between wallets"},
      {"id": "manage-rewards", "file": "04-manage-rewards.md", "description": "Create redeemable rewards catalog"},
      {"id": "balance-tiers", "file": "05-balance-and-tiers.md", "description": "Check balances and tier status"},
      {"id": "marketplace", "file": "06-marketplace-trading.md", "description": "P2P token trading with atomic escrow"},
      {"id": "analytics", "file": "07-analytics-crm.md", "description": "Program analytics and CRM data"},
      {"id": "referrals", "file": "08-referrals.md", "description": "Referral programs for organic growth"},
      {"id": "vouchers", "file": "09-vouchers.md", "description": "Voucher lifecycle management"},
      {"id": "server-wallets", "file": "10-server-wallets.md", "description": "CDP MPC wallets for autonomous transactions"}
    ]
  },
  "why_use": {
    "headline": "Loyalty-as-a-Service for AI Agents",
    "value_propositions": [
      {
        "title": "Full Infrastructure Out of the Box",
        "description": "Creating an ERC-20 token is 5% of the work. Loyal Spark provides rewards, vouchers, tiers, analytics, CRM, marketing automation, and marketplace — all via API."
      },
      {
        "title": "Autonomous Server Wallets",
        "description": "Each agent gets a Coinbase MPC wallet on Base. No private keys to manage — sign transactions server-side with enterprise-grade security."
      },
      {
        "title": "Network Effect & Liquidity",
        "description": "A standalone token is an island. Tokens on Loyal Spark are tradeable on the built-in marketplace, convertible between programs, and have real utility through vouchers."
      },
      {
        "title": "Trust & Verification",
        "description": "A random agent token has zero trust. Tokens issued through a verified protocol with audit history carry built-in credibility."
      },
      {
        "title": "Ready-Made Audience",
        "description": "Agents creating solo tokens must find holders themselves. Through Loyal Spark, agents access existing merchant customer bases instantly."
      },
      {
        "title": "DeFi Yield Integration",
        "description": "Loyalty tokens can be invested in Aave/Compound strategies via Round-Up feature. Tokens grow in value passively — impossible with a bare ERC-20."
      },
      {
        "title": "Composability via Single API",
        "description": "Create program → set up tiers → launch referrals → automate minting → track analytics. All through one REST API or MCP Server."
      },
      {
        "title": "Pay-as-you-go Pricing",
        "description": "Start free with 100 API calls/month. Scale to Pro ($29/mo) or Enterprise ($99/mo) with lower transaction fees and higher limits. All payments in USDC on Base."
      }
    ],
    "analogy": "Think Shopify vs. coding your own store. You could deploy a token yourself, but why build rewards infrastructure from scratch when a protocol exists?"
  },
  "quickstart": {
    "steps": [
      "1. Go to https://loyalspark.online/merchant and sign in (email, passkey, or wallet)",
      "2. Open 'AI Agents' tab → Register an agent → Get API key (lsk_...)",
      "3. Read the Skills guide: https://loyalspark.online/.well-known/skills/00-getting-started.md",
      "4. Use the API key in x-api-key header for REST or MCP calls",
      "5. Create a server wallet: POST /agent-api with action 'create_server_wallet'",
      "6. Start minting tokens, creating rewards, and managing programs!"
    ]
  },
  "contact": {
    "website": "https://loyalspark.online",
    "docs": "https://loyalspark.online/api-docs",
    "email": "admin@loyalspark.online",
    "twitter": "https://x.com/Loyal_Spark"
  },
  "tags": [
    "loyalty",
    "rewards",
    "defi",
    "base",
    "erc20",
    "a2a",
    "marketplace",
    "mcp",
    "cdp",
    "mpc-wallet",
    "ai-agents"
  ]
}