REST API Reference

The Reward Agent exposes all 45 tools as standard REST endpoints at /api/v1/*. Use any HTTP client — no MCP required.

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

Response Format

Success:

{
  "data": { ... },
  "meta": { "tool": "rsnc_agent_brand_info", "timestamp": "2026-03-05T00:00:00Z" }
}

Error:

{
  "error": { "message": "Brand not found", "code": "not_found", "status": 404 }
}

Error codes: auth_required (401), forbidden (403), validation (400), not_found (404), rate_limit (429), internal (500).

Authentication

Authenticated endpoints require the same HMAC-SHA256 headers used by MCP:

Header	Value
X-RSNC-Agent-Key	Your agent key ID
X-RSNC-Timestamp	Unix timestamp (seconds)
X-RSNC-Signature	HMAC-SHA256 signature

See Authentication for the signing process.

Rate Limits

Type	Limit
Public (unauthenticated)	100 requests/minute per IP
Authenticated	20 requests/minute per agent key (configurable)

---

Discovery

No authentication required.

Get Network Info

GET /api/v1/network/info

Returns chain configuration, contract addresses, and exchange rates.

curl https://agent.rsnc.network/api/v1/network/info

Get Network Stats

GET /api/v1/network/stats

Returns active brand count, user count, and reward totals.

List Brands

GET /api/v1/brands

Query Param	Type	Description
category	string	Filter by category (retail, gaming, dining, travel)
limit	number	Max brands to return (default: 50, max: 200)
offset	number	Pagination offset (default: 0)

curl "https://agent.rsnc.network/api/v1/brands?category=retail&limit=10"

Check Brand

GET /api/v1/brands/check

Query Param	Type	Description
query	string	Brand name, domain, or URL

curl "https://agent.rsnc.network/api/v1/brands/check?query=nike.com"

Brand Rankings

GET /api/v1/brands/rankings

Query Param	Type	Description
category	string	Filter by category
limit	number	Number of brands to rank (default: 10, max: 10)

---

Brand

No authentication required.

Get Brand Info

GET /api/v1/brands/:brandId

Returns reward program details: events, reward amounts, cooldown periods.

curl https://agent.rsnc.network/api/v1/brands/0xABC123

Get Brand Perks

GET /api/v1/brands/:brandId/perks

Query Param	Type	Description
category	string	Filter perks by category

---

User

Authentication required.

Get User Balance

GET /api/v1/users/:userId/brands/:brandId/balance

Returns current balance, total earned, total redeemed.

curl https://agent.rsnc.network/api/v1/users/[email protected]/brands/0xABC/balance \
  -H "X-RSNC-Agent-Key: your-key-id" \
  -H "X-RSNC-Timestamp: 1709500000" \
  -H "X-RSNC-Signature: <computed>"

Get User Stats

GET /api/v1/users/:userId/brands/:brandId/stats

Returns earnings, redemptions, streaks, and achievements.

Get User Portfolio

GET /api/v1/users/:userId/portfolio

Returns cross-brand balance breakdown, active streaks, and best affordable perk.

---

Rewards

Authentication required.

Process Event

POST /api/v1/events

{
  "brandId": "0xABC...",
  "eventType": "purchase",
  "userId": "[email protected]",
  "metadata": { "order_total": 50 }
}

curl -X POST https://agent.rsnc.network/api/v1/events \
  -H "Content-Type: application/json" \
  -H "X-RSNC-Agent-Key: your-key-id" \
  -H "X-RSNC-Timestamp: 1709500000" \
  -H "X-RSNC-Signature: <computed>" \
  -d '{"brandId":"0xABC","eventType":"purchase","userId":"[email protected]"}'

Process Bulk Events

POST /api/v1/events/bulk

{
  "events": [
    { "brandId": "0xABC", "eventType": "purchase", "userId": "[email protected]" },
    { "brandId": "0xABC", "eventType": "signup", "userId": "[email protected]" }
  ]
}

---

Perks

Browse is public; redeem requires authentication.

Browse Perks

GET /api/v1/perks

Query Param	Type	Description
category	string	Filter by perk category
maxPrice	number	Maximum RSNC cost
brandId	string	Scope to a specific brand
limit	number	Max perks to return (default: 20, max: 100)

curl "https://agent.rsnc.network/api/v1/perks?maxPrice=5000&limit=10"

Redeem Perk

POST /api/v1/perks/redeem

Authentication required.

{
  "perkId": "perk-123",
  "userId": "[email protected]",
  "brandId": "0xABC..."
}

---

Leaderboard

No authentication required.

Get Leaderboard

GET /api/v1/brands/:brandId/leaderboard

Query Param	Type	Description
metric	enum	rsnc_earned, streak, or activity (default: rsnc_earned)
period	enum	daily, weekly, monthly, or all_time (default: all_time)
limit	number	Max entries (default: 10, max: 100)

---

Growth

No authentication required.

Estimate ROI

POST /api/v1/growth/estimate-roi

{
  "industry": "retail",
  "monthlyCustomers": 5000,
  "averageOrderValue": 75
}

Request Info

POST /api/v1/growth/request-info

{
  "businessName": "Acme Corp",
  "contactEmail": "[email protected]",
  "website": "https://acme.com",
  "industry": "retail"
}

---

Onboarding

Authentication required + canOnboard permission.

Onboard Brand

POST /api/v1/onboarding/brands

{
  "brandAddress": "0xDEF...",
  "businessName": "Acme Corp",
  "contactEmail": "[email protected]",
  "website": "https://acme.com",
  "category": "retail",
  "description": "Premium retail brand"
}

Manage Keys

POST /api/v1/onboarding/keys

{
  "action": "rotate",
  "brandId": "0xDEF..."
}

Actions: rotate, revoke, status.

---

Analytics

No authentication required.

Network Analytics

GET /api/v1/analytics/network

Query Param	Type	Description
period	enum	7d, 30d, or 90d (default: 30d)

Brand Analytics

GET /api/v1/analytics/brands/:brandId

Query Param	Type	Description
period	enum	7d, 30d, or 90d (default: 30d)

Event Performance

GET /api/v1/analytics/brands/:brandId/events

Query Param	Type	Description
period	enum	7d, 30d, or 90d (default: 30d)

Perk Analytics

GET /api/v1/analytics/brands/:brandId/perks

Brand Health

GET /api/v1/analytics/brands/:brandId/health

Returns health score (0-100), letter grade, strengths, weaknesses, and recommendations.

---

Management

Authentication required + canManageProgram permission.

Create Event

POST /api/v1/brands/:brandId/events

{
  "eventType": "purchase",
  "rewardAmount": 10,
  "maxClaims": 0,
  "cooldownHours": 24
}

Update Event

PATCH /api/v1/brands/:brandId/events/:eventId

{
  "rewardAmount": 15,
  "enabled": true
}

Create Perk

POST /api/v1/brands/:brandId/perks

{
  "name": "10% Off Next Purchase",
  "description": "Get 10% off your next order",
  "priceInPoints": 500,
  "maxSupply": 100,
  "category": "discount"
}

Update Perk

PATCH /api/v1/brands/:brandId/perks/:collectionId

{
  "priceInPoints": 400,
  "isActive": true
}

---

Agent Rewards

Authentication required.

My Rewards

GET /api/v1/agent/rewards

Returns your agent's RSNC earnings, activity stats, and rate cap allowances.

Claim Reward

POST /api/v1/agent/rewards/claim

{
  "rewardType": "discovery",
  "brandAddress": "0xABC..."
}

Reward types: discovery (100 RSNC), onboarding (500 RSNC).

---

Comparison

No authentication required.

Compare Brands

GET /api/v1/compare/brands

Query Param	Type	Description
brandIds	string	Comma-separated brand IDs (2-5)
period	enum	7d, 30d, or 90d (default: 30d)

curl "https://agent.rsnc.network/api/v1/compare/brands?brandIds=0xAAA,0xBBB,0xCCC"

Compare Cashback

GET /api/v1/compare/cashback

Query Param	Type	Description
brandIds	string	Comma-separated brand IDs (2-10)
category	string	Category to auto-discover brands
purchaseAmount	number	Purchase amount in USD

Either brandIds or category is required.

curl "https://agent.rsnc.network/api/v1/compare/cashback?category=retail&purchaseAmount=100"

---

Recommendations

Best Deals

GET /api/v1/deals

No authentication required (personalized results need auth).

Query Param	Type	Description
intent	string	Shopping intent (e.g., "running shoes")
category	string	Direct category filter
userId	string	Optional user ID for personalized results
budget	number	Max perk cost to consider
limit	number	Max deals to return (default: 10)

Next Goal

GET /api/v1/users/:userId/goals

Authentication required.

Query Param	Type	Description
brandId	string	Focus on a specific brand
targetPerkId	string	Calculate path to a specific perk

---

Commerce Routing

Route Purchase

GET /api/v1/commerce/route

No authentication required.

Query Param	Type	Description
intent	string	What the user wants to buy
category	string	Direct category filter
purchaseAmount	number	Expected purchase amount in USD
userId	string	Optional user ID for personalized routing

curl "https://agent.rsnc.network/api/v1/commerce/route?intent=running+shoes&purchaseAmount=150"

Stack Deals

GET /api/v1/commerce/stack

Authentication required.

Query Param	Type	Description
brandId	string	The brand to optimize the deal for
purchaseAmount	number	Purchase amount in USD
userId	string	User ID to check redeemable perks

---

Intelligence

User-level tools require authentication; brand-level tools are public.

User Persona

GET /api/v1/intelligence/users/:userId/persona

Authentication required. Returns behavioral profile, persona archetype, affinities, and network position.

User Recommendations

GET /api/v1/intelligence/users/:userId/recommendations

Authentication required.

Query Param	Type	Description
limit	number	Max recommendations (default: 5, max: 20)

Perk Intelligence

GET /api/v1/intelligence/brands/:brandId/perks

No auth required. Returns heat scores, conversion funnels, supply depletion rates.

Perk Audience

GET /api/v1/intelligence/brands/:brandId/perks/:collectionId/audience

No auth required. Returns persona breakdown of users who claimed this perk.

Brand Audience

GET /api/v1/intelligence/brands/:brandId/audience

No auth required. Returns user persona distribution, engagement levels, platform split.

---

Network Intelligence

No authentication required.

Network Flows

GET /api/v1/network/flows

Query Param	Type	Description
period	enum	7d, 30d, or 90d (default: 30d)

Shows how users flow between brands — emitters vs attractors.

Network Trending

GET /api/v1/network/trending

Query Param	Type	Description
period	enum	7d, 30d, or 90d (default: 7d)
limit	number	Max trending items per category (default: 10, max: 50)

---

Suggestions

No authentication required.

Suggest Events

GET /api/v1/brands/:brandId/suggestions/events

AI-recommended reward event configurations based on network-wide patterns.

Suggest Perks

GET /api/v1/brands/:brandId/suggestions/perks

AI-recommended perk configurations based on audience composition and balance distribution.

---

Converse

POST /api/v1/converse

Authentication required + pro/enterprise tier.

Natural language queries processed through a Plan → Execute → Synthesize pipeline.

{
  "query": "Which brand gives the best cashback for a $100 purchase in retail?"
}

See Converse for full documentation.