Business features

---

1. Agent wallet management

Credits wallet

• Primary balance (credit_balance) shown on sidebar and dashboard.
• Used to buy credits and distribute to shops.

USD online balance

• Separate USD wallet (online_balance_net).
• Used to buy credits or withdraw crypto.
• Separate ledger at /online-transactions.

Buy credits (CreditPurchaseModal)

Two methods:

Method	Flow
Crypto	ZeroxProcessing static wallets (BTC, DOGE, LTC…), QR code
Balance	Convert USD → credits per cost_rate

flowchart LR
  A[Agent opens buy credit modal] --> B{Choose method}
  B -->|Crypto| C[Select coin → static wallet QR]
  B -->|Balance| D[Enter USD → preview credits]
  D --> E[POST /agent/convert-balance-to-credits]
  C --> F[Agent sends crypto → backend callback]

Distribute & withdraw credits

Action	API	Description
Distribute to shop	POST /agent/credits/distribute	Agent → Shop
Withdraw from shop to agent	POST /agent/shops/:id/credits/withdraw	Shop → Agent

---

2. Shop management

List (/shops)

• View all shops under the agent.
• Create shop: name, username, email, phone, password, cost_rate (must be > agent cost rate).
• Suspend / Unsuspend via ShopGovernanceModal.

Shop detail (/shops/:shopId)

Overview tab

• Shop info, credit balance, USD balance.
• Actions: distribute credits, withdraw credits from shop.

Security tab

Action	API
Rename	PATCH /agent/shops/:id/name
Change password	PATCH /agent/shops/:id/password
Update cost rate	PATCH /agent/shops/:id/cost
Popup permission	PATCH /agent/shops/:id/popup-permissions

Credit / USD transactions tab

• Separate ledger per shop.
• Transaction detail modal.

Games tab

• Enable/disable game providers for shop.
• GET/PUT /agent/shops/:id/game-mappings.

Hierarchy stats (AgentHierarchyMiniTree)

• Deposit/withdrawal/user stats per shop by date range.
• API: GET /agent/shops/stats?from=...&to=....

---

3. Player management

List (/players)

• All players under agent shops.
• Client-side filter: shop, username, phone, email.

Detail (/players/:playerId)

AgentPlayerDetailPanel shows:

• Profile, balance, linked shop.
• Wallet transaction history (GET /agent/players/:id/transactions).

note

Agent cannot deposit/redeem credits directly for players — that belongs to Shop Portal.

---

4. Credit transactions (/transactions)

• Uses PortalCreditTransactionsLedger from @kioskgaming/ui.
• Filter: period, type, search; pagination; CSV export.
• Credit transaction detail modal.

---

5. USD withdrawal (/online-transactions)

Crypto withdrawal flow from USD wallet:

sequenceDiagram
  participant A as Agent
  participant P as Agent Portal
  participant B as Backend

  A->>P: Open USD withdrawal form
  P->>B: GET /agent/online-balance/withdrawals/otp/eligibility
  P->>B: POST .../otp/send
  A->>P: Enter OTP
  P->>B: POST .../otp/verify
  A->>P: Select network, enter address
  P->>B: GET .../withdrawals/fee (preview)
  P->>B: POST /agent/online-balance/withdrawals

• Networks: BTC, ETH, USDT (ERC/TRC per config).
• Limits: GET /agent/portal-withdrawal-limits.
• Requires verified email/phone account.

---

6. Provider Fees (/provider-fees)

• Read-only — agent can view but not edit.
• Shows fees by provider/operation/methodId.
• Gateway fee, system fee, network fee.

---

7. Fraud Indicators (/fraud-indicators)

• PlayerFraudIndicatorsPanel from @kioskgaming/ui.
• Filter by shop.
• Indicator detail + withdrawal profit analysis.
• Resolve indicator with notes.

---

8. Communication

Broadcasts (receive)

• AgentNotificationBell polls every 2 minutes.
• GET /agent/broadcasts → acknowledge via POST .../ack.

Broadcasts & Popups (send) — requires can_delegate_popups

Type	Route	API
Broadcast	/broadcasts/send	POST /agent/broadcasts
In-app popup	/popups/send	POST /agent/in-app-popups

Popup modes: once / sticky_daily.

---

9. Settings & Security (/settings)

Setting	API	Notes
Cost rate	Display from profile	Read-only — set by super agent/admin
Low balance warning	PATCH /agent/settings/low-balance-warning	Minimum threshold $50
2FA login	PATCH /agent/settings/two-factor	Email/phone, must be verified first
Account verification	send-otp → confirm	VerifyNowTrigger in header

---

10. Agent vs Shop Portal comparison

Feature	Agent Portal	Shop Portal
Shop management	✅ Create, suspend, cost rate	—
Player management	✅ View (read-only actions)	✅ Create, deposit, ban
Credit distribution	✅ Agent → Shop	—
Buy credits	✅	✅
USD crypto withdrawal	✅	✅
Approve player withdrawal	—	✅
Cashier management	—	✅
Kiosk domain	—	✅
Provider fees	Read-only	Editable
Game mappings	✅ Per shop	—

---

Implementation notes

1. Default port 3003 — avoids conflict with admin (3000) and shop (3004).
2. CORS: add localhost:3003 to admin Domains or use DISABLE_CORS=true for local dev.
3. Payment return: backend redirects to /payment/success|cancelled|error.
4. Shop cost rate: must be greater than agent cost rate when creating/updating shop.
5. Zerox methods cache: useSupportedZeroxMethods caches 24h in localStorage.