Referral Management

At a Glance

What This Section Does

Manage the referral program where users earn commissions for inviting others. Create commission tiers (like "Default" or "KOL" for influencers), approve withdrawal requests, and track earnings across the referral network.

Who Should Use This

1. Referral Program Managers: Oversee the referral system and payouts
2. Finance Team: Process commission withdrawals and monitor costs
3. Partnership Managers: Set up special tiers for influencers and partners

Most Common Tasks

1. Review Pending Payouts: Approve commission withdrawals
2. Create Commission Tiers: Set up rates for different user types
3. Assign User to Tier: Give users special commission rates
4. View Commission History: Track all payments

Before You Start

Make sure you have this permission:

• referral : Required to manage the referral program

tip

Create a "KOL" tier with higher rates for influencers who bring many users.

1. Tab Viewing

Overview Statistics Viewing Sequence

Step	Action	Details
1	Access Referral Management	Navigate to Referrals from the main navigation menu to reach /admin/referral/manage.
2	View Overview Tab	The Overview tab is selected by default, displaying key referral system statistics.
3	Review Pending Claims	Check the Pending claims card showing the number of commission claims awaiting review.
4	Review Total Commissions Paid	Check the Total commissions Paid card displaying the cumulative amount paid to referrers.
5	Review Active Referrers	Check the Total Active Referrers card showing the count of users currently earning referral commissions.

Pending Claims Review Sequence

Step	Action	Details
1	Check Pending Claims Count	View the number displayed in the Pending claims card (e.g., "0").
2	Click Review Button	Click the Review Pending Claims button to navigate to pending commission claims.
3	Process Claims	Review and approve or reject pending claims as needed.

2. Tier Management

Tier Viewing Sequence

Step	Action	Details
1	Access Tier Management	Scroll to the Tier management section in the Overview tab.
2	View Tier Table	Review the table displaying all existing commission tiers with their names and distribution rates.
3	Search for Tier	Use the Search for tier textbox to filter tiers by name.
4	Review Tier Details	Each tier shows Name and Commission Distribution Rate for Level 1, Level 2, and Level 3.

Tier Creation Sequence

Step	Action	Details
1	Click Create New Tier	Click the + Create new tier button in the Tier management section.
2	Open Creation Dialog	A dialog titled "Create new tier" appears.
3	Enter Tier Name	Type a unique name for the tier in the Tier name field.
4	Set Level 1 Rate	Enter the commission percentage for Level 1 (Direct) referrers using the spinbutton.
5	Set Level 2 Rate	Enter the commission percentage for Level 2 referrers using the spinbutton.
6	Set Level 3 Rate	Enter the commission percentage for Level 3 referrers using the spinbutton.
7	Save or Cancel	Click Save to create the tier or Cancel to discard changes.

Tier Creation Fields

Field	Description	Default Value
Tier name	Unique identifier for the commission tier (e.g., "KOL", "Default", "Premium").	(empty)
Level 1 (Direct)	Commission percentage for direct referrals (first level in the referral chain).	5
Level 2	Commission percentage for second level referrals (referee of referee).	3
Level 3	Commission percentage for third level referrals (deepest level in chain).	2

Tier Editing Sequence

Step	Action	Details
1	Locate Tier	Find the tier you want to edit in the Tier management table.
2	Click Edit Button	Click the Edit button in the corresponding row.
3	Modify Tier Settings	Update the tier name or commission distribution rates as needed.
4	Save Changes	Click Save to apply changes or Cancel to discard.

Existing Tiers Overview

Tier Name	Level 1	Level 2	Level 3	Description
KOL	30%	10%	10%	High commission tier for Key Opinion Leaders or influencers with large followings.
Default	5%	3%	2%	Standard commission tier assigned to regular users by default.

3. User Network Management

User Network Viewing Sequence

Step	Action	Details
1	Click User Network Tab	Select the User network tab to view all users in the referral system.
2	View User Table	Review the table displaying users with their referral information.
3	Use Search Function	Enter keywords in the Search field to filter users by username.
4	Apply Date Filter	Click Select date range to filter users by their join date.
5	Apply Status Filter	Use the first dropdown to filter by user status (All, Active, Suspended, etc.).
6	Apply Sort Filter	Use the second dropdown to sort by Joined At or other criteria.

User Network Table Columns

Column	Description
Users	Username of the referred user in the referral system.
Parent	Username of the referrer who invited this user (empty if no parent referrer).
Tier	The commission tier assigned to this user (e.g., Default, KOL).
Earnings	Total commission earnings for this user, displayed with currency symbol.
Joined At	Date and time when the user joined the referral system (format: MMM DD YYYY, HH:MM).
Status	Current status of the user (Active, Suspended, etc.).
Actions	More actions button to access additional user management options.

User Editing Sequence

Step	Action	Details
1	Locate User	Find the user you want to edit in the User network table.
2	Click More Actions	Click the More actions button (three dots icon) in the Actions column.
3	Select Edit	Click Edit from the dropdown menu.
4	Review User Information	The Update referral dialog displays the user's avatar, username, and current settings.
5	Change Tier	Select a different tier from the Tier dropdown if needed.
6	Review Commission Rates	View the Commission Distribution Rate for Level 1, Level 2, and Level 3 based on selected tier.
7	Suspend User (Optional)	Click the Suspend button to suspend the user's referral privileges.
8	Save or Cancel	Click Save to apply changes, Cancel to discard, or Close to exit without saving.

User Edit Dialog Fields

Field	Description	Editable
User Avatar	Two letter abbreviation of username displayed as avatar.	No
Username	Full username of the user being edited.	No
Tier	Commission tier dropdown to assign user to different tier.	Yes
Commission Distribution Rate	Display of Level 1, Level 2, and Level 3 commission percentages based on selected tier.	No (auto updates with tier)

4. Manual Review Queue

Manual Review Queue Viewing Sequence

Step	Action	Details
1	Click Manual Review Queue Tab	Select the Manual review queue tab to view commission claims requiring manual approval.
2	View Queue Table	Review the table displaying claims that meet or exceed the auto approval threshold.
3	Use Search Function	Enter keywords in the Search field to filter claims by username.
4	Apply Date Filter	Click Select date range to filter claims by creation date.
5	Apply Status Filter	Use the first dropdown to filter by claim status (All, Pending, Approved, Rejected, etc.).
6	Apply Sort Filter	Use the second dropdown to sort by Created At or other criteria.

Manual Review Queue Table Columns

Column	Description
Users	Username of the user who submitted the commission claim.
Amount	Requested withdrawal amount with currency symbol.
Created At	Date and time when the claim was created.
Status	Current status of the claim (Pending, Approved, Rejected, etc.).
Actions	Buttons to approve, reject, or view details of the claim.

Claim Review Sequence

Step	Action	Details
1	Locate Claim	Find the claim you want to review in the Manual review queue table.
2	Review Claim Details	Check the username, amount, and creation date.
3	Verify Eligibility	Ensure the user meets requirements for commission payout.
4	Make Decision	Click Approve to process payment or Reject to deny the claim.
5	Add Rejection Reason	If rejecting, provide a clear reason for the user.

5. History Tab Function

Commission History Viewing Sequence

Step	Action	Details
1	Click History Tab	Select the History tab to view all processed commission payments.
2	View History Table	Review the table displaying all completed, rejected, or paid commission claims.
3	Use Search Function	Enter keywords in the Search field to filter by username.
4	Apply Date Filter	Click Select date range to filter by creation date.
5	Apply Status Filter	Use the first dropdown to filter by payment status (All, Paid, Rejected, etc.).
6	Apply Sort Filter	Use the second dropdown to sort by Created At or other criteria.

History Table Columns

Column	Description
Users	Username of the user who received or was denied the commission.
Amount	Commission amount that was paid or requested, displayed with currency symbol.
Created At	Date and time when the payment or claim was created.
Status	Final status of the transaction (Paid, Rejected, etc.).
Rejected Reason	Explanation for rejection if the claim was denied (empty for paid claims).
Tx Hash	Transaction hash link for blockchain verification (displayed as shortened hash like "79b7e").
Logs	Button to view detailed transaction logs and processing history.
Actions	Additional action buttons if available for the record.

Transaction Verification Sequence

Step	Action	Details
1	Locate Transaction	Find the paid commission record in the History table.
2	Click Tx Hash Link	Click the transaction hash link (e.g., "79b7e") to view blockchain details.
3	Verify on Blockchain	The link opens the blockchain explorer showing full transaction details.
4	View Logs (Optional)	Click the See logs button to view internal processing logs for the transaction.

6. Settings Tab

Commission Settings Viewing Sequence

Step	Action	Details
1	Click Settings Tab	Select the Settings tab to view and manage system wide referral configuration.
2	Review Fee Allocation	Check the Fee Allocation to Referral Pool percentage (e.g., 10%).
3	Review Commission Model	Check the Commission Distribution Model showing Level 1, Level 2, and Level 3 percentages.
4	Review Payout Rules	Check the Minimum Claim Amount and Auto Approval Threshold settings.
5	Check System Status	View the Referral System toggle to see if the system is enabled or disabled.

Commission Distribution Model Editing Sequence

Step	Action	Details
1	Locate Distribution Model	Find the Commission Distribution Model section in Settings.
2	Click Edit Button	Click the Edit button next to the Commission Distribution Model heading.
3	Modify Level Percentages	Update the percentages for Level 1, Level 2, and Level 3 as needed.
4	Verify Total	Ensure the total of all three levels equals 100%.
5	Save or Cancel	Click Save to apply changes or Cancel to discard.

Payout Rules Editing Sequence

Step	Action	Details
1	Locate Payout Rules	Find the Payout Rules section in Settings.
2	Click Edit Button	Click the Edit button next to the Payout Rules heading.
3	Set Minimum Claim Amount	Update the minimum amount users must accumulate before claiming commissions.
4	Set Auto Approval Threshold	Update the threshold below which claims are automatically approved.
5	Save or Cancel	Click Save to apply changes or Cancel to discard.

Settings Configuration Details

Setting	Current Value	Description
Fee Allocation to Referral Pool	10%	Percentage of total platform fees allocated to the referral commission pool from trading and redemptions.
Level 1 (Direct)	5%	Default commission split for direct referrals in the distribution model.
Level 2	3%	Default commission split for second level referrals.
Level 3	2%	Default commission split for third level referrals.
Referral System Status	Enabled	Toggle indicating whether the referral system is currently active.

7. Search & Filter

Search Functionality

Tab	Search Field Purpose	Search Behavior
User network	Filter users by username	Real time search that filters table as you type.
Manual review queue	Filter claims by username	Real time search that filters table as you type.
History	Filter records by username	Real time search that filters table as you type.
Overview (Tier management)	Filter tiers by name	Real time search that filters tier table as you type.

Date Range Filter Sequence

Step	Action	Details
1	Locate Date Filter	Find the Select date range button in the desired tab.
2	Click Date Range Button	Click the button to open the date range picker.
3	Select Start Date	Choose the beginning date for the filter range.
4	Select End Date	Choose the ending date for the filter range.
5	Apply Filter	Confirm the selection to filter table data by the specified date range.

Status Filter Options

Filter Dropdown	Available Options	Purpose
Status Filter (User network)	All, Active, Suspended, etc.	Filter users by their current account status.
Status Filter (Manual review queue)	All, Pending, Approved, Rejected, etc.	Filter claims by processing status.
Status Filter (History)	All, Paid, Rejected, etc.	Filter historical records by final status.

Sort Filter Options

Tab	Sort Options	Purpose
User network	Joined At, Earnings, etc.	Sort users by join date, commission earnings, or other criteria.
Manual review queue	Created At, Amount, etc.	Sort claims by submission date, amount, or other criteria.
History	Created At, Amount, etc.	Sort historical records by date, amount, or other criteria.

Overview

Back-office staff must be assigned the permission key to access and whitelisted to operate market.

No.	Key Features	Permission Key	Whitelist Type
1	Overview Dashboard	referral	-
2	Tier Management	referral	-
3	User Network Management	referral	-
4	Manual Review Queue	referral	-
5	Commission History	referral	-
6	System Settings Configuration	referral	-

Step	Instruction
1	Navigate to Referrals from the main navigation menu.
2	The Overview tab displays by default showing three key statistics cards.
3	Pending claims card shows the number of commission withdrawals requiring review (currently X).
4	Total commissions Paid card displays cumulative payouts (currently $X.XX).
5	Total Active Referrers card shows the count of users earning commissions (currently XX).
6	Click Review Pending Claims to navigate to the Manual review queue tab.

Tier Management

Step	Instruction
1	Scroll to the Tier management section in the Overview tab.
2	View existing tiers in the table: KOL (30%, 10%, 10%) and Default (5%, 3%, 2%).
3	Use Search for tier field to filter tiers by name.
4	Click + Create new tier to open the creation dialog.
5	Enter a unique Tier name and set commission percentages for Level 1, Level 2, and Level 3.
6	Click Save to create the tier or Cancel to discard.
7	To edit existing tiers, click the Edit button in the corresponding tier row.

User Network Management

Step	Instruction
1	Click the User network tab to view all enrolled users.
2	The table displays Users, Parent, Tier, Earnings, Joined At, Status, and Actions for each user.
3	Use the Search field to filter users by username.
4	Click Select date range to filter by join date.
5	Use the status dropdown to filter by Active, Suspended, or other statuses.
6	Use the sort dropdown to order by Joined At or other criteria.
7	Click More actions button (three dots) for a user, then select Edit.
8	In the Update referral dialog, change the Tier dropdown to assign a different commission tier.
9	Review the Commission Distribution Rate which updates automatically based on selected tier.
10	Click Suspend to disable the user's referral privileges if needed.
11	Click Save to apply changes or Close to exit.

Manual Review Queue

Step	Instruction
1	Click the Manual review queue tab to view claims requiring approval.
2	The table shows Users, Amount, Created At, Status, and Actions for claims at or above the auto approval threshold.
3	Use Search, date range, status filter, and sort options to manage the queue.
4	Review each claim to verify user eligibility and claim legitimacy.
5	Click Approve to process payment or Reject to deny the claim with a reason.
6	Approved claims move to History tab with Paid status and transaction hash.
7	Rejected claims move to History tab with Rejected status and reason displayed.

Commission History

Step	Instruction
1	Click the History tab to view all processed commission transactions.
2	The table displays Users, Amount, Created At, Status, Rejected Reason, Tx Hash, Logs, and Actions.
3	Use Search, date range, status filter, and sort options to find specific records.
4	For paid transactions, click the Tx Hash link (e.g., "79b7e") to view blockchain verification.
5	Click See logs button to view detailed processing history for any transaction.
6	Review Rejected Reason column for denied claims to understand why they were not approved.
7	Use this history for auditing, reporting, and user support inquiries.

System Settings Configuration

Step	Instruction
1	Click the Settings tab to access system wide referral configuration.
2	Review Fee Allocation to Referral Pool showing 10% of platform fees fund commissions.
3	In Commission Distribution Model section, view default rates: Level 1 (5%), Level 2 (3%), Level 3 (2%).
4	Click Edit next to Commission Distribution Model to modify the default split percentages.
5	Ensure the total of all three levels equals 100% before saving.
6	In Payout Rules section, review Minimum Claim Amount and Auto Approval Threshold settings.
7	Click Edit next to Payout Rules to adjust minimum withdrawal amount or auto approval limit.
8	Review Referral System toggle showing whether the system is enabled (currently enabled and locked).
9	All settings changes affect future transactions; existing commitments remain unchanged.

Search & Filter

Step	Instruction
1	Locate the Search field at the top of any tab with table data.
2	Type keywords to filter results in real time (filters by username or tier name).
3	Click Select date range button to open date picker.
4	Choose start and end dates to filter records by creation or join date range.
5	Use the first dropdown to filter by status (All, Active, Suspended, Pending, Paid, Rejected, etc.).
6	Use the second dropdown to sort by various criteria (Joined At, Created At, Amount, Earnings).
7	Combine multiple filters for precise data views (e.g., Active users who joined in September).
8	Clear filters by removing text from Search or selecting "All" in status dropdown.

Best Practices for Referral System

Practice	Description
Regular Monitoring	Check the Overview tab daily to monitor pending claims, commission payouts, and active referrer growth.
Timely Claim Processing	Review and process pending claims promptly to maintain user trust and satisfaction with the referral program.
Tier Strategy	Design tier structures that incentivize desired user behaviors while maintaining sustainable commission costs.
Verify High Value Claims	Always manually review claims approaching or exceeding the auto approval threshold for potential fraud or errors.
Document Rejections	Provide clear, specific reasons when rejecting claims to help users understand requirements and improve future claims.
Audit Transaction History	Regularly review the History tab to identify patterns, verify blockchain records, and ensure payment accuracy.
Balance Commission Rates	Ensure commission distribution rates are competitive enough to attract referrers while maintaining platform profitability.
Monitor User Suspension	Use suspension feature judiciously and only for policy violations, not for legitimate activity disputes.
Configure Thresholds Appropriately	Set minimum claim amounts and auto approval thresholds based on transaction costs and risk tolerance.
Test Configuration Changes	When modifying settings like commission rates or payout rules, monitor the impact on user behavior and system costs.

Product Glossary

Term	Description
Referral System	A program that rewards users for inviting new participants to the platform. Referrers earn commissions based on the activity of users they invite.
Referral System Management	The administrative interface for managing referral relationships, commission tiers, payouts, and system settings.
Overview Tab	The main dashboard tab displaying key statistics (pending claims, total commissions paid, active referrers) and tier management tools.
User Network Tab	Tab displaying all users enrolled in the referral system with their referral relationships, tiers, earnings, and status.
Manual Review Queue Tab	Tab showing commission claims that require administrator review before approval, typically claims meeting or exceeding the auto approval threshold.
History Tab	Tab displaying all processed commission payments, including paid and rejected claims with transaction details.
Settings Tab	Tab containing system wide configuration for commission rates, payout rules, and referral system status.
Referrer	A user who invites others to join the platform and earns commissions based on the referred users' activity.
Referee	A user who joins the platform through a referral link from another user (the referrer).
Commission	Earnings paid to referrers based on platform fees generated by their referred users' trading and redemption activities.
Commission Tier	A named configuration defining commission distribution rates for different referrer categories (e.g., Default, KOL).
Tier Name	Unique identifier for a commission tier such as "Default", "KOL", or "Premium".
KOL Tier	High commission tier designed for Key Opinion Leaders or influencers with large followings (Level 1: 30%, Level 2: 10%, Level 3: 10%).
Default Tier	Standard commission tier automatically assigned to regular users (Level 1: 5%, Level 2: 3%, Level 3: 2%).
Commission Distribution Rate	The percentage split of commissions across three levels of the referral chain, expressed as Level 1, Level 2, and Level 3 percentages.
Level 1 (Direct)	First level in the referral chain, representing users directly referred by the referrer. Receives the highest commission percentage.
Level 2	Second level in the referral chain, representing users referred by Level 1 referees. Receives moderate commission percentage.
Level 3	Third and deepest level in the referral chain, representing users referred by Level 2 referees. Receives the lowest commission percentage.
Referral Chain	The hierarchical structure of referral relationships extending up to three levels deep from the original referrer.
Parent	The referrer who directly invited a specific user. Displayed in the Parent column of the User network table.
Earnings	Total accumulated commission amount a user has earned through the referral program, displayed with currency symbol.
Active Status	Indicates a user is currently enrolled and earning commissions in the referral system.
Suspended Status	Indicates a user's referral privileges have been temporarily or permanently disabled by an administrator.
Pending Claims	Number of commission withdrawal requests awaiting administrator review and approval.
Total Commissions Paid	Cumulative amount of all commission payments successfully processed and distributed to referrers.
Total Active Referrers	Count of users currently enrolled in the referral system and eligible to earn commissions.
Review Pending Claims Button	Action button that navigates administrators to the Manual review queue for processing pending commission requests.
Claim	A withdrawal request submitted by a user to receive their accumulated commission earnings.
Auto Approval	Automated processing of commission claims below the specified threshold without requiring manual administrator review.
Manual Review	Administrator evaluation and approval process required for commission claims meeting or exceeding the auto approval threshold.
Fee Allocation to Referral Pool	Percentage of total platform fees (from trading and redemptions) allocated to fund the referral commission pool. Currently set at 10%.
Minimum Claim Amount	The minimum commission balance a user must accumulate before being allowed to submit a withdrawal request.
Auto Approval Threshold	The maximum claim amount that can be automatically approved without manual review. Claims at or above this amount require administrator approval.
Tx Hash	Transaction hash, a unique blockchain identifier for a completed commission payment. Displayed as shortened hash (e.g., "79b7e") with link to full blockchain record.
Blockchain Explorer	External website that displays detailed information about blockchain transactions, accessed by clicking Tx Hash links.
See Logs Button	Action button that opens detailed processing logs and history for a specific commission transaction.
Rejected Reason	Administrator provided explanation for why a commission claim was denied, displayed in the History table for rejected claims.
More Actions Button	Dropdown menu button (three dots icon) in the Actions column providing access to user management options like Edit and Suspend.
Update Referral Dialog	Modal window for editing a user's tier assignment and viewing their commission distribution rates.
Create New Tier Dialog	Modal window for creating a new commission tier with custom name and distribution rates.
Tier Dropdown	Selection menu in the Update referral dialog for assigning users to different commission tiers.
Suspend Button	Action button in the Update referral dialog to disable a user's referral privileges and earnings.
Search Field	Text input for filtering table data by username or tier name with real time results.
Select Date Range Button	Action button that opens a date picker for filtering records by creation or join date.
Status Filter Dropdown	Selection menu for filtering table data by status (Active, Suspended, Pending, Paid, Rejected, etc.).
Sort Filter Dropdown	Selection menu for sorting table data by criteria such as Joined At, Created At, Amount, or Earnings.
Tier Management	Section in the Overview tab for creating, editing, and viewing commission tiers.
Search for Tier	Text input field for filtering the tier management table by tier name.
Edit Button (Tier)	Action button in the tier table for modifying existing tier names and commission rates.
+ Create New Tier Button	Action button that opens the dialog for creating a new commission tier configuration.
Commission Distribution Model	System wide default configuration defining how commissions are split across three referral levels, editable in Settings.
Payout Rules	Configuration section defining minimum claim amount and auto approval threshold for commission withdrawals.
Referral System Toggle	Switch control in Settings for enabling or disabling the entire referral system platform wide. Currently enabled and disabled for editing.
Trading Fees	Platform fees collected from user trading activity, a portion of which funds the referral commission pool.
Redemption Fees	Platform fees collected when users redeem tokens or positions, a portion of which funds the referral commission pool.
Edit Button (Settings)	Action buttons in Settings tab for modifying Commission Distribution Model or Payout Rules.
Save Button	Confirmation button to apply and persist changes made in dialogs or forms.
Cancel Button	Action button to discard changes and close dialogs without saving modifications.
Close Button	Action button to exit dialogs, equivalent to Cancel when no changes have been made.