Rewards

The Rewards API manages the gamification system including points, missions, challenges, referrals, and access keys. Points are earned through trading activity, completing missions, login streaks, and referrals. Most rewards endpoints require authentication.

Endpoints

Method	Path	Auth	Description
GET	`/api/v1/rewards`	Bearer	Get user rewards dashboard
GET	`/api/v1/rewards/points-history`	Bearer	Get points history for chart
PATCH	`/api/v1/rewards/missions/:id`	Bearer	Complete a mission
POST	`/api/v1/rewards/missions/social-post`	Bearer	Report a social post for mission progress
POST	`/api/v1/rewards/missions/feature-use`	Bearer	Report a feature use for mission progress
GET	`/api/v1/rewards/referrals`	Bearer	Get referral details
GET	`/api/v1/rewards/challenges`	Bearer	Get active challenges
GET	`/api/v1/rewards/access-keys/mine`	Bearer	Get user's access keys
POST	`/api/v1/rewards/access-keys/generate`	Bearer	Generate a new access key
GET	`/api/v1/rewards/access-keys/remaining`	Public	Get remaining beta slots
PUT	`/api/v1/rewards/referral-code`	Bearer	Set a custom referral code
GET	`/api/v1/rewards/referral-code/check`	Bearer	Check referral code availability
GET	`/api/v1/rewards/referral-tree`	Bearer	Get 3-layer referral tree
GET	`/api/v1/rewards/leaderboard`	Bearer	Get points leaderboard

Rewards Dashboard

Get a comprehensive overview of the user's rewards data including points balance, active missions, streaks, and level progress.

// GET /api/v1/rewards

// Response 200
{
  "points": 4250,
  "level": 5,
  "streak": {
    "current": 7,
    "longest": 14,
    "lastLoginDate": "2026-03-27"
  },
  "missions": [
    {
      "id": "mission-uuid-123",
      "title": "Place 5 Trades",
      "description": "Place 5 trades on any market",
      "reward": 100,
      "progress": 3,
      "target": 5,
      "completed": false,
      "type": "daily"
    }
  ],
  "rank": 42,
  "nextLevelPoints": 5000
}

Complete Mission

Mark a mission as complete and claim its point reward. The backend validates that the mission's requirements have been met before awarding points.

// PATCH /api/v1/rewards/missions/mission-uuid-123

// Response 200
{
  "missionId": "mission-uuid-123",
  "pointsAwarded": 100,
  "newTotal": 4350
}

Points History

Get a time-series of points earned, useful for rendering a points growth chart.

Query Parameters:

Parameter	Type	Description
`range`	string	Time range for the history data

Referrals

Get details about the user's referral activity including referral code, number of referrals, and earnings.

// GET /api/v1/rewards/referrals

// Response 200
{
  "referralCode": "FRIEND123",
  "customCode": "MYCODE",
  "totalReferrals": 8,
  "totalEarnings": 320,
  "referrals": [
    {
      "walletAddress": "0xabcd...1234",
      "joinedAt": "2026-03-20T10:00:00.000Z",
      "pointsEarned": 40
    }
  ]
}

Access Keys

Users earn access keys that can be shared to invite others to the beta. Keys are allocated based on points and engagement.

// GET /api/v1/rewards/access-keys/mine

// Response 200
{
  "keys": [
    {
      "key": "VEZTA-ABCD-1234",
      "status": "unused",
      "createdAt": "2026-03-25T12:00:00.000Z"
    }
  ]
}

Notes

Points are tracked in a ledger (PointsLedger) with source attribution for auditability
Missions reset on different schedules: daily, weekly, or one-time
The referral system supports a 3-layer tree structure for multi-level referral tracking
The feature-use endpoint accepts a feature string to track usage of specific platform features for mission progress
The remaining beta slots endpoint is public and does not require authentication