Loyal Spark
Loyalty-as-a-service on Base. Agents create B20 loyalty programs, mint points, run rewards and vouchers, and trade on a P2P market via REST or MCP; pay per call in USDC (x402).
Máy chủ MCP được lưu trữ
npx add-mcp 'https://api.loyalspark.online/loyalty-mcp'Cài vào Claude Code, Codex, Cursor và nhiều công cụ khác
Tài liệu
GuideGuide PricingPricing For AgentsFor Agents API DocsAPI Docs Install appInstall app PitchPitch
For AI agents
Loyalty points, rewards & vouchers API on Base (REST + MCP, USDC via x402)
89 paid tools · from $0.001 USDC · x402 + MPP · Base mainnet
Loyalty points, rewards & vouchers API for AI agents
Launch loyalty programs, issue points, create rewards and redeem vouchers on Base — over REST or MCP. Pay per call in USDC via x402 (or MPP). No signup: read tools work with payment alone; a $0.01 call to POST /x402-gateway/register-agent gives a merchant key (lsk_) for writes. Wallets that hold points use a recipient key (rwk_).
New programs deploy as Base-native B20 Asset programs by default (one factory-precompile tx, active after register). The signer pays Base gas in ETH: fund the signing wallet with about 0.00001 ETH on Base first (covers a deploy plus a few mints; USDC alone cannot pay gas). This API does not sponsor agent or CDP server wallets. The mint protocol fee is loyalty tokens of that program (Free / Pay-per-call 1.25%, Pro 0.5%, Enterprise 0.25%), not USDC. Legacy ERC-20 factory remains available via token_standard: "erc20".
API reference OpenAPI agent.json
Start here
- 1.Start with no key. Voucher lookup is free:
GET /agent-api/vouchers/status?code=LOYAL-…(30 req/min per network without a key). Every tool marked pay only in the price list works with payment alone — the paying wallet is the caller. Writes (mint, deploy, create rewards, trade) need your key together with the payment; without the key you are not charged. - 2.Get the key that matches the job. External agents without a subscription pay $0.01 at
POST /x402-gateway/register-agentto get a full 5-scopelsk_key on the Free plan (1 agent, 200 calls/mo, 1,000 tokens/mo, 1.25% mint fee). Wallets with a Merchant Store Plan (Starter/Growth/Scale) or a paid Pro or Enterprise Agent Plan can register via the dashboard loyalspark.online/merchant or SIWE below and operate strictly within their plan's scope and call limits. Wallets that hold points needrwk_— SIWE +recipient-api/register, also below. - 3.Read the two required docs: getting started (keys, plans, auth) and endpoint workflows (why one endpoint is rarely one task).
- 4.Smoke test REST:
curl -H "x-api-key: $KEY" https://api.loyalspark.online/agent-api/programs— or the publicGET /vouchers/status?code=LOYAL-…with no key. - 5.Connect MCP (config snippets below) or pay per call via
x402/MPP— price list below. On paid calls, payment alone is enough for recipient-api, merchant GET reads, merchant read MCP tools, and holder MCP tools. Send the key together with the payment only for writes (mint, deploy, create rewards, trade, bazaar). - 6.Then orchestrate. For multi-step actions (create program → deploy → register → create reward → mint) follow llms-full.txt and the skills index at /.well-known/skills/.
REST
38 authenticated routes + public GET /vouchers/status and GET /platform
Base URL (append path):
https://api.loyalspark.online/agent-api
MCP
Streamable HTTP · JSON-RPC 2.0
Server URL:
https://api.loyalspark.online/loyalty-mcp
Pay per call
x402 exact (USDC Base) · MPP (Tempo)
x402: https://api.loyalspark.online/x402-gateway
MPP: https://api.loyalspark.online/mpp-gateway
Already used by AI agents
Loyal Spark is live in agent marketplaces — autonomous agents discover and pay for our REST and MCP resources per call in USDC on Base. Verify live call/payer activity on agentic.market, onchain USDC settlements on Basescan, and the paid server listing on x402scan. Crawler map: index.txt.
Agent plans & limits
Limits apply per owner wallet and reset on the 1st of each month (UTC). External agents without a store or paid plan can unlock the Free plan for $0.01 via x402, subscribe to Pro/Enterprise in USDC, or pay per call on x402.
Free
$0.01 x402
- 1 agent (all 5 scopes)
- 200 API calls / month
- 1,000 mint tokens / month
- Mint fee 1.25%
Pro
$49/mo
- Up to 5 agents
- 10,000 API calls / month
- Unlimited minting
- Mint fee 0.50%
Enterprise
$129/mo
- Unlimited agents
- Unlimited API calls
- Unlimited minting
- Mint fee 0.25%
Ready to subscribe?
Pay in USDC on Base from your wallet — no manual transfer, activation is automatic.
- Step 1. Connect the owner wallet of your agents on Base.
- Step 2. Choose Pro or Enterprise and monthly or annual billing.
- Step 3. Confirm one USDC transaction — limits unlock automatically.
Annual billing: 15% off Pro, 20% off Enterprise. Payment in USDC on Base. Details: loyalspark.online/pricing.
Three steps
1
Merchant
Pay $0.01 USDC at POST /x402-gateway/register-agent, or sign in at loyalspark.online/merchant and open the AI Agents tab.
2
Key
Register an agent and store the lsk_... key in your runtime or MCP headers.
3
Call
Hit /programs or plug MCP into Cursor / Claude — use Skills for guided flows.
Autonomous merchant key (lsk_ via x402)
No dashboard. Pay $0.01 USDC on Base. Wallets without a store or paid agent plan receive a full 5-scope lsk_ key on the Free plan (1 agent, 200 calls/mo, 1,000 tokens/mo, 1.25% mint fee). Wallets with an existing Store or Agent plan receive a key scoped to that plan.
Free-plan key (lsk_ with all 5 scopes, 200 calls/mo, 1,000 tokens/mo, 1.25% mint fee) — pay $0.01 USDC on Base. No browser and no API key on this call.
1) POST https://api.loyalspark.online/x402-gateway/register-agent
First response is HTTP 402. Pay that exact USDC amount on Base. Do not send x-api-key.
Optional body: {"name":"My agent"}
2) If the payer wallet has no Merchant Store Plan or Pro/Enterprise Agent Plan, it owns a new lsk_ key on the Free plan (shown once):
- 1 agent seat
- 200 API calls / month (across direct /agent-api, /loyalty-mcp, and /x402-gateway calls)
- 1,000 mint tokens / month & 1.25% mint fee (in loyalty tokens)
- All 5 scopes: read, create_program, mint, trade, manage_rewards
If the wallet belongs to a merchant on a Store Plan (Starter/Growth/Scale) or a Paid Agent Plan (Pro/Enterprise), the key operates strictly within that plan's scope and call limits.
Look first, still with no key: GET https://api.loyalspark.online/x402-gateway/public-programs is $0.001 and lists active programs. That list is not your own programs.
Autonomous merchant key (lsk_ via SIWE)
No merchant dashboard: prove wallet ownership with a signed message (Base mainnet). Issued when the wallet has a Merchant Store Plan, a paid Pro or Enterprise Agent Plan, or is rotating an existing Free-plan key. Otherwise the response is HTTP 402 and next_action pay_x402 ($0.01 at POST /x402-gateway/register-agent).
SIWE registration (lsk_ scoped to your plan) — no web login. The wallet needs a Merchant Store Plan (Starter/Growth/Scale), a paid Pro or Enterprise Agent Plan, or an existing Free-plan key to rotate (otherwise returns HTTP 402 payment_required — pay $0.01 at POST /x402-gateway/register-agent first). Any write scope also includes read.
1) Nonce:
curl -sS -X POST "https://api.loyalspark.online/siwe-nonce"
2) Sign this EIP-4361 message (replace address, nonce, Issued At). Domain loyalspark.online, URI https://loyalspark.online, Chain ID 8453. localhost and 127.0.0.1 are also accepted when the URI hostname matches; other domains, including other *.lovable.app sites, are rejected.
loyalspark.online wants you to sign in with your Ethereum account:
0xYourWalletAddress
Register Loyal Spark merchant agent
URI: https://loyalspark.online
Version: 1
Chain ID: 8453
Nonce: YOUR_NONCE
Issued At: 2026-10-21T18:00:00.000Z
3) One-time lsk_ key:
curl -sS -X POST "https://api.loyalspark.online/agent-register-siwe" \
-H "Content-Type: application/json" \
-d '{"message":"<full SIWE message>","signature":"0x...","name":"My agent","scopes":["mint","create_program"]}'
A missing scope returns required_scope and how_to_get_scope. Docs: https://loyalspark.online/.well-known/skills/00-getting-started.md
First REST call
curl -sS -H "x-api-key: lsk_YOUR_API_KEY" \
"https://api.loyalspark.online/agent-api/programs"
Cursor / VS Code MCP
Merge into .cursor/mcp.json — use rwk_ with the recipient server URL for holder agents.
{
"mcpServers": {
"loyal-spark": {
"url": "https://api.loyalspark.online/loyalty-mcp",
"headers": {
"x-api-key": "lsk_YOUR_API_KEY"
}
}
}
}
Recipient AI agents (rwk_)
For autonomous wallets that receive loyalty tokens (e.g. another agent thanked on-chain). Keys are created with a SIWE signature from that wallet — no merchant dashboard. REST base: https://api.loyalspark.online/recipient-api
Recipient keys (rwk_) are for wallets that receive loyalty points — not merchants.
1) Nonce (same as web SIWE):
curl -sS -X POST "https://api.loyalspark.online/siwe-nonce"
2) Build a standards-compliant EIP-4361 SIWE message including that nonce for the recipient wallet (no special statement phrase; Chain ID 8453); sign with that wallet.
3) One-time key:
curl -sS -X POST "https://api.loyalspark.online/recipient-api/register" \
-H "Content-Type: application/json" \
-d '{"message":"<SIWE message>","signature":"0x...","name":"optional label"}'
4) Call APIs with header: x-api-key: rwk_...
5) Send loyalty tokens to any address (holder-signed transfer calldata; program must be active):
curl -sS -X POST "https://api.loyalspark.online/recipient-api/prepare-transfer" \
-H "Content-Type: application/json" \
-H "x-api-key: rwk_YOUR_RECIPIENT_KEY" \
-d '{"token_address":"0x...","to":"0x...","amount":10.5}'
MCP: prepare_loyalty_token_transfer
Then: GET /balances, GET /rewards?token_address=..., POST /redeem-reward with reward_id + transfer tx hash.
Recipient MCP (20 tools)
URL: https://api.loyalspark.online/recipient-loyalty-mcp
{
"mcpServers": {
"loyal-spark-recipient": {
"url": "https://api.loyalspark.online/recipient-loyalty-mcp",
"headers": {
"x-api-key": "rwk_YOUR_RECIPIENT_KEY"
}
}
}
}
get_recipient_profile``list_my_loyalty_balances``get_my_loyalty_balance``prepare_loyalty_token_transfer``list_rewards_for_program``get_reward_workflow_status``prepare_reward_redemption``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
Source: src/constants/recipientMcpToolNames.ts · server recipient-loyalty-mcp/index.ts
89 paid resources
x402 · USDC on Base
MPP · same prices
Price list — same as the Bazaar and x402scan catalogs
Every paid route and MCP tool, exactly as listed at api.loyalspark.online/.well-known/x402. "Pay only" = payment alone works, no API key. "Pay + key" = send your lsk_/rwk_ key with the payment; without it you are not charged. Free: GET /me, GET /vouchers/status, GET /tx-receipt.
Merchant REST — 29 api.loyalspark.online/x402-gateway<route>
| Method | Route | What it does | Auth | USD |
|---|---|---|---|---|
| GET | /analytics | Fetch merchant loyalty program analytics, mint/redeem volume, and holder metrics. | pay only | $0.005 |
| GET | /balance | Read B20/ERC-20 loyalty token balance for a wallet address on Base. | pay only | $0.001 |
| GET | /customers | List a merchant's loyalty program customers with token balances, tiers, and rewards activity. | pay only | $0.002 |
| GET | /merchant-profile | Get merchant profile, brand settings, and loyalty configuration. | pay only | $0.001 |
| GET | /offers | List active P2P marketplace offers for loyalty token swaps on Base. | pay only | $0.001 |
| GET | /programs | List the merchant wallet's B20 loyalty programs on Base. | pay only | $0.001 |
| GET | /public-programs | Returns active public programs, not the caller's own. | pay only | $0.001 |
| GET | /resolve-recipient | Resolve a customer email, wallet, or @username to a Base wallet. | pay only | $0.001 |
| GET | /rewards | List redeemable rewards configured for a loyalty program. | pay only | $0.001 |
| GET | /vouchers | List issued reward vouchers and redemption status for a program. | pay only | $0.001 |
| GET | /workflow/program-status | Check a loyalty program's setup and rewards workflow status: deploy, register, activate, rewards. | pay only | $0.001 |
| POST | /accept-offer | Accept an open P2P loyalty token swap offer on Base. | pay + key | $0.01 |
| POST | /activate-program | Activate or pause a loyalty program on Base. | pay + key | $0.01 |
| POST | /cancel-offer | Cancel an open P2P loyalty token swap offer and release escrowed tokens. | pay + key | $0.005 |
| POST | /earn | Award loyalty tokens to a customer based on purchase amount and program earn rate. | pay + key | $0.01 |
| POST | /merchant-profile | Create or replace the merchant profile and brand settings for loyalty rewards. | pay + key | $0.005 |
| POST | /mint | Mint B20/ERC-20 loyalty tokens on Base to a customer wallet or email. | pay + key | $0.01 |
| POST | /offers | Create a P2P escrow marketplace offer to swap loyalty tokens on Base. | pay + key | $0.01 |
| POST | /program-status | Update or synchronize a loyalty program's operational status. | pay + key | $0.005 |
| POST | /programs | Create and deploy a new B20 loyalty token program on Base (legacy ERC-20 optional). | pay + key | $0.01 |
| POST | /redeem-reward | Redeem loyalty tokens for a reward and issue a redemption voucher. | pay + key | $0.01 |
| POST | /register-agent | Start here: get a loyalty & rewards API key. | pay only | $0.01 |
| POST | /register-program | Register an already-deployed onchain B20 loyalty token contract in Loyal Spark. | pay + key | $0.01 |
| POST | /rewards | Create a new redeemable reward in a merchant loyalty program. | pay + key | $0.01 |
| POST | /transfer | Transfer loyalty tokens between wallets on Base. | pay + key | $0.005 |
| POST | /update-program-config | Update loyalty program metadata, reward rules, or tier thresholds. | pay + key | $0.005 |
| POST | /vouchers/use | Mark a customer reward voucher code as used at checkout. | pay + key | $0.005 |
| POST | /workflow/generate-program-defaults | Generate recommended loyalty token economics, tiers, and reward defaults for a business. | pay + key | $0.001 |
| PUT | /merchant-profile | Update the merchant profile and brand settings for loyalty rewards. | pay + key | $0.005 |
Recipient REST — 12 api.loyalspark.online/x402-gateway/recipient-api<route>
| Method | Route | What it does | Auth | USD |
|---|---|---|---|---|
| GET | /balance | Get a recipient wallet's balance for a specific loyalty token on Base. | pay only | $0.001 |
| GET | /balances | List all loyalty token balances held by a customer/recipient wallet on Base. | pay only | $0.001 |
| GET | /offers | Browse open P2P marketplace offers to buy or swap loyalty tokens on Base. | pay only | $0.001 |
| GET | /rewards | Browse available loyalty rewards that a customer can redeem with tokens. | pay only | $0.001 |
| GET | /vouchers | List a customer's redeemed reward vouchers and voucher codes. | pay only | $0.001 |
| GET | /workflow/reward-status | Check whether a customer has enough tokens and eligibility to redeem a reward. | pay only | $0.001 |
| POST | /accept-offer | Accept an open P2P loyalty token swap offer as a recipient. | pay only | $0.01 |
| POST | /cancel-offer | Cancel a recipient's open P2P loyalty token swap offer. | pay only | $0.005 |
| POST | /offers | Create a recipient P2P escrow offer to swap loyalty tokens on Base. | pay only | $0.01 |
| POST | /prepare-transfer | Prepare an unsigned B20/ERC-20 loyalty token transfer transaction on Base. | pay only | $0.005 |
| POST | /redeem-reward | Redeem customer loyalty tokens for a reward voucher. | pay only | $0.01 |
| POST | /workflow/prepare-reward-redemption | Prepare the token approval and redemption steps for a customer reward. | pay only | $0.005 |
Merchant MCP tools — 32 api.loyalspark.online/x402-gateway/mcp-tools/<tool>
| Tool | What it does | Auth | USD |
|---|---|---|---|
| activate_loyalty_program | Build activation calldata for an inactive loyalty program (on-chain activate + DB status). | pay + key | $0.01 |
| check_voucher_status | Look up voucher status (active, used, expired) by human-readable code or internal id. | pay only | $0.001 |
| create_gift_certificate | Issue gift or welcome certificates (LOYAL-XXXXXX); single code or batch up to 100 per call. | pay + key | $0.01 |
| create_loyalty_program | Build factory calldata to deploy a new B20 loyalty token on Base. | pay + key | $0.01 |
| create_personalized_offer | Create a targeted retention P2P or bonus offer for a specific customer wallet. | pay + key | $0.01 |
| create_reward | Create a new redeemable reward (customer pays token cost on-chain, then redeems for a voucher). | pay + key | $0.01 |
| delete_report | Permanently delete an agent report from the merchant dashboard. | pay + key | $0.01 |
| earn_points | Calculate and mint loyalty tokens from a purchase amount using the program cashback rate (earn / cashback flow). | pay + key | $0.01 |
| export_customers | Export customer list with balances and tiers for a loyalty program (CSV-ready JSON). | pay only | $0.002 |
| generate_program_defaults | Autonomous planner: propose program name, token symbol, cashback economics, and starter rewards from merchant business context. | pay only | $0.001 |
| get_my_profile | Authenticated merchant agent profile. | pay only | $0.001 |
| get_platform_info | Loyal Spark protocol metadata on Base L2. | pay only | $0.001 |
| get_program_analytics | Aggregate program analytics: holders, mint volume, redemptions, and tier distribution for a merchant. | pay only | $0.005 |
| get_program_workflow_status | Autonomous status planner: returns the current merchant program lifecycle step and the machine-readable next_actions[]. | pay only | $0.001 |
| get_token_balance | Read a customer's loyalty token balance and tier level for a specific program. | pay only | $0.001 |
| list_gift_certificates | List gift certificates issued by the authenticated merchant with optional status filter. | pay only | $0.01 |
| list_loyalty_programs | List B20/ERC-20 loyalty programs owned by the authenticated merchant; optionally include expired programs. | pay only | $0.001 |
| list_marketplace_offers | List open P2P token-swap offers for a loyalty program (peer-to-peer marketplace). | pay only | $0.001 |
| list_my_reports | List AI agent reports previously submitted by this merchant agent. | pay + key | $0.01 |
| list_rewards | List redeemable rewards configured for a loyalty program (name, cost in tokens, active flag). | pay only | $0.001 |
| mark_gift_certificate_minted | Finalize a claimed certificate after on-chain mint (pending_mint -> redeemed); requires mint tx hash. | pay + key | $0.01 |
| mint_loyalty_tokens | Fee-first mint calls[] (protocol fee first, then recipient) + fee_obligation_id. | pay + key | $0.01 |
| redeem_reward | Redeem a reward for an active voucher after the customer paid the token cost on-chain (requires transfer tx hash). | pay + key | $0.01 |
| register_loyalty_program | Register an already-deployed loyalty token in Loyal Spark (links on-chain contract to merchant dashboard). | pay + key | $0.01 |
| revoke_gift_certificate | Revoke an active gift certificate so it can no longer be claimed (active -> revoked). | pay + key | $0.01 |
| send_report | Submit a structured AI agent report to the merchant dashboard (insights, alerts, action items). | pay + key | $0.01 |
| transfer_loyalty_tokens | Build B20/ERC-20 transfer calldata to send loyalty tokens from the merchant or agent wallet to any address. | pay + key | $0.005 |
| update_program_config | Update program economics: cashback rate, points per dollar, and related merchant settings. | pay + key | $0.005 |
| update_program_status | Update loyalty program status in the database (active, paused, expired, cancelled). | pay + key | $0.005 |
| update_report_status | Update merchant workflow status on an agent report (open, in_progress, resolved). | pay + key | $0.01 |
| update_reward_status | Activate or deactivate a reward without deleting it (controls visibility in customer apps). | pay + key | $0.01 |
| use_voucher | Mark an active voucher as used at checkout (merchant scans code or voucher id). | pay + key | $0.005 |
Recipient MCP tools — 16 api.loyalspark.online/x402-gateway/recipient-mcp-tools/<tool>
| Tool | What it does | Auth | USD |
|---|---|---|---|
| accept_p2p_offer | Accept another holder's P2P offer and record the match in Loyal Spark. | pay only | $0.01 |
| cancel_p2p_offer | Cancel a P2P offer you created before it is accepted. | pay only | $0.005 |
| claim_gift_certificate | Claim an active gift certificate; binds it to your wallet (status active -> pending_mint). | pay only | $0.01 |
| create_p2p_offer | Create a P2P swap intent: offer loyalty tokens in exchange for another B20/ERC-20 token amount. | pay only | $0.01 |
| get_my_loyalty_balance | Balance and tier for one loyalty program token held by the authenticated recipient wallet. | pay only | $0.001 |
| get_recipient_profile | Recipient agent profile bound to rwk_ API key: wallet address, key scopes, and registration metadata. | pay + key | $0.001 |
| get_reward_workflow_status | Autonomous status planner for recipients. | pay only | $0.001 |
| list_my_gift_certificates | List gift certificates claimed by your wallet with optional status filter. | pay only | $0.01 |
| list_my_loyalty_balances | All loyalty token balances and tier levels for the holder wallet linked to this rwk_ key. | pay only | $0.001 |
| list_my_vouchers | List vouchers issued to your wallet (active, used, expired) across enrolled loyalty programs. | pay only | $0.001 |
| list_p2p_offers | List open peer-to-peer token swap offers; optional filter by loyalty token (same price band as merchant GET /offers). | pay only | $0.001 |
| list_rewards_for_program | List active rewards you can redeem for a program where your wallet has loyalty activity or balance. | pay only | $0.001 |
| lookup_gift_certificate | Preview a gift certificate by LOYAL-XXXXXX code without claiming (face value, expiry, program). | pay only | $0.01 |
| prepare_loyalty_token_transfer | Build B20/ERC-20 transfer calldata for the holder wallet to send loyalty tokens to any address (submit tx locally). | pay only | $0.005 |
| prepare_reward_redemption | One-shot planner: returns B20/ERC-20 transfer calldata for the reward token cost plus the recipient_reward workflow. | pay only | $0.005 |
| redeem_my_reward | Redeem a reward into an active voucher after paying the token cost on-chain (requires transfer tx hash). | pay only | $0.01 |
Skills (Markdown)
Sixteen step-by-step guides (00–15) live under /.well-known/skills/.
Store earn webhook
Any store can add points without gas. POST the order to /earn-webhook/{merchant id or wallet} with headers X-LoyalSpark-Timestamp (unix seconds) and X-LoyalSpark-Signature (hex HMAC-SHA256 of timestamp, a dot, and the raw body; 5-minute window). Points = amount × program percent × 20. The same order id is ignored. refunded: true claws the points back. The merchant creates the secret in the portal. It is shown once.
TS=$(date +%s)
BODY='{"order_id":"1001","amount":57.90,"currency":"USD","email":"ada@shop.test"}'
SIG=$(printf '%s' "${TS}.${BODY}" | openssl dgst -sha256 -hmac "YOUR_SECRET" | awk '{print $2}')
curl -X POST "https://api.loyalspark.online/earn-webhook/MERCHANT_ID" \
-H "Content-Type: application/json" \
-H "X-LoyalSpark-Timestamp: $TS" \
-H "X-LoyalSpark-Signature: $SIG" \
-d "$BODY"
MCP tool ids (44)
Source of truth: src/constants/mcpToolNames.ts (sync with 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``list_mints``list_fee_obligations``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``list_store_discount_codes``update_store_discount_code``set_store_sales_channel``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
P2P offers for recipients (rwk_)
Holder wallets can browse open swap offers, post their own (creator = caller's wallet), accept somebody else's, or cancel their own active offer. The API only records intent and returns escrow contract hints — the actual on-chain step (token approve + escrow create/accept/cancel) is performed by the wallet, exactly like the merchant agent-api.
P2P offers — recipient wallets swap loyalty tokens with each other.
The API records intent and returns escrow contract hints. The actual on-chain
swap (token approve + escrow create/accept/cancel) is performed separately
by the wallet — same pattern as the merchant agent-api.
# List open offers (optionally filter by token)
curl -sS "https://api.loyalspark.online/recipient-api/offers" \
-H "x-api-key: rwk_YOUR_RECIPIENT_KEY"
# Create an offer (your wallet = creator)
curl -sS -X POST "https://api.loyalspark.online/recipient-api/offers" \
-H "Content-Type: application/json" \
-H "x-api-key: rwk_YOUR_RECIPIENT_KEY" \
-d '{"offer_token_address":"0x...","offer_amount":"100","request_token_address":"0x...","request_amount":"50"}'
# Accept someone else's offer
curl -sS -X POST "https://api.loyalspark.online/recipient-api/accept-offer" \
-H "Content-Type: application/json" \
-H "x-api-key: rwk_YOUR_RECIPIENT_KEY" \
-d '{"offer_id":"<uuid>","transaction_hash":"0x..."}'
# Cancel your own active offer
curl -sS -X POST "https://api.loyalspark.online/recipient-api/cancel-offer" \
-H "Content-Type: application/json" \
-H "x-api-key: rwk_YOUR_RECIPIENT_KEY" \
-d '{"offer_id":"<uuid>"}'
MCP equivalents: list_p2p_offers · create_p2p_offer · accept_p2p_offer · cancel_p2p_offer
REST: https://api.loyalspark.online/recipient-api/offers · /accept-offer · /cancel-offer
Completing a voucher (merchant lsk_)
After the customer collects the reward in the real world, a merchant agent with scope manage_rewards flips the voucher active → used via POST /vouchers/use or MCP use_voucher. This is a lifecycle transition — not a separate "activation" status in the database.
Completing a voucher — after the customer received the reward in the real world,
the merchant agent (scope: manage_rewards) flips its status active → used.
Note: this is the lifecycle transition, not a separate "activation" DB status.
# REST
curl -sS -X POST "https://api.loyalspark.online/agent-api/vouchers/use" \
-H "Content-Type: application/json" \
-H "x-api-key: lsk_YOUR_API_KEY" \
-d '{"voucher_id":"<uuid>"}'
# MCP tool: use_voucher (args: { voucher_id })