Reward Agent Tools Reference
The Reward Agent provides 45 tools across 17 modules. 27 tools are public (no auth required), and 18 require HMAC authentication.
Discovery Tools
Browse and search the Resonance network. No authentication required.
rsnc_agent_network_info
Returns info about the Resonance rewards network — chain configuration, contract addresses, and exchange rates.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) |
rsnc_agent_list_brands
Search and browse brands offering cashback, rewards, and deals.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | Filter by category (e.g., "retail", "gaming", "dining", "travel") |
limit | number | No | Max brands to return (default: 50, max: 200) |
offset | number | No | Pagination offset (default: 0) |
rsnc_agent_network_stats
Returns how many brands, users, and rewards are active across the network.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) |
rsnc_agent_check_brand
Check if a brand or website is on the network. Returns program details if found, or info on how to join.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Brand name, domain, or URL (e.g., "nike.com", "Starbucks") |
rsnc_agent_brand_rankings
See which brands offer the most rewards, best cashback rates, or most active programs.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | Filter by category |
limit | number | No | Number of brands to rank (default: 10, max: 10) |
Brand Tools
Get details about specific brands. No authentication required.
rsnc_agent_brand_info
Get a brand's reward program details: what actions earn cashback, reward amounts, and cooldown periods.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
rsnc_agent_brand_perks
Browse a brand's available rewards — discounts, free products, exclusive access, and more.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
category | string | No | Filter perks by category |
User Tools
Check user balances, activity, and cross-brand portfolio. Authentication required.
rsnc_agent_user_balance
Check how much cashback a user has earned and can spend.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User identifier (email or wallet address) |
brandId | string | Yes | The brand identifier |
rsnc_agent_user_stats
Get a user's complete reward profile: earnings, redemptions, streaks, and achievements.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User identifier (email or wallet address) |
brandId | string | Yes | The brand identifier |
rsnc_agent_user_portfolio
Get a unified view of a user's rewards across ALL brands — total balance, per-brand breakdown, active streaks, and the best perk they can afford right now. The cross-brand loyalty dashboard.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User identifier (email or wallet address) |
Reward Tools
Process reward events. Authentication required.
rsnc_agent_process_event
Record a qualifying action (purchase, signup, review, referral) to earn cashback for a user.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
eventType | string | Yes | Event type (e.g., "purchase", "review", "referral") |
userId | string | Yes | User email address |
metadata | object | No | Optional metadata to attach |
rsnc_agent_process_bulk
Record multiple events in one request — batch purchases, signups, or engagement events.
| Parameter | Type | Required | Description |
|---|---|---|---|
events | array | Yes | Array of events, each with brandId, eventType, userId, and optional metadata |
Perks Tools
Browse and redeem perks. Browse is public; redeem requires authentication.
rsnc_agent_browse_perks
Search for deals and rewards across all brands or filter by category and budget. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | Filter by perk category |
maxPrice | number | No | Maximum RSNC cost |
brandId | string | No | Scope to a specific brand |
limit | number | No | Max perks to return (default: 20, max: 100) |
rsnc_agent_redeem_perk
Claim a reward for a user using their earned cashback. Authentication required.
| Parameter | Type | Required | Description |
|---|---|---|---|
perkId | string | Yes | The perk ID to redeem |
userId | string | Yes | User identifier (email or wallet) |
brandId | string | Yes | The brand identifier |
Leaderboard Tools
View rankings. No authentication required.
rsnc_agent_leaderboard
See top earners and most active customers for a brand.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
metric | enum | No | rsnc_earned, streak, or activity (default: rsnc_earned) |
period | enum | No | daily, weekly, monthly, or all_time (default: all_time) |
limit | number | No | Max entries (default: 10, max: 100) |
Growth Tools
Business evaluation and lead capture. No authentication required.
rsnc_agent_estimate_roi
Estimate the ROI of adding a Resonance cashback program based on industry and business metrics.
| Parameter | Type | Required | Description |
|---|---|---|---|
industry | enum | Yes | retail, dining, travel, gaming, or other |
monthlyCustomers | number | No | Estimated monthly customers |
averageOrderValue | number | No | Average transaction value in USD |
rsnc_agent_request_info
Request information about adding Resonance to a business. Captures contact details.
| Parameter | Type | Required | Description |
|---|---|---|---|
businessName | string | Yes | Name of the business |
contactEmail | string | Yes | Contact email (valid email format) |
website | string | No | Business website URL |
industry | string | No | Business industry category |
Onboarding Tools
Register brands on the network. Authentication required + canOnboard permission.
rsnc_agent_onboard_brand
Register a new brand, generate credentials, and send a welcome email.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandAddress | string | Yes | Brand's wallet address (0x-prefixed, 40+ hex chars) |
businessName | string | Yes | Brand/business name |
contactEmail | string | Yes | Contact email (becomes portal login) |
website | string | No | Brand website URL |
category | string | No | Industry category |
description | string | No | Short business description |
rsnc_agent_manage_keys
Manage API keys for brands you onboarded. Rotate, revoke, or check status.
| Parameter | Type | Required | Description |
|---|---|---|---|
action | enum | Yes | rotate, revoke, or status |
brandId | string | Yes | Brand wallet address |
Analytics Tools
View performance metrics. No authentication required.
rsnc_agent_network_analytics
Real-time network analytics: users, brands, rewards, trending categories, and growth metrics.
| Parameter | Type | Required | Description |
|---|---|---|---|
period | enum | No | 7d, 30d, or 90d (default: 30d) |
rsnc_agent_brand_analytics
Deep analytics for a specific brand: daily trends, customer velocity, event activity, and program health.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
period | enum | No | 7d, 30d, or 90d (default: 30d) |
rsnc_agent_event_performance
Per-event metrics: claim rates, unique users, and reward efficiency.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
period | enum | No | 7d, 30d, or 90d (default: 30d) |
rsnc_agent_perk_analytics
Perk collection performance: redemption rates, popularity, supply utilization.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
rsnc_agent_brand_health
Program health assessment with data-driven recommendations. Returns a score (0-100) and letter grade.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
Returns: Health score, grade (A/B/C/D), breakdown (event diversity, claim activity, perk availability, customer growth), strengths, weaknesses, and recommendations.
Management Tools
Create and update events and perks. Authentication required + canManageProgram permission.
rsnc_agent_create_event
Create a new reward event defining what user actions earn cashback.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | Brand wallet address |
eventType | enum | Yes | purchase, signup, review, referral, or custom |
rewardAmount | number | Yes | RSNC tokens per claim (> 0) |
maxClaims | number | No | Max total claims, 0 = unlimited (default: 0) |
cooldownHours | number | No | Hours between claims per user (default: 24) |
customName | string | No | Required when eventType is "custom" |
detectionMethod | enum | No | webhook, form_submission, or api_webhook (default: webhook) |
Data gates: Warns if brand has < 14 days of data (does not block).
rsnc_agent_update_event
Update an existing event's configuration.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | Brand wallet address |
eventId | string | Yes | Event identifier to update |
rewardAmount | number | No | New RSNC per claim (> 0) |
maxClaims | number | No | New max claims (0 = unlimited) |
cooldownHours | number | No | New cooldown in hours |
enabled | boolean | No | Enable or disable the event |
At least one optional field must be provided. Data gates: Warns if event has < 50 claims in last 90 days when changing reward amount.
rsnc_agent_create_perk
Create a new perk collection.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | Brand wallet address |
name | string | Yes | Display name |
description | string | Yes | What the user receives |
priceInPoints | number | Yes | RSNC cost to redeem (> 0) |
maxSupply | number | Yes | Total supply (> 0) |
maxPerUser | number | No | Max redemptions per user (default: 1) |
category | string | No | Perk category (e.g., "discount", "freebie", "vip") |
tags | string[] | No | Tags for search and filtering |
Data gate: Brand must have at least one active reward event.
rsnc_agent_update_perk
Update a perk collection's configuration.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | Brand wallet address |
collectionId | number | Yes | Perk collection ID |
priceInPoints | number | No | New RSNC cost (> 0) |
maxSupply | number | No | New total supply (> 0) |
isActive | boolean | No | Enable or disable |
description | string | No | New description |
At least one optional field must be provided. Data gates: Warns if perk is < 7 days old when changing price.
Agent Rewards Tools
Track and claim rewards for agent activity. Authentication required.
rsnc_agent_my_rewards
Check your agent's RSNC earnings, activity stats, and rate cap allowances.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) |
rsnc_agent_claim_reward
Claim a reward for a valuable agent action.
| Parameter | Type | Required | Description |
|---|---|---|---|
rewardType | enum | Yes | discovery (100 RSNC) or onboarding (500 RSNC) |
brandAddress | string | Yes | The brand address for this action |
Comparison Tools
Compare brands side-by-side. No authentication required.
rsnc_agent_compare_brands
Compare 2-5 brands across all performance metrics with per-metric winners and insights.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandIds | string[] | Yes | 2-5 brand identifiers to compare |
period | enum | No | 7d, 30d, or 90d (default: 30d) |
Metrics compared: Velocity, customers reached, transactions, RSNC distributed, event diversity, event claims, active perks, perk claims.
rsnc_agent_compare_cashback
Compare cashback rates across brands for a specific purchase amount. Shows exactly how much you earn at each brand — "Buy $100 at Brand A = $8 back vs Brand B = $3 back". The key decision tool for purchase routing.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandIds | string[] | No | Brands to compare (2-10). Omit to auto-discover via category. |
category | string | No | Category to auto-discover brands (retail, dining, travel, gaming) |
purchaseAmount | number | Yes | Purchase amount in USD to calculate exact cashback |
Either brandIds or category must be provided for brand discovery.
Commerce Routing Tools
The core "driver" capabilities that turn the agent from a loyalty dashboard into an active commerce participant. route_purchase is public; stack_deals requires authentication for personalized deal stacking.
rsnc_agent_route_purchase
Find the best brand to buy from based on cashback and rewards. Given a shopping intent, compares all matching brands and ranks them by total reward value — cashback earned, perks redeemable, and effective savings. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
intent | string | Yes | What the user wants to buy (e.g., "running shoes", "coffee") |
category | string | No | Direct category filter (retail, dining, travel, gaming) |
purchaseAmount | number | No | Expected purchase amount in USD |
userId | string | No | Optional user ID for personalized routing |
rsnc_agent_stack_deals
Calculate the optimal deal stack for a specific purchase at a specific brand. Combines base cashback + best redeemable perk + active promotions to show total savings. Use after route_purchase to maximize value at the chosen brand. Authentication required.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand to optimize the deal for |
purchaseAmount | number | Yes | Purchase amount in USD |
userId | string | Yes | User ID to check redeemable perks against their balance |
Returns: Base cashback rate and amount, best redeemable perk with discount code, streak multiplier bonus, and total savings breakdown.
Recommendation Tools
Smart deal matching and goal-based engagement nudges. best_deals is public; next_goal requires authentication.
rsnc_agent_best_deals
Find the best cashback deals and rewards matching a shopping intent. Searches brands by category, ranks by reward value, and optionally personalizes results based on user balances. No auth required (personalized results need auth).
| Parameter | Type | Required | Description |
|---|---|---|---|
intent | string | Yes | What the user wants to do (e.g., "buy running shoes", "get coffee") |
category | string | No | Direct category filter — overrides intent-based matching |
userId | string | No | Optional user ID for personalized results (balance, affordable perks) |
budget | number | No | Optional max perk cost to consider |
limit | number | No | Maximum deals to return (default: 10) |
rsnc_agent_next_goal
Calculate the fastest path to a user's next attainable reward. Shows exactly how many actions (purchases, reviews, referrals) are needed to afford a specific perk. Creates urgency and drives engagement. Authentication required.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User identifier (email or wallet address) |
brandId | string | No | Focus on a specific brand (omit to find best goal across all active brands) |
targetPerkId | string | No | Calculate path to a specific perk (omit to find most attainable) |
Intelligence Tools
Behavioral profiling, personalized recommendations, and audience analytics. User-level tools require authentication; brand-level tools are public.
rsnc_agent_user_persona
Get a user's behavioral profile: earn patterns, persona archetype, tag/brand affinities, price preferences, and network position. Authentication required.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User identifier (email or wallet address) |
Returns: Persona archetype (e.g., "deal_hunter", "loyal_advocate", "casual_earner"), earn patterns, brand affinities, price sensitivity, and network position metrics.
rsnc_agent_user_recommendations
Get personalized perk recommendations for a user, scored by persona affinity and affordability. Authentication required.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | User identifier (email or wallet address) |
limit | number | No | Maximum recommendations to return (default: 5, min: 1, max: 20) |
Returns: Ranked list of perks with affinity scores, affordability status, and reasoning.
rsnc_agent_perk_intelligence
Get intelligence on a brand's perks: heat scores, conversion funnels, supply depletion rates, and retention impact. Helps optimize perk catalogs. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
Returns: Per-perk heat scores, conversion rates, supply depletion projections, and catalog optimization recommendations.
rsnc_agent_perk_audience
Get the persona breakdown of users who claimed a specific perk: archetypes, engagement levels, and platform distribution. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
collectionId | number | Yes | The perk collection ID |
Returns: Archetype distribution, engagement levels, platform breakdown, and audience insights.
rsnc_agent_brand_audience
Get a brand's user persona distribution: archetype breakdown, engagement levels, platform split, and archetype drift over time. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
Returns: Archetype breakdown, engagement level distribution, platform split, and drift trends.
Network Intelligence Tools
Cross-brand flow analysis and trending data. No authentication required.
rsnc_agent_network_flows
See how users flow between brands across the network. Shows which brands are emitters (users leave to redeem elsewhere) vs attractors (users come to redeem). All data is anonymous and category-level. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
period | enum | No | 7d, 30d, or 90d (default: 30d) |
Returns: Brand-to-brand flow data, emitter/attractor classification, category-level movement patterns, and network health metrics.
rsnc_agent_network_trending
See what's trending across the Resonance network: hottest perk categories, fastest growing brand categories, and overall network health metrics. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
period | enum | No | 7d, 30d, or 90d (default: 7d) |
limit | number | No | Maximum trending items per category (default: 10, min: 1, max: 50) |
Returns: Trending perk categories, fastest growing brand categories, network health summary, and momentum indicators.
Suggestion Tools
AI-powered event and perk recommendations for brands. No authentication required.
rsnc_agent_suggest_events
Get AI-recommended reward event configurations for a brand. Analyzes what event types, reward amounts, and cooldowns work best in the brand's category based on network-wide patterns. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
Returns: Recommended event types with suggested reward amounts, cooldown periods, and projected engagement impact.
rsnc_agent_suggest_perks
Get AI-recommended perk configurations for a brand. Suggests perk types, pricing, and supply limits based on audience composition and balance distribution patterns. No auth required.
| Parameter | Type | Required | Description |
|---|---|---|---|
brandId | string | Yes | The brand identifier |
Returns: Recommended perk configurations with suggested pricing, supply limits, categories, and projected redemption rates.