Build referral tracking and reward distribution endpoints

[Chucks1093]

Summary

Implement endpoints for registering referral relationships, tracking referred wallet activity, and querying referral reward earnings.

Scope

• POST /referrals/register links referee wallet to referrer with referral code
• GET /referrals/earnings returns total earned and per-referral breakdown
• GET /referrals/referred returns list of referred wallets and their status
• Referral fee recorded when referred wallet completes first trade
• Referral code generated and stored per wallet

Acceptance Criteria

• Referral registration stores relationship correctly
• Earnings endpoint returns accurate totals and breakdown
• Referred wallets list shows join date and first trade status
• Fee recorded only on first trade from referred wallet
• Duplicate referral registration for same wallet returns 409

ETA

12 hours

[Johnsource-hub]

@Johnsource-hub has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hello Maintainer, I’ve reviewed the requirements thoroughly and am ready to work on this issue. Please assign it to me.

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

[boluxx123]

@boluxx123 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi Maintainer, would like to work on this issue and make PR immediately today

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

[byteMara]

@byteMara has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

I would like to work on this

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

[ollypee22]

@ollypee22 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi maintainer i would like to work on this issue

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

[Stanley-Owoh]

@Stanley-Owoh has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Good day maintainer please assign this issue to me i can work on it immediately with positive results
Thank you

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

[Rafiat30]

@Rafiat30 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

can i work on this

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

[drips-wave]

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

🧑‍💻 @ollypee22: 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]

Congratulations, @Stanley-Owoh! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @Stanley-Owoh: 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 🌊