# Resonance — Open-Loop Loyalty Infrastructure (Full Reference)

> Resonance is a loyalty network that brands plug into. You define what actions earn credits, and your customers earn those credits by participating — across Discord, Telegram, Slack, your website, your app, or anywhere you integrate. Credits are spendable on perks offered by any brand in the network.

## Key Facts

- Token: RSNC (on Soneium mainnet)
- Zero blockchain complexity — users don't need wallets or crypto knowledge
- Gasless transactions — all blockchain fees covered
- Open-loop — credits earned on any platform are spendable across the entire network
- Built on Cloudflare Workers for global, low-latency performance
- 45 MCP tools across 17 modules for AI-powered loyalty management
- OpenAPI spec: https://docs.rsnc.network/openapi.yaml

## Smart Contracts (Soneium Mainnet)

- RSNC Token: 0x4183CD8fE04bA0f10Ca83cf9E76e58ef8dB7cb33
- PerkNFT: 0x997f05E7447Fdde75d47eBb12D4D6C65013AA0Da
- PointsSale: 0x02939031C36637a4c46d86832D7015a2F350cc7D

## URLs

- Partner Portal: https://partners.rsnc.network
- Event Handler API: https://api.rsnc.network/resonance-api/manual-event
- Gas Relayer: https://relayer.rsnc.network/relay
- Reward Agent: https://agent.rsnc.network
- Perks Marketplace: https://perks.rsnc.network
- Documentation: https://docs.rsnc.network

---

## Authentication (HMAC-SHA256)

All server-to-server API calls use HMAC-SHA256 signatures.

Headers:
- `X-Resonance-Brand-Id`: Your brand address (0x...)
- `X-Resonance-Signature`: HMAC-SHA256 hex digest
- `X-Resonance-Timestamp`: Unix timestamp in milliseconds

String-to-sign format: `{timestamp}:{brandId}:{requestBody}`

---

## Event Handler API

**Endpoint:** `POST https://api.rsnc.network/resonance-api/manual-event`

**Request Body:**
```json
{
  "brandId": "0xYourBrandId",
  "eventType": "custom_action",
  "userEmail": "platform_userId@rsnc.network",
  "metadata": {}
}
```

**Response:**
```json
{
  "success": true,
  "rewardAmount": 10,
  "txHash": "0x..."
}
```

---

## Gas Relayer API

**Endpoint:** `POST https://relayer.rsnc.network/relay`

Executes gasless ERC-20 permit+transfer transactions.

---

## OAuth Pregeneration API

**Endpoint:** `POST https://api.rsnc.network/resonance-api/pregen`

Creates wallets for users before they sign up. Supports: Discord, Twitter, GitHub, Google, Telegram, Spotify, Instagram, TikTok.

---

## User Identification

Format: `{platform}_{userId}@rsnc.network`

Examples:
- `discord_123456789@rsnc.network`
- `telegram_987654321@rsnc.network`
- `mygame_player42@rsnc.network`
- `user@email.com` (direct email)

---

## Reward Agent — 45 MCP Tools (17 Modules)

Access via MCP, REST API, CLI, A2A, or Converse.

### MCP Configuration
```json
{
  "mcpServers": {
    "resonance-agent": {
      "url": "https://agent.rsnc.network/mcp"
    }
  }
}
```

### All 45 Tools by Module

**Network (2 tools — public)**
- `network_info` — Network overview, stats, supported platforms
- `network_health` — Service health status

**Brand (4 tools — mixed)**
- `brand_list` — List brands with filtering (public)
- `brand_detail` — Brand details and configuration (public)
- `brand_analytics` — Engagement analytics with time range (authenticated)
- `brand_audience` — Audience composition insights (authenticated)

**User (4 tools — mixed)**
- `user_balance` — Check RSNC balance (public)
- `user_history` — Transaction history (public)
- `user_persona` — AI-generated behavioral profile (authenticated)
- `user_recommendations` — Personalized recommendations (authenticated)

**Event (3 tools — mixed)**
- `event_list` — List available events for a brand (public)
- `event_detail` — Event configuration details (public)
- `event_trigger` — Trigger a reward event (authenticated)

**Perk (5 tools — mixed)**
- `perk_list` — Browse available perks (public)
- `perk_detail` — Perk details and eligibility (public)
- `perk_claim` — Claim/redeem a perk (authenticated)
- `perk_intelligence` — Perk performance analytics (authenticated)
- `perk_audience` — Perk audience analysis (authenticated)

**Leaderboard (2 tools — public)**
- `leaderboard_get` — Get rankings by metric and period
- `leaderboard_position` — User's position on leaderboard

**Streak (2 tools — public)**
- `streak_status` — Current streak info with milestones
- `streak_history` — Historical streak data

**Achievement (3 tools — public)**
- `achievement_list` — Available achievements for a brand
- `achievement_detail` — Achievement requirements and progress
- `achievement_progress` — User's progress on achievements

**Wallet (2 tools — mixed)**
- `wallet_lookup` — Find wallet by email (public)
- `wallet_create` — Create wallet via OAuth pregeneration (authenticated)

**Transaction (2 tools — public)**
- `transaction_status` — Check transaction status
- `transaction_history` — Transaction history with filters

**Gas Relayer (1 tool — authenticated)**
- `gas_relay` — Execute gasless token transfer

**Admin (2 tools — authenticated)**
- `admin_configure` — Update brand configuration
- `admin_create_event` — Create new event type

**Intelligence (3 tools — authenticated)**
- `user_persona` — Generate AI behavioral profile
- `user_recommendations` — Personalized user recommendations
- `perk_intelligence` — Perk performance analytics

**Network Intelligence (2 tools — authenticated)**
- `network_flows` — Cross-brand token flow analysis
- `network_trending` — Trending brands, events, perks

**Suggestions (2 tools — authenticated)**
- `suggest_events` — AI-suggested events for a brand
- `suggest_perks` — AI-suggested perks for a brand

**OAuth (3 tools — mixed)**
- `oauth_providers` — List supported OAuth providers (public)
- `oauth_status` — Check pregeneration status (public)
- `oauth_pregen` — Pregenerate wallet (authenticated)

**Platform (3 tools — public)**
- `platform_list` — Supported platforms
- `platform_features` — Features for a platform
- `platform_compare` — Compare platforms

---

## REST API — 45 Endpoints

Base URL: `https://agent.rsnc.network/api/v1`

### Public Endpoints (no auth)
- `GET /network/info`
- `GET /network/health`
- `GET /brands`
- `GET /brands/:brandId`
- `GET /users/:identifier/balance`
- `GET /users/:identifier/history`
- `GET /brands/:brandId/events`
- `GET /brands/:brandId/events/:eventId`
- `GET /brands/:brandId/perks`
- `GET /brands/:brandId/perks/:perkId`
- `GET /brands/:brandId/leaderboard`
- `GET /brands/:brandId/leaderboard/:identifier/position`
- `GET /users/:identifier/streak`
- `GET /users/:identifier/streak/history`
- `GET /brands/:brandId/achievements`
- `GET /brands/:brandId/achievements/:achievementId`
- `GET /users/:identifier/achievements/progress`
- `GET /wallets/:email`
- `GET /transactions/:txHash`
- `GET /users/:identifier/transactions`
- `GET /oauth/providers`
- `GET /oauth/status/:email`
- `GET /platforms`
- `GET /platforms/:platform/features`
- `GET /platforms/compare`

### Authenticated Endpoints (HMAC required)
- `POST /events/trigger`
- `POST /perks/:perkId/claim`
- `POST /wallets/create`
- `POST /gas/relay`
- `PUT /admin/config`
- `POST /admin/events`
- `GET /brands/:brandId/analytics`
- `GET /brands/:brandId/audience`
- `GET /users/:identifier/persona`
- `GET /users/:identifier/recommendations`
- `GET /brands/:brandId/perks/:perkId/intelligence`
- `GET /brands/:brandId/perks/:perkId/audience`
- `GET /network/flows`
- `GET /network/trending`
- `GET /brands/:brandId/suggestions/events`
- `GET /brands/:brandId/suggestions/perks`
- `POST /oauth/pregen`
- `POST /converse`

---

## CLI Commands (`rsnc`)

Install: `npm install -g @resonance/cli`

### Command Groups
- `rsnc network info|health` — Network information
- `rsnc brand list|detail|analytics|audience` — Brand management
- `rsnc user balance|history|persona|recommendations` — User queries
- `rsnc event list|detail|trigger` — Event operations
- `rsnc perk list|detail|claim|intelligence|audience` — Perk operations
- `rsnc leaderboard get|position` — Leaderboard queries
- `rsnc streak status|history` — Streak information
- `rsnc achievement list|detail|progress` — Achievement tracking
- `rsnc wallet lookup|create` — Wallet operations
- `rsnc tx status|history` — Transaction queries
- `rsnc gas relay` — Gasless transfers
- `rsnc admin config|create-event` — Admin operations
- `rsnc intel persona|recommendations|perk-intel|flows|trending` — Intelligence
- `rsnc suggest events|perks` — AI suggestions
- `rsnc oauth providers|status|pregen` — OAuth management

---

## Discord Bot — Slash Commands

### Member Commands
- `/join` — Claim welcome bonus (one-time)
- `/daily` — Daily check-in with streak bonuses
- `/claim <event_id>` — Claim a specific reward event
- `/balance` — Check RSNC balance (works in DMs)
- `/streak` — View streak status and milestones
- `/achievements` — View unlocked achievements
- `/voice check` — View voice channel time progress
- `/voice claim` — Claim voice time rewards
- `/perks` — Browse available perks
- `/perk-buy id:<id>` — Purchase a perk with RSNC
- `/buy-role list|info` — View and purchase roles
- `/leaderboard` — Server rankings (type, period filters)
- `/help` — Get help on commands and topics
- `/roles` — View loyalty roles and effects
- `/link steam|unlink|status` — Link external accounts
- `/activity` — View activity patterns
- `/game-night create|active|join` — Gaming events

### Admin Commands — Setup
- `/setup wizard` — Guided setup wizard
- `/setup connect brand_id security_key` — Connect to brand
- `/setup status` — Connection health
- `/setup check` — Permission audit
- `/setup disconnect` — Remove connection
- `/setup security-key` — Update HMAC key

### Admin Commands — Configuration
- `/config events` — Enable/disable events
- `/config reward` — Set reward amounts
- `/config streaks` — Streak settings
- `/config stacking` — Role bonus stacking mode
- `/config channels` — Include/exclude channels
- `/config user` — Enable/disable users
- `/config test-mode` — Safe testing mode
- `/config admin-roles` — Admin permissions
- `/config admin-channel` — Admin channel
- `/config third-party view` — Third-party bot integrations
- `/config voice` — Voice channel settings
- `/config role-bonus` — Role bonus multipliers

### Admin Commands — Rewards & Drops
- `/reward @user` — Manual reward distribution
- `/drop` — Create button or reaction drops
- `/reaction-drop` — Legacy reaction drops
- `/watch start|stop|list` — Auto-drops for channels

### Admin Commands — Perks
- `/perk create|edit|delete|list` — Manage perks

### Admin Commands — Analytics
- `/stats` — Dashboard (period, breakdown, compare)
- `/kpi set|report|list|compare` — KPI targets
- `/kpi alert-config` — Metric alerts
- `/kpi compound-alert create|list|view|remove|toggle|history` — Multi-condition alerts
- `/kpi custom-metric create|list|view|edit|remove|test` — Formula-based metrics
- `/kpi preset list|view|apply|create|remove` — Save configurations
- `/kpi role-alerts set|list|remove` — Role-based alert routing
- `/segments list|view` — User segmentation
- `/audit` — Audit logs with filtering and CSV export
- `/export` — Export data (rewards, audit, users, config)
- `/reports schedule|preview|disable|list` — Automated reports

### Admin Commands — Goals
- `/goals set|progress|celebrate|remove` — Community goals

### Admin Commands — Testing
- `/test all` — Full diagnostic suite
- `/test connectivity` — Service connections
- `/test permissions` — Bot permissions
- `/test config` — Configuration validation
- `/test reward` — Dry-run reward pipeline
- `/test reward-live` — Live reward test (net 0)
- `/test write` — Database write test
- `/test cron` — CRON activity test
- `/test gateway` — Natural participation test
- `/test report` — Full diagnostic report

### Default Events (Auto-Created)
1. `daily_checkin` — GM/GN messages, 24h cooldown, 2 RSNC
2. `news_tracker` — Reaction engagement, 1 claim per instance, 5 RSNC
3. `regular_engagement` — Quality messages (100+ chars), 5/day max, 10 RSNC

---

## Telegram Bot — Slash Commands

### Member Commands
- `/start` — Initialize bot
- `/daily` — Daily check-in
- `/balance` — Check RSNC balance
- `/streak` — View streak status
- `/leaderboard` — Group rankings
- `/perks` — Browse perks
- `/achievements` — View achievements
- `/help` — Get help

### Admin Commands
- `/setup <brand_id> <security_key>` — Connect group
- `/config` — Configuration options
- `/stats` — Analytics dashboard
- `/reward` — Manual rewards

---

## Slack Bot — Commands

### Member Commands
- `/resonance daily` — Daily check-in
- `/resonance balance` — Check RSNC balance
- `/resonance streak` — View streak status
- `/resonance leaderboard` — Workspace rankings
- `/resonance perks` — Browse perks
- `/resonance help` — Get help

### Admin Commands
- `/resonance setup <brand_id> <security_key>` — Connect workspace
- `/resonance config` — Configuration options
- `/resonance stats` — Analytics dashboard

---

## Shared Services

All platforms share:
- **Streak Service** — Track consecutive daily activity with configurable milestones, multipliers, and freeze protection
- **Leaderboard Service** — Rankings by rsnc_earned, activity, streak, claims with daily/weekly/monthly/all-time periods
- **Achievement Service** — Configurable milestones with progress tracking and unlock rewards
- **Perks Service** — Create, manage, redeem perks across the network with inventory and eligibility rules
- **Community Service** — Cross-platform user profiles and identity resolution

---

## Integrations Available

| Platform | Status | Setup Time |
|----------|--------|------------|
| Discord | Production | 5 min |
| Telegram | Production | 5 min |
| Slack | Production | 5 min |
| Custom HTTP | Production | 30-60 min |
| Shopify | Production | 15-30 min |
| Reward Agent (MCP/REST/CLI) | Production | 2 min |

---

## Support

- Discord: https://discord.gg/rsnc-network
- Email: support@rsnc.network
- Developers: developers@rsnc.network
- Partner Portal: https://partners.rsnc.network
- Documentation: https://docs.rsnc.network