Referral v2 API Routes
Codebase: /Desktop/referralv2/insiders-referral-v2
Service: Separate Express app — runs independently from the main Insiders backend
Referral v2 is a standalone service with its own database (Prisma/PostgreSQL). The frontend can cut over by swapping VITE_API_URL — the endpoint contract matches the legacy v1 API in the main backend.
Route prefixes
| Prefix | Router | Audience |
|---|---|---|
/api/referral | referral.ts | End users (authed) |
/api/kol | kol.ts | KOL applicants + authed users |
/api/scheme | scheme.ts | Public scheme info |
/api/admin | admin.ts | Admin panel (SIWE-authed) |
/api/admin/auth | adminAuth.ts | Admin SIWE auth |
/api/internal | internal.ts | Service-to-service (internalAuth middleware) |
User Referral · /api/referral
All routes require user JWT (authMiddleware).
| Method | Path | Description |
|---|---|---|
| GET | /chain | 5-level descendant tree (v2 native) |
| GET | /balance | Per-level earnings (?currency=pUSD|USDC) |
| GET | /payouts | Auto-payout history |
| GET | /tier | Legacy tier snapshot + v2 depth-unlock |
| GET | /codes | User's referral codes (pass-through from legacy) |
| POST | /codes/:codeId/set-default | Set a code as default |
| GET | /codes/:codeId/referees | Referees under a code (enriched with level) |
| GET | /codes/:codeId/scheme | Scheme assigned to a code |
| PATCH | /codes/:codeId/scheme | Assign scheme to a code |
| GET | /platform-fee | User's effective platform fee % |
GET /balance defaults to currency=pUSD (Phase D addendum 2026-05-27). Pass ?currency=USDC to read legacy USDC balances.
KOL · /api/kol
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /leaderboard | — | KOL leaderboard |
| POST | /apply | 🔒 | Submit KOL application |
| GET | /me | 🔒 | Current user's KOL status |
| POST | /vanity-codes | 🔒 | Create vanity referral code |
| PATCH | /landing-message | 🔒 | Update KOL landing message |
Scheme · /api/scheme
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /active | — | Currently active default scheme |
| GET | /public | — | All public schemes |
Admin · /api/admin
🚫
Requires admin SIWE authentication via /api/admin/auth. Do not expose to end users.
Scheme management
| Method | Path | Description |
|---|---|---|
| POST | /scheme | Create new scheme |
| GET | /scheme | Get default scheme |
| GET | /scheme/all | List all schemes |
| POST | /scheme/assign | Assign scheme to a code |
| POST | /codes/:codeId/scheme | Assign scheme directly to code |
KOL management
| Method | Path | Description |
|---|---|---|
| GET | /kol/applications/queue | Pending KOL applications |
| POST | /kol/applications/:id/reject | Reject KOL application |
| POST | /kol/approve | Approve KOL |
| POST | /kol/suspend | Suspend KOL |
| POST | /kol/terminate | Terminate KOL |
User management
| Method | Path | Description |
|---|---|---|
| GET | /users/by-tg/:tgId | Lookup user by Telegram ID |
| GET | /users/by-wallet/:address | Lookup user by wallet address |
| GET | /users/:userId/full | Full user profile |
| PATCH | /users/:userId/rebate-tier | Override user's rebate tier |
| POST | /users/:userId/platform-fee | Set custom platform fee |
| GET | /users/:userId/platform-fee | Get user's platform fee |
Platform fee analytics
| Method | Path | Description |
|---|---|---|
| GET | /platform-fee/summary | Overall fee collection summary |
| GET | /platform-fee/daily | Daily fee breakdown |
| GET | /platform-fee/top-sources | Top fee-generating sources |
Withdrawals
| Method | Path | Description |
|---|---|---|
| GET | /withdrawals/queue | Pending withdrawal queue |
| POST | /withdrawals/:id/mark-dispatched | Mark withdrawal dispatched |
| POST | /withdrawals/batch-mark-dispatched | Batch mark dispatched |
| POST | /withdrawals/:id/force-mark-dispatched | Force mark dispatched |
| POST | /withdrawals/:id/cancel | Cancel withdrawal |
Anti-abuse
| Method | Path | Description |
|---|---|---|
| GET | /anti-abuse/queue | Anti-abuse review queue |
| POST | /anti-abuse/resolve | Resolve anti-abuse flag |
Leaderboard
| Method | Path | Description |
|---|---|---|
| GET | /leaderboard/top-referrers | Top referrers leaderboard |
Admin Auth · /api/admin/auth
SIWE (Sign-In with Ethereum) based admin authentication.
| Method | Path | Description |
|---|---|---|
| GET | / | Get SIWE nonce |
| POST | / | Verify SIWE signature → admin session |
Internal · /api/internal
🚫
Service-to-service only. Protected by internalAuth middleware (shared secret header). Not for frontend use.
| Method | Path | Description |
|---|---|---|
| POST | /shadow-trade | Record a trade for shadow parity checking |
| POST | /accrual (TBC) | Trigger payout accrual for a trade |
Cron jobs
| Job | Schedule | Description |
|---|---|---|
dailyPayoutBatch | Daily | Batch-processes pending payout accruals |
dailyParityReport | Daily | Shadow parity divergence report (v1 vs v2 diff) |