[Backend] User Referral Dashboard API

[Olowodarey]

📋 Description

Create endpoints for users to view their referral stats, generate codes, and track rewards.

Acceptance Criteria

• GET /users/referrals/stats for referral metrics
• POST /users/referrals/code/generate to create custom referral code
• GET /users/referrals/history to view referred users and rewards
• GET /users/referrals/leaderboard to see top referrers
• Calculate pending vs. claimed referral rewards
• Track conversion funnel (signup → deposit → reward)

Response Example

{
  referralCode: "JOHN2026",
  totalReferrals: 12,
  successfulReferrals: 8,
  pendingRewards: 150.00,
  claimedRewards: 450.00,
  rank: 45
}

Tasks

• Create referral endpoints
• Implement code generation
• Add leaderboard
• Track conversion funnel
• Calculate rewards
• Write tests

[devxsameer]

@devxsameer has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I’d like to take this issue. I’m a backend-leaning full stack developer with experience building analytics and reward systems, and I can implement the referral dashboard APIs with code generation, reward calculations, leaderboard, and proper tracking of referral conversions with clean and testable logic.

ETA: 4–5 hours.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @devxsameer to this issue.

[Haroldwonder]

@Haroldwonder has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hi. Can I work on this?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Haroldwonder to this issue.

[drips-wave]

Congratulations, @Haroldwonder! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @Haroldwonder: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @Haroldwonder as part of the Stellar Wave Program's 3rd Wave 🥳

😎 @Haroldwonder: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.