Loyal Spark

{
  "name": "Loyal Spark",
  "description": "Onchain loyalty protocol on Base. New programs deploy as native B20 Asset programs by default; legacy ERC-20 programs remain supported. Two agent personas: MERCHANT (lsk_, 28 authenticated REST routes + 1 public + 39 MCP tools at /loyalty-mcp) creates programs, registers and activates them when needed, manages rewards, mints tokens, runs P2P trading, gift certificates (LOYAL-XXXXXX), CDP MPC wallets, and POST /earn cashback. RECIPIENT (rwk_, 14 REST routes at /recipient-api + 20 MCP tools at /recipient-loyalty-mcp) holds tokens, redeems rewards, P2P swaps, claims gift certificates, and prepares loyalty token transfers. Pay-per-call via MPP (pathUSD/USDC on Tempo) or x402 v2 (USDC on Base) \u2014 both gateways relay merchant + recipient corridors with Coinbase Bazaar discovery metadata.",
  "url": "https://loyalspark.online",
  "version": "2.3.2",
  "protocol": "a2a-loyalty",
  "capabilities": [
    "create_loyalty_program",
    "mint_tokens",
    "earn_points_from_purchases",
    "manage_rewards",
    "marketplace_trading",
    "customer_analytics",
    "tier_management",
    "referral_programs",
    "voucher_management",
    "server_wallet_creation",
    "autonomous_transactions"
  ],
  "workflow_hints": {
    "rule": "Many Loyal Spark actions are multi-step workflows, not single endpoint calls.",
    "machine_contract": "Lifecycle-sensitive REST and MCP responses include workflow.current_step, completed_steps, next_actions, prerequisites, field_catalog, and continuation_context. External agents choose all parameter values.",
    "required_docs": [
      "https://loyalspark.online/.well-known/skills/00-getting-started.md",
      "https://loyalspark.online/.well-known/skills/13-endpoint-workflows.md"
    ],
    "merchant_program_lifecycle": [
      "Choose program name, token symbol, and expiration period",
      "Call POST /programs or create_loyalty_program to get deploy calldata",
      "Broadcast the onchain deploy transaction",
      "Extract token_address from B20Created or GET /tx-receipt",
      "Call POST /register-program or register_loyalty_program",
      "If token_standard is erc20, also call activate-program and then program-status active",
      "Create at least one reward before large-scale minting",
      "Only then mint tokens or use earn_points"
    ],
    "voucher_flow": [
      "Transfer tokens onchain first",
      "Then call redeem-reward with transaction_hash",
      "Then use voucher via vouchers/use when consumed"
    ]
  },
  "authentication": {
    "type": "api_key",
    "header": "x-api-key",
    "prefix": "lsk_",
    "registration_url": "https://loyalspark.online/merchant",
    "registration_note": "Sign in with email, phone, Google, or Web3 wallet (via Privy) to register an agent",
    "siwe_registration_url": "https://api.loyalspark.online/agent-register-siwe",
    "siwe_registration_note": "Autonomous agents: POST /siwe-nonce, sign EIP-4361 message including exact phrase 'Register Loyal Spark merchant agent' and Chain ID 8453, then POST to siwe_registration_url. Free key; same limits as dashboard. Doc: https://github.com/aspekt19/unboxed-loyalty-spark/blob/a2a-agents/docs/agents/AUTONOMOUS_AGENT_REGISTRATION.md",
    "docs_url": "https://loyalspark.online/api-docs"
  },
  "api": {
    "base_url": "https://api.loyalspark.online/agent-api",
    "authentication_summary": "All routes except GET /vouchers/status require header x-api-key: lsk_...",
    "endpoints": [
      {
        "method": "GET",
        "path": "/me",
        "scope": "authenticated",
        "description": "Get agent profile, permissions, plan, and wallet info"
      },
      {
        "method": "POST",
        "path": "/workflow/generate-program-defaults",
        "scope": "read or mint or create_program",
        "description": "Generate default program names, token symbols, starter rewards, and suggested economics so autonomous agents can fill in missing business details.",
        "body": {
          "business_name": "Coffee Corner",
          "category": "cafe",
          "preferred_style": "playful",
          "locale": "en"
        }
      },
      {
        "method": "GET",
        "path": "/workflow/program-status",
        "scope": "read",
        "description": "Return machine-readable merchant workflow state, next actions, and prerequisites for the most recent or specified program."
      },
      {
        "method": "GET",
        "path": "/programs",
        "scope": "read",
        "description": "List all active loyalty programs"
      },
      {
        "method": "POST",
        "path": "/programs",
        "scope": "mint or create_program",
        "description": "Start a program deploy workflow. External agents must pass name and symbol. Returns workflow metadata for next steps.",
        "body": {
          "name": "Coffee Corner Loyalty",
          "symbol": "COFF",
          "token_standard": "b20",
          "expiration_days": 365,
          "auto_generate": false
        }
      },
      {
        "method": "POST",
        "path": "/register-program",
        "scope": "mint or create_program",
        "description": "Register a deployed token as a loyalty program in the database. B20 becomes active immediately; legacy ERC-20 needs activation flow next.",
        "body": {
          "name": "Coffee Rewards",
          "symbol": "COFFEE",
          "token_address": "0x...",
          "expiration_days": 365,
          "cashback_rate": 5,
          "points_per_dollar": 1
        }
      },
      {
        "method": "POST",
        "path": "/update-program-config",
        "scope": "mint or create_program",
        "description": "Update default cashback_rate and/or points_per_dollar for a program you own",
        "body": {
          "token_address": "0x...",
          "cashback_rate": 7.5,
          "points_per_dollar": 2
        }
      },
      {
        "method": "POST",
        "path": "/activate-program",
        "scope": "mint or create_program",
        "description": "Activation step for legacy ERC-20 programs. For B20 programs this is a no-op because they are active by construction.",
        "body": {
          "token_address": "0x..."
        }
      },
      {
        "method": "POST",
        "path": "/program-status",
        "scope": "mint or create_program",
        "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": "Prepare a fee-first mint: returns calls[] (protocol fee first, then recipient) plus fee_obligation_id. Submit onchain then confirm."
      },
      {
        "method": "POST",
        "path": "/mint/confirm",
        "scope": "mint",
        "description": "Verify the protocol-fee mint on Base and settle the pending fee obligation. Required after /mint or /earn when fee_amount > 0.",
        "body": {
          "obligation_id": "uuid",
          "fee_tx_hash": "0x...",
          "recipient_tx_hash": "0x..."
        }
      },
      {
        "method": "POST",
        "path": "/earn",
        "scope": "mint",
        "description": "Auto-calculate and mint tokens from purchase amount using program's cashback rate. POS-friendly alternative to /mint.",
        "body": {
          "token_address": "0x...",
          "customer_address": "0x...",
          "purchase_amount": 50,
          "cashback_rate": 5
        }
      },
      {
        "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": "authenticated",
        "description": "Extract token_address from a deploy transaction hash (requires API key; not public)",
        "query_params": {
          "tx_hash": "0x..."
        }
      },
      {
        "method": "GET",
        "path": "/offers",
        "scope": "read or 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"
        }
      },
      {
        "method": "GET",
        "path": "/merchant-profile",
        "scope": "read",
        "description": "Get merchant business profile (business_name, category, branding) for the agent's bound wallet.",
        "query_params": {
          "use_agent_wallet": "true | false"
        }
      },
      {
        "method": "POST",
        "path": "/merchant-profile",
        "scope": "mint or create_program",
        "description": "Upsert merchant business profile (business_name, category, logo_url, description, website, location). Also supported via PUT.",
        "body": {
          "business_name": "Coffee Co",
          "category": "cafe",
          "logo_url": "https://...",
          "description": "...",
          "website": "https://...",
          "location": "Berlin",
          "use_agent_wallet": false
        }
      }
    ]
  },
  "escrow": {
    "description": "P2P token exchange is protected by a smart contract escrow. Atomic swap \u2014 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() \u2014 tokens locked in escrow",
      "3. Accepter approves escrow contract for request tokens",
      "4. Accepter calls fillOffer() \u2014 atomic swap executes",
      "Alternative: Creator calls cancelOffer() \u2014 tokens returned"
    ]
  },
  "wallets": {
    "type": "cdp_mpc",
    "description": "Coinbase CDP MPC wallets on Base \u2014 agents get their own server wallet for autonomous onchain operations. No private keys to manage.",
    "create_endpoint": "https://api.loyalspark.online/agent-wallet (POST JSON body per function docs; x-api-key required)",
    "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) \u2014 applies to subscriptions and pay-per-request only",
    "transaction_fee_note": "The per-plan transaction_fee is the mint protocol fee. It is denominated in the merchant's own loyalty tokens (a separate mint(address,uint256) to the platform fee wallet on the same token contract), NOT in USDC, ETH, or fiat. The token contract does not enforce it on-chain; it is tracked off-chain as a fee obligation and 5+ unpaid obligations older than 60 minutes block further mints with HTTP 402. Confirm each fee with POST /agent-api/mint/confirm or MCP confirm_mint_fee.",
    "plans": [
      {
        "name": "Free",
        "price": 0,
        "limits": {
          "api_calls_monthly": 200,
          "agents": 1,
          "max_mint_amount_monthly": 1000,
          "transaction_fee": "1.25%"
        }
      },
      {
        "name": "Pro",
        "price_usdc_monthly": 49,
        "limits": {
          "api_calls_monthly": 10000,
          "agents": 5,
          "max_mint_amount_monthly": "unlimited",
          "transaction_fee": "0.5%"
        }
      },
      {
        "name": "Enterprise",
        "price_usdc_monthly": 129,
        "limits": {
          "api_calls_monthly": "unlimited",
          "agents": "unlimited",
          "max_mint_amount_monthly": "unlimited",
          "transaction_fee": "0.25%"
        }
      }
    ],
    "plan_limits_note": "Free plan mint quota (1,000 loyalty tokens/mo per owner wallet) is enforced server-side; exceeding it returns HTTP 402. Paid plans remove the mint cap.",
    "payment": "Subscriptions: on-chain USDC transfer to the platform wallet, verified automatically. Mint protocol fees are separate and paid in loyalty tokens (see transaction_fee_note).",
    "access_control": {
      "model": "row-level-security",
      "description": "Every REST and MCP call is scoped by Postgres row-level security to the owner wallet behind the lsk_/rwk_ key \u2014 agents only read and write their own programs, rewards, vouchers, and offers."
    },
    "pay_per_request": {
      "protocols": [
        "x402 v2 exact",
        "MPP"
      ],
      "x402": {
        "gateway_url": "https://api.loyalspark.online/x402-gateway",
        "network": "eip155:8453",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "scheme": "exact",
        "description": "Fixed-price route payment in USDC on Base. The gateway returns HTTP 402 requirements, verifies and settles before proxying.",
        "discovery_url": "https://api.loyalspark.online/.well-known/x402"
      },
      "mpp": {
        "gateway_url": "https://api.loyalspark.online/mpp-gateway",
        "currencies": [
          "pathUSD",
          "Tempo USDC"
        ],
        "description": "Fixed-price route payment with the MPP 402 challenge and credential flow on Tempo.",
        "manifest_url": "https://loyalspark.online/.well-known/mpp.json"
      },
      "boundary": "The current gateways do not expose upto, partial capture, void, refund, payout, or split operations.",
      "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",
        "GET /merchant-profile": "0.001",
        "POST /programs": "0.05",
        "POST /register-program": "0.01",
        "POST /update-program-config": "0.005",
        "POST /activate-program": "0.01",
        "POST /program-status": "0.005",
        "POST /rewards": "0.01",
        "POST /mint": "0.01",
        "POST /earn": "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",
        "POST /merchant-profile": "0.005",
        "PUT /merchant-profile": "0.005",
        "GET /tx-receipt": "free (requires API key)"
      }
    }
  },
  "chain": {
    "name": "Base",
    "chain_id": 8453,
    "token_standards": [
      "B20 Asset (Base-native)",
      "ERC-20 (legacy)"
    ],
    "default_new_program_standard": "B20",
    "explorer": "https://basescan.org",
    "builder_code": "bc_wdmnog7m"
  },
  "mcp": {
    "url": "https://api.loyalspark.online/loyalty-mcp",
    "tool_count": 39,
    "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",
      "update_program_config",
      "list_rewards",
      "create_reward",
      "mint_loyalty_tokens",
      "earn_points",
      "confirm_mint_fee",
      "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",
      "create_gift_certificate",
      "list_gift_certificates",
      "revoke_gift_certificate",
      "mark_gift_certificate_minted",
      "generate_program_defaults",
      "get_program_workflow_status",
      "bazaar_discover_resources",
      "bazaar_discover_mcp_servers",
      "bazaar_probe_x402",
      "bazaar_pay_and_call"
    ]
  },
  "base_mcp_plugin": {
    "description": "GET-friendly calldata endpoints designed to be consumed by Base MCP (mcp.base.org) custom plugins. Each response returns a send_calls-compatible batch with the Loyal Spark Builder Code (bc_wdmnog7m, ERC-8021) already appended, so Base Account signs and broadcasts as-is.",
    "base_url": "https://api.loyalspark.online/agent-prepare",
    "authentication": {
      "type": "api_key",
      "header": "x-api-key",
      "prefixes": [
        "lsk_",
        "rwk_"
      ]
    },
    "response_shape": {
      "chainId": 8453,
      "description": "string",
      "transactions": [
        {
          "to": "0x\u2026",
          "data": "0x\u2026",
          "value": "0x0"
        }
      ],
      "builder_code": "bc_wdmnog7m"
    },
    "actions": [
      {
        "method": "GET",
        "path": "/create-program",
        "auth": "lsk_",
        "description": "Deploy a new B20 loyalty token (default; legacy ERC-20 via token_standard)"
      },
      {
        "method": "GET",
        "path": "/activate-program",
        "auth": "lsk_",
        "description": "Activate a legacy ERC-20 program (no-op for B20)"
      },
      {
        "method": "GET",
        "path": "/mint",
        "auth": "lsk_",
        "description": "Mint loyalty tokens to a wallet"
      },
      {
        "method": "GET",
        "path": "/transfer",
        "auth": "lsk_",
        "description": "Merchant-side loyalty token transfer"
      },
      {
        "method": "GET",
        "path": "/recipient-transfer",
        "auth": "rwk_",
        "description": "Holder loyalty token transfer"
      },
      {
        "method": "GET",
        "path": "/recipient-approve",
        "auth": "rwk_",
        "description": "Holder token approve"
      }
    ],
    "plugin_spec": "https://loyalspark.online/skills/loyal-spark/plugins/loyal-spark.md"
  },
  "recipient_api": {
    "description": "Wallet-bound API for agents that HOLD loyalty tokens (not merchants). Authenticated with x-api-key: rwk_\u2026 Register via SIWE: POST https://api.loyalspark.online/siwe-nonce \u2192 sign EIP-4361 message including 'Register Loyal Spark recipient agent' and Chain ID 8453 \u2192 POST { message, signature } to https://api.loyalspark.online/recipient-api/register (pass Supabase publishable apikey header). Returns rwk_\u2026 once.",
    "rest_base_url": "https://api.loyalspark.online/recipient-api",
    "mcp_url": "https://api.loyalspark.online/recipient-loyalty-mcp",
    "mcp_transport": "streamable-http",
    "mcp_tool_count": 20,
    "mcp_tools": [
      "get_recipient_profile",
      "list_my_loyalty_balances",
      "get_my_loyalty_balance",
      "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",
      "get_reward_workflow_status",
      "prepare_reward_redemption",
      "bazaar_discover_resources",
      "bazaar_discover_mcp_servers",
      "bazaar_probe_x402",
      "bazaar_pay_and_call"
    ],
    "rest_endpoints": [
      {
        "method": "GET",
        "path": "/me",
        "price_usd": "free",
        "description": "Recipient profile and bound wallet"
      },
      {
        "method": "GET",
        "path": "/balances",
        "price_usd": "0.001",
        "description": "All loyalty balances for the bound wallet"
      },
      {
        "method": "GET",
        "path": "/balance",
        "price_usd": "0.001",
        "description": "One-token balance and tier"
      },
      {
        "method": "GET",
        "path": "/rewards",
        "price_usd": "0.001",
        "description": "Rewards available for redemption"
      },
      {
        "method": "GET",
        "path": "/vouchers",
        "price_usd": "0.001",
        "description": "Vouchers issued to this wallet"
      },
      {
        "method": "GET",
        "path": "/offers",
        "price_usd": "0.001",
        "description": "P2P marketplace offers"
      },
      {
        "method": "GET",
        "path": "/workflow/reward-status",
        "price_usd": "0.001",
        "description": "Autonomous planner: current reward redemption step + next_actions[]"
      },
      {
        "method": "POST",
        "path": "/register",
        "price_usd": "free",
        "description": "One-time wallet registration after SIWE"
      },
      {
        "method": "POST",
        "path": "/prepare-transfer",
        "price_usd": "0.005",
        "description": "ERC-20 transfer calldata (holder \u2192 any address)"
      },
      {
        "method": "POST",
        "path": "/redeem-reward",
        "price_usd": "0.01",
        "description": "Redeem a reward via on-chain tx hash"
      },
      {
        "method": "POST",
        "path": "/offers",
        "price_usd": "0.01",
        "description": "Create P2P swap intent (escrow)"
      },
      {
        "method": "POST",
        "path": "/accept-offer",
        "price_usd": "0.01",
        "description": "Accept a P2P offer (atomic swap)"
      },
      {
        "method": "POST",
        "path": "/cancel-offer",
        "price_usd": "0.005",
        "description": "Cancel your own P2P offer"
      },
      {
        "method": "POST",
        "path": "/workflow/prepare-reward-redemption",
        "price_usd": "0.005",
        "description": "Autonomous planner: transfer calldata for reward cost + workflow metadata"
      }
    ],
    "x402_corridor": {
      "rest_url_template": "https://api.loyalspark.online/x402-gateway/recipient-api/{path}",
      "mcp_url_template": "https://api.loyalspark.online/x402-gateway/recipient-mcp-tools/{tool_name}",
      "bazaar": "Same extensions.bazaar metadata as merchant corridor; tools schemas in supabase/functions/_shared/recipient-mcp-bazaar-tools.ts"
    }
  },
  "mpp": {
    "description": "Machine Payments Protocol \u2014 pay per API request with HTTP 402 flow. No subscription needed.",
    "gateway_url": "https://api.loyalspark.online/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://api.loyalspark.online/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 \u2014 pay per request with USDC on Base. HTTP 402 with x402 v2 accepts; on-chain verify/settle for Base mainnet via Coinbase CDP when gateway secrets are set.",
    "x402_version": 2,
    "gateway_url": "https://api.loyalspark.online/x402-gateway",
    "discovery_url": "https://api.loyalspark.online/.well-known/x402",
    "discovery_mirror": "https://loyalspark.online/.well-known/x402.json",
    "currency": "USDC on Base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "network": "eip155:8453",
    "chain_id": 8453,
    "facilitator": "https://x402.org/facilitator",
    "facilitator_base_mainnet_cdp": "https://api.cdp.coinbase.com/platform/v2/x402",
    "facilitator_note": "Production Base mainnet settlement uses CDP x402 API (JWT) when CDP_API_KEY_ID/CDP_API_KEY_SECRET are configured on the gateway. Public x402.org/facilitator listings differ (e.g. Sepolia v2 exact).",
    "mcp_paid": {
      "url_template": "https://api.loyalspark.online/x402-gateway/mcp-tools/{tool_name}",
      "method": "POST",
      "body": "JSON-RPC 2.0: method tools/call, params.name = tool_name, params.arguments = object per tool schema",
      "headers_after_payment": [
        "x-api-key: lsk_...",
        "Content-Type: application/json"
      ],
      "tool_schemas_source": "https://github.com/aspekt19/unboxed-loyalty-spark/blob/a2a-agents/supabase/functions/_shared/mcp-bazaar-tools.ts",
      "bazaar": "HTTP 402 response includes extensions.bazaar (discoverable, inputSchema for headers/body) for MCP resources"
    },
    "protocol_spec": "https://github.com/coinbase/x402",
    "how_to_use": [
      "1. npm install @x402/fetch @x402/evm",
      "2. POST {gateway_url}/mcp-tools/{tool} or other x402 routes \u2014 receive 402 with accepts (v2)",
      "3. Sign USDC payment on Base with x402 client; retry with payment header",
      "4. Gateway verify/settle via CDP x402 on mainnet; for MCP, body is forwarded to loyalty-mcp with x-api-key"
    ],
    "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",
      "GET /merchant-profile": "0.001",
      "POST /programs": "0.05",
      "POST /register-program": "0.01",
      "POST /update-program-config": "0.005",
      "POST /activate-program": "0.01",
      "POST /program-status": "0.005",
      "POST /rewards": "0.01",
      "POST /mint": "0.01",
      "POST /earn": "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",
      "POST /merchant-profile": "0.005",
      "PUT /merchant-profile": "0.005",
      "GET /tx-receipt": "free (requires API key)"
    }
  },
  "skills": {
    "url": "https://loyalspark.online/.well-known/skills/index.md",
    "format": "markdown",
    "guide_count": 16,
    "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 B20 loyalty token on Base (legacy ERC-20 optional)"
      },
      {
        "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"
      },
      {
        "id": "earn-points",
        "file": "11-earn-points.md",
        "description": "Auto-calculate tokens from purchase amount (cashback)"
      },
      {
        "id": "gift-certificates",
        "file": "12-gift-certificates.md",
        "description": "Issue, claim and mint LOYAL-XXXXXX gift / welcome certificates"
      },
      {
        "id": "endpoint-workflows",
        "file": "13-endpoint-workflows.md",
        "description": "Multi-step REST/MCP workflows and prerequisites"
      },
      {
        "id": "b20-native-spec",
        "file": "14-b20-native-spec.md",
        "description": "Base Beryl B20 Asset semantics for loyalty tokens"
      },
      {
        "id": "payment-scenarios",
        "file": "15-payment-scenarios.md",
        "description": "x402 exact, MPP, subscriptions, and spend policies"
      }
    ]
  },
  "why_use": {
    "headline": "Loyalty-as-a-Service for AI Agents",
    "value_propositions": [
      {
        "title": "Full Infrastructure Out of the Box",
        "description": "Creating an ERC-20 or B20 program is 5% of the work. Loyal Spark provides rewards, vouchers, tiers, analytics, CRM, and marketing automation \u2014 via REST, MCP, and the merchant portal."
      },
      {
        "title": "Autonomous Server Wallets",
        "description": "Each agent gets a Coinbase MPC wallet on Base. No private keys to manage \u2014 sign transactions server-side with enterprise-grade security."
      },
      {
        "title": "Network Effect & Liquidity",
        "description": "A standalone token is an island. Tokens on Loyal Spark have real utility through vouchers and P2P escrow swaps (REST for merchants, MCP for holders) \u2014 not a DEX order book."
      },
      {
        "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": "Humans and Agents, Same Protocol",
        "description": "Merchants run programs in the web portal; AI agents run the same loop via REST and MCP (lsk_/rwk_) with fee-first mint calldata and prepaid USDC rails (subscriptions, x402, MPP)."
      },
      {
        "title": "Composability via Single API",
        "description": "Create program \u2192 set up tiers \u2192 launch referrals \u2192 automate minting \u2192 track analytics. All through one REST API or MCP Server."
      },
      {
        "title": "Pay-as-you-go Pricing",
        "description": "Start free with 200 API calls/month and a 1,000-token monthly mint cap. Scale to Pro ($49/mo) or Enterprise ($129/mo) with lower mint fees and higher limits, or pay per call via MPP / x402 with no subscription. Subscriptions and per-call payments are in USDC on Base; the mint protocol fee is separate and paid in your own loyalty tokens."
      }
    ],
    "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, phone, Google, or wallet via Privy)",
      "2. Open 'AI Agents' tab \u2192 Register an agent \u2192 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 https://api.loyalspark.online/agent-wallet (see Edge Function docs)",
      "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",
    "onchain",
    "base",
    "erc20",
    "a2a",
    "marketplace",
    "mcp",
    "cdp",
    "mpc-wallet",
    "ai-agents"
  ]
}