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

託管 MCP 伺服器

npx add-mcp 'https://api.loyalspark.online/loyalty-mcp'

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

Loyal Spark

GuideGuide PricingPricing For AgentsFor Agents API DocsAPI Docs Install appInstall app PitchPitch

Log inLog in

For AI agents

Loyalty points, rewards & vouchers API on Base (REST + MCP, USDC via x402)

Get API key

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

See all 89 tools & prices

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. 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. 2.Get the key that matches the job. External agents without a subscription pay $0.01 at POST /x402-gateway/register-agent to get 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 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 need rwk_ — SIWE + recipient-api/register, also below.
  3. 3.Read the two required docs: getting started (keys, plans, auth) and endpoint workflows (why one endpoint is rarely one task).
  4. 4.Smoke test REST: curl -H "x-api-key: $KEY" https://api.loyalspark.online/agent-api/programs — or the public GET /vouchers/status?code=LOYAL-… with no key.
  5. 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. 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

Full pricing

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.

Pay for a plan

  1. Step 1. Connect the owner wallet of your agents on Base.
  2. Step 2. Choose Pro or Enterprise and monthly or annual billing.
  3. 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>

MethodRouteWhat it doesAuthUSD
GET/analyticsFetch merchant loyalty program analytics, mint/redeem volume, and holder metrics.pay only$0.005
GET/balanceRead B20/ERC-20 loyalty token balance for a wallet address on Base.pay only$0.001
GET/customersList a merchant's loyalty program customers with token balances, tiers, and rewards activity.pay only$0.002
GET/merchant-profileGet merchant profile, brand settings, and loyalty configuration.pay only$0.001
GET/offersList active P2P marketplace offers for loyalty token swaps on Base.pay only$0.001
GET/programsList the merchant wallet's B20 loyalty programs on Base.pay only$0.001
GET/public-programsReturns active public programs, not the caller's own.pay only$0.001
GET/resolve-recipientResolve a customer email, wallet, or @username to a Base wallet.pay only$0.001
GET/rewardsList redeemable rewards configured for a loyalty program.pay only$0.001
GET/vouchersList issued reward vouchers and redemption status for a program.pay only$0.001
GET/workflow/program-statusCheck a loyalty program's setup and rewards workflow status: deploy, register, activate, rewards.pay only$0.001
POST/accept-offerAccept an open P2P loyalty token swap offer on Base.pay + key$0.01
POST/activate-programActivate or pause a loyalty program on Base.pay + key$0.01
POST/cancel-offerCancel an open P2P loyalty token swap offer and release escrowed tokens.pay + key$0.005
POST/earnAward loyalty tokens to a customer based on purchase amount and program earn rate.pay + key$0.01
POST/merchant-profileCreate or replace the merchant profile and brand settings for loyalty rewards.pay + key$0.005
POST/mintMint B20/ERC-20 loyalty tokens on Base to a customer wallet or email.pay + key$0.01
POST/offersCreate a P2P escrow marketplace offer to swap loyalty tokens on Base.pay + key$0.01
POST/program-statusUpdate or synchronize a loyalty program's operational status.pay + key$0.005
POST/programsCreate and deploy a new B20 loyalty token program on Base (legacy ERC-20 optional).pay + key$0.01
POST/redeem-rewardRedeem loyalty tokens for a reward and issue a redemption voucher.pay + key$0.01
POST/register-agentStart here: get a loyalty & rewards API key.pay only$0.01
POST/register-programRegister an already-deployed onchain B20 loyalty token contract in Loyal Spark.pay + key$0.01
POST/rewardsCreate a new redeemable reward in a merchant loyalty program.pay + key$0.01
POST/transferTransfer loyalty tokens between wallets on Base.pay + key$0.005
POST/update-program-configUpdate loyalty program metadata, reward rules, or tier thresholds.pay + key$0.005
POST/vouchers/useMark a customer reward voucher code as used at checkout.pay + key$0.005
POST/workflow/generate-program-defaultsGenerate recommended loyalty token economics, tiers, and reward defaults for a business.pay + key$0.001
PUT/merchant-profileUpdate the merchant profile and brand settings for loyalty rewards.pay + key$0.005

Recipient REST — 12 api.loyalspark.online/x402-gateway/recipient-api<route>

MethodRouteWhat it doesAuthUSD
GET/balanceGet a recipient wallet's balance for a specific loyalty token on Base.pay only$0.001
GET/balancesList all loyalty token balances held by a customer/recipient wallet on Base.pay only$0.001
GET/offersBrowse open P2P marketplace offers to buy or swap loyalty tokens on Base.pay only$0.001
GET/rewardsBrowse available loyalty rewards that a customer can redeem with tokens.pay only$0.001
GET/vouchersList a customer's redeemed reward vouchers and voucher codes.pay only$0.001
GET/workflow/reward-statusCheck whether a customer has enough tokens and eligibility to redeem a reward.pay only$0.001
POST/accept-offerAccept an open P2P loyalty token swap offer as a recipient.pay only$0.01
POST/cancel-offerCancel a recipient's open P2P loyalty token swap offer.pay only$0.005
POST/offersCreate a recipient P2P escrow offer to swap loyalty tokens on Base.pay only$0.01
POST/prepare-transferPrepare an unsigned B20/ERC-20 loyalty token transfer transaction on Base.pay only$0.005
POST/redeem-rewardRedeem customer loyalty tokens for a reward voucher.pay only$0.01
POST/workflow/prepare-reward-redemptionPrepare 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>

ToolWhat it doesAuthUSD
activate_loyalty_programBuild activation calldata for an inactive loyalty program (on-chain activate + DB status).pay + key$0.01
check_voucher_statusLook up voucher status (active, used, expired) by human-readable code or internal id.pay only$0.001
create_gift_certificateIssue gift or welcome certificates (LOYAL-XXXXXX); single code or batch up to 100 per call.pay + key$0.01
create_loyalty_programBuild factory calldata to deploy a new B20 loyalty token on Base.pay + key$0.01
create_personalized_offerCreate a targeted retention P2P or bonus offer for a specific customer wallet.pay + key$0.01
create_rewardCreate a new redeemable reward (customer pays token cost on-chain, then redeems for a voucher).pay + key$0.01
delete_reportPermanently delete an agent report from the merchant dashboard.pay + key$0.01
earn_pointsCalculate and mint loyalty tokens from a purchase amount using the program cashback rate (earn / cashback flow).pay + key$0.01
export_customersExport customer list with balances and tiers for a loyalty program (CSV-ready JSON).pay only$0.002
generate_program_defaultsAutonomous planner: propose program name, token symbol, cashback economics, and starter rewards from merchant business context.pay only$0.001
get_my_profileAuthenticated merchant agent profile.pay only$0.001
get_platform_infoLoyal Spark protocol metadata on Base L2.pay only$0.001
get_program_analyticsAggregate program analytics: holders, mint volume, redemptions, and tier distribution for a merchant.pay only$0.005
get_program_workflow_statusAutonomous status planner: returns the current merchant program lifecycle step and the machine-readable next_actions[].pay only$0.001
get_token_balanceRead a customer's loyalty token balance and tier level for a specific program.pay only$0.001
list_gift_certificatesList gift certificates issued by the authenticated merchant with optional status filter.pay only$0.01
list_loyalty_programsList B20/ERC-20 loyalty programs owned by the authenticated merchant; optionally include expired programs.pay only$0.001
list_marketplace_offersList open P2P token-swap offers for a loyalty program (peer-to-peer marketplace).pay only$0.001
list_my_reportsList AI agent reports previously submitted by this merchant agent.pay + key$0.01
list_rewardsList redeemable rewards configured for a loyalty program (name, cost in tokens, active flag).pay only$0.001
mark_gift_certificate_mintedFinalize a claimed certificate after on-chain mint (pending_mint -> redeemed); requires mint tx hash.pay + key$0.01
mint_loyalty_tokensFee-first mint calls[] (protocol fee first, then recipient) + fee_obligation_id.pay + key$0.01
redeem_rewardRedeem 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_programRegister an already-deployed loyalty token in Loyal Spark (links on-chain contract to merchant dashboard).pay + key$0.01
revoke_gift_certificateRevoke an active gift certificate so it can no longer be claimed (active -> revoked).pay + key$0.01
send_reportSubmit a structured AI agent report to the merchant dashboard (insights, alerts, action items).pay + key$0.01
transfer_loyalty_tokensBuild B20/ERC-20 transfer calldata to send loyalty tokens from the merchant or agent wallet to any address.pay + key$0.005
update_program_configUpdate program economics: cashback rate, points per dollar, and related merchant settings.pay + key$0.005
update_program_statusUpdate loyalty program status in the database (active, paused, expired, cancelled).pay + key$0.005
update_report_statusUpdate merchant workflow status on an agent report (open, in_progress, resolved).pay + key$0.01
update_reward_statusActivate or deactivate a reward without deleting it (controls visibility in customer apps).pay + key$0.01
use_voucherMark 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>

ToolWhat it doesAuthUSD
accept_p2p_offerAccept another holder's P2P offer and record the match in Loyal Spark.pay only$0.01
cancel_p2p_offerCancel a P2P offer you created before it is accepted.pay only$0.005
claim_gift_certificateClaim an active gift certificate; binds it to your wallet (status active -> pending_mint).pay only$0.01
create_p2p_offerCreate a P2P swap intent: offer loyalty tokens in exchange for another B20/ERC-20 token amount.pay only$0.01
get_my_loyalty_balanceBalance and tier for one loyalty program token held by the authenticated recipient wallet.pay only$0.001
get_recipient_profileRecipient agent profile bound to rwk_ API key: wallet address, key scopes, and registration metadata.pay + key$0.001
get_reward_workflow_statusAutonomous status planner for recipients.pay only$0.001
list_my_gift_certificatesList gift certificates claimed by your wallet with optional status filter.pay only$0.01
list_my_loyalty_balancesAll loyalty token balances and tier levels for the holder wallet linked to this rwk_ key.pay only$0.001
list_my_vouchersList vouchers issued to your wallet (active, used, expired) across enrolled loyalty programs.pay only$0.001
list_p2p_offersList 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_programList active rewards you can redeem for a program where your wallet has loyalty activity or balance.pay only$0.001
lookup_gift_certificatePreview a gift certificate by LOYAL-XXXXXX code without claiming (face value, expiry, program).pay only$0.01
prepare_loyalty_token_transferBuild 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_redemptionOne-shot planner: returns B20/ERC-20 transfer calldata for the reward token cost plus the recipient_reward workflow.pay only$0.005
redeem_my_rewardRedeem 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/.

Open skills index

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