# Loyal Spark — Onchain Loyalty Protocol (Full Reference)

> Loyalty-as-a-Service for AI agents and merchants on Base L2. Deploy ERC-20 tokens, manage rewards, trade on P2P marketplace — via REST API, MCP Server, or pay-per-request gateways.

## Overview

Loyal Spark is a dual-mode protocol: humans interact via web UI with wallet authentication (SIWE), while AI agents integrate via REST API, MCP Server, or HTTP 402 payment gateways. The protocol runs on Base mainnet (chain ID 8453) and uses ERC-20 tokens for loyalty points.

## Discovery Endpoints

- Agent Manifest: https://loyalspark.online/.well-known/agent.json
- OpenAPI 3.1.0: https://loyalspark.online/openapi.json
- MCP Server: https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/loyalty-mcp (Streamable HTTP)
- MPP Manifest: https://loyalspark.online/.well-known/mpp.json
- AI Plugin: https://loyalspark.online/.well-known/ai-plugin.json
- Skills Guide: https://loyalspark.online/.well-known/skills/index.md

## Authentication

All API calls require an `x-api-key` header with a key prefixed `lsk_`.

To get an API key:
1. Visit https://loyalspark.online/merchant
2. Connect a Web3 wallet
3. Open "AI Agents" tab
4. Register an agent and copy the key

## REST API — 19 Endpoints

Base URL: https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/agent-api

### Read Operations (GET)

| Endpoint | Price | Description |
|----------|-------|-------------|
| /me | free | Agent profile, plan, wallet info |
| /programs | $0.001 | List active loyalty programs |
| /rewards?token_address=0x... | $0.001 | Rewards for a program |
| /balance?token_address=0x...&wallet_address=0x... | $0.001 | Token balance and tier |
| /customers?token_address=0x... | $0.002 | Customer list with balances |
| /vouchers?token_address=0x... | $0.001 | Voucher list |
| /analytics?token_address=0x... | $0.005 | Program metrics |
| /offers | $0.001 | Active P2P marketplace offers |
| /tx-receipt?tx_hash=0x... | free | Extract token_address from deploy tx |

### Write Operations (POST)

| Endpoint | Price | Scope | Description |
|----------|-------|-------|-------------|
| /programs | $0.05 | mint | Get calldata to deploy new ERC-20 token |
| /register-program | $0.01 | mint | Register deployed token in database |
| /activate-program | $0.01 | mint | Get activation calldata (unpause + enable minting) |
| /program-status | $0.005 | mint | Update program status |
| /rewards | $0.01 | manage_rewards | Create a redeemable reward |
| /mint | $0.01 | mint | Mint tokens to customer wallet |
| /transfer | $0.005 | mint | Transfer tokens between wallets |
| /offers | $0.01 | trade | Create P2P escrow offer |
| /accept-offer | $0.01 | trade | Accept a P2P offer |
| /cancel-offer | $0.005 | trade | Cancel your P2P offer |

### Example: Mint Tokens

```bash
curl -X POST \
  -H "x-api-key: lsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token_address":"0x...","recipient_address":"0x...","amount":100}' \
  https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/agent-api/mint
```

Response returns calldata with Builder Code for onchain execution.

## MCP Server — 14 Tools

URL: https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/loyalty-mcp
Transport: Streamable HTTP
Auth: x-api-key header

### Tools

1. `get_platform_info` — Protocol metadata and capabilities
2. `get_my_profile` — Agent identity, plan, wallet
3. `list_loyalty_programs` — All active programs
4. `create_loyalty_program` — Deploy calldata for new token
5. `register_loyalty_program` — Register deployed token
6. `activate_loyalty_program` — Activation calldata
7. `update_program_status` — Update status in DB
8. `list_rewards` — Rewards for a program
9. `create_reward` — Create redeemable reward
10. `mint_loyalty_tokens` — Mint calldata
11. `transfer_loyalty_tokens` — Transfer calldata
12. `get_token_balance` — Balance and tier info
13. `get_program_analytics` — Metrics and performance
14. `list_marketplace_offers` — P2P offers

### MCP Configuration for Claude/Cursor

```json
{
  "mcpServers": {
    "loyal-spark": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/loyalty-mcp"],
      "env": {
        "HTTP_HEADER_x-api-key": "lsk_YOUR_KEY"
      }
    }
  }
}
```

## Payment Gateways

### MPP (Machine Payments Protocol)
- Gateway: https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/mpp-gateway
- Currency: pathUSD on Tempo (also accepts USDC 0x20C0...b50)
- Flow: Request → 402 challenge → pay → retry with credential
- SDK: `npm install -g mppx`

### x402 (Coinbase Protocol)
- Gateway: https://bzxmejzssxjazswgwqqs.supabase.co/functions/v1/x402-gateway
- Currency: USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
- Facilitator: https://facilitator.x402.org
- SDK: `@x402/fetch`, `@x402/evm`
- Spec: https://github.com/coinbase/x402

## Agent Wallets

Agents can create Coinbase CDP MPC wallets for autonomous onchain operations:
- No private keys to manage
- Server-side transaction signing
- Support for `use_agent_wallet: true` in program creation
- Create via: POST /agent-api with action `create_server_wallet`

## Subscription Plans

| Plan | Price | API Calls/mo | Agents | Tx Fee |
|------|-------|-------------|--------|--------|
| Free | $0 | 100 | 1 | 1% |
| Pro | $29 USDC | 10,000 | 5 | 0.5% |
| Enterprise | $99 USDC | Unlimited | Unlimited | 0.25% |

Payment: On-chain USDC transfer on Base, verified automatically.

## Smart Contracts

| Contract | Address | Chain |
|----------|---------|-------|
| LoyaltyTokenFactory | 0x5F3DdBa12580CFdc6016258774cCc19C4250dA80 | Base |
| LoyalSparkERC20 | 0xe6BA426C9c51281B929a17444De02c65815E27C3 | Base |
| LoyaltyTokenEscrow | 0xA569C95AfC1BCF381c48BcF336ED9D2c014bcdDF | Base |
| Builder Code | bc_wdmnog7m (ERC-8021) | Base |

## P2P Marketplace (Escrow)

Atomic token swaps via smart contract:
1. Creator approves escrow for offer tokens
2. Creator calls createOffer() — tokens locked
3. Accepter approves escrow for request tokens
4. Accepter calls fillOffer() — atomic swap
5. Alternative: cancelOffer() returns tokens

Protocol fee: 0.5% on completed swaps.

## Skills (Step-by-Step Guides)

11 structured Markdown guides at `/.well-known/skills/`:
- 00: Getting Started (register, API key, first request)
- 01: Create Loyalty Program (deploy ERC-20)
- 02: Mint Tokens
- 03: Transfer Tokens
- 04: Manage Rewards
- 05: Balance and Tiers
- 06: Marketplace Trading
- 07: Analytics & CRM
- 08: Referrals
- 09: Vouchers
- 10: Server Wallets (CDP MPC)

## Tags

loyalty, rewards, defi, base, erc20, ai-agents, mcp, rest-api, mpp, x402, cdp, mpc-wallet, p2p-marketplace, escrow, onchain

## Contact

- Website: https://loyalspark.online
- Docs: https://loyalspark.online/api-docs
- Email: admin@loyalspark.online
- Twitter: https://x.com/Loyal_Spark