Referral System Management

1. Overview Tab

Overview statistics

Step	Action	Details
1	Access Referral Management	Navigate to Referrals in the main menu, then to Manage.
2	View Overview tab	Overview is selected by default.
3	Review Pending claims	Card shows the number of commission claims awaiting review (e.g. "0").
4	Review Total commissions Paid	Card shows cumulative amount paid to referrers (e.g. "$0").
5	Review Total Active Referrers	Card shows count of users currently earning referral commissions.
6	Review Pending Claims action	Click Review Pending Claims to open the Manual review queue tab.

Tier management

Step	Action	Details
1	Open Tier management	Scroll to the Tier management section on the Overview tab.
2	View tier table	Table columns: Name, Commission Distribution Rate (e.g. "L1: 7%, L2: 2%, L3: 1%"), and an Edit button per row.
3	Search for tier	Use Search for tier to filter tiers by name.
5	Create tier	Click + Create new tier to open the creation dialog.

Create new tier

Step	Action	Details
1	Open dialog	Create new tier dialog appears.
2	Tier name	Enter a unique name in Tier name.
3	Commission Distribution Rate (%)	Set Level 1 (Direct), Level 2, and Level 3 with the spinbuttons (defaults e.g. 5, 3, 2).
4	Save or cancel	Save to create; Cancel to close without saving.

Tier creation fields

Field	Description	Default (example)
Tier name	Unique name for the tier (e.g. "KOL", "Default", "Premium").	(empty)
Level 1 (Direct)	Commission % for direct referrals.	5
Level 2	Commission % for second-level referrals.	3
Level 3	Commission % for third-level referrals.	2

Edit tier dialog

Step	Action	Details
1	Open dialog	Click Edit in a tier row; Edit tier dialog opens.
2	Name	Name is read-only (disabled); tier name cannot be changed here.
3	Commission Distribution Rate (%)	Edit Level 1 (Direct), Level 2, Level 3 with the spinbuttons.
4	Referrer count	Dialog shows "Referrer in this tier: N" (e.g. 68).
5	Save or cancel	Save to apply; Cancel to close without saving.

Tier editing

Step	Action	Details
1	Find tier	Locate the tier in the Tier management table.
2	Edit	Click Edit in that row.
3	Change settings	Update Level 1, 2, 3 rates (name is read-only in Edit).
4	Save or cancel	Save to apply; Cancel to discard.

Example tiers

Tier name	Level 1	Level 2	Level 3	Description
KOL	30%	10%	10%	For Key Opinion Leaders / influencers.
Default	5%	3%	2% (or as configured)	Standard tier for regular users.

2. User network tab

Viewing the user network

Step	Action	Details
1	Open tab	Select the User network tab.
2	View table	Table lists users with referral info (see column list below).
3	Search	Use Search... to filter by username (real-time).
4	Filter by date	Use Select date range to filter by join date.
5	Filter by expiry (if shown)	Use Filter by Expires Date when available.
6	Status filter	First dropdown: All, Active, Suspended, etc.
7	Sort	Second dropdown: e.g. Joined At or other criteria.

User network table columns

Column	Description
Users	Username of the user in the referral system (may be empty for some rows).
Parent	Username of the referrer who invited this user (empty if none).
Tier	Commission tier (e.g. Default, KOL).
Earnings	Total commission earnings (e.g. "token 0").
Joined At	When the user joined (e.g. "Feb 11 2026, 10:13").
Status	e.g. Active, Suspended.
Is Root Referral	Whether this user is a root referrer (e.g. "No").
Actions	More actions (e.g. Edit).

Editing a user

Step	Action	Details
1	Find user	Locate the user in the User network table.
2	More actions	Click More actions in the Actions column.
3	Edit	Choose Edit from the menu.
4	Update referral dialog	Dialog shows avatar, username, Is Root Referral switch, tier, and commission distribution.
5	Set Is Root Referral (optional)	Toggle Is Root Referral on or off.
6	Change tier	Use the Tier dropdown to assign another tier.
7	Suspend (optional)	Use Suspend to disable referral privileges.
8	Save or close	Save to apply; Cancel or Close to exit.

Update referral dialog (Edit user)

The Update referral dialog shows:

1. Avatar / username: Read-only (e.g. "GI", "GiBSon").
2. Is Root Referral: Toggle (switch); use it to set or clear root referral status.
3. Tier: Dropdown to assign a different commission tier.
4. Commission Distribution Rate: Level 1, Level 2, Level 3 % (read-only, from selected tier).
5. Suspend: Button to suspend the user's referral privileges.
6. Cancel: Discard changes and close.
7. Save: Apply changes.
8. Close: Close without saving (same as Cancel when unchanged).

User edit dialog fields

Field	Description	Editable
User avatar	Short label/avatar for the user (e.g. "GI").	No
Username	Full username.	No
Is Root Referral	Switch to mark user as root referrer or not.	Yes
Tier	Commission tier dropdown.	Yes
Commission Distribution Rate	Level 1, 2, 3 % (from selected tier).	No (updates with tier)

3. Manual review queue tab

Viewing the queue

Step	Action	Details
1	Open tab	Select Manual review queue (or click Review Pending Claims on Overview).
2	View table	Table shows claims that need manual approval (e.g. at/above auto-approval limit).
3	Search	Search... filters by username.
4	Filters	Filter by Expires Date and Select date range filter by date.
5	Status filter	First dropdown: All, Pending, Approved, Rejected, etc.
6	Sort	Second dropdown: e.g. Created At or other criteria.

Manual review queue table columns

Column	Description
Users	Username of the user who submitted the claim.
Amount	Requested amount (with currency/token).
Created At	When the claim was created.
Status	Pending, Approved, Rejected, etc.
Actions	Approve, Reject, or view details.

Reviewing a claim

Step	Action	Details
1	Locate claim	Find the claim in the Manual review queue table.
2	Check details	Verify username, amount, and creation date.
3	Verify eligibility	Confirm the user and claim meet payout rules.
4	Decide	Click Approve to process or Reject to deny.
5	Rejection reason	If rejecting, provide a clear reason.

4. History tab

Viewing commission history

Step	Action	Details
1	Open tab	Select History.
2	View table	Table shows processed commission payments (paid/rejected).
3	Search	Search... filters by username.
4	Date filter	Select date range and (if shown) Filter by Expires Date by creation date.
5	Status filter	First dropdown: All, Paid, Rejected, etc.
6	Sort	Second dropdown: e.g. Created At.

History table columns

Column	Description
Users	Username of the user who received or was denied the commission.
Amount	Amount paid or requested (with currency/token).
Created At	When the payment/claim was created.
Status	Paid, Rejected, etc.
Rejected Reason	Reason if the claim was rejected.
Tx Hash	Short link (e.g. "79b7e") to blockchain details.
Logs	Button to open transaction/logs details.
Actions	Any extra actions for the record.

Verifying a transaction

Step	Action	Details
1	Find record	Locate the paid commission in the History table.
2	Tx Hash	Click the Tx Hash link to open the blockchain explorer.
3	Logs	Click See logs for processing details.

5. Invite codes tab

Purpose

Manage invite codes: view owners, codes, tags, status, and expiry. Export or batch-generate codes.

Viewing invite codes

Step	Action	Details
1	Open tab	Select Invite codes.
2	View table	Table lists invite codes with Owner, Code, Tag, Status, Created At, Expired At.
3	Export	Export All to export all invite codes (e.g. as CSV).
4	Batch generate	Batch Generate opens the Batch Generate Invite Codes dialog.
5	Search	Search... to filter (e.g. by owner or code).
6	Date filter	Select date range to filter by creation/expiry.
7	Status / sort	First dropdown: All or by status; second: e.g. Created At.

Batch Generate Invite Codes

Step	Action	Details
1	Open dialog	Click Batch Generate on the Invite codes tab.
2	Dialog title	Batch Generate Invite Codes — "Generate multiple referral invite codes for a BD account. Codes will be exported as CSV."
3	Owner Account (User ID)*	Textbox: the BD account user ID to attribute the codes to.
4	Quantity*	Spinbutton: number of codes to generate (default 100, max 500).
5	Cohort Tag*	Textbox: tag to identify the cohort (e.g. VIETNAM_KOL_FEB).
6	Expiry (Days)*	Spinbutton: days until codes expire (default 7, max 30).
7	Actions	Generate & Export CSV to create and download; Cancel or Close to exit.

Invite codes table columns

Column	Description
Owner	User who owns the code: avatar + link to user profile (e.g. MKTtest2 → /admin/users/{userId}).
Code	Invite code (e.g. "XM-QA6FJS"); Copy code button to copy to clipboard.
Tag	Cohort/tag label (e.g. "KOL_1").
Status	Active or Used.
Created At	When the code was created (e.g. "Feb 06 2026, 10:09").
Expired At	Expiry date/time.

6. Settings tab

Commission settings

Step	Action	Details
1	Open tab	Select Settings.
2	Commission settings	Platform Fee Share for Referrals (%) (e.g. 10%) — share of platform trading/redemption fees that funds the referral pool.
3	Commission Distribution Model	Level 1 (Direct), Level 2, Level 3 percentages (e.g. 7%, 2%, 1%). Click Edit to change.
4	Payout Rules	Minimum Withdrawal Amount (e.g. 1 in platform token/$) and Auto-Approval Limit (e.g. 50) — withdrawals below this are auto-approved; at or above require admin review. Click Edit to change.
5	Referral System	Toggle to enable/disable the referral system (may be locked).
6	Force Invite Code	Toggle: when enabled, users must use an invite code to register. (May be locked.)

Editing Commission Distribution Model

Step	Action	Details
1	Find section	In Settings, locate Commission Distribution Model (description: how rewards are split across 3 levels).
2	Edit	Click Edit; the section switches to inline edit (no modal).
3	Set levels	Level 1 (Direct), Level 2, Level 3 appear as spinbuttons with % (e.g. 7%, 2%, 1%). Update as needed (e.g. ensure total is as required).
4	Save	Click Save changes to apply. (No Cancel — revert by editing again.)

Editing Payout Rules

Step	Action	Details
1	Find section	In Settings, locate Payout Rules.
2	Edit	Click Edit; the section switches to inline edit (no modal).
3	Minimum Withdrawal Amount ($)	Spinbutton with token/$ (e.g. 1). Description: users must earn at least this amount before they can request a payout.
4	Auto-Approval Limit ($)	Spinbutton (e.g. 50). Description: withdrawals under this amount are approved instantly; at or above require admin review.
5	Save	Click Save changes to apply.

Settings reference

Setting	Example / note	Description
Platform Fee Share for Referrals (%)	10%	Share of platform fees going to the referral pool.
Level 1 (Direct)	7%	Default split for direct referrals.
Level 2	2%	Second-level referrals.
Level 3	1%	Third-level referrals.
Minimum Withdrawal Amount	1 (token/$)	Minimum earnings before a user can request payout.
Auto-Approval Limit	50 (token/$)	Below this amount, claims are auto-approved; at or above, manual review.
Referral System	Enabled (toggle)	Master switch for the referral system. May be disabled (locked) in some environments.
Force Invite Code	On/Off (toggle)	If on, registration requires an invite code. May be disabled (locked) in some environments.

7. Search and filters

Search

Tab	Search purpose	Behavior
User network	By username	Real-time filter as you type.
Manual review queue	By username	Real-time filter.
History	By username	Real-time filter.
Invite codes	By owner/code etc.	Real-time filter.
Overview (Tier management)	By tier name	Real-time filter.

Date and other filters

1. Select date range: Used on User network, Manual review queue, History, and Invite codes to filter by date (e.g. join date, created date, expiry).
2. Filter by Expires Date: On User network (and optionally elsewhere) when available.
3. Status dropdown: First dropdown on each tab (All, Active, Suspended, Pending, Paid, Rejected, etc.).
4. Sort dropdown: Second dropdown (Joined At, Created At, Amount, Earnings, etc.).