The Agents and Affiliates systems let you grow your player network through human networks. Agents are trusted operators who recruit and manage players under a commission hierarchy. Affiliates are marketers who earn rewards for referring new registrations.
Both systems must be enabled in Settings > Features before they appear in the navigation.
Agents
Navigate to Agents in the admin sidebar.
The Agent system supports a multi-level hierarchy of agents, each managing their own player base. Agents earn commissions from their players’ activity, and commissions can cascade up the hierarchy through configurable templates.
Agent Concepts
| Term | Description |
|---|---|
| Agent | A user account designated with agent status who manages assigned players |
| Role Tier | A named level in the hierarchy (e.g., Master Agent, Sub-Agent) with a set of permissions |
| Custom Role | A reusable permission set that can be assigned to individual agents for fine-grained overrides beyond their role tier |
| Commission Template | A reusable configuration defining how agent earnings are calculated |
| Settlement | A periodic calculation and payment of commissions owed to agents |
| Holdback | A percentage of each settlement withheld for a configurable period before release |
| Hierarchy Tree | The parent-child relationship structure of all agents |
| Agent Balance | A separate balance account that holds an agent’s earned commissions |
| Financial Freeze | A flag that blocks all financial operations for an agent while keeping the account active |
Viewing Agents
The Agents page shows a searchable, paginated list of all agents with their role tier, status, balance, and player count.
Filters:
- Search — Username or email
- All Role Tiers — Filter to a specific tier
- All Statuses — Active, Suspended, Pending KYC, Closed
- All Depths — Filter by how deep in the hierarchy the agent sits
Use Migrate Legacy Agents to create agent records for any legacy agents that are missing them.
Agent Statuses
| Status | Description |
|---|---|
active | Fully operational. Can manage players, earn commissions, and perform financial operations |
suspended | Temporarily disabled. Cannot operate but retains hierarchy placement and data |
pending_kyc | Awaiting identity verification before activation |
closed | Permanently deactivated. Retained for historical records |
Change an agent’s status from the Agent Details modal or via the hierarchy status endpoint. All status changes are recorded in the agent audit log.
Creating an Agent
To designate a user as an agent:
- Go to Agents and click Add Agent.
- Search for the user. Only users who are not already agents are listed.
- Optionally assign a Parent Agent (to place them in the hierarchy), a Role Tier, and a Commission Template.
- Click Designate as Agent.
Agent Details
Click any agent row to open the Agent Details modal. This modal is divided into collapsible sections:
Overview
- Username, email, and registration date
- Agent status (Active, Suspended, Pending KYC, or Closed) and an action button to change it
- Agent balance with a Freeze button to block financial operations
- Stats: Total Players, Active Players, Total Transfers
Hierarchy Placement
Shows where this agent sits in the hierarchy:
- Depth — How many levels below the root this agent is
- Parent Agent — The agent above this one (if any)
- Direct Sub-Agents — How many agents report to this one
- Subtree Player Count — Total players in this agent’s entire downline
Actions:
- Reassign — Move this agent under a different parent agent
- Detach — Remove this agent from their parent, making them a root-level agent
- Remove Agent Status — Revoke agent status entirely (only allowed if the agent has no assigned players and no sub-agents)
To reassign, select the new parent from the dropdown (the list excludes this agent and their own descendants to prevent circular references) and confirm.
Role and Permissions
Displays the agent’s assigned Role Tier and the permissions that tier grants. You can change the role tier using the dropdown. The effective permissions list updates to reflect the new tier immediately.
Optionally assign a Custom Role for fine-grained permission overrides beyond what the tier provides.
You can also set per-agent permission overrides that take precedence over both the role tier and custom role. Use this for one-off adjustments without creating a new custom role.
Commission Template
Shows the current commission template assigned to the agent. Use the dropdown to assign a different template. Commission templates control how the agent’s earnings are calculated (see Commission Templates below).
Assigned Players
Lists all players under this agent’s management with:
- Username and email
- Assigned date
Actions:
- Add Player — Opens a search modal to find and assign a player to this agent
- Remove Player — Unassign a player from this agent’s roster
Players can only be assigned to one agent at a time.
Adjust Balance
Credit or debit the agent’s balance manually:
- Enter a positive number to credit, negative to debit
- Provide a reason (required)
- The projected balance is shown before confirming
Hierarchy Tree View
Navigate to Agents > Agent Hierarchy in the admin sidebar.
The hierarchy tree displays all agents in a visual tree structure. Each node shows:
- Agent username and status
- Role tier name
- Player count
- Agent balance
Agents without a parent appear at the root level. Agents deeper in the tree are connected by lines to their parent.
Hierarchy and Profit Settings
Navigate to Settings and open the Agents tab. See Settings – Agents Tab for the hierarchy, profit, transfer policy, and feature toggle settings.
Role Tiers
Navigate to Agents > Agent Role Tiers.
Role tiers define named levels in your agent hierarchy, each with a specific set of permissions. Common tiers include "Master Agent", "Sub-Agent", and "Club Agent", though you can create any tier structure.
Creating a Role Tier
- Click Create Role Tier.
- Enter a Name (e.g., "Master Agent") and optional Description.
- Set the Depth Level — the hierarchical position this tier is designed for (lower numbers = higher in hierarchy). This is metadata; an agent’s actual depth is determined by their position in the parent-child tree.
- Configure the Permissions — toggle each capability this tier grants (see Agent Permission Keys below).
- Optionally set Max Sub-Agents and Max Players limits for agents assigned to this tier.
- Save.
Editing and Deleting Role Tiers
Click the edit icon to update a tier’s name, depth, permissions, or limits. The edit panel shows how many agents are currently assigned to the tier.
Deleting a role tier is only possible if no agents are currently assigned to it.
Default Tier Permissions by Depth
The system provides recommended permission sets based on depth level:
| Depth | Typical Name | Permissions |
|---|---|---|
| 0 | Master Agent | All 32 permissions |
| 1 | Regional Agent | All except wholesale purchase, manual adjustment, and export |
| 2 | Sub-Agent | Player management, basic finance, sub-agent lifecycle, own reports |
| 3+ | Affiliate | View-only access and basic player creation |
These defaults are suggestions. You can configure any combination of permissions for any tier.
Custom Roles
Navigate to Agents > Custom Roles.
Custom roles provide an additional layer of permission configuration beyond role tiers. While role tiers define permissions for an entire hierarchy level, custom roles let you create reusable permission sets that can be assigned to individual agents.
Creating a Custom Role
- Click Create Custom Role.
- Enter a Name and optional Description.
- Configure the Permissions — toggle each capability this role grants.
- Save.
How Custom Roles Interact with Role Tiers
An agent’s effective permissions are resolved in this order:
- Role Tier permissions — the base set from the agent’s assigned tier
- Custom Role permissions — if assigned, these override the tier permissions
- Per-agent permission overrides — if set, these take final precedence
Custom roles are useful when you need a small group of agents to have different permissions than their tier normally provides, without creating a new tier.
Editing and Deleting Custom Roles
Click the edit icon to update a role’s name, description, or permissions. The edit panel shows how many agents are currently assigned to the role.
Deleting a custom role is only possible if no agents are currently assigned to it.
Commission Templates
Navigate to Agents > Commission Templates.
Commission templates are reusable configurations that define how agent commissions are calculated. Assign a template to an agent to control their earning formula.
Commission Model Types
Each template can contain one or more commission models. The supported model types are:
| Model Type | Description |
|---|---|
rake_share | Agent earns a percentage of the rake generated by their players |
cpa | Cost Per Acquisition — a fixed payment for each new player the agent recruits |
revenue_share | Agent earns a share of net revenue (rake minus costs) |
tiered | Commission rate varies based on volume thresholds |
flat_fee | A fixed periodic fee regardless of activity |
Commission Model Parameters
Each model supports the following configuration:
| Parameter | Description |
|---|---|
| Rate | The commission rate (percentage or fixed amount depending on model type) |
| Game Type Overrides | Per-game-type rate overrides (e.g., a different rake share for Omaha vs. Hold’em) |
| Qualification Criteria | Conditions that must be met for the commission to apply |
| Negative Carryover | Whether negative balances carry forward to the next settlement period |
| Calculation Mode | Retroactive (top_down) or Marginal (bottom_up) |
| Tier Thresholds | For tiered models: volume thresholds and their corresponding rates |
Template Settings
Beyond the commission models, each template has these configuration options:
| Setting | Description |
|---|---|
| Settlement Schedule | How often settlements run: daily, weekly, biweekly, monthly, or manual |
| Minimum Payout | Minimum amount before a settlement is generated (commissions below this threshold roll over) |
| Holdback Percentage | Percentage of each settlement withheld as a reserve (released after the holdback period) |
| Holdback Period (Days) | Number of days before held-back funds are released to the agent |
| Max Rakeback Percentage | Cap on the maximum rakeback an agent can offer to their players |
Creating a Commission Template
- Click Create Commission Template.
- Enter a Name.
- Add one or more commission models with their parameters.
- Configure settlement schedule, minimum payout, holdback, and rakeback limits.
- Save.
Each template can be assigned to multiple agents. The template details panel shows how many agents are currently using it.
Assigning a Template
From the Agent Details modal (Commission Template section), select a template from the dropdown and save. The change takes effect at the next settlement run.
Settlements
Navigate to Agents > Settlements.
Settlements are periodic calculations that compute the commissions owed to each agent and transfer them to their agent balance.
Settlement List
The settlement list shows all past settlements with:
- Agent name
- Period
- Status: Calculated, Approved, Disputed, Paid
- Payout amount (after holdback deduction)
Filters:
- Agent
- Status
- From Date and To Date
Click a settlement to open Settlement Details with the Financial Summary (gross rake, rakeback paid, net commission, holdback, and payout) and the Calculation Breakdown.
Settlement Status Workflow
CALCULATED → APPROVED → PAID
↓ ↓
DISPUTED DISPUTED
↓
APPROVED| Status | Available Actions |
|---|---|
| Calculated | Approve, Dispute |
| Approved | Mark as Paid |
| Disputed | Approve (after resolving the dispute) |
| Paid | View only |
When a settlement is marked as Paid, the payout amount is automatically credited to the agent’s balance in a serialized transaction that prevents double-payment.
When a settlement is Disputed, you can provide a reason. The dispute reason and timestamp are stored with the settlement record.
Running Settlements
Settlements run automatically on a schedule when Auto-run Scheduled Settlements is enabled in the Settings > Agents tab. To process all agents with due settlements now, click Run Settlements and confirm.
Holdback Releases
When a commission template has a holdback percentage configured, a portion of each settlement is withheld and released automatically on its release date. Holdback releases have no page in the admin sidebar. They are available through the admin API at GET /api/v1/admin/holdback-releases.
Financial Controls
Navigate to Agents > Financial Controls.
The Agent Financial Controls page provides tools for managing agent financial operations on a per-agent basis.
Selecting an Agent
Use the search bar at the top of the page to find and select an agent by username. Once selected, their financial overview loads with all controls below.
Financial Overview
The overview panel shows the current state of an agent’s financial configuration at a glance:
- Financial Limits — Current deposit and withdrawal limits
- Credit Line — Available credit line amount
- Wholesale Discount — Discount percentage for chip purchases
- Financial Frozen — Whether financial operations are currently blocked
Financial Limits
Set per-agent caps on deposits, withdrawals, and approval thresholds.
Deposit Limits:
| Limit | Description |
|---|---|
| Max Single Deposit | Maximum amount for a single deposit transaction |
| Max Daily Deposit | Maximum total deposits per day |
| Max Weekly Deposit | Maximum total deposits per week |
| Max Monthly Deposit | Maximum total deposits per month |
Withdrawal Limits:
| Limit | Description |
|---|---|
| Max Single Withdrawal | Maximum amount for a single withdrawal |
| Max Daily Withdrawal | Maximum total withdrawals per day |
| Max Weekly Withdrawal | Maximum total withdrawals per week |
| Max Monthly Withdrawal | Maximum total withdrawals per month |
Approval:
| Limit | Description |
|---|---|
| Approval Threshold | Transactions above this amount require admin approval before processing |
Leave any limit blank to impose no restriction for that field.
Credit Lines
Set a credit line for an agent, allowing them to operate with a negative balance up to the credit line amount. Enter the credit line amount and save.
Wholesale Discounts
Set a discount percentage for bulk chip purchases. This is used when agents buy chips in volume to distribute to their players. Enter the Discount Percentage (0-50%) and save.
Financial Freeze
Freeze or unfreeze an agent’s financial operations. When frozen:
- The agent cannot make deposits or withdrawals
- The agent cannot transfer chips
- Commission settlements are blocked
- The agent can still log in and view their data
Use this as an investigative measure when suspicious activity is detected.
Transaction Approvals
When an agent’s transactions exceed the approval threshold, they enter a pending state. The Pending Approvals section lists all transactions across all agents that require admin review.
For each pending transaction, you can:
- Approve — Execute the transaction
- Reject — Cancel the transaction with an optional reason
Transfer Policy
Agent-to-Agent Transfer Policy is a global setting that controls whether and how agents can transfer chips between each other. Set it under Global Settings on this page or in the Settings > Agents tab.
| Policy | Description |
|---|---|
| Disabled | No agent-to-agent transfers allowed |
| Same Parent Only | Transfers only between agents who share the same parent agent |
| Any Agent | Transfers between any agents are allowed |
| With Approval | Transfers are allowed but require admin approval before processing |
Affiliates
Navigate to Affiliates in the admin sidebar.
The Affiliate system rewards users who refer new players to your site. Each registered user can have a unique referral code, and when someone registers using that code, rewards flow to the referrer based on configured commission levels.
The Affiliates page is organized into five tabs: Overview, Commission Levels, Referrals, Referral Codes, and Rewards.
Overview Tab
Displays summary statistics for the affiliate program, including Total Affiliates, Total Referrals, Total Distributed, and Conversion Rate, along with Referral Status Breakdown, Recent Activity (Last 30 Days), and Rewards by Level.
The Affiliate Leaderboard on this tab ranks your top performers By Referrals or By Earnings. Select a period: Today, This Week, This Month, This Year, or All Time.
Commission Levels Tab
Commission levels define the reward structure for referrals. Up to 10 levels can be configured, supporting multi-level referral chains where a referrer’s upline also earns a portion of the reward.
Level Configuration
| Field | Description |
|---|---|
| Level (1-10) | 1 = direct referrer, 2 = referrer’s referrer, etc. |
| Reward | 10 for a fixed amount or 5% for a percentage |
Managing Levels
- Click Add Commission Level to add a new level.
- Click Edit to update an existing level.
- Click Delete to remove a level.
Level 1 rewards the direct referrer. Level 2 rewards the referrer’s referrer, and so on.
Referrals Tab
The Referral Registrations list shows players who signed up using a referral code.
Status Workflow
PENDING → CONFIRMED → REWARDED
↘ ↓
REJECTED| Status | Meaning |
|---|---|
| PENDING | Registered but not yet verified |
| CONFIRMED | Registration confirmed, eligible for reward |
| REWARDED | Reward has been distributed to the referrer |
| REJECTED | Rejected due to fraud or policy violation |
Filtering Referrals
Filter by status (Pending, Confirmed, Rewarded, Rejected) to focus on the records requiring attention.
Actions
| Action | Description |
|---|---|
| Confirm | Manually confirm a pending referral as legitimate |
| Reward | Trigger reward distribution for a confirmed referral |
| Reject | Mark as fraudulent or invalid |
| Auto-Confirm Verified | Bulk confirm pending referrals whose referred users are verified |
Referral Codes Tab
Lists all referral codes. Search by code or username.
Each code entry shows the code, its owner, click count, conversions, status, and creation date.
| Action | Description |
|---|---|
| Regenerate | Generate a new code for a user (invalidates the old one) |
| Delete | Remove a referral code entirely |
Rewards Tab
The Affiliate Rewards list shows all rewards that have been calculated or distributed. Use All Levels to filter by commission level. Summary cards show the reward count, total distributed, and average reward.
Agent Permission Keys
Role tiers, custom roles, and per-agent overrides use the same set of 32 permission keys organized into five categories.
Player Permissions
| Key | Description |
|---|---|
player.create | Create new player accounts |
player.view | View player profiles and information |
player.edit | Edit player account details |
player.suspend | Suspend or unsuspend players |
player.transfer | Transfer players between agents |
player.view_balance | View player balance information |
player.view_hand_history | View player hand history |
player.set_limits | Set deposit/withdrawal/betting limits on players |
Finance Permissions
| Key | Description |
|---|---|
finance.deposit | Process deposits for players |
finance.withdraw | Process withdrawals for players |
finance.set_credit_line | Set credit lines for players |
finance.view_transactions | View transaction history |
finance.manual_adjustment | Make manual balance adjustments |
finance.transfer_chips | Transfer chips between accounts |
finance.wholesale_purchase | Buy chips in bulk at wholesale rates |
Sub-Agent Permissions
| Key | Description |
|---|---|
subagent.create | Create sub-agents under this agent |
subagent.edit | Edit sub-agent details |
subagent.suspend | Suspend or unsuspend sub-agents |
subagent.set_commission | Set commission rates for sub-agents |
subagent.set_limits | Set financial limits on sub-agents |
subagent.view_reports | View sub-agent reports and statistics |
Club Permissions
| Key | Description |
|---|---|
club.create | Create private clubs |
club.set_rake | Configure rake settings for club tables |
club.set_buyin | Set buy-in amounts for club tables |
club.manage_tables | Create and manage tables within clubs |
club.invite_players | Invite players to clubs |
club.set_chip_price | Set chip pricing within clubs |
Report Permissions
| Key | Description |
|---|---|
reports.own_commission | View own commission reports |
reports.subtree_rake | View rake reports for the entire downline |
reports.player_activity | View player activity reports |
reports.financial_summary | View financial summary reports |
reports.export | Export report data |
Audit Logging
All significant agent operations are recorded in the agent audit log. Logged actions include:
- Agent status changes (active, suspended, pending_kyc, closed)
- Hierarchy changes (create, reassign, detach)
- Settlement approvals, disputes, and payments
- Financial operations (deposits, withdrawals, transfers)
- Player assignments and removals
- Commission distribution events
Audit entries capture the action type, the agent involved, the resource affected, and the admin who performed the action. Admin actions on agents are also available in Logs (see the Logs guide).
Permissions Reference
Agents
| Action | Required Permission |
|---|---|
| View agents | agents:view |
| Create/edit/delete agents | agents:edit |
| View settlements | agents:view |
| Approve/pay settlements | agents:edit |
| View role tiers | agents:view |
| Manage role tiers | agents:edit |
| View commission templates | agents:view |
| Manage commission templates | agents:edit |
| View custom roles | agents:view |
| Manage custom roles | agents:edit |
| View financial controls | agents:view |
| Manage financial controls | agents:edit |
| Approve/reject transactions | agents:edit |
| View hierarchy settings | agents:view |
| Manage hierarchy settings | agents:edit |
The agents feature toggle must also be enabled globally.
Affiliates
The Affiliates sidebar entry requires affiliate-fraud:view, and the affiliates feature toggle must be enabled.
| Action | Required Permission |
|---|---|
| View affiliate overview, referrals, codes, and rewards | Any admin |
| Confirm, reward, or reject referrals | settings:edit |
| Manage commission levels | settings:edit |
| Regenerate or delete codes | settings:edit |