Interface dedicated toAgency— network management regional distributor gaming shop, credits purchase/distribution, online USD wallet, cash transaction monitoring, and communication with the kiosk ecosystem.
Agent is the second layer in KioskGaming's four-layer hierarchy. Each Agent is in charge many Shops and receive credits from SuperAgent or the platform.
Agent:Regional distributor. Buy credits from SuperAgent/platform, sell credits to shops via cash transactions (cash-credits), establishcostRatefor each shop and monitor credit wallet + online USD wallet.
B2B Chain: SuperAgent → Agent→ Shop → Cashier → Player. Credits flow down; Cash/USD flows back upcostRate.
Repo notes:Nested folderkioskgaming_backend/just a reference backend clone — the frontend calls the API viaREACT_APP_API_BASE_URL, do not import backend code.
The standard operating process of an Agent from purchasing credits to monitoring shop performance.
Agent opensCreditPurchaseModal, select quantity and payment method (ZeroX crypto, eCash, bank transfer...). After payment is completed, credits are added to the Agent's wallet.
From the shop details page, use AgentSellCreditsCashToShopTrigger
(SellCreditsCashModalfrom@kioskgaming/ui) call
POST /agent/shops/:id/cash-credits— record cash paid by the shop
and distribute credits simultaneously.
Agent creates a new shop with information: name, email, phone number, password and costRate— decimal rate (0.05 = 5%) Agent collects on each credit delivered to that shop.
Dashboard displays credits balance, shop list, number of players, recent transactions andAgentHierarchyMiniTree— visual hierarchy tree Agent → Shops.
If the shop violates, the Agent uses itShopGovernanceModalto pause (Suspend), reopen (Unsuspend) or terminate the contract (Terminate) of a shop.
Agent has full CRUD rights for Shops within its scope, including setting prices and control operating status.
Usage formreact-hook-formv7. Fields: name, username, email, phone, password andcostRate (% → cost_ratedecimal). File:ShopsPage.tsx
List all shops with status, credits balance, number of players and quick action button. Support distributing credits directly from the list.
Route /shops/:shopIduseShopDetailPageRedesign.tsx (import alias ShopDetailPage). Display credit/USD shop wallet, game mapping, sell/withdraw credits.
ShopGovernanceModal.tsxprovides three administrative actions with validation:Suspend, Unsuspend, Terminate.
costRateis a decimal number 0–1 (eg 0.05 = 5%). Shop must have costRatebiggeragent's costRate.
Amount owed by shop = credits × shopCostRate; agent profit = credits × (shopCostRate − agentCostRate).
UseformatCostRate()andpercentInputToRate() in costFormat.ts.
| Shop status | Show | Agent can do it | Transaction |
|---|---|---|---|
| Active | Green badge | Distribute credits, view details, Suspend / Terminate | Normal |
| Suspended | Golden badge | Unsuspend, Terminate, see details | Blocked |
| Terminated | Red badge | View only — cannot be restored | Closed |
Credits are the intermediate currency in the system. Agent buys credits from the platform and distributes them Go to the shops to let the shops serve the players. This is the core currency flow of the entire ecosystem.
Balancecredit_balanceon dashboard. Buy itCreditPurchaseModal, convert from USD toconvertBalanceToCredits. Ledger at/transactions.
online_balance_net— accumulated commission/cash. Page/online-transactions, withdraw crypto via OTP +createAgentOnlineBalanceWithdrawal.
Agent enters or selects the amount he wants to buy. With eCash, only select from a fixed list (ECASH_APP_ALLOWED_AMOUNTS).
Show options: ZeroX crypto, eCash app, bank transfer, etc. Each method has its own separate UI.
Modal embed iframe checkout provider + open new tab button. ZeroX static wallets via/agent/payments/zeroxprocessing/static-wallets.
AgentPaymentReturnPage.tsxReceive redirect after payment. Credits are added to the Agent wallet.
ZeroX Crypto— Cryptocurrency payments. Display wallet address, QR code. Options defined atZEROX_PAYMENT_OPTIONS.
eCash App— Internal payment application. Only accept denominations listed inECASH_APP_ALLOWED_AMOUNTS.
Bank Transfer— Traditional bank transfer with account information provided.
SellCreditsCashToShopTriggeron Shop Detail callcreateShopCashCredits. Record cash transactions + distribute credits once.
WithdrawCreditsFromShopTrigger → POST /agent/shops/:id/credits/withdraw. Refund credits to agent wallet when needed.
Agents have many communication channels with shops and players: system-wide broadcast, targeted popups and real-time notification bell.
Send a broadcast message to all shops/players belonging to the Agent. Link markup support is handled bybroadcastLinkMarkup.ts.
Send notification popups to a specific shop. Suitable for privacy alerts, store-specific promotion announcements.
Bell icon with badge counting the number of unread notifications. Displayed in the header of every page. Demo:🔔 3Notification
AgentInAppPopupGate.tsxis a wrapper component placed at a high level in the component tree. It listens for broadcasts/popups coming from the server andautomatically block the screento display a message before the Agent continues using the app.
broadcastLinkMarkup.ts:The parser converts special link syntax in broadcast content into clickable HTML anchor tags.BroadcastMessageBody.tsxrender the parsed result.
Enter content; link markup supported [text](url).
Backend sends message to all shops/players under Agent.
Shops/players receive popup overlay on login or in real time.
Dashboard Home (DashboardPage.tsx) is the Agent's operating center — providing
Instant overview of the entire network.
AgentHierarchyMiniTree.tsx— Compact hierarchical tree displayed right on the Dashboard. Visualize the Agent → Shops relationship with summary metrics for each branch.
AvailableCreditsCallout.tsx— featured block displays the Agent's current credit balance, with "Buy Credits" and "Distribute" buttons for quick access.
AgentHomeRecentTransactions.tsx— most recent transactions displayed on Dashboard. List type, amount, shop involved and time.
Full transaction history page (AgentTransactionsPage.tsx) with filter by time, transaction type and shop.
| Widget | Component | Data displayed | Action |
|---|---|---|---|
| Credit Balance | AvailableCreditsCallout |
Agent wallet balance | Purchase/Distribution |
| Shops Overview | DashboardPage |
Total shops, active / suspended | See details |
| Players Count | DashboardPage |
Total players under all shops | Xem PlayersPage |
| Recent Transactions | AgentHomeRecentTransactions |
5–10 most recent transactions | See all |
| Hierarchy Tree | AgentHierarchyMiniTree |
Agent tree → Shops | Drill-down shop |
Technical stack, directory structure, important utilities and ZeroX payment integration.
// Switch display % → internal rate
percentInputToRate(5) // "5%" → 0.05
// Internal format rate → display
formatCostRate(0.05) // 0.05 → "5%"// eCash: only allows fixed denominations
ECASH_APP_ALLOWED_AMOUNTS = [
50, 100, 200, 500, 1000
]
// ZeroX: crypto option
ZEROX_PAYMENT_OPTIONS = [
{ id: 'eth', label: 'Ethereum' },
{ id: 'usdt', label: 'USDT' },
...
]ZeroXis the platform's crypto payments integration. Agent chooses token (ETH, USDT...), The system displays the wallet address and QR code. After the on-chain transaction is confirmed, Backend webhook updates Agent balance automatically.
sanitizeUser.tssanitize user data before displaying — remove sensitive information, standardize field names. Used before rendering any user object to the UI.
| Route | Component | Function |
|---|---|---|
/ |
DashboardPage |
Home — credits + USD balance |
/transactions |
AgentTransactionsPage |
Ledger credit wallet |
/online-transactions |
OnlineBalanceTransactionsPage |
Ledger USD wallet + withdrawal |
/cash-transactions |
CashTransactionsLedgerPage |
Cash transactions with shops |
/provider-fees |
ProviderFeesPage |
Provider fee (read-only) |
/fraud-indicators |
FraudIndicatorsPage |
Warning about cheating players |
/shops |
ShopsPage |
List + create shop |
/shops/:shopId |
ShopDetailPageRedesign |
Shop details + sell/withdraw credits |
/players |
PlayersPage |
Players (read-only) |
/broadcasts/send |
SendBroadcastPage |
Send broadcast |
/popups/send |
SendShopPopupPage |
Send in-app popups |
/settings |
SettingsPage |
2FA, balance alerts, verification |
/payment/{success,cancelled,error} |
AgentPayment*Page |
Callback after online payment |
Agents have visibility over all players belonging to all shops in the network, but do not directly interfere with player accounts.
Lists all players across all Agent shops. Can filter by shop and status. Displays username, source store, balance, registration date.
View details of a player: personal information, transaction history, recent sessions, which shop manages it. Read-only from the Agent side.
Note on authorization: Agent Are nothas the right to create, edit or delete players. Players are created by the Shop or registered themselves. Agent only has rights to view players within your network.
Dashboard, Shops, ShopDetail, Players, Transactions, Online/Cash transactions, Provider fees, Fraud, Broadcast, Popup, Settings, Payment return
/agent/*, /agent-auth/* via Axios singleton services/api.ts → backend B2B routes
craco start/build · packages file:../packages/ui + page-loading · PORT 3003
Credit CDN + USD online balance; Buy online, sell cash to the shop, withdraw crypto
SuperAgent → Agent → Shop → Cashier → Player
Xem 04+ Technical details— full endpoint, auth, cookbook