Points System

The points system rewards users for engaging with the platform. You earn points by completing various actions such as creating a nickname, generating a referral code, completing KYC, and referring other users. This guide covers how to view your points, check your ranking position, and see the overall leaderboard.

Overview

The points system provides gamification features that reward user engagement:

  • Earn Points - Complete actions to earn points automatically
  • Track Ranking - See your position in the leaderboard
  • View Leaderboard - See top users by points
  • Achievement Rewards - Points are awarded for various achievements

How Points Work

Points are automatically awarded when you complete certain actions:

  • Creating a Nickname - 1,000 points
  • Creating a Referral Code - 1,000 points
  • Being Referred - 100 points (for the referrer)
  • Completing KYC - 5,000 points

Points are tracked per tenant and cannot be transferred between users.

Prerequisites

Before viewing points, ensure you have:

  • Completed authentication and have a valid access token
  • Created a nickname (required for viewing your position)

Get Your Position

Retrieve your current position in the points ranking, along with your nickname and total points.

Get your position

curl -X GET https://api.example.com/api/points/position \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Position retrieved successfully",
  "data": {
    "position": 5,
    "nickname": "johndoe",
    "points": 7500
  }
}

Response Fields:

  • position - Your current rank in the leaderboard (1-based, where 1 is the highest)
  • nickname - Your nickname
  • points - Your total points

Response (No points):

{
  "status": 404,
  "message": "You have no points"
}

Response (No nickname):

{
  "status": 404,
  "message": "You have no nickname. It's necessary to create a nickname first"
}

Note: Results are cached for 10 minutes to improve performance.

Get Ranking

Retrieve the complete leaderboard showing all users ranked by their points. The ranking includes user nicknames and their point totals.

Get ranking

curl -X GET https://api.example.com/api/points/ranking \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Ranking retrieved successfully",
  "data": {
    "ranking": [
      {
        "position": 1,
        "nickname": "topuser",
        "points": 15000
      },
      {
        "position": 2,
        "nickname": "seconduser",
        "points": 12000
      },
      {
        "position": 3,
        "nickname": "thirduser",
        "points": 10000
      }
    ]
  }
}

Response Fields:

  • ranking - Array of user objects, sorted by points (highest first)
  • Each user object includes:
    • position - Rank position (1-based)
    • nickname - User's nickname
    • points - Total points

Response (No ranking):

{
  "status": 404,
  "message": "No ranking found"
}

Note: Results are cached for 10 minutes to improve performance.

Points Earning Actions

Here are the actions that award points:

Creating a Nickname

  • Points: 1,000
  • Action: Create your first nickname
  • One-time: Yes

Creating a Referral Code

  • Points: 1,000
  • Action: Generate your referral code
  • One-time: Yes

Referring Someone

  • Points: 100
  • Action: Someone registers using your referral code
  • Repeatable: Yes (per referral)

Completing KYC

  • Points: 5,000
  • Action: Complete the KYC verification process
  • One-time: Yes

Ranking System

The ranking system works as follows:

  1. Position Calculation: Users are ranked by total points (highest first)
  2. Tie Breaking: If users have the same points, the ranking is determined by the order they achieved that score
  3. Real-time Updates: Rankings are updated when points are earned
  4. Caching: Rankings are cached for 10 minutes for performance

Caching

The API uses caching to improve performance:

  • Position: Cached for 10 minutes
  • Ranking: Cached for 10 minutes

Cache invalidation happens automatically when points are updated, but there may be a short delay before changes are reflected in the cached results.

Error Handling

No Points

{
  "status": 404,
  "message": "You have no points"
}

This error occurs when you haven't earned any points yet.

No Nickname

{
  "status": 404,
  "message": "You have no nickname. It's necessary to create a nickname first"
}

This error occurs when trying to view your position without having created a nickname.

No Ranking Found

{
  "status": 404,
  "message": "No ranking found"
}

This error occurs when there are no users with points in the system yet.

Complete Flow Example

Here's a complete example of checking points:

# 1. Create nickname (earns 1,000 points)
curl -X POST https://api.example.com/api/nickname \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "nickname": "johndoe"
  }'

# 2. Create referral code (earns 1,000 points)
curl -X POST https://api.example.com/api/referral \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 3. Complete KYC (earns 5,000 points)
# ... complete KYC process ...

# 4. Check your position
curl -X GET https://api.example.com/api/points/position \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 5. View ranking
curl -X GET https://api.example.com/api/points/ranking \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Important Notes

  1. Automatic Awarding: Points are automatically awarded when you complete eligible actions. You don't need to claim them manually.

  2. One-Time Rewards: Some actions (nickname, referral code, KYC) award points only once. You cannot earn these points multiple times.

  3. Repeatable Rewards: Referring users awards points each time someone uses your referral code.

  4. Nickname Required: To view your position in the ranking, you must have created a nickname. Users without nicknames are not shown in the ranking.

  5. Tenant-Specific: Points and rankings are specific to each tenant. Your points in one tenant don't affect your ranking in another.

  6. Cache Delay: Due to caching, there may be a short delay (up to 10 minutes) before your latest points are reflected in the ranking.

  7. Position Calculation: Your position is calculated based on your total points compared to all other users. Lower position numbers indicate higher rankings.

Tips for Earning Points

  1. Complete All Actions: Make sure to create a nickname, generate a referral code, and complete KYC to maximize your points.

  2. Refer Friends: Share your referral code with friends to earn additional points each time someone registers.

  3. Check Regularly: Monitor your position to see how you're doing compared to other users.

  4. Stay Active: Keep engaging with the platform to maintain your ranking position.

Was this page helpful?