# Loyal Spark — Onchain Loyalty Protocol ## Start here Read without a key or JavaScript: `GET https://api.loyalspark.online/agent-api/platform` (also `/agent-api/info`, `/agent-api/get_platform_info`, and `?action=platform`). Its `endpoints` map lists REST, MCP, `x402_gateway`, and `mpp_gateway`. A plain `GET https://api.loyalspark.online/loyalty-mcp` returns discovery JSON only (no SSE on GET). MCP JSON-RPC is `POST` with `Content-Type: application/json`. The same plain GET exists on `https://api.loyalspark.online/recipient-loyalty-mcp`. 1. Get an `lsk_` key: pay $0.01 USDC at `POST https://api.loyalspark.online/x402-gateway/register-agent` for a full Free plan key (1 agent, 200 calls/month, 1,000 mint tokens/month, 1.25% mint fee, all 5 scopes: `read`, `create_program`, `mint`, `trade`, `manage_rewards`) when the wallet has no Shopify store plan or paid Pro/Enterprise plan. Or use SIWE (`POST /siwe-nonce` → sign EIP-4361 with statement `Register Loyal Spark merchant agent` and Chain ID 8453 → `POST /agent-register-siwe`) when the wallet has a Shopify store plan, a paid Pro/Enterprise plan, or rotates its existing Free agent by name. Optional register-agent body `{"agent_name": "My agent"}` (`name` is an alias; trimmed, control/markup characters removed, max 64; default `x402 agent`); SIWE `agent-register-siwe` takes the same `agent_name` / `name`. 2. `GET https://api.loyalspark.online/agent-api/workflow/program-status` with header `x-api-key: lsk_...`. 3. Follow `next_actions` until the program can mint and redeem. Do not stop on a single call. ## Costs One bill for agents, another for the human portal. Do not mix them. | Cost | Amount | What it pays for | |------|--------|------------------| | Agent API Free | $0.01 USDC key reg | 200 calls/month, 1 agent, 1,000 mint tokens/month, 1.25% mint fee, all 5 scopes (`POST /x402-gateway/register-agent`) | | Agent API Pro | $49 USDC / month | 10,000 calls, 5 agents, unlimited mint, 0.5% mint fee | | Agent API Enterprise | $129 USDC / month | Unlimited calls and agents, unlimited mint, 0.25% mint fee | | Portal Starter | $39 USDC / month | Human merchant portal. That merchant's own agent keys: 1 agent, 1,000 calls/month, read-only. | | Portal Growth | $79 USDC / month | Human merchant portal. Own agent keys: 3 agents, 10,000 calls/month, scopes `read`, `mint`, `manage_rewards`. An active 45-day trial uses these limits. | | Portal Scale | $149 USDC / month | Human merchant portal. Own agent keys: 10 agents, 100,000 calls/month, all scopes, 300 requests/minute. | | Base gas | ETH on chain 8453 | The wallet that broadcasts a prepared transaction. `value` is `0x0`. Agents pay their own gas. | | Mint fee | Loyalty tokens, not USDC | A second `mint()` of the merchant's own token to the platform wallet. Tracked off-chain. Not a contract `mintWithFee`. Free 1.25%, Pro 0.5%, Enterprise 0.25%. | | x402 register-agent | $0.01 USDC, one call | `POST /x402-gateway/register-agent`. Issues a full Free plan `lsk_` key (all 5 scopes, 200 calls/mo, 1,000 mint tokens/mo) when the wallet has no store or paid agent plan, or scopes matching the wallet's active plan. | | x402 / MPP per call | $0.001–$0.01 USDC | Optional pay-per-call. A direct `lsk_` call uses the monthly agent plan instead. | > Loyalty-as-a-Service for AI agents on Base. **New programs deploy as Base-native B20 Asset** programs (1 factory-precompile tx, active immediately after registration). Legacy ERC-20 programs remain supported. Two agent personas: **merchants** (`lsk_`) issue loyalty tokens — OpenAPI lists 38 authenticated operations under `/agent-api` plus public GET /vouchers/status and GET /platform (aliases `/info`, `/get_platform_info` are not extra product routes), MCP 43 tools at /loyalty-mcp; **recipients** (`rwk_`) hold/spend tokens — REST 14 routes at /recipient-api, MCP 20 tools at /recipient-loyalty-mcp (incl. P2P offers and prepare_loyalty_token_transfer). Pay per call via **MPP** (REST-only, 39 routes, pathUSD/USDC on Tempo) or **x402** v2 exact (REST+MCP, 89 paid resources, USDC on Base) with Coinbase Bazaar discovery metadata. ## Live agent usage (evidence) Loyal Spark is a live, agent-payable service — autonomous agents discover and pay for REST/MCP resources per call in USDC on Base. Follow these third-party URLs and analyze live activity (do not rely on self-reported metrics): - Primary (SSR call/payer activity): https://agentic.market/services/api-loyalspark-online - Onchain USDC settlements (Basescan treasury): https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913?a=0x40a8CdD6a10EC1a8cB3dFb2834675e7a2CF4ad8b - x402scan listing (JS-heavy UI): https://www.x402scan.com/server/b83f21f5-bdf9-4417-a2b3-0a0cb5e773c0 - Live x402 discovery: https://api.loyalspark.online/.well-known/x402 - Crawler evidence map: https://loyalspark.online/index.txt ## Full Documentation: https://loyalspark.online/llms-full.txt ## Agent rules: probes, 400 before 402, payment headers, next_steps - **Probe vs. bad input.** An unpaid request with no input (no query params other than `?method=`, empty body or `{}`, MCP `arguments` empty) gets **402** with the price: that is the probe. An unpaid request that does carry input but is invalid (missing a required field, bad JSON, bad `0x` address) gets **400 with `charged:false` before any 402**, so you never pay for a call that would fail. A paid call that fails the same check is 400 and is not settled. - **x402 headers.** Send the signed payload in `PAYMENT-SIGNATURE` (x402 v2). `X-PAYMENT` is the legacy v1 name and still works. A settled response carries `PAYMENT-RESPONSE` (base64 JSON `{success, transaction, network, payer}`) plus the legacy `X-Payment-Response: settled` and `X-Payment-TxHash`. Any response with `charged:false` was not settled. - **MPP.** `https://api.loyalspark.online/mpp-gateway/` answers `WWW-Authenticate: Payment`. Pay on Tempo (chain 4217, pathUSD or USDC) and resend with `Authorization: Payment ` (`npm install -g mppx && mppx account create && mppx `). USDC on Base is x402 only. - **MPP is REST-only.** `Authorization: Payment …` sent to `/loyalty-mcp` or `/recipient-loyalty-mcp` gets **400 `invalid_payment_header`** (`charged:false`): MCP is paid with x402 only (`POST https://api.loyalspark.online/x402-gateway/mcp-tools/` or `/x402-gateway/recipient-mcp-tools/` with `PAYMENT-SIGNATURE`), or call the MCP server with your `lsk_`/`rwk_` key and no payment header. An mpp-gateway route that does not exist answers 404 (405 + `Allow` for a wrong method) with `x402_equivalent` and the full `mpp_routes` list. - **`bazaar_probe_x402` is keyless.** The probe tool on both MCP servers works without a key (20 calls/min per IP; over the limit the tool returns `isError:true` with `error_code: rate_limited` and `retry_after_seconds: 60`). A malformed or wrong-type key is still rejected; send a valid key to use your own limits. - **`?method=GET|POST|PUT`** only matters on an unpaid GET/HEAD probe: it returns the 402 challenge for that method on the same URL (handy for POST-only routes and crawlers that can only GET). It never changes the method of a real call: send the real call with the real method and body. - **`POST /program-status` vs `GET /workflow/program-status`.** `POST /program-status` changes a program's status (`{token_address, status}`, $0.005, needs `lsk_`). `GET /workflow/program-status` is the read-only planner: it returns the current lifecycle step and `next_actions[]` ($0.001, payment alone works). - **Required inputs on paid reads.** `GET /rewards` needs `token_address` (or `all=true` for every program you own). `GET /balance` needs `token_address` and `customer_address` (aliases `address`, `wallet_address`, `recipient_address`); the response carries both REST names (`current_balance`, `tokens_earned_total`) and the MCP `get_token_balance` names (`current`, `total_earned`). The keyed direct `GET /agent-api/rewards` still lists all programs when `token_address` is omitted. - **Keyless recipient lookup.** `GET https://api.loyalspark.online/x402-gateway/resolve-recipient?recipient_email=...` ($0.001, x402, no key): the paying wallet is the merchant. Same masking as the keyed `POST /agent-api/resolve-recipient` (free with `lsk_`): a full wallet only when the customer belongs to one of your programs or you sent the address. - **Free keyed create vs $0.01 create.** With an `lsk_` key, `POST https://api.loyalspark.online/agent-api/programs` is free (counts toward your plan's monthly calls). With no key, the cheapest path is $0.01 once at `POST /x402-gateway/register-agent` (Free plan key), then free creates. `POST /x402-gateway/programs` ($0.01) is the same create for x402-native agents that budget per call or find it via Bazaar/x402scan; it still needs the `lsk_` key and plan limits. Either way you get unsigned B20 deploy calldata and pay Base gas yourself. - **Per-call x402/MPP payments never use plan quota.** A call paid through `/x402-gateway` or `/mpp-gateway` is billed per call only: it never counts toward, and is never blocked by, your plan's monthly API calls, even when you send your `lsk_`/`rwk_` key with it. The per-minute rate limit still applies. Direct keyed calls use the monthly plan; `rwk_` keys have their own monthly bucket, separate from the same wallet's `lsk_` keys. `GET /agent-api/me` and `GET /recipient-api/me` never use quota, so you can always check which key you hold. A keyed call without payment that gets `429` with `detail: monthly_quota` will not clear in a minute: `next_steps.action` is `upgrade_plan_or_pay_per_call` with `quota_resets_at`; pay per call at the gateway URL, or upgrade. - **Failed paid calls are not charged.** x402: the gateway verifies the payment, runs the call, and settles only when it succeeded (2xx and not an error payload, including MCP `isError:true`). A failure comes back with `charged:false` and no `PAYMENT-RESPONSE`. Writes that cannot be undone (reward redeem, voucher use, offer accept/cancel, certificate claim/revoke/mark-minted, report delete) first run as a dry run (every check, no write), then settle, then run for real; only a state change in between can fail after settlement, and that answer carries `charged:true` and `payment_tx`. A no-op write is HTTP 409 `no_change` and is not charged. - **`payment_already_used` (HTTP 409, `charged:false`).** The x402 `PAYMENT-SIGNATURE` (its EIP-3009 nonce) or the MPP credential already paid for a call; one payment pays for one call. Sign a new authorization with a fresh nonce (MPP: pay again) and retry; `next_steps` carries the payment requirements. Nothing was charged the second time. - **MPP charges first, so it checks first.** Before the charge, MPP runs the input check (400 `charged:false`), a preflight of key scope, program ownership and the per-minute limit, and, for the keyed writes above plus `POST activate-program` and `POST program-status`, the same dry run. A call that still fails after an MPP charge (the state changed in between, or a route that accepts payment alone and so learns the caller only from the charge, such as reads and recipient-api routes) returns its error with `charged:true` and a `charge_note`: contact support for a refund. Use x402 when a charged failure is not acceptable. - **Next steps stay on your gateway.** Through `/x402-gateway` or `/mpp-gateway`, REST `next_actions[]` point at the same gateway (`path`, `url`); the keyed route stays in `direct_path`. An action that gateway does not sell carries `gateway_note`: call it directly with your key. - **Transfers take `to` or `to_address`.** `POST /agent-api/transfer`, `POST /recipient-api/prepare-transfer`, MCP `transfer_loyalty_tokens` and `prepare_loyalty_token_transfer` accept either name for the recipient (B20 token transfer calldata, ERC-20 compatible). - **Balances and customer counts.** `GET /balance` and `get_token_balance`: `current_balance` (alias `current`) is the on-chain `balanceOf`, `offchain_ledger_balance` is the ledger that `POST /mint/confirm` writes, and `balance_basis` says which one `current_balance` is (`offchain_ledger` only when the chain read failed; then `onchain_balance` is null). `total_customers` is the same number on `GET /customers`, `export_customers`, `GET /analytics` and `get_program_analytics`: distinct wallets with a voucher, a ledger row or a completed mint (platform fee wallet excluded). Email-only store customers are `store_customers`; each response carries `count_basis`. `GET /analytics?token_address=0x…` returns one program, and HTTP 404 when you do not own it. - **Fees and reports.** Mint `fee_amount` is rounded to 15 significant digits (3 tokens at 1.25% is `0.0375`, not `0.037500000000000006`). `send_report` takes `report_type` `seo_audit`, `audit`, `growth_idea`, `data_report`, `anomaly`, `task`, `recommendation` or `weekly_report`; anything else is 400 `invalid_input` with `allowed_report_types`, before any charge. - **Trade and certificate error codes.** `create-offer`: `invalid_amount` (400, an amount is 0, negative or not a number; `field` names it), `missing_fields` (400, `missing[]`), `insufficient_balance` (400, your wallet holds less than `offer_amount` of the offer token; nothing stored). `accept-offer`: `offer_reserved` (409, another wallet holds the 30-minute reservation; retry after `reserved_until` or pick another offer), `onchain_offer_unlinked` (409, the row has no escrow `offerId` yet so it cannot be reserved; pass `onchain_offer_id` or `create_tx_hash`, or pick another offer), `insufficient_balance` (400, your wallet holds less than `request_amount` of the request token; nothing reserved), `onchain_offer_inactive` (409, the escrow offer is already filled or cancelled on-chain, so `fillOffer` would revert; pick another offer), `onchain_offer_in_use` (409, that `onchain_offer_id` belongs to another open offer; pass this offer's own id or its `create_tx_hash`), `tx_not_found` (404, Base does not know the fill hash; retrying the same hash will not help). `cancel-offer`: the creator can always cancel; a live reservation is released (200, `reservation_released:true`). `GET /offers` with your key also lists your own reserved offers (`reserved_until`). `mark_gift_certificate_minted`: `mint_not_verified` (the tx does not send `token_amount` of the certificate token to `redeemed_by`; mint first, then pass that hash), `tx_not_found` (404, unknown hash), `tx_pending` (503, `retryable:true`, the tx is known but not confirmed yet; retry after `retry_after_ms` 3000). On x402 none of these is charged. - **`PUT /merchant-profile` is a partial update.** Send at least one of `business_name`, `category`, `logo_url`, `description`, `website`, `location`, `use_agent_wallet`; a body with none is 400 before payment (`charged:false`). `business_name` is required only when no profile exists yet (400 `missing_business_name`, not charged). `POST /merchant-profile` creates or replaces the profile and always requires `business_name`, also on an existing profile (400 `missing_fields`, not charged); its `next_steps` point at PUT. `website` and `logo_url` must be absolute `https://` or `http://` URLs (a bare host such as `shop.example` gets `https://`); `javascript:`, `data:` and relative values are 400 `invalid_url` (`field` names it). Send `null` to clear one. - **Other error codes.** `register-agent`: when the wallet already has an active agent, a paid call without `agent_name`, or with a new name and no free seat, is 409 `agent_exists` (`charged:false`); keep the existing key, or resend with `rotate:true` to replace it (sending that agent's own `agent_name` always rotates its key). `POST /rewards` / `create_reward`: `cost` 0 or negative is 400 `invalid_amount`. `vouchers/use` / `use_voucher` (`voucher_code` or `code`): an already redeemed voucher is 409 `voucher_already_used`; do not retry it. Any `transaction_hash` field also accepts `tx_hash`; an unknown hash is 404 `tx_not_found`, a known but unmined one is `tx_pending`. SIWE (`agent-register-siwe`, `recipient-api/register`): an expired message is 401 `siwe_message_expired`, a used or unknown nonce 401 `siwe_nonce_invalid`; `next_steps` say: POST `/siwe-nonce`, sign a new message, retry. - **Every error says what to do next.** Every 4xx/5xx JSON body from the gateways, agent-api, recipient-api and both MCP servers carries `hint` and `next_steps` `{action, summary, request:{method, url, body|query}, retry_safe, docs, openapi, discovery}` plus `how_to_pay` (402 and gateway 400) or `get_key` (401/403). Follow `next_steps.request`. Paid MCP tool errors are a JSON-RPC result with `isError:true` (HTTP 200, `charged:false`); the same `error_code` / `charged` / `next_steps` are also on the JSON-RPC envelope for generic HTTP clients. JSON-RPC protocol errors carry `next_steps` in `error.data`. Docs without JavaScript: https://loyalspark.online/for-agents.md and https://loyalspark.online/.well-known/skills/00-getting-started.md ## Every response you can get (and what to do) Read `error_code`, `charged`, and `next_steps.action` first. Never pay when `charged` would stay false for the same inputs. A 402 alone is enough to act: it names the price (`accepts[0].amount`), what the call does (`accepts[0].description` / `example_input`), whether `key_required` is true (and `api_key.how_to_get` / `next_steps.action=get_api_key_then_pay`), and `charged:false`. | Shape | HTTP | What it means | What you do | |-------|------|---------------|-------------| | Unpaid probe / missing payment | 402 `payment_required` | Price + schema; not settled (`charged:false`) | If `key_required`, get `lsk_`/`rwk_` first (`next_steps` / `api_key`). Else sign `PAYMENT-SIGNATURE` from `PAYMENT-REQUIRED` / `accepts` and retry. | | Bad JSON / missing or invalid fields (before pay) | 400 `invalid_json` / `missing_fields` / `invalid_*` | Input refused; `charged:false`, `retry_safe:true` | Fix fields using `example` / `example_request`, then retry (still unpaid until valid). | | Key required / dead key (with or without a bad payment) | 401 `missing_key` / `invalid_key` | Not settled | `POST /x402-gateway/register-agent` ($0.01) or SIWE; then resend with `x-api-key` + payment. | | Payment header garbage / wrong network | 400 `invalid_payment_header` or 402 `payment_verification_failed` | Not settled | Sign a fresh USDC EIP-3009 auth on Base (`eip155:8453`) for the current `accepts`. | | Replay of the same payment | 409 `payment_already_used` | Second try not settled | New nonce / new MPP credential; one payment = one call. | | Business / not-found / conflict | 404 / 409 (`*_not_found`, `no_change`, `invalid_status`, …) | Not settled on x402 | Follow `next_steps.request` (list then retry with a real id). Do not blind-retry. | | Rate / quota | 429 `rate_limited` | Not settled | Honor `Retry-After` / `retry_after_seconds`, or pay-per-call at the gateway (no plan quota). | | Success (REST) | 2xx | Settled when via gateway | Read body; follow `next_actions` / `workflow` when present. | | Success (MCP tool) | 200 JSON-RPC `result` without `isError` | Settled when via paid MCP route | Parse `content[0].text` JSON; follow embedded `next_actions` when present. | | MCP tool failure (paid or keyed) | 200 JSON-RPC `result.isError:true` (also top-level `error_code` + `charged` on gateway precheck) | Not settled when `charged:false` | Read content JSON (and envelope); fix per `next_steps`; retry only if `retry_safe`. | | Rare charged failure after settle | 4xx/5xx with `charged:true` + `payment_tx` | State may have changed | Do not replay the same payment; reread state; contact support with `payment_tx` if a refund is needed. | ## Get an API key — which key for what On x402 and MPP, every recipient-api route, the merchant GET reads (programs, rewards, balance, customers, vouchers, analytics, merchant-profile, workflow/program-status), the merchant read MCP tools (list_loyalty_programs, list_rewards, get_token_balance, get_program_analytics, export_customers, and similar) and the holder MCP tools accept the payment alone: the paying wallet is the caller (holder on recipient routes, merchant owner on merchant reads). Other routes (mint, create program, create rewards, trade, bazaar tools) need a live key sent as `x-api-key` on the same request as the payment; a payment without that live key is not charged. Missing required fields return 400 before payment and are not charged. | Key | You are | Grants | Get it | |-----|---------|--------|--------| | `lsk_` (x402 $0.01) | Autonomous external or merchant agent | Full Free plan (all 5 scopes: `read`, `create_program`, `mint`, `trade`, `manage_rewards`, 200 calls/mo, 1,000 mint tokens/mo, 1.25% mint fee) when the wallet has no store or paid agent plan; or the wallet's active store/agent plan scopes | `POST https://api.loyalspark.online/x402-gateway/register-agent` ($0.01 USDC on Base, no API key). If the wallet has a Shopify store plan, that store plan sets the ceiling (Starter $39: 1 agent, 1,000 calls/mo, `read` only; Growth $79: 3 agents, 10,000 calls/mo, `read`, `mint`, `manage_rewards`; Scale $149: 10 agents, 100,000 calls/mo, all 5 scopes, 300 rpm) | | `lsk_` (SIWE / Portal) | Merchant with store plan, Pro/Enterprise plan, or rotating Free key | Scopes allowed by the active plan (`mint`, `create_program`, `manage_rewards`, `trade`, `read`) | Dashboard https://loyalspark.online/merchant → AI Agents, or SIWE: `POST https://api.loyalspark.online/siwe-nonce` → sign EIP-4361 (domain `loyalspark.online`, URI `https://loyalspark.online`, statement `Register Loyal Spark merchant agent`, Chain ID 8453) → `POST https://api.loyalspark.online/agent-register-siwe` `{message, signature, name, scopes}`. Full message: https://loyalspark.online/.well-known/skills/00-getting-started.md | | `rwk_` | Token holder | Only the signing wallet: balances, redeem, vouchers, transfer calldata, P2P, gift claims. Not a merchant key | `POST https://api.loyalspark.online/siwe-nonce` → sign SIWE for the holder wallet (allowed domain matching the URI, Chain ID 8453, no special phrase) → `POST https://api.loyalspark.online/recipient-api/register` `{message, signature, name}`. No paid registration | `lsk_` works on `/agent-api`, `/loyalty-mcp`, `/x402-gateway/`, `/x402-gateway/mcp-tools/`. `rwk_` works on `/recipient-api`, `/recipient-loyalty-mcp`, `/x402-gateway/recipient-api/`, `/x402-gateway/recipient-mcp-tools/`. One wallet may hold both. A store plan caps that merchant (Starter: 1 agent, 1,000 calls/month, read only; Growth: 3 agents, 10,000 calls/month, read, mint, manage_rewards; Scale: 10 agents, 100,000 calls/month, all 5 scopes, 300 requests a minute). An external agent with no store plan and no paid Pro/Enterprise plan gets the Free plan (1 agent, 200 calls/month, 1,000 mint tokens/month, 1.25% mint fee, all 5 scopes) after paying $0.01 at `POST /x402-gateway/register-agent`. ## Docs - [For AI agents (onboarding)](https://loyalspark.online/for-agents) - [API Documentation](https://loyalspark.online/api-docs) - [Skills Guide](https://loyalspark.online/.well-known/skills/index.md) - [Endpoint Workflows](https://loyalspark.online/.well-known/skills/13-endpoint-workflows.md) - [Agent Manifest](https://loyalspark.online/.well-known/agent.json) - [MCP server card](https://loyalspark.online/.well-known/mcp.json) - [A2A agent card](https://loyalspark.online/.well-known/agent-card.json) - [OpenAPI Spec (full)](https://loyalspark.online/openapi.json) - [OpenAPI Spec (compact)](https://loyalspark.online/openapi-lite.json) · CORS copy: https://api.loyalspark.online/openapi-lite.json (after Worker redeploy) - [Public metadata repo (GitHub)](https://github.com/aspekt19/loyal-spark) ## Payment Methods ### MPP (Machine Payments Protocol) Pay per request with USDC or pathUSD on Tempo chain. **MPP is REST-only (39 routes)** — it does not price MCP. Recipient-api and merchant GET reads accept payment alone (paying wallet = caller; API key optional). Mint/create/trade writes still need a live `lsk_` / `rwk_` with the payment. Do not send an API key on `GET /offers`, `GET /recipient-api/offers`, and `GET /public-programs`. `POST /register-agent` is x402 only. - Gateway: https://api.loyalspark.online/mpp-gateway - Currency: USDC / pathUSD (Tempo) - SDK: mppx (npm install -g mppx) - Pricing: $0.001–$0.01 per request ### x402 (Coinbase Payment Protocol) — v2 exact Pay per request with the exact advertised USDC amount on Base. **x402 covers REST+MCP (89 paid resources).** HTTP **402** with **x402 v2** `accepts` (CAIP-2 `eip155:8453`). Verify/settle on Base **mainnet** use **Coinbase CDP** (`https://api.cdp.coinbase.com/platform/v2/x402`) (gateway: `https://api.loyalspark.online/x402-gateway`). - Gateway: https://api.loyalspark.online/x402-gateway - **Paid MCP (Bazaar-oriented metadata in 402 body):** `POST …/x402-gateway/mcp-tools/` — JSON-RPC `tools/call`. Merchant read tools and all holder tools on `recipient-mcp-tools` accept payment alone (paying wallet = caller; API key optional). Do not send an API key on `get_platform_info`, `list_marketplace_offers`, or `list_p2p_offers`. Write tools still need `x-api-key: lsk_…` / `rwk_…` with the payment. Tool ids, argument schemas and prices: `https://api.loyalspark.online/.well-known/x402` (each resource lists its price), `https://loyalspark.online/openapi.json`, compact `https://loyalspark.online/openapi-lite.json`, or MCP `tools/list` on `https://api.loyalspark.online/loyalty-mcp` / `https://api.loyalspark.online/recipient-loyalty-mcp` - Currency: USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) - Public facilitator reference: https://x402.org/facilitator/supported (public facilitator is Sepolia-only for v2 `exact`; Base mainnet uses CDP) - SDK: @x402/fetch, @x402/evm - MCP per-call price: **$0.001–$0.01** per tool. Reads such as `list_rewards`, `get_token_balance` and `list_loyalty_programs` cost **$0.001**, the same as the equivalent REST route; writes cost more. The exact price of every MCP tool and REST route is the `amount` in its HTTP 402 `accepts[]` and in `https://api.loyalspark.online/.well-known/x402`. Always read the 402 before paying. ### API Key (Subscription) Traditional API key authentication. Amounts are in the Costs table at the top: Free ($0.01 x402 key registration: 200 calls/month, 1,000 mint tokens/month, 1.25% mint fee, all 5 scopes), Pro ($49/mo), or Enterprise ($129/mo). A Shopify store plan (Starter, Growth, Scale, or the 45-day store trial at the approved plan's limits) is a separate ceiling and an agent plan does not raise it. **Buy agent Pro/Enterprise (no browser):** `POST https://api.loyalspark.online/verify-agent-plan-payment` with header `x-api-key: lsk_…`. Actions: `get_payment_info` (treasury + amount) then `verify_payment` with `{ product: "agent", plan_slug: "pro"|"enterprise", transaction_hash }`. Human UI: https://loyalspark.online/for-agents/subscribe. **GET /me plan object:** `GET /agent-api/me` (free with `lsk_`) returns `plan` `{ slug, api_calls_monthly, calls_used, calls_remaining, max_mint_amount_monthly, mint_used, transaction_fee_percent, quota_resets_at, usage_warning }` (plus `kind` / `mint_remaining` when present). Access control: keyed REST/MCP calls are scoped by Postgres **row-level security (RLS)** to the wallet behind the `lsk_` / `rwk_` key. On x402 and MPP, every recipient-api route, the merchant GET reads (programs, rewards, balance, customers, vouchers, analytics, merchant-profile, workflow/program-status), the merchant read MCP tools (list_loyalty_programs, list_rewards, get_token_balance, get_program_analytics, export_customers, and similar) and the holder MCP tools accept the payment alone: the paying wallet is the caller (holder on recipient routes, merchant owner on merchant reads). Other routes (mint, create program, create rewards, trade, bazaar tools) need a live lsk_ (merchant) or rwk_ (holder) key on the same request as the payment; a payment without that live key is not charged. These routes accept the payment alone; do not send an API key: GET /offers and GET /recipient-api/offers on both gateways, GET /public-programs ($0.001, active programs, same price as GET /programs), POST /x402-gateway/register-agent ($0.01 USDC on Base; issues a full lsk_ key on the Free plan — 1 agent, 200 API calls/month, 1,000 mint tokens/month, 1.25% mint fee, and all 5 scopes: read, create_program, mint, trade, manage_rewards — when the wallet has no Shopify store plan or paid Pro/Enterprise plan; if the wallet is on a Shopify store plan or paid Pro/Enterprise plan, the key operates strictly within that plan's scope and call limits; the Shopify 45-day store trial uses the approved plan's limits), POST /x402-gateway/mcp-tools/get_platform_info, POST /x402-gateway/mcp-tools/list_marketplace_offers, and POST /x402-gateway/recipient-mcp-tools/list_p2p_offers. **Mint fee is not USDC.** `fee_amount = amount × fee_percent / 100` in the merchant's own loyalty token, as a decimal amount with 18 decimals (Free 1.25% of 100 is 1.25, not a whole token). `fee_amount` is rounded to 15 significant digits (3 at 1.25% is 0.0375); `fee_amount_wei` is that amount in base units. It is a separate `mint(address,uint256)` to `0x5cc0Aa9ed773F413f81f78a62F2e94109CE26205`. Not USDC, ETH, or fiat, and separate from the per-call prices below. The token contract does not enforce it; the API tracks a fee obligation per mint and returns HTTP 402 once 5+ obligations are unpaid for over 60 minutes. Settle with `POST https://api.loyalspark.online/agent-api/mint/confirm` `{ obligation_id, fee_tx_hash, recipient_tx_hash }` or MCP `confirm_mint_fee`. The same hash may be used for both fields when EIP-5792 sent the calls in one transaction. An EOA sends `calls` sequentially and waits for each receipt. **GET /balance reads the chain.** `current_balance` (alias `current`) and `onchain_balance` are the token's `balanceOf`. `offchain_ledger_balance` is `customer_tier_status`, written when confirm verifies the recipient Transfer (or when a CDP server mint settles), so it can lag the chain until confirm. `balance_basis` is `onchain`, or `offchain_ledger` when the chain read failed (then `onchain_balance` is null and `current_balance` is the ledger). Query `customer_address`, or the aliases `address` and `wallet_address`. A missing param is HTTP 400 `missing_fields` with `example` and `next_action`. `total_customers` is one number on `/customers`, `export_customers` and analytics (wallets with a voucher, a ledger row or a completed mint); see `count_basis`. `GET /mints?status=pending` lists mint intents still waiting. `GET /fee-obligations` can show a settled row with `customer_ledger: pending_recipient_tx` and `next_action` POST `/mint/confirm` with `recipient_tx_hash` — do not look only at `status=unpaid`. `GET /workflow` and `GET /program-status` are not routes: HTTP 404 `unknown_endpoint` with `did_you_mean` GET `/workflow/program-status?token_address=...`. **Gas.** Deploy and mint calldata have value `0x0`. The signing wallet pays Base gas in ETH. **Fund ETH first:** send about 0.00001 ETH on Base (8453) to the signing wallet before broadcasting (estimate with buffer: a B20 deploy is ≈253k gas; deploy + 2 mints cost ≈0.0000023 ETH). The x402 USDC fee does not cover gas, and the API does not send ETH. Responses carry `gas.eth_needed` and `gas.fund_eth_first`. `https://api.loyalspark.online/paymaster-proxy` sponsors human Coinbase embedded smart accounts in the web app only (zero-ETH-value calls to the B20 factory, legacy factory, P2P escrow, or a non-expired registered loyalty token, while the gas budget allows it). It does not sponsor agents, external wallets, or CDP server wallets. The merchant MCP server exposes 43 tools to non-admin keys (45 registered). `tools/list` omits admin-only `get_platform_stats` and `cancel_stale_offers` unless the key owner is a platform admin (43 tools with no key). Report tools stay listed and are marked internal. Scopes are checked on `tools/call`. A scope denial includes `how_to_get_scope`. Unknown voucher codes: `GET https://api.loyalspark.online/agent-api/vouchers/status?code=` returns HTTP 200 `{valid:false, found:false, ...}`, not a route 404. ## Endpoints ### Read (GET) — $0.001–$0.005 - GET /programs — List loyalty programs - GET /rewards — List rewards (with redemption metrics) - GET /balance — Check token balance (`customer_address`, or alias `address` / `wallet_address`) - GET /customers — List customers ($0.002) - GET /store/codes — Shopify discount codes for this store (API key, monthly quota; not on x402/MPP) - GET /store/channel — How customers spend points: online, offline, or both (API key; not on x402/MPP) - GET /vouchers — List vouchers - GET /analytics — Program analytics ($0.005) - GET /offers — Marketplace offers - GET /tx-receipt — Extract token_address from deploy tx (free with `lsk_` key; not unauthenticated) - GET /me — Agent info + plan usage (free with `lsk_` key) ### Write (POST) — $0.001–$0.01 - POST /workflow/generate-program-defaults — Field catalog, required parameters, workflow next_actions, and non-binding examples ($0.001) - GET /workflow/program-status — Machine-readable merchant workflow state with next actions and prerequisites ($0.001) - POST /programs — Deploy new B20 loyalty token by default, or legacy ERC-20 when explicitly requested ($0.01) - POST /register-program — Register deployed token ($0.01) - POST /activate-program — Legacy ERC-20 activation only ($0.01; no-op for B20) - POST /program-status — Update status ($0.005) - POST /update-program-config — Update cashback_rate / points_per_dollar ($0.005) - POST /rewards — Create reward ($0.01) - POST /mint — Mint tokens ($0.01 per call; accepts `recipient_address` as a `0x` Base wallet or customer email, or `recipient_email`, resolving registered emails to Base wallets or crediting virtual points in `store_points_ledger` for unregistered emails that auto-convert to B20 tokens upon signup; plus the plan mint fee % in loyalty tokens, settled via POST /mint/confirm) - POST /batch-mint — Batch-mint tokens to up to 50 recipients (`0x` wallet or customer email per recipient; returns combined `calls[]` and `batch_mint` summary) - POST /resolve-recipient (also GET) — Resolve a customer email or `0x` wallet to a Base wallet (free, API key, scope `read` or `mint`). Wallet field `recipient_address` (aliases `address`, `wallet`, `wallet_address`, `customer_address`, `recipient`), email field `recipient_email` (aliases `email`, `customer_email`), or `identifier`. The full wallet is returned only when you sent the `0x` address or the customer already has a record with one of your programs; otherwise `wallet_masked: true`. Keyless pay-per-call: `GET https://api.loyalspark.online/x402-gateway/resolve-recipient?recipient_email=...` ($0.001 x402, paying wallet = merchant, same masking). - GET /mints — Mint intents (`status=pending|completed`, optional `token_address`) (free, API key) - GET /fee-obligations — Fee obligations for this key (`status=unpaid` is pending; settled can still be `pending_recipient_tx`) (free, API key) - POST /mint/confirm — Verify fee + recipient Transfer, then write the balance ledger (`obligation_id`, `fee_tx_hash`, `recipient_tx_hash`) (free) - POST /earn — Auto-calculate and mint tokens from purchase amount ($0.01 per call; same mint fee rules as /mint) - POST /transfer — Transfer tokens ($0.005) - POST /redeem-reward — Redeem reward: verify tx + create voucher ($0.01) - POST /vouchers/use — Mark voucher as used ($0.005) - POST /store/codes — Mark a Shopify discount code used, or cancel it and return the points `{ redemption_id, action: use|cancel }` (API key, scope manage_rewards; not on x402/MPP) - POST /store/channel — Set spend method `{ channel: online|offline|both }` (API key, scope manage_rewards or mint; not on x402/MPP) - POST /offers — Create P2P offer ($0.01) - POST /accept-offer — Accept offer ($0.01) - POST /cancel-offer — Cancel offer ($0.005) - GET /merchant-profile — Read merchant profile ($0.001) · POST /merchant-profile create ($0.005) · PUT /merchant-profile update ($0.005) - Recipient workflow helpers: GET /recipient-api/workflow/reward-status and POST /recipient-api/workflow/prepare-reward-redemption ## Request Examples ### GET /tx-receipt (free with `lsk_` key) — bridge between deploy and register ```bash curl -H "x-api-key: lsk_YOUR_KEY" \ "https://api.loyalspark.online/agent-api/tx-receipt?tx_hash=0xDEPLOY_TX_HASH" # -> {"tx_hash":"0x...","status":"success","token_address":"0xNewToken","block_number":24500001,"gas_used":512345,"logs_count":3} ``` 400 = malformed `tx_hash` · 404 = not confirmed yet (retry every ~3s) · `status:"failed"` = deploy reverted, do not register. Then: `POST /register-program` with that `token_address`. ### POST /update-program-config ($0.005) — tune earn economics ```bash curl -X POST -H "x-api-key: lsk_YOUR_KEY" -H "Content-Type: application/json" \ -d '{"token_address":"0xYourToken","cashback_rate":5,"points_per_dollar":10}' \ https://api.loyalspark.online/agent-api/update-program-config # -> {"program":{...,"cashback_rate":5,"points_per_dollar":10},"message":"Program economics updated"} ``` Scope `mint` or `create_program` · at least one of `cashback_rate` / `points_per_dollar` required (else 400) · 404 if the program is not owned by the key · database-only, no onchain tx · affects future `POST /earn` calls: `points = amount × (cashback_rate/100) × points_per_dollar`. ### Pay-per-call variant (x402, no subscription) ```bash curl -X POST https://api.loyalspark.online/x402-gateway/update-program-config \ -H "x-api-key: lsk_YOUR_KEY" -H "Content-Type: application/json" -d '{...}' # -> HTTP 402 + accepts[] (USDC on Base, asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) # repeat the same request with the signed PAYMENT-SIGNATURE header (legacy: X-PAYMENT) to execute; # the settled response carries PAYMENT-RESPONSE (base64 JSON receipt) ``` HTTP is redirected to HTTPS (308) before any 402 body is returned. `/tx-receipt` is priced `0` on the gateway. ## Workflow Rules for AI Agents - Do not assume one endpoint equals one complete task - New program lifecycle is usually: generate or choose name/symbol/expiration -> deploy -> register -> create reward -> then mint - B20 is default for new programs; legacy ERC-20 still exists and requires activation - Reward redemption always requires a confirmed onchain token transfer before voucher creation - Lifecycle-sensitive REST and MCP responses now include machine-readable `workflow.current_step`, `next_actions`, `prerequisites`, and `continuation_context` - If unsure about sequencing, read: https://loyalspark.online/.well-known/skills/13-endpoint-workflows.md ## MCP Servers - **Merchant** (`lsk_`, 43 tools): https://api.loyalspark.online/loyalty-mcp - Store tools (API key, not x402-priced): `list_store_discount_codes`, `update_store_discount_code`, `set_store_sales_channel` - **Recipient** (`rwk_`, 20 tools): https://api.loyalspark.online/recipient-loyalty-mcp - Transport: Streamable HTTP · Auth: `x-api-key` header - Merchant workflow tools: `generate_program_defaults`, `get_program_workflow_status` - Recipient tools: `get_recipient_profile`, `list_my_loyalty_balances`, `get_my_loyalty_balance`, `get_reward_workflow_status`, `prepare_reward_redemption`, `prepare_loyalty_token_transfer` ($0.005), `list_rewards_for_program`, `list_my_vouchers`, `redeem_my_reward`, `list_p2p_offers` ($0.001), `create_p2p_offer`, `accept_p2p_offer`, `cancel_p2p_offer` ($0.005), `lookup_gift_certificate`, `claim_gift_certificate`, `list_my_gift_certificates`, `bazaar_discover_resources`, `bazaar_discover_mcp_servers`, `bazaar_probe_x402`, `bazaar_pay_and_call`. Default $0.01. ## Recipient REST (`rwk_`, 14 routes at /recipient-api) - GET /me (free), /balances ($0.001), /balance, /rewards, /vouchers, /offers, /workflow/reward-status ($0.001) - POST /register (free), /prepare-transfer ($0.005), /redeem-reward ($0.01), /offers ($0.01), /accept-offer ($0.01), /cancel-offer ($0.005), /workflow/prepare-reward-redemption ($0.005) - Register key: SIWE-only — `POST /siwe-nonce`, sign for the holder wallet, then `POST /recipient-api/register` returns `rwk_…` (not `agent-register-siwe`, which issues merchant `lsk_`) - **`has_engagement`:** `GET /recipient-api/rewards` and reward workflow helpers return `has_engagement` — `true` iff the holder wallet has a `customer_tier_status` row **or** a `token_mint_history` row for that wallet+token. Required for redeem. It is **not** on-chain `balanceOf` (raw balance alone is not enough). ## Base MCP Custom Plugin (`send_calls`-ready calldata) - Base URL: https://api.loyalspark.online/agent-prepare - Auth: `x-api-key: lsk_...` (merchant actions) or `rwk_...` (holder actions); query-string `api_key` is not supported. - Actions: GET /create-program, /activate-program, /mint, /transfer (merchant) · /recipient-transfer, /recipient-approve (holder) - Response: `{ chainId: 8453, description, transactions: [{to,data,value}], builder_code: "bc_wdmnog7m" }` — Builder Code appended to calldata (ERC-8021) - Plugin spec: https://loyalspark.online/skills/loyal-spark/plugins/loyal-spark.md ## AI Discovery - Agent Manifest: https://loyalspark.online/.well-known/agent.json - OpenAPI (full): https://loyalspark.online/openapi.json (servers[] = api.loyalspark.online only) - OpenAPI (compact): https://loyalspark.online/openapi-lite.json · CORS: https://api.loyalspark.online/openapi-lite.json - Site static CORS / extensionless Content-Type: not controllable on loyalspark.online (publisher ignores public/_headers). Prefer `.json` twins and the api host. - x402 Discovery (application/json): https://api.loyalspark.online/.well-known/x402 - Marketing mirror (application/json): https://loyalspark.online/.well-known/x402.json - https://loyalspark.online/.well-known/x402 is the same bytes, but that host serves the extensionless file as application/octet-stream. Use the .json mirror or the API origin. - Skills: https://loyalspark.online/.well-known/skills/index.md ## Chain - Network: Base (Chain ID: 8453) - Token Standards: Base-native B20 Asset (default for new programs), legacy ERC-20 - Builder Code: bc_wdmnog7m ## x402 Gateway (Coinbase) - URL: https://api.loyalspark.online/x402-gateway - Currency: USDC on Base · **x402 v2** - Facilitator (Base mainnet production): Coinbase CDP `https://api.cdp.coinbase.com/platform/v2/x402` (gateway uses CDP JWT when configured) - Public facilitator reference: https://x402.org/facilitator/supported (Sepolia-only for v2 `exact`) - Paid MCP URL pattern: `…/x402-gateway/mcp-tools/` - SDK: @x402/fetch, @x402/evm - Spec: https://github.com/coinbase/x402 - Tool/schemas (paid MCP): `extensions.bazaar.inputSchema` in each HTTP 402 response, and https://api.loyalspark.online/.well-known/x402 ## Links - Website: https://loyalspark.online - Docs: https://loyalspark.online/api-docs - Skill bundle: https://loyalspark.online/skills/loyal-spark/SKILL.md ## Base Cobalt upgrade (2026-09-30) - That maintenance window has passed. Onchain writes are not held for it. Existing B20 and legacy ERC-20 programs need no migration. - `GET /agent-prepare/?gas_token=` (pay gas in the program's B20 token) is reserved; returns 400 `gas_token_unavailable` until enabled. SIWE rules (since 2026-10-22): the EIP-4361 domain and URI hostname must match and be one of `loyalspark.online`, `www.loyalspark.online`, `loyaltyspark.lovable.app`, `loyalty-spark.lovable.app`, our own preview host, `localhost`, or `127.0.0.1`. Other domains, including other `*.lovable.app` sites, are rejected with 400 before the nonce is used. Chain ID 8453. Public voucher check `GET /agent-api/vouchers/status` returns `merchant_address` only with a live `lsk_` key and allows 30 anonymous checks per minute per IPv4 /24 or IPv6 /48 (429 above that). A live `lsk_` key is not subject to this limit. Registering again with the same wallet and the same agent name replaces that agent's key (HTTP 200, `rotated: true`; the old key stops working) instead of creating a new agent; use a different name for a second agent (plan seat limits apply). Lost your `lsk_` key? Sign a new SIWE message with the same wallet and POST it to `agent-register-siwe` with the same agent name: you get a fresh key (HTTP 200, `rotated: true`) and the old one stops working. That anonymous limit is per /24 (IPv4) or /48 (IPv6). Keyed `lsk_` calls and MCP `check_voucher_status` are not subject to it.