Loyal Spark

Official39 toolsLive

by aspekt19 · TypeScript

Base MCP (39 tools) on Base: programs, mint, rewards. lsk_ key; plan limits enforced. /for-agents

io.github.aspekt19/loyal-spark MCP Server

Loyal Spark is a Web3 onchain loyalty protocol on Base Mainnet. It enables merchants and AI agents to create onchain loyalty programs, mint points (B20 by default), manage rewards/vouchers, and automate the loyalty loop via REST, MCP, and pay-per-call gateways (x402 / MPP), with plan limits enforced.

🛠️ Key Features

Base MCP server with 39 tools
Onchain loyalty programs on Base Mainnet
Points minting and rewards/vouchers management
lsk_ key; plan limits enforced
Access via MCP under /for-agents

🚀 Use Cases

Merchants creating onchain loyalty programs
AI agents interacting through MCP (and REST) workflows
Automating loyalty loops that include minting and reward distribution

⚡ Developer Benefits

Tool-based integration via MCP (39 tools)
Dual integration paths: REST and MCP
Pay-per-call gateways support: x402 / MPP

⚠️ Limitations

Functionality subject to plan limits

Captured live from the server via tools/list.

get_platform_info

Get info about Loyal Spark protocol on Base L2

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

get_my_profile

Get authenticated agent's profile

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

generate_program_defaults

Workflow planner: field catalog, required parameters, next_actions, and non-binding examples. External agents must choose their own name, symbol, and economics.

Parameters6

business_name	string	optional
category	string	optional
description	string	optional
locale	string	optional
preferred_style	string	optional
target_audience	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "business_name": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "locale": {
      "type": "string"
    },
    "preferred_style": {
      "type": "string"
    },
    "target_audience": {
      "type": "string"
    }
  }
}

get_program_workflow_status

Explain the next merchant action: current_step, required fields, and ordered next_actions (you provide all parameter values)

Parameters1

token_address

string

optional

Optional token to inspect

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Optional token to inspect"
    }
  }
}

list_loyalty_programs

List loyalty programs owned by the agent's merchant

Parameters1

include_expired

boolean

optional

Include expired programs

Raw schema

{
  "type": "object",
  "properties": {
    "include_expired": {
      "type": "boolean",
      "description": "Include expired programs"
    }
  }
}

create_loyalty_program

Get factory calldata to deploy a new loyalty token on Base. Defaults to B20 (Base native ERC-20 superset, single tx, active immediately). Pass token_standard='erc20' for the legacy factory. For B20, MINT_ROLE is granted atomically to the merchant admin AND to the agent's CDP wallet (or explicit extra_minters) so autonomous agents can mint with no follow-up transaction.

Parameters11

name	string	optional	Program name (required for external agents)
symbol	string	optional	Token symbol, 2-5 chars (required for external agents)
expiration_days	number	optional	Program duration in days (default: 365)
token_standard	string	optional	'b20' (default, single-tx deploy on Base precompile factory) or 'erc20' (legacy factory, requires activate_loyalty_program follow-up)
agent_wallet_address	string	optional	(B20 only) Additional wallet to grant MINT_ROLE atomically. Defaults to the agent's active CDP MPC wallet if not provided.
extra_minters	array	optional	(B20 only) Extra addresses to grant MINT_ROLE atomically in the same deploy tx.
auto_generate	boolean	optional	Internal automation only — fills missing name/symbol from examples. External agents should pass explicit name and symbol.
business_context	object	optional	Optional context for examples only
preferred_style	string	optional
locale	string	optional
target_audience	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Program name (required for external agents)"
    },
    "symbol": {
      "type": "string",
      "description": "Token symbol, 2-5 chars (required for external agents)"
    },
    "expiration_days": {
      "type": "number",
      "description": "Program duration in days (default: 365)"
    },
    "token_standard": {
      "type": "string",
      "description": "'b20' (default, single-tx deploy on Base precompile factory) or 'erc20' (legacy factory, requires activate_loyalty_program follow-up)"
    },
    "agent_wallet_address": {
      "type": "string",
      "description": "(B20 only) Additional wallet to grant MINT_ROLE atomically. Defaults to the agent's active CDP MPC wallet if not provided."
    },
    "extra_minters": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "(B20 only) Extra addresses to grant MINT_ROLE atomically in the same deploy tx."
    },
    "auto_generate": {
      "type": "boolean",
      "description": "Internal automation only — fills missing name/symbol from examples. External agents should pass explicit name and symbol."
    },
    "business_context": {
      "type": "object",
      "description": "Optional context for examples only"
    },
    "preferred_style": {
      "type": "string"
    },
    "locale": {
      "type": "string"
    },
    "target_audience": {
      "type": "string"
    }
  }
}

register_loyalty_program

Register a deployed token as a loyalty program in the database. B20 tokens are registered as active; legacy ERC-20 as inactive (activate next).

Parameters7

name	string	required	Program name
symbol	string	required	Token symbol
token_address	string	required	Deployed token contract address (0x...)
expiration_days	number	optional	Duration in days (default: 365)
cashback_rate	number	optional	Default cashback percent for earn (1–100). Omit for DB default (5).
points_per_dollar	number	optional	Loyalty points per $1 spent (1–1000). Omit for DB default (1).
token_standard	string	optional	'b20' (default) or 'erc20' (legacy)

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Program name"
    },
    "symbol": {
      "type": "string",
      "description": "Token symbol"
    },
    "token_address": {
      "type": "string",
      "description": "Deployed token contract address (0x...)"
    },
    "expiration_days": {
      "type": "number",
      "description": "Duration in days (default: 365)"
    },
    "cashback_rate": {
      "type": "number",
      "description": "Default cashback percent for earn (1–100). Omit for DB default (5)."
    },
    "points_per_dollar": {
      "type": "number",
      "description": "Loyalty points per $1 spent (1–1000). Omit for DB default (1)."
    },
    "token_standard": {
      "type": "string",
      "description": "'b20' (default) or 'erc20' (legacy)"
    }
  },
  "required": [
    "name",
    "symbol",
    "token_address"
  ]
}

activate_loyalty_program

For legacy ERC-20 programs: returns unpauseUtility + enableMinting calldata. For B20 programs: no-op (already active).

Parameters1

token_address

string

required

Token contract address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address (0x...)"
    }
  },
  "required": [
    "token_address"
  ]
}

update_program_status

Update program status in database after onchain activation/pause

Parameters2

token_address	string	required	Token contract address
status	string	required	New status: active, paused, or inactive

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address"
    },
    "status": {
      "type": "string",
      "description": "New status: active, paused, or inactive"
    }
  },
  "required": [
    "token_address",
    "status"
  ]
}

update_program_config

Update default cashback_rate and/or points_per_dollar for a program (same as merchant dashboard sliders)

Parameters3

token_address	string	required	Token contract address (0x...)
cashback_rate	number	optional	New default cashback % for earn (1–100). Omit to leave unchanged.
points_per_dollar	number	optional	New points per $1 (0–1000, exclusive 0). Omit to leave unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address (0x...)"
    },
    "cashback_rate": {
      "type": "number",
      "description": "New default cashback % for earn (1–100). Omit to leave unchanged."
    },
    "points_per_dollar": {
      "type": "number",
      "description": "New points per $1 (0–1000, exclusive 0). Omit to leave unchanged."
    }
  },
  "required": [
    "token_address"
  ]
}

list_rewards

List rewards for a loyalty program by token_address. Includes redemption metrics (total vouchers issued, redeemed, and last-30-day counts) for each reward.

Parameters1

token_address

string

required

Token contract address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address (0x...)"
    }
  },
  "required": [
    "token_address"
  ]
}

create_reward

Create a new reward redeemable with loyalty tokens

Parameters4

token_address	string	required	Token contract address
name	string	required	Reward name
description	string	optional	Reward description
cost	number	required	Token cost to redeem

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address"
    },
    "name": {
      "type": "string",
      "description": "Reward name"
    },
    "description": {
      "type": "string",
      "description": "Reward description"
    },
    "cost": {
      "type": "number",
      "description": "Token cost to redeem"
    }
  },
  "required": [
    "token_address",
    "name",
    "cost"
  ]
}

mint_loyalty_tokens

Record mint intent and get a fee-first `calls[]` bundle: protocol fee mint FIRST, then the recipient mint. The protocol fee is charged in the merchant's own loyalty tokens (not USDC). Submit both calls in order (atomically via EIP-5792 send_calls if your wallet supports it), then call confirm_mint_fee (or POST /agent-api/mint/confirm) with the fee tx hash. Unconfirmed fee obligations block future mints.

Parameters3

token_address	string	required	Token contract address
recipient	string	required	Recipient wallet (0x...)
amount	number	required	Tokens to mint

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address"
    },
    "recipient": {
      "type": "string",
      "description": "Recipient wallet (0x...)"
    },
    "amount": {
      "type": "number",
      "description": "Tokens to mint"
    }
  },
  "required": [
    "token_address",
    "recipient",
    "amount"
  ]
}

transfer_loyalty_tokens

Get calldata to transfer loyalty tokens between wallets

Parameters3

token_address	string	required	Token contract address (0x...)
to	string	required	Recipient wallet (0x...)
amount	number	required	Tokens to transfer

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address (0x...)"
    },
    "to": {
      "type": "string",
      "description": "Recipient wallet (0x...)"
    },
    "amount": {
      "type": "number",
      "description": "Tokens to transfer"
    }
  },
  "required": [
    "token_address",
    "to",
    "amount"
  ]
}

earn_points

Calculate and mint loyalty tokens based on purchase amount and program's cashback rate. Returns a fee-first `calls[]` bundle (protocol fee mint first, then the customer mint) — submit in order, atomically via EIP-5792 if supported, then call confirm_mint_fee (or POST /agent-api/mint/confirm). Unconfirmed fee obligations block future mints.

Parameters4

token_address	string	required	Token contract address (0x...)
customer_address	string	required	Customer wallet (0x...)
purchase_amount	number	required	Purchase amount in currency units (e.g. dollars)
cashback_rate	number	optional	Override cashback rate (%). If omitted, uses the program's default rate.

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address (0x...)"
    },
    "customer_address": {
      "type": "string",
      "description": "Customer wallet (0x...)"
    },
    "purchase_amount": {
      "type": "number",
      "description": "Purchase amount in currency units (e.g. dollars)"
    },
    "cashback_rate": {
      "type": "number",
      "description": "Override cashback rate (%). If omitted, uses the program's default rate."
    }
  },
  "required": [
    "token_address",
    "customer_address",
    "purchase_amount"
  ]
}

confirm_mint_fee

Confirm that the protocol fee transaction for a previous mint/earn was broadcast on Base. Verifies the fee mint on-chain and clears the obligation. Unconfirmed fee obligations block future mints.

Parameters3

obligation_id	string	required	fee_obligation_id returned by mint_loyalty_tokens or earn_points
fee_tx_hash	string	required	Transaction hash of the protocol fee mint
recipient_tx_hash	string	optional	Optional transaction hash of the recipient mint

Raw schema

{
  "type": "object",
  "properties": {
    "obligation_id": {
      "type": "string",
      "description": "fee_obligation_id returned by mint_loyalty_tokens or earn_points"
    },
    "fee_tx_hash": {
      "type": "string",
      "description": "Transaction hash of the protocol fee mint"
    },
    "recipient_tx_hash": {
      "type": "string",
      "description": "Optional transaction hash of the recipient mint"
    }
  },
  "required": [
    "obligation_id",
    "fee_tx_hash"
  ]
}

get_token_balance

Get loyalty token balance and tier info for a customer

Parameters2

token_address	string	required	Token contract address
customer_address	string	required	Customer wallet

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address"
    },
    "customer_address": {
      "type": "string",
      "description": "Customer wallet"
    }
  },
  "required": [
    "token_address",
    "customer_address"
  ]
}

get_program_analytics

Get analytics for your loyalty programs

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

list_marketplace_offers

List active token trading offers on the marketplace

Parameters2

status	string	optional	Filter: active/completed/cancelled
limit	number	optional	Max results (1-100)

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter: active/completed/cancelled"
    },
    "limit": {
      "type": "number",
      "description": "Max results (1-100)"
    }
  }
}

redeem_reward

Redeem a reward by providing a verified token transfer transaction hash. Creates a voucher for the customer.

Parameters3

reward_id	string	required	UUID of the reward to redeem
customer_address	string	required	Wallet address of the customer who transferred tokens
transaction_hash	string	required	Onchain tx hash of the token transfer from customer to merchant

Raw schema

{
  "type": "object",
  "properties": {
    "reward_id": {
      "type": "string",
      "description": "UUID of the reward to redeem"
    },
    "customer_address": {
      "type": "string",
      "description": "Wallet address of the customer who transferred tokens"
    },
    "transaction_hash": {
      "type": "string",
      "description": "Onchain tx hash of the token transfer from customer to merchant"
    }
  },
  "required": [
    "reward_id",
    "customer_address",
    "transaction_hash"
  ]
}

use_voucher

Mark a voucher as used (redeemed by customer at merchant). Merchant-only operation.

Parameters2

voucher_code	string	optional	Voucher code (e.g. LOYAL-XXXX-XXXX-XXXX-XXXX)
voucher_id	string	optional	Voucher UUID (alternative to code)

Raw schema

{
  "type": "object",
  "properties": {
    "voucher_code": {
      "type": "string",
      "description": "Voucher code (e.g. LOYAL-XXXX-XXXX-XXXX-XXXX)"
    },
    "voucher_id": {
      "type": "string",
      "description": "Voucher UUID (alternative to code)"
    }
  }
}

check_voucher_status

Check voucher status by code or ID. Public endpoint — no API key or authentication required.

Parameters2

code	string	optional	Voucher code (e.g. LOYAL-XXXX-XXXX-XXXX-XXXX)
voucher_id	string	optional	Voucher UUID (alternative to code)

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Voucher code (e.g. LOYAL-XXXX-XXXX-XXXX-XXXX)"
    },
    "voucher_id": {
      "type": "string",
      "description": "Voucher UUID (alternative to code)"
    }
  }
}

get_platform_stats

Get global platform statistics across all merchants. Admin-only: requires agent owned by an admin wallet.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

cancel_stale_offers

Cancel marketplace offers that have been active for more than N days with no completions. Admin-only action tool.

Parameters1

max_age_days

number

optional

Cancel offers older than this many days (default: 14)

Raw schema

{
  "type": "object",
  "properties": {
    "max_age_days": {
      "type": "number",
      "description": "Cancel offers older than this many days (default: 14)"
    }
  }
}

create_personalized_offer

Create a personalized offer for a specific customer. Use when analytics reveal engagement patterns (e.g., inactive customers, high-value segments).

Parameters7

token_address	string	required	Token contract address
customer_address	string	required	Customer wallet address
title	string	required	Offer title (e.g., 'Welcome back! 20% bonus tokens')
description	string	optional	Offer description
bonus_tokens	number	optional	Bonus tokens to award
discount_percentage	number	optional	Discount percentage (0-100)
valid_days	number	optional	How many days the offer is valid (default: 7)

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token contract address"
    },
    "customer_address": {
      "type": "string",
      "description": "Customer wallet address"
    },
    "title": {
      "type": "string",
      "description": "Offer title (e.g., 'Welcome back! 20% bonus tokens')"
    },
    "description": {
      "type": "string",
      "description": "Offer description"
    },
    "bonus_tokens": {
      "type": "number",
      "description": "Bonus tokens to award"
    },
    "discount_percentage": {
      "type": "number",
      "description": "Discount percentage (0-100)"
    },
    "valid_days": {
      "type": "number",
      "description": "How many days the offer is valid (default: 7)"
    }
  },
  "required": [
    "token_address",
    "customer_address",
    "title"
  ]
}

update_reward_status

Activate or deactivate a reward in the catalog. Use to manage reward availability based on analytics.

Parameters2

reward_id	string	required	UUID of the reward
is_active	boolean	required	true to activate, false to deactivate

Raw schema

{
  "type": "object",
  "properties": {
    "reward_id": {
      "type": "string",
      "description": "UUID of the reward"
    },
    "is_active": {
      "type": "boolean",
      "description": "true to activate, false to deactivate"
    }
  },
  "required": [
    "reward_id",
    "is_active"
  ]
}

send_report

Send a report to the developer/owner. Use this to submit SEO audits, growth ideas, data reports, anomalies, recommendations, or weekly summaries. The report will appear in the merchant's Agent Reports dashboard.

Parameters6

agent_role	string	required	Your role: ceo, seo, growth, or analyst
report_type	string	required	Type: seo_audit, growth_idea, data_report, anomaly, task, recommendation, or weekly_report
title	string	required	Report title (max 500 chars)
content	string	required	Report body text (max 10000 chars)
priority	string	optional	Priority: low, medium, high, or critical
action_items	array	optional	List of suggested action items

Raw schema

{
  "type": "object",
  "properties": {
    "agent_role": {
      "type": "string",
      "description": "Your role: ceo, seo, growth, or analyst"
    },
    "report_type": {
      "type": "string",
      "description": "Type: seo_audit, growth_idea, data_report, anomaly, task, recommendation, or weekly_report"
    },
    "title": {
      "type": "string",
      "description": "Report title (max 500 chars)"
    },
    "content": {
      "type": "string",
      "description": "Report body text (max 10000 chars)"
    },
    "priority": {
      "type": "string",
      "description": "Priority: low, medium, high, or critical"
    },
    "action_items": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of suggested action items"
    }
  },
  "required": [
    "agent_role",
    "report_type",
    "title",
    "content"
  ]
}

list_my_reports

List your previously submitted reports. Allows reviewing past reports, checking status (new/reviewed/done), and identifying what still needs attention.

Parameters2

status	string	optional	Filter by status: new, reviewed, done (optional)
limit	number	optional	Max results 1-50 (default: 20)

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by status: new, reviewed, done (optional)"
    },
    "limit": {
      "type": "number",
      "description": "Max results 1-50 (default: 20)"
    }
  }
}

update_report_status

Update report status to 'reviewed' or 'done'. Use 'done' when the action items have been completed. Use 'reviewed' to acknowledge a report.

Parameters2

report_id	string	required	UUID of the report
status	string	required	New status: reviewed or done

Raw schema

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "description": "UUID of the report"
    },
    "status": {
      "type": "string",
      "description": "New status: reviewed or done"
    }
  },
  "required": [
    "report_id",
    "status"
  ]
}

delete_report

Delete a report that is no longer relevant. Use to clean up outdated or irrelevant reports.

Parameters1

report_id

string

required

UUID of the report to delete

Raw schema

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "description": "UUID of the report to delete"
    }
  },
  "required": [
    "report_id"
  ]
}

export_customers

Export customer data for a specific loyalty program. Returns wallet addresses, voucher stats, balances, and tier info. Use for analytics, segmentation, and personalized offers.

Parameters1

token_address

string

required

Token address of the loyalty program

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Token address of the loyalty program"
    }
  },
  "required": [
    "token_address"
  ]
}

create_gift_certificate

Create a gift / welcome certificate (UDS-style) with a unique 6-character redemption code (LOYAL-XXXXXX). Customer redeems via QR or by entering the code; merchant then mints tokens on-chain. Use for welcome bonuses, promo campaigns, partnership gifts.

Parameters9

token_address	string	required	ERC-20 loyalty token address (must belong to the agent's merchant)
usd_amount	number	required	Certificate face value in USD (positive)
points_per_dollar	number	optional	Optional override of program rate (e.g. 10 = 10 tokens per $1). Defaults to program's points_per_dollar.
max_redemption_percent	number	optional	Max % of any future purchase the customer can pay with these tokens (5–100). Default 50.
title	string	optional	Display title (default: 'Gift Certificate')
description	string	optional	Optional descriptive text shown to the customer
expires_in_days	number	optional	Validity period in days (omit for no expiry)
image_url	string	optional	Optional public image URL for the cert design
quantity	number	optional	Number of certificates to create as a batch (1–100, default 1)

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "ERC-20 loyalty token address (must belong to the agent's merchant)"
    },
    "usd_amount": {
      "type": "number",
      "description": "Certificate face value in USD (positive)"
    },
    "points_per_dollar": {
      "type": "number",
      "description": "Optional override of program rate (e.g. 10 = 10 tokens per $1). Defaults to program's points_per_dollar."
    },
    "max_redemption_percent": {
      "type": "number",
      "description": "Max % of any future purchase the customer can pay with these tokens (5–100). Default 50."
    },
    "title": {
      "type": "string",
      "description": "Display title (default: 'Gift Certificate')"
    },
    "description": {
      "type": "string",
      "description": "Optional descriptive text shown to the customer"
    },
    "expires_in_days": {
      "type": "number",
      "description": "Validity period in days (omit for no expiry)"
    },
    "image_url": {
      "type": "string",
      "description": "Optional public image URL for the cert design"
    },
    "quantity": {
      "type": "number",
      "description": "Number of certificates to create as a batch (1–100, default 1)"
    }
  },
  "required": [
    "token_address",
    "usd_amount"
  ]
}

list_gift_certificates

List gift certificates issued by the agent's merchant (with status and redemption info).

Parameters3

token_address	string	optional	Filter by program token address (optional)
status	string	optional	Filter by status: active, pending_mint, redeemed, expired, revoked
limit	number	optional	Max rows (default 50, max 200)

Raw schema

{
  "type": "object",
  "properties": {
    "token_address": {
      "type": "string",
      "description": "Filter by program token address (optional)"
    },
    "status": {
      "type": "string",
      "description": "Filter by status: active, pending_mint, redeemed, expired, revoked"
    },
    "limit": {
      "type": "number",
      "description": "Max rows (default 50, max 200)"
    }
  }
}

revoke_gift_certificate

Revoke an active gift certificate (status active → revoked). Only the issuing merchant can revoke. Already-redeemed/minted certificates cannot be revoked.

Parameters1

certificate_id

string

required

UUID of the certificate from create_gift_certificate / list_gift_certificates

Raw schema

{
  "type": "object",
  "properties": {
    "certificate_id": {
      "type": "string",
      "description": "UUID of the certificate from create_gift_certificate / list_gift_certificates"
    }
  },
  "required": [
    "certificate_id"
  ]
}

mark_gift_certificate_minted

After the merchant submits the on-chain mint transaction for a claimed gift certificate, call this to mark it as minted (status pending_mint → redeemed) and store the mint tx hash.

Parameters2

certificate_id	string	required	UUID of the certificate
transaction_hash	string	required	Base L2 mint transaction hash (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "certificate_id": {
      "type": "string",
      "description": "UUID of the certificate"
    },
    "transaction_hash": {
      "type": "string",
      "description": "Base L2 mint transaction hash (0x...)"
    }
  },
  "required": [
    "certificate_id",
    "transaction_hash"
  ]
}

bazaar_discover_resources

Discover third-party x402-paid resources published in Coinbase CDP's Bazaar (docs, data feeds, AI inference, etc). Read-only. Filter by free-text q and/or network (e.g. 'base').

Parameters4

q	string	optional	Free-text filter matched against the resource JSON (name/description/url)
network	string	optional	Filter by network, e.g. 'base' or 'base-sepolia'
limit	number	optional	Max rows returned (default 25, max 100)
cursor	string	optional	Pagination cursor from a previous call

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Free-text filter matched against the resource JSON (name/description/url)"
    },
    "network": {
      "type": "string",
      "description": "Filter by network, e.g. 'base' or 'base-sepolia'"
    },
    "limit": {
      "type": "number",
      "description": "Max rows returned (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from a previous call"
    }
  }
}

bazaar_discover_mcp_servers

Discover third-party MCP servers published in Coinbase CDP's Bazaar. Read-only. Filter by free-text q and/or network.

Parameters4

q	string	optional	Free-text filter matched against the server JSON
network	string	optional	Filter by network, e.g. 'base'
limit	number	optional	Max rows (default 25, max 100)
cursor	string	optional	Pagination cursor

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Free-text filter matched against the server JSON"
    },
    "network": {
      "type": "string",
      "description": "Filter by network, e.g. 'base'"
    },
    "limit": {
      "type": "number",
      "description": "Max rows (default 25, max 100)"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor"
    }
  }
}

bazaar_probe_x402

GET a candidate x402 URL and, if it responds HTTP 402, return the parsed payment requirements (accepts[]) so the caller can decide whether to pay. HTTPS only. No signing performed.

Parameters1

url

string

required

Full https:// URL of the x402-paid endpoint

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full https:// URL of the x402-paid endpoint"
    }
  },
  "required": [
    "url"
  ]
}

bazaar_pay_and_call

Pay and call any x402-paid HTTPS endpoint using the merchant agent's CDP MPC wallet (EIP-3009 exact scheme on Base USDC). Probes the URL for HTTP 402, picks a compatible requirement, signs TransferWithAuthorization via CDP, retries with X-PAYMENT header, and returns the paid response. Requires scope 'mint' and a pre-created CDP wallet. Safety cap: max_usdc (default 0.25, hard limit 10).

Parameters7

url	string	required	Full https:// URL of the x402 resource
method	string	optional	HTTP method (default GET)
body	any	optional	Optional JSON request body for non-GET methods
headers	object	optional	Extra request headers (Accept/Content-Type auto-set)
max_usdc	number	optional	Spend cap for THIS call in USDC (default 0.25, must be ≤ 10)
allowed_networks	array	optional	Networks to accept (default ['base'])
allowed_schemes	array	optional	x402 schemes to accept (default ['exact'])

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full https:// URL of the x402 resource"
    },
    "method": {
      "type": "string",
      "enum": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "description": "HTTP method (default GET)"
    },
    "body": {
      "description": "Optional JSON request body for non-GET methods"
    },
    "headers": {
      "type": "object",
      "description": "Extra request headers (Accept/Content-Type auto-set)"
    },
    "max_usdc": {
      "type": "number",
      "description": "Spend cap for THIS call in USDC (default 0.25, must be ≤ 10)"
    },
    "allowed_networks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Networks to accept (default ['base'])"
    },
    "allowed_schemes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "x402 schemes to accept (default ['exact'])"
    }
  },
  "required": [
    "url"
  ]
}

README.md30 KBView on GitHub

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).

code

┌─────────────────────────────────────────────────┐
│              Loyal Spark Platform                │
│                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │  Web UI   │    │ REST API │    │MCP Server│   │
│  │ (humans)  │    │ (agents) │    │ (agents) │   │
│  └─────┬─────┘    └─────┬────┘    └─────┬────┘   │
│        │                │               │        │
│        ▼                ▼               ▼        │
│  ┌──────────────────────────────────────────┐    │
│  │        Backend (Edge Functions)           │    │
│  │    Auth · RLS · DB · Realtime             │    │
│  └─────────────────┬────────────────────────┘    │
│                    │                             │
│        ┌───────────┴───────────┐                 │
│        ▼                       ▼                 │
│  ┌──────────┐          ┌──────────────┐          │
│  │ Base L2  │          │ CDP Server   │          │
│  │ Contracts│          │ Wallet (MPC) │          │
│  └──────────┘          └──────────────┘          │
└─────────────────────────────────────────────────┘

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) and roundup/ (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–15 under /.well-known/skills/) for agent onboarding, B20 semantics, and payment rails

Technology Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui (Radix)
Animations	Framer Motion
Blockchain	Wagmi v2, Viem, RainbowKit, Privy (`@privy-io/react-auth` + `@privy-io/wagmi`)
Network	Base Mainnet (Chain ID: 8453)
Smart Contracts	Base-native B20 Asset precompile + legacy ERC-20 factory
Backend	Supabase (PostgreSQL, RLS, Deno Edge Functions, Realtime)
Native apps	Capacitor 8 (iOS / Android) — see `docs/development/NATIVE_BUILD_GUIDE.md`
Agent Wallets	Coinbase CDP MPC (Server Wallets)
State	TanStack Query v5
Routing	React Router DOM v6
Forms	React Hook Form + Zod validation
Builder Attribution	Base Builder Code (ERC-8021)

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.

Role	Address	When
B20 Factory (Base precompile)	`0xB20f000000000000000000000000000000000000`	Default — `createB20` → token `0xB200…`
LoyaltyTokenFactory (legacy)	`0x5F3DdBa12580CFdc6016258774cCc19C4250dA80`	Opt-in `erc20` — `createLoyaltyToken` + activation
LoyalSparkERC20 (implementation)	`0xe6BA426C9c51281B929a17444De02c65815E27C3`	Logic for legacy proxy tokens
LoyaltyTokenEscrow (P2P)	`0xA569C95AfC1BCF381c48BcF336ED9D2c014bcdDF`	Marketplace swaps

Network: Base Mainnet (Chain ID: 8453)

Program creation (summary)

Path	Deploy	Activate	Portal
B20 (default)	1× `createB20` on `0xB20f…`	Not required	Yes
Legacy ERC-20	1× `createLoyaltyToken` on `0x5F3DdB…`	`unpauseUtility` + `enableMinting`	API only

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 wallets
balanceOf(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-key header 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.

Folder	Purpose
`scripts/x402-paid-mcp-test/`	Smoke test: paid MCP via x402 (USDC on Base, `@x402/fetch`).
`scripts/x402-paid-agent-api/`	Same stack, paid agent-api routes (`GET/POST` to `x402-gateway/<resource>`).
`scripts/traffic-bot-x402-bridge.py`	Example Python → Node subprocess hook for bots that already send loyalty txs on Base.
`scripts/agent-register-siwe/`	Helper: build SIWE message + sign + call `agent-register-siwe` (same as production).

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

bash

# List loyalty programs
curl -H "x-api-key: lsk_YOUR_KEY" \
  https://api.loyalspark.online/agent-api/programs

# Mint tokens — returns a fee-first calls[] bundle (1.25% fee on Free plan,
# minted in your own loyalty tokens); settle it via POST /agent-api/mint/confirm
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://api.loyalspark.online/agent-api/mint

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).

Method	Path	Scope	Description
GET	`/me`	authenticated	Agent profile & permissions
GET	`/workflow/program-status`	read	Autonomous planner: lifecycle step + `next_actions[]`
GET	`/programs`	read	List loyalty programs
POST	`/workflow/generate-program-defaults`	read, mint, or `create_program`	Propose program name, symbol, economics, and starter rewards from business context
POST	`/programs`	mint or `create_program`	Calldata to deploy loyalty token (B20 default, or legacy ERC-20 with `token_standard: "erc20"`)
POST	`/register-program`	mint or `create_program`	Register deployed token (optional `cashback_rate`, `points_per_dollar`)
POST	`/update-program-config`	mint or `create_program`	Update `cashback_rate` / `points_per_dollar` for a program
POST	`/activate-program`	mint or `create_program`	Legacy ERC-20 activation only (no-op for B20)
POST	`/program-status`	mint or `create_program`	Update program status
GET	`/rewards`	read	List rewards
POST	`/rewards`	manage_rewards	Create reward
POST	`/mint`	mint	Fee-first mint `calls[]` + `fee_obligation_id`
POST	`/mint/confirm`	mint	Settle protocol fee after mint/earn (obligation_id + fee_tx_hash)
POST	`/earn`	mint	Cashback: mint from purchase amount × rate (same fee-first + confirm)
POST	`/transfer`	mint	Transfer tokens
GET	`/balance`	read	Token balance & tier
GET	`/customers`	read	Customer list
GET	`/vouchers`	read	List vouchers
GET	`/vouchers/status`	public	Check voucher status (no API key)
POST	`/redeem-reward`	read	Redeem reward → create voucher
POST	`/vouchers/use`	manage_rewards	Mark voucher as used
GET	`/analytics`	read	Program analytics
GET	`/offers`	read	Marketplace offers
POST	`/offers`	trade	Create P2P offer
POST	`/accept-offer`	trade	Accept P2P offer
POST	`/cancel-offer`	trade	Cancel P2P offer
GET	`/tx-receipt`	authenticated	Extract token_address from deploy tx
GET	`/merchant-profile`	read	Read merchant profile
POST	`/merchant-profile`	manage_rewards	Create or update merchant profile (`PUT` also accepted)

MCP Server (for LLMs)

Connect Claude, GPT, or any MCP-compatible agent:

json

{
  "mcpServers": {
    "loyal-spark": {
      "url": "https://api.loyalspark.online/loyalty-mcp",
      "headers": {
        "x-api-key": "lsk_YOUR_KEY"
      }
    }
  }
}

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_).

bash

# Prepare a mint (returns { transactions: [{to,data,value}], … } for send_calls)
curl -H "x-api-key: lsk_YOUR_KEY" \
  "https://api.loyalspark.online/agent-prepare/mint?token=0xTOKEN&to=0xCUSTOMER&amount=100"

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.

Piece	URL / path
REST	`https://api.loyalspark.online/recipient-api`
MCP	`https://api.loyalspark.online/recipient-loyalty-mcp`
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.

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:

#	Skill	Description
00	Getting Started	Register agent (merchant UI or SIWE), get `lsk_`, first request
01	Create Loyalty Program	Deploy B20 loyalty token on Base (legacy ERC-20 optional)
02	Mint Tokens	Mint tokens to customer wallets
03	Transfer Tokens	Transfer tokens between wallets
04	Manage Rewards	Create redeemable rewards catalog
05	Balance & Tiers	Check balances and tier status
06	Marketplace Trading	P2P token trading with atomic escrow
07	Analytics & CRM	Program analytics and CRM data
08	Referrals	Referral programs for organic growth
09	Vouchers	Voucher lifecycle management
10	Server Wallets	CDP MPC wallets for autonomous transactions
11	Earn Points (Cashback)	Mint from purchase amount × cashback rate
12	Gift Certificates	Issue, claim, and mint `LOYAL-XXXXXX` certificates
13	Endpoint Workflows	Multi-step REST/MCP flows and prerequisites
14	B20 Native Spec	Base Beryl B20 Asset semantics for loyalty tokens
15	Payment Scenarios	x402 exact, MPP, subscriptions, spend policies

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:

bash

curl -X POST \
  -H "x-api-key: lsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"create_wallet"}' \
  https://api.loyalspark.online/agent-wallet

Benefits:

No private key management — keys are in Coinbase's secure enclave
Server-side transaction signing
Automatic Builder Code attribution (ERC-8021)

Pricing

Plan	Monthly	API Calls	Agents	Mint fee	Mint cap
Free	$0	200	1	1.25%	1,000 tokens/mo
Pro	$49 USDC	10,000	5	0.5%	Unlimited
Enterprise	$129 USDC	Unlimited	Unlimited	0.25%	Unlimited

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

bash

git clone https://github.com/aspekt19/unboxed-loyalty-spark.git
cd unboxed-loyalty-spark
npm install
npm run dev

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

code

unboxed-loyalty-spark/
├── AGENTS.md                      # Entry map for AI / coding agents
├── docs/                          # Human docs (guides, integrations, pitch notes)
│   ├── development/               # Build & deploy
│   ├── integrations/              # Farcaster, OpenServ, A2A, prompts
│   ├── pitch-deck/                # Investor deck (Markdown sources)
│   └── supabase/                  # DB/edge runbooks
├── src/
│   ├── components/
│   │   ├── ui/                    # shadcn/ui library
│   │   ├── agents/                # AI agent management
│   │   ├── rewards/               # Rewards & vouchers
│   │   ├── crm/                   # CRM & analytics
│   │   ├── marketing/             # Campaigns
│   │   ├── automation/            # Marketing automation
│   │   ├── tiers/                 # Customer tiers
│   │   ├── referral/              # Referral programs
│   │   ├── roundup/               # DeFi investment (frozen)
│   │   ├── marketplace/           # Token trading (frozen)
│   │   ├── reviews/               # Customer reviews
│   │   ├── onboarding/            # Welcome flows & tours
│   │   ├── merchant/              # Merchant shell & tabs (Team, Programs, …)
│   │   ├── team/                  # Branches, employees, invite redemption
│   │   └── admin/                 # Platform administration
│   ├── hooks/                     # Data fetching (TanStack Query + Supabase) — keep queries here
│   ├── config/                    # Contract addresses & ABIs
│   ├── contexts/                  # Auth context
│   ├── integrations/supabase/     # Database client & types
│   ├── pages/                     # Routes (e.g. ForAgentsPage → /for-agents, ApiDocsPage → /api-docs)
│   └── lib/                       # Utilities
├── examples/agent-mcp/            # Copy-paste MCP + curl for agents
├── scripts/                       # Optional dev helpers (x402 MCP smoke test, SIWE lsk_ helper) — not bundled in the web app
├── public/
│   ├── .well-known/
│   │   ├── agent.json             # AI agent discovery
│   │   ├── skills/                # Markdown skills for agents (00–12)
│   │   └── farcaster.json         # Farcaster manifest
│   ├── openapi.json               # OpenAPI 3.1 (API + x402 hints)
│   ├── llms.txt / llms-full.txt   # Short / long summaries for LLM crawlers
│   └── media-kit/                 # Brand & press assets
├── capacitor.config.ts            # Native app IDs (see docs/development/)
├── contracts/                     # Solidity contracts
├── supabase/
│   ├── functions/                 # Edge Functions — see supabase/functions/README.md
│   └── migrations/                # Database migrations
└── README.md

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

Resource	URL	Purpose
Agent onboarding (web)	/for-agents	Keys, REST, MCP, gateways, discovery — one page for builders
Agent Manifest	/.well-known/agent.json	Full protocol spec, capabilities, pricing
MPP Manifest	/.well-known/mpp.json	Machine Payment Protocol manifest
OpenAPI Spec	/openapi.json	OpenAPI 3.1.0 with x-payment-info
Skills Library	/.well-known/skills/	16 step-by-step guides for agents (`00`–`15`)
LLMs.txt	/llms.txt	Protocol summary for LLM crawlers
Prompt Guide	PROMPT_GUIDE.md	Ready-to-use system prompts
Copy-paste MCP / curl	examples/agent-mcp/	Starter configs in the repo
Repo quickstart (keys, SIWE, x402)	docs/agents/QUICKSTART.md	Short paths for coding agents

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.

Protocol	Network	Asset	Gateway
x402 exact	Base	USDC	`https://api.loyalspark.online/x402-gateway`
MPP	Tempo	pathUSD / USDC	`https://api.loyalspark.online/mpp-gateway`

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 root server.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: admin@loyalspark.online

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.

Install

Tools (39)

get_platform_infoget_my_profilegenerate_program_defaultsget_program_workflow_statuslist_loyalty_programscreate_loyalty_programregister_loyalty_programactivate_loyalty_program

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.loyalspark.online/loyalty-mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "loyal-spark": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.loyalspark.online/loyalty-mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.aspekt19/loyal-spark MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

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

send_report

list_my_reports

update_report_status

delete_report

export_customers

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

Loyal Spark — Onchain Loyalty Protocol

Overview

Features

For Merchants (Web UI)

For Customers (Web UI)

For AI Agents (REST API + MCP)

Technology Stack

Smart Contract Architecture

Program creation (summary)

Token operations (both standards)

AI Agent Integration

Quick Start

Optional repo scripts (development / agent onboarding)

REST API

API Endpoints (28 authenticated + 1 public)

MCP Server (for LLMs)

Base MCP custom plugin (send_calls-ready calldata)

Recipient agents (wallet holders, rwk_)

Agent Discovery

Skills for AI Agents

Server Wallets (CDP MPC)

Pricing

Getting Started

Prerequisites

Installation

Sign In Options

Project Structure

Edge Functions

Security

Builder Code

For AI Agents

Discovery Endpoints

Payment Gateways (pay per call — no subscription)

Catalogues & Registries

Links & Resources

Built With

Base MCP custom plugin (`send_calls`-ready calldata)

Recipient agents (wallet holders, `rwk_`)