{"openapi":"3.1.0","info":{"title":"Loyal Spark REST (compact)","version":"2.2.0","summary":"Merchant (/agent-api) + recipient (/recipient-api) REST. Full OpenAPI: https://loyalspark.online/openapi.json","description":"Compact OpenAPI for Loyal Spark agents on Base: /agent-api/* (lsk_) and /recipient-api/* (rwk_) only. Full paid x402 corridor + MCP tools: https://loyalspark.online/openapi.json","contact":{"name":"Loyal Spark","email":"admin@loyalspark.online","url":"https://loyalspark.online"},"license":{"name":"MIT","url":"https://loyalspark.online"},"x-logo":{"url":"https://loyalspark.online/new-favicon.png","altText":"Loyal Spark"},"x-provider":"Loyal Spark","x-brand":"Loyal Spark","x-builder-code":"bc_wdmnog7m"},"servers":[{"url":"https://api.loyalspark.online","description":"Loyal Spark — canonical API origin for x402scan discovery and paid resource invocation. All listed x402 gateway paths return live HTTP 402 payment requirements."}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Agent API key (lsk_... merchant or rwk_... recipient)"},"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X","description":"SIWE proof (identity-only routes)"}},"schemas":{"AgentError":{"type":"object","required":["error","error_code"],"additionalProperties":true,"properties":{"error":{"type":"string"},"error_code":{"type":"string","description":"Stable machine code. 401 bodies use error_code and do not also send code."},"missing":{"type":"array","items":{"type":"string"}},"example":{},"docs":{"type":"string"},"next_action":{"type":"object","description":"Merchant (lsk_): POST /x402-gateway/register-agent ($0.01, method+url+body). Holder (rwk_): free SIWE registration (first_step POST /siwe-nonce, then POST /recipient-api/register)."},"next_steps":{"type":"object","description":"Machine-readable first step matching next_action (register-agent for lsk_; siwe-nonce for rwk_)."},"siwe_register":{"type":"object","description":"SIWE registration template (merchant or holder). Prefer this over siwe_after_payment."},"siwe_after_payment":{"type":"object","deprecated":true,"description":"Deprecated alias of siwe_register. SIWE is free and comes first; it is not after payment."},"free_plan_option":{"type":"object","description":"Merchant only: $0.01 POST /x402-gateway/register-agent Free-plan lsk_ option."}}}}},"tags":[{"name":"Merchant REST","description":"Authenticated merchant REST API (lsk_)"},{"name":"Recipient REST","description":"Holder REST API (rwk_)"}],"paths":{"/agent-api/me":{"get":{"operationId":"direct_get_agent_api_me","summary":"Get agent profile, scopes, plan and wallet","description":"Returns the merchant agent's profile (owner address, plan, API scopes, wallet metadata). Free: identity-only. Direct /agent-api/me on https://api.loyalspark.on…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["agent"],"additionalProperties":true,"properties":{"agent":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"owner_address":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[]}},"/agent-api/programs":{"get":{"operationId":"direct_get_agent_api_programs","summary":"List loyalty programs","description":"Lists all loyalty programs owned by the authenticated merchant agent (active + expired). Direct /agent-api/programs on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["programs"],"additionalProperties":true,"properties":{"programs":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[]},"post":{"operationId":"direct_post_agent_api_programs","summary":"Get calldata to deploy a loyalty token","description":"Default: B20 factory calldata (createB20 on 0xB20f…, one tx, active after register). Legacy: set token_standard erc20 for LoyaltyTokenFactory 0x5F3DdB… + activ…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"contract_call":{"type":"object","additionalProperties":true},"tx":{"type":"object","required":["to","data","value","chainId"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"}}},"token_address":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","symbol"],"additionalProperties":true,"properties":{"name":{"type":"string","maxLength":50},"symbol":{"type":"string","minLength":2,"maxLength":5},"expiration_days":{"type":"number","minimum":1},"token_standard":{"type":"string","enum":["b20","erc20"],"default":"b20"},"agent_wallet_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"extra_minters":{"type":"array","items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"use_agent_wallet":{"type":"boolean"}}}}}}}},"/agent-api/rewards":{"get":{"operationId":"direct_get_agent_api_rewards","summary":"List rewards for a program","description":"Returns the reward catalog for a given loyalty token (token_address required as query). Direct /agent-api/rewards on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["rewards"],"additionalProperties":true,"properties":{"rewards":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"all","in":"query","required":false,"schema":{"type":"string","enum":["true"]}}]},"post":{"operationId":"direct_post_agent_api_rewards","summary":"Create a redeemable reward","description":"Creates a reward in the merchant catalog (name, description, cost in points, optional stock and validity). Direct /agent-api/rewards on https://api.loyalspark.…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"reward":{"type":"object","additionalProperties":true},"id":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","cost","token_address"],"additionalProperties":true,"properties":{"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"name":{"type":"string"},"description":{"type":"string"},"cost":{"type":"number","minimum":1}}}}}}}},"/agent-api/balance":{"get":{"operationId":"direct_get_agent_api_balance","summary":"Get on-chain token balance, off-chain ledger, virtual pending points, and tier","description":"current_balance / current is the live on-chain balanceOf on Base. onchain_balance repeats it (null if the chain read failed, then current_balance falls back to…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["balance"],"additionalProperties":true,"properties":{"balance":{"type":"object","additionalProperties":true,"properties":{"current_balance":{"type":"number"},"current":{"type":"number"},"onchain_balance":{"type":["number","null"]},"offchain_ledger_balance":{"type":"number"},"balance_basis":{"type":"string"},"tokens_earned_total":{"type":"number"},"total_earned":{"type":"number"},"virtual_pending_balance":{"type":"number"},"tier":{"type":["object","null"],"additionalProperties":true},"token_address":{"type":"string"},"customer_address":{"type":"string"}}},"balance_source":{"type":"string"},"balance_source_note":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"customer_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}]}},"/agent-api/customers":{"get":{"operationId":"direct_get_agent_api_customers","summary":"List customers for a program","description":"Union of voucher holders, customer_tier_status rows, and completed mint recipients for the token. The platform fee wallet is excluded. total / total_customers…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"customers":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"number"},"total_customers":{"type":"number"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}]}},"/agent-api/mints":{"get":{"operationId":"direct_get_agent_api_mints","summary":"List mint intents","description":"Mint intents for this key's merchant wallets. Query token_address optional, status pending (transaction_hash null) or completed. Pending rows include next_acti…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"mints":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[]}},"/agent-api/fee-obligations":{"get":{"operationId":"direct_get_agent_api_fee_obligations","summary":"List protocol-fee obligations","description":"Obligations for this API key. Query status=unpaid (alias of pending), pending, settled, or failed. Each unpaid row includes next_action with the POST /mint/con…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"obligations":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[]}},"/agent-api/vouchers":{"get":{"operationId":"direct_get_agent_api_vouchers","summary":"List vouchers issued by the merchant","description":"Returns vouchers issued by the authenticated merchant; filterable by customer_address. Direct /agent-api/vouchers on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["vouchers"],"additionalProperties":true,"properties":{"vouchers":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","used","expired","cancelled"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}]}},"/agent-api/vouchers/status":{"get":{"tags":["Merchant REST"],"operationId":"get_agent_api_vouchers_status","summary":"Public voucher verification","description":"Public endpoint: check whether a voucher code or id is valid, used or expired. No API key required. Anonymous callers are limited to 30 checks per minute per I…","security":[],"parameters":[{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"voucher_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"valid":{"type":"boolean"},"found":{"type":"boolean"},"status":{"type":"string"},"code":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}},"/agent-api/analytics":{"get":{"operationId":"direct_get_agent_api_analytics","summary":"Program analytics","description":"One row per program you own: total_customers (the same set GET /customers counts), voucher_customers, active customers (30d/7d), vouchers issued and redeemed,…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"analytics":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}]}},"/agent-api/offers":{"get":{"operationId":"direct_get_agent_api_offers","summary":"List P2P marketplace offers","description":"Returns active P2P swap offers across loyalty tokens (filterable by token_address). Payment alone gives access; do not send an API key. Direct /agent-api/offer…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["offers"],"additionalProperties":true,"properties":{"offers":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}]},"post":{"operationId":"direct_post_agent_api_offers","summary":"Create a P2P swap offer","description":"Creates a P2P swap offer between two loyalty tokens (offer_token / offer_amount ↔ request_token / request_amount). Direct /agent-api/offers on https://api.loya…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"offer":{"type":"object","additionalProperties":true},"status":{"type":"string"},"message":{"type":"string"},"tx":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer_token_address","offer_amount","request_token_address","request_amount"],"additionalProperties":true,"properties":{"offer_token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"offer_amount":{"type":"number","exclusiveMinimum":0},"request_token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"request_amount":{"type":"number","exclusiveMinimum":0}}}}}}}},"/agent-api/tx-receipt":{"get":{"operationId":"direct_get_agent_api_tx_receipt","summary":"Fetch transaction receipt","description":"Fetches a Base L2 transaction receipt by hash. Free helper for agents tracking on-chain confirmations. Direct /agent-api/tx-receipt on https://api.loyalspark.o…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"receipt":{"type":"object","additionalProperties":true},"token_address":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"tx_hash","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},{"name":"hash","in":"query","required":false,"schema":{"type":"string"}}]}},"/agent-api/merchant-profile":{"get":{"operationId":"direct_get_agent_api_merchant_profile","summary":"Read merchant profile","description":"Returns the merchant public profile (name, logo, description) for the authenticated agent owner. Direct /agent-api/merchant-profile on https://api.loyalspark.o…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"profile":{"type":"object","additionalProperties":true},"business_name":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"use_agent_wallet","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}]},"post":{"operationId":"direct_post_agent_api_merchant_profile","summary":"Create merchant profile","description":"Creates or replaces the merchant public profile for the authenticated agent owner. business_name is always required, also when a profile already exists (400 mi…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"profile":{"type":"object","additionalProperties":true},"business_name":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["business_name"],"additionalProperties":true,"properties":{"business_name":{"type":"string","maxLength":100},"category":{"type":"string","enum":["cafe","restaurant","retail","beauty","fitness","grocery","pharmacy","entertainment","services","education","travel","other"]},"logo_url":{"type":"string"},"description":{"type":"string"},"website":{"type":"string"},"location":{"type":"string"},"use_agent_wallet":{"type":"boolean"}}}}}}},"put":{"operationId":"direct_put_agent_api_merchant_profile","summary":"Update merchant profile","description":"Partial update of merchant profile fields for the authenticated agent owner: send at least one of business_name, category, logo_url, description, website, loca…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"profile":{"type":"object","additionalProperties":true},"business_name":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"minProperties":1,"anyOf":[{"required":["business_name"]},{"required":["category"]},{"required":["logo_url"]},{"required":["description"]},{"required":["website"]},{"required":["location"]},{"required":["use_agent_wallet"]}],"properties":{"business_name":{"type":"string","maxLength":100},"category":{"type":"string"},"logo_url":{"type":"string"},"description":{"type":"string"},"website":{"type":"string"},"location":{"type":"string"},"use_agent_wallet":{"type":"boolean"}}}}}}}},"/agent-api/workflow/program-status":{"get":{"operationId":"direct_get_agent_api_workflow_program_status","summary":"Autonomous program workflow status","description":"Returns the current merchant program lifecycle step and machine-readable next_actions[] for self-orchestration. Direct /agent-api/workflow/program-status on ht…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["workflow"],"additionalProperties":true,"properties":{"program":{"type":["object","null"],"additionalProperties":true},"examples":{"type":"object","additionalProperties":true},"workflow":{"type":"object","additionalProperties":true,"properties":{"workflow":{"type":"string"},"actor":{"type":"string"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"prerequisites":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"blocking_reason":{"type":["string","null"]}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}]}},"/agent-api/store/codes":{"get":{"operationId":"direct_get_agent_api_store_codes","summary":"List Shopify discount codes","description":"Shopify discount codes for this merchant. Optional query token_address. Not on x402 or MPP. Direct /agent-api/store/codes on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"codes":{"type":"array","items":{"type":"object","additionalProperties":true}},"ok":{"type":"boolean"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string"}}]},"post":{"operationId":"direct_post_agent_api_store_codes","summary":"Use or cancel a Shopify discount code","description":"Body redemption_id and action use or cancel. Scope manage_rewards. Not on x402 or MPP. Direct /agent-api/store/codes on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"codes":{"type":"array","items":{"type":"object","additionalProperties":true}},"ok":{"type":"boolean"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/agent-api/store/channel":{"get":{"operationId":"direct_get_agent_api_store_channel","summary":"Read the store spend channel","description":"Returns channel online, offline, or both. Not on x402 or MPP. Direct /agent-api/store/channel on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","enum":["online","offline","both"]}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[]},"post":{"operationId":"direct_post_agent_api_store_channel","summary":"Set the store spend channel","description":"Body channel online, offline, or both. Scope manage_rewards or mint. Not on x402 or MPP. Direct /agent-api/store/channel on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"channel":{"type":"string","enum":["online","offline","both"]}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/agent-api/platform":{"get":{"operationId":"direct_get_agent_api_platform","summary":"Public platform discovery and capabilities","description":"Public endpoint (no API key, no payment): returns Loyal Spark protocol metadata, chain info, endpoints, pricing, and onboarding steps. Direct /agent-api/platfo…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"chain_id":{"type":"number"},"endpoints":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[],"parameters":[]}},"/agent-api/info":{"get":{"operationId":"direct_get_agent_api_info","summary":"Public platform discovery alias","description":"Alias of GET /agent-api/platform. Returns public protocol metadata without an API key. Direct /agent-api/info on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"chain_id":{"type":"number"},"endpoints":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[],"parameters":[]}},"/agent-api/get_platform_info":{"get":{"operationId":"direct_get_agent_api_get_platform_info","summary":"Public platform discovery alias (MCP tool name)","description":"Alias of GET /agent-api/platform matching the MCP get_platform_info tool name. Direct /agent-api/get_platform_info on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"chain_id":{"type":"number"},"endpoints":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[],"parameters":[]}},"/agent-api/resolve-recipient":{"get":{"operationId":"direct_get_agent_api_resolve_recipient","summary":"Resolve a customer email or identifier to a Base 0x wallet address","description":"Resolves a customer email or 0x address to a Base wallet. Wallet: recipient_address (aliases address, wallet, wallet_address, customer_address, recipient). Ema…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"wallet_address":{"type":"string"},"wallet_masked":{"type":"boolean"},"email":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"recipient_email","in":"query","required":false,"schema":{"type":"string","format":"email"}},{"name":"recipient_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"identifier","in":"query","required":false,"schema":{"type":"string"}},{"name":"address","in":"query","required":false,"schema":{"type":"string"}},{"name":"wallet","in":"query","required":false,"schema":{"type":"string"}},{"name":"wallet_address","in":"query","required":false,"schema":{"type":"string"}},{"name":"customer_address","in":"query","required":false,"schema":{"type":"string"}},{"name":"recipient","in":"query","required":false,"schema":{"type":"string"}},{"name":"email","in":"query","required":false,"schema":{"type":"string"}},{"name":"customer_email","in":"query","required":false,"schema":{"type":"string"}}]},"post":{"operationId":"direct_post_agent_api_resolve_recipient","summary":"Resolve a customer email or identifier to a Base 0x wallet address","description":"POST body, same fields as GET: recipient_address (aliases address, wallet, wallet_address, customer_address, recipient), recipient_email (aliases email, custom…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"wallet_address":{"type":"string"},"wallet_masked":{"type":"boolean"},"email":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"recipient_address":{"type":"string"},"address":{"type":"string"},"wallet":{"type":"string"},"wallet_address":{"type":"string"},"customer_address":{"type":"string"},"recipient":{"type":"string"},"recipient_email":{"type":"string"},"email":{"type":"string"},"customer_email":{"type":"string"},"identifier":{"type":"string"}}}}}}}},"/agent-api/register-program":{"post":{"operationId":"direct_post_agent_api_register_program","summary":"Register a deployed loyalty token in the database","description":"Persists a deployed loyalty token (name, symbol, token_address, optional cashback_rate / points_per_dollar). deploy_tx_hash is documented in the field catalog…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"program":{"type":"object","additionalProperties":true},"token_address":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","symbol","token_address"],"additionalProperties":true,"properties":{"name":{"type":"string"},"symbol":{"type":"string"},"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"expiration_days":{"type":"number","minimum":1},"cashback_rate":{"type":"number","minimum":0,"maximum":100},"points_per_dollar":{"type":"number","minimum":0},"use_agent_wallet":{"type":"boolean"}}}}}}}},"/agent-api/update-program-config":{"post":{"operationId":"direct_post_agent_api_update_program_config","summary":"Update default cashback / points-per-dollar","description":"Updates the loyalty program economics (cashback_rate 0-50%, points_per_dollar). Owner agent only. Direct /agent-api/update-program-config on https://api.loyals…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"program":{"type":"object","additionalProperties":true},"cashback_rate":{"type":"number"},"points_per_dollar":{"type":"number"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token_address"],"additionalProperties":true,"properties":{"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"cashback_rate":{"type":"number","minimum":0,"maximum":100},"points_per_dollar":{"type":"number","minimum":0}}}}}}}},"/agent-api/activate-program":{"post":{"operationId":"direct_post_agent_api_activate_program","summary":"Get activation calldata for an inactive program","description":"Returns calldata to unpause a program and enable mint operations. Caller submits the on-chain tx. Each step keeps contract_call and adds tx. The response also…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"contract_call":{"type":"object","additionalProperties":true},"tx":{"type":"object","required":["to","data","value","chainId"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"}}},"calls":{"type":"array","items":{"type":"object","required":["to","data","value"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"}}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token_address"],"additionalProperties":true,"properties":{"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"use_agent_wallet":{"type":"boolean"}}}}}}}},"/agent-api/program-status":{"post":{"operationId":"direct_post_agent_api_program_status","summary":"Set program status in the database","description":"Sets the database status (active / paused / archived) of a loyalty program. Direct /agent-api/program-status on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"message":{"type":"string"},"program":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"previous_status":{"type":"string"},"new_status":{"type":"string"}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token_address","status"],"additionalProperties":true,"properties":{"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"status":{"type":"string","enum":["active","paused","expired","cancelled"]}}}}}}}},"/agent-api/mint":{"post":{"operationId":"direct_post_agent_api_mint","summary":"Mint loyalty tokens (fee-first calls[] or virtual points for unregistered email)","description":"Accepts recipient_address as a 0x Base wallet address or customer email (or pass recipient_email to automatically resolve the customer's wallet). If the email…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"mint":{"type":"object","additionalProperties":true},"fee_percent":{"type":"number"},"fee_amount":{"type":"number"},"fee_amount_wei":{"type":"string"},"fee_currency":{"type":"string"},"fee_wallet":{"type":"string"},"fee_obligation_id":{"type":["string","null"]},"calls":{"type":"array","items":{"type":"object","required":["to","data","value"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"}}}},"tx":{"type":"object","required":["to","data","value","chainId"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"}}},"execution":{"type":"object","additionalProperties":true},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"message":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token_address","amount"],"additionalProperties":true,"anyOf":[{"required":["recipient_address"]},{"required":["recipient_email"]}],"properties":{"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"recipient_address":{"type":"string"},"recipient":{"type":"string"},"recipient_email":{"type":"string"},"amount":{"type":"number","minimum":0,"maximum":1000000000}}}}}}}},"/agent-api/earn":{"post":{"operationId":"direct_post_agent_api_earn","summary":"Record an earn / cashback for a purchase (0x wallet or email)","description":"Computes and mints loyalty points for a purchase (uses program's cashback_rate and points_per_dollar). Accepts customer_address (0x wallet or email) or custome…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"message":{"type":"string"},"calls":{"type":"array","items":{"type":"object","required":["to","data","value"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"}}}},"tx":{"type":"object","required":["to","data","value","chainId"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token_address","customer_address","purchase_amount"],"additionalProperties":true,"properties":{"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"customer_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"purchase_amount":{"type":"number","minimum":0},"cashback_rate":{"type":"number","minimum":0,"maximum":100}}}}}}}},"/agent-api/transfer":{"post":{"operationId":"direct_post_agent_api_transfer","summary":"Get transfer calldata for loyalty tokens","description":"Returns B20/ERC-20 transfer calldata for the merchant agent to move loyalty tokens. The response keeps contract_call and adds tx {to, data, value: 0x0, chainId…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"message":{"type":"string"},"calls":{"type":"array","items":{"type":"object","additionalProperties":true}},"tx":{"type":"object","required":["to","data","value","chainId"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token_address","to_address","amount"],"additionalProperties":true,"properties":{"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"number","minimum":0,"maximum":1000000000}}}}}}}},"/agent-api/redeem-reward":{"post":{"operationId":"direct_post_agent_api_redeem_reward","summary":"Redeem a reward for a customer","description":"Burns reward cost from customer balance and issues a voucher; returns voucher code and id. Direct /agent-api/redeem-reward on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"voucher":{"type":"object","additionalProperties":true},"voucher_code":{"type":"string"},"voucher_id":{"type":"string"},"message":{"type":"string"},"workflow":{"type":"object","additionalProperties":true,"properties":{"workflow":{"type":"string"},"actor":{"type":"string"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"prerequisites":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"blocking_reason":{"type":["string","null"]}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"404":{"description":"HTTP 404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reward_id","customer_address","transaction_hash"],"additionalProperties":true,"properties":{"reward_id":{"type":"string","format":"uuid"},"customer_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"transaction_hash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"tx_hash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}}}}}}}},"/agent-api/vouchers/use":{"post":{"operationId":"direct_post_agent_api_vouchers_use","summary":"Mark a voucher as used","description":"Marks a previously-issued voucher as used (consumed at point-of-sale). Direct /agent-api/vouchers/use on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"voucher":{"type":"object","additionalProperties":true},"status":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"HTTP 409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"voucher_code":{"type":"string"},"code":{"type":"string"},"voucher_id":{"type":"string","format":"uuid"}}}}}}}},"/agent-api/accept-offer":{"post":{"operationId":"direct_post_agent_api_accept_offer","summary":"Accept a P2P swap offer (two-phase)","description":"Phase 1 (no transaction_hash): reserves the offer for your wallet (active -> accepted) and returns approve + fillOffer escrow calldata. Phase 2: call again wit…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"offer":{"type":"object","additionalProperties":true},"status":{"type":"string"},"message":{"type":"string"},"tx":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"404":{"description":"HTTP 404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"HTTP 409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer_id"],"additionalProperties":true,"properties":{"offer_id":{"type":"string","format":"uuid"},"onchain_offer_id":{"type":"number"},"transaction_hash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}}}}}}}},"/agent-api/cancel-offer":{"post":{"operationId":"direct_post_agent_api_cancel_offer","summary":"Cancel an own P2P swap offer","description":"Cancels a P2P swap offer the caller created (status active only). Direct /agent-api/cancel-offer on https://api.loyalspark.online.","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"offer":{"type":"object","additionalProperties":true},"status":{"type":"string"},"message":{"type":"string"},"tx":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"HTTP 409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer_id"],"additionalProperties":true,"properties":{"offer_id":{"type":"string","format":"uuid"}}}}}}}},"/agent-api/workflow/generate-program-defaults":{"post":{"operationId":"direct_post_agent_api_workflow_generate_program_defaults","summary":"Generate program defaults from business context","description":"Autonomous planner: proposes program name, symbol, cashback economics, and starter rewards from merchant business context. Direct /agent-api/workflow/generate-…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"field_catalog":{"type":"object","additionalProperties":true},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"examples":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"business_name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"locale":{"type":"string"},"preferred_style":{"type":"string"},"target_audience":{"type":"string"},"use_agent_wallet":{"type":"boolean"}}}}}}}},"/agent-api/mint/confirm":{"post":{"operationId":"direct_post_agent_api_mint_confirm","summary":"Settle a mint and credit the recipient","description":"Body obligation_id, fee_tx_hash, and recipient_tx_hash. Verifies the protocol-fee mint and the recipient Transfer (mint of amount of token_address from 0x0 to…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"confirmed":{"type":"boolean"},"message":{"type":"string"},"obligation_id":{"type":"string"},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/agent-api/batch-mint":{"post":{"operationId":"direct_post_agent_api_batch_mint","summary":"Batch-mint loyalty tokens to multiple recipients (0x wallet or email)","description":"Accepts token_address and recipients[] (up to 50 items, each with amount and recipient_address, recipient_email, email, or recipient). Automatically resolves r…","tags":["Merchant REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"ok":{"type":"boolean"},"message":{"type":"string"},"calls":{"type":"array","items":{"type":"object","required":["to","data","value"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"}}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/recipient-api/me":{"get":{"operationId":"direct_get_recipient_api_me","summary":"Get recipient agent profile","description":"Returns the recipient (holder) agent profile bound to its wallet (rwk_ key). Direct /recipient-api/me on https://api.loyalspark.online.","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["recipient_agent"],"additionalProperties":true,"properties":{"recipient_agent":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"wallet_address":{"type":"string"},"api_key_prefix":{"type":"string"},"total_requests":{"type":"number"},"created_at":{"type":"string"}}},"note":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[]}},"/recipient-api/balances":{"get":{"operationId":"direct_get_recipient_api_balances","summary":"List all loyalty balances for the holder","description":"Returns balances and tiers across every loyalty program the holder participates in. Direct /recipient-api/balances on https://api.loyalspark.online.","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["balances"],"additionalProperties":true,"properties":{"balances":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[]}},"/recipient-api/balance":{"get":{"operationId":"direct_get_recipient_api_balance","summary":"Get balance for one loyalty token","description":"Returns balance and tier for the holder for a single loyalty token. Direct /recipient-api/balance on https://api.loyalspark.online.","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["balance"],"additionalProperties":true,"properties":{"balance":{"type":"object","additionalProperties":true,"properties":{"current_balance":{"type":"number"},"current":{"type":"number"},"onchain_balance":{"type":["number","null"]},"offchain_ledger_balance":{"type":"number"},"balance_basis":{"type":"string"},"tokens_earned_total":{"type":"number"},"total_earned":{"type":"number"},"virtual_pending_balance":{"type":"number"},"tier":{"type":["object","null"],"additionalProperties":true},"token_address":{"type":"string"},"customer_address":{"type":"string"}}},"balance_source":{"type":"string"},"balance_source_note":{"type":"string"}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}]}},"/recipient-api/rewards":{"get":{"operationId":"direct_get_recipient_api_rewards","summary":"List rewards available to the holder","description":"Lists redeemable rewards for a program. Response always includes has_engagement (boolean): false when the holder wallet has no activity on the program (active…","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["rewards","has_engagement"],"additionalProperties":true,"properties":{"rewards":{"type":"array","items":{"type":"object","additionalProperties":true}},"has_engagement":{"type":"boolean","description":"true when the holder wallet already has loyalty activity or balance on this program; false returns the active catalog only (no prior engagement)."},"note":{"type":"string"},"workflow":{"type":"object","additionalProperties":true,"properties":{"workflow":{"type":"string"},"actor":{"type":"string"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"prerequisites":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"blocking_reason":{"type":["string","null"]}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}]}},"/recipient-api/vouchers":{"get":{"operationId":"direct_get_recipient_api_vouchers","summary":"List vouchers issued to the holder","description":"Returns the holder's vouchers (redeemed rewards) with status. Direct /recipient-api/vouchers on https://api.loyalspark.online.","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["vouchers"],"additionalProperties":true,"properties":{"vouchers":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]+$"}}]}},"/recipient-api/offers":{"get":{"operationId":"direct_get_recipient_api_offers","summary":"List P2P marketplace offers visible to the holder","description":"Lists P2P swap offers the holder can accept (filterable by token_address). Payment alone gives access; do not send an API key. Direct /recipient-api/offers on…","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["offers"],"additionalProperties":true,"properties":{"offers":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}]},"post":{"operationId":"direct_post_recipient_api_offers","summary":"Create P2P swap offer","description":"Creates a P2P swap intent between two loyalty tokens. Direct /recipient-api/offers on https://api.loyalspark.online.","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"offer":{"type":"object","additionalProperties":true},"status":{"type":"string"},"message":{"type":"string"},"tx":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"offer_token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"offer_amount":{"type":"number","exclusiveMinimum":0},"request_token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"request_amount":{"type":"number","exclusiveMinimum":0}},"anyOf":[{"maxProperties":0},{"required":["offer_token_address","offer_amount","request_token_address","request_amount"]}],"x-bare-call-default":"view"}}}}}},"/recipient-api/workflow/reward-status":{"get":{"operationId":"direct_get_recipient_api_workflow_reward_status","summary":"Autonomous reward redemption status","description":"Returns the current reward redemption step and machine-readable next_actions[] for the holder. Direct /recipient-api/workflow/reward-status on https://api.loya…","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"reward":{"type":["object","null"],"additionalProperties":true},"balance":{"type":["object","null"],"additionalProperties":true},"workflow":{"type":"object","additionalProperties":true,"properties":{"workflow":{"type":"string"},"actor":{"type":"string"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"prerequisites":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"blocking_reason":{"type":["string","null"]}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"parameters":[{"name":"token_address","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"reward_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}]}},"/recipient-api/register":{"post":{"operationId":"direct_post_recipient_api_register","summary":"Register / refresh the recipient profile","description":"Idempotent: refreshes recipient profile metadata. Free. Direct /recipient-api/register on https://api.loyalspark.online.","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"api_key":{"type":"string"},"recipient_agent":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message","signature"],"additionalProperties":true,"properties":{"message":{"type":"string"},"signature":{"type":"string"},"agent_name":{"type":"string"}}}}}}}},"/recipient-api/prepare-transfer":{"post":{"operationId":"direct_post_recipient_api_prepare_transfer","summary":"Prepare B20/ERC-20 transfer calldata","description":"Returns B20/ERC-20 transfer calldata for the holder to send loyalty tokens to any address. Direct /recipient-api/prepare-transfer on https://api.loyalspark.onl…","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"note":{"type":"string"},"from_wallet":{"type":"string"},"program":{"type":"object","additionalProperties":true},"contract_call":{"type":"object","additionalProperties":true},"tx":{"type":"object","required":["to","data","value","chainId"],"properties":{"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"}}},"workflow":{"type":"object","additionalProperties":true,"properties":{"workflow":{"type":"string"},"actor":{"type":"string"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"prerequisites":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"blocking_reason":{"type":["string","null"]}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"token_address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"number","exclusiveMinimum":0}},"anyOf":[{"maxProperties":0},{"required":["token_address","to","amount"]}],"x-bare-call-default":"view"}}}}}},"/recipient-api/redeem-reward":{"post":{"operationId":"direct_post_recipient_api_redeem_reward","summary":"Redeem a reward","description":"Redeems a reward using a transfer tx hash; returns the issued voucher. Direct /recipient-api/redeem-reward on https://api.loyalspark.online.","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"voucher":{"type":"object","additionalProperties":true},"voucher_code":{"type":"string"},"voucher_id":{"type":"string"},"message":{"type":"string"},"workflow":{"type":"object","additionalProperties":true,"properties":{"workflow":{"type":"string"},"actor":{"type":"string"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"prerequisites":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"blocking_reason":{"type":["string","null"]}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"404":{"description":"HTTP 404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"reward_id":{"type":"string","format":"uuid"},"transaction_hash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"tx_hash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"anyOf":[{"maxProperties":0},{"required":["reward_id","transaction_hash"]}],"x-bare-call-default":"view"}}}}}},"/recipient-api/accept-offer":{"post":{"operationId":"direct_post_recipient_api_accept_offer","summary":"Accept a P2P swap offer (two-phase)","description":"Phase 1 (no transaction_hash): reserves the offer (active -> accepted) and returns approve + fillOffer escrow calldata. Phase 2: call again with transaction_ha…","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"offer":{"type":"object","additionalProperties":true},"status":{"type":"string"},"message":{"type":"string"},"tx":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"404":{"description":"HTTP 404","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"HTTP 409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer_id"],"additionalProperties":true,"properties":{"offer_id":{"type":"string","format":"uuid"},"onchain_offer_id":{"type":"number"},"transaction_hash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}}}}}}}},"/recipient-api/cancel-offer":{"post":{"operationId":"direct_post_recipient_api_cancel_offer","summary":"Cancel own P2P swap offer","description":"Cancels a P2P swap offer created by the holder. Direct /recipient-api/cancel-offer on https://api.loyalspark.online.","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"offer":{"type":"object","additionalProperties":true},"status":{"type":"string"},"message":{"type":"string"},"tx":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"HTTP 409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"offer_id":{"type":"string","format":"uuid"}},"anyOf":[{"maxProperties":0},{"required":["offer_id"]}],"x-bare-call-default":"view"}}}}}},"/recipient-api/workflow/prepare-reward-redemption":{"post":{"operationId":"direct_post_recipient_api_workflow_prepare_reward_redemption","summary":"Prepare reward redemption plan + transfer calldata","description":"One-shot planner: returns B20/ERC-20 transfer calldata for the reward cost plus workflow so the agent can broadcast then redeem. Direct /recipient-api/workflow…","tags":["Recipient REST"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"reward":{"type":"object","additionalProperties":true},"transfer_preparation":{"type":"object","additionalProperties":true},"balance":{"type":["object","null"],"additionalProperties":true},"message":{"type":"string"},"workflow":{"type":"object","additionalProperties":true,"properties":{"workflow":{"type":"string"},"actor":{"type":"string"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"prerequisites":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{"type":"object","additionalProperties":true}},"blocking_reason":{"type":["string","null"]}}}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"429":{"description":"HTTP 429","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"reward_id":{"type":"string","format":"uuid"}},"anyOf":[{"maxProperties":0},{"required":["reward_id"]}],"x-bare-call-default":"view"}}}}}},"/verify-agent-plan-payment":{"post":{"tags":["Billing"],"operationId":"verifyAgentPlanPayment","summary":"Agent/merchant plan payment info and USDC verify","description":"POST https://api.loyalspark.online/verify-agent-plan-payment. Actions: get_payment_info (treasury, per-plan limits, annual prices, required_sender_rule, steps)…","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["get_payment_info","verify_payment","retry_verification","admin_verify"]},"product":{"type":"string","enum":["agent","merchant"],"default":"agent"},"plan_slug":{"type":"string","enum":["pro","enterprise","starter","growth","scale"]},"billing_cycle":{"type":"string","enum":["monthly","annual"],"default":"monthly"},"transaction_hash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"subscription_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"string"},"subscription_wallet":{"type":"string"},"usdc_contract":{"type":"string"},"chain_id":{"type":"integer"},"required_sender_rule":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"plans":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"price_usdc_monthly":{"type":"number"},"annual_price_usdc":{"type":"number"},"max_api_calls_monthly":{"type":["integer","null"]},"max_mint_amount_monthly":{"type":["number","null"]},"max_agents":{"type":["integer","null"]},"transaction_fee_percent":{"type":["number","null"]},"limits":{"type":"object","additionalProperties":true}}}},"verified":{"type":"boolean"},"plan_effective":{"type":"boolean"},"effective_limits":{"type":"object","additionalProperties":true},"error_code":{"type":"string"},"next_steps":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"HTTP 400","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"401":{"description":"HTTP 401","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"403":{"description":"HTTP 403","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}},"409":{"description":"HTTP 409","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentError"}}}}}}}}}
