Managing Wallets
Operational guide for per-user wallets — monitoring, balance tracking, and best practices.
Managing Wallets
Operational guide for per-user wallets. For API setup, see Wallet Payments.
Architecture
| Property | Details |
|---|---|
| Addresses per user | 2 (one TRC20, one ERC20) |
| Persistence | Permanent — same address for all deposits |
| Monitoring | Payment detector cron every 10 seconds |
| Balance tracking | Off-chain ledger updated on confirmed deposit |
Deposit Detection
On detection: transaction recorded → fee deducted → net amount credited → webhook fires.
Set isActive: false to stop monitoring a wallet. Address remains valid but deposits won't be auto-detected.
Fees
| Deposit Min Fee | Withdrawal Fee | |
|---|---|---|
| TRC20 | 1 USDT | 2 USDT flat |
| ERC20 | 1.50 USDT | 2–2.5 USDT flat |
Fee payer configurable per merchant. Details: Settlement & Reconciliation
Pagination
All list endpoints capped at 100 per page.
| Parameter | Default | Max |
|---|---|---|
page | 1 | — |
limit | 20 | 100 |
search | — | userId, email, name, walletAddress |
Best Practices
- Store wallet addresses in your DB alongside user records
- Display both addresses (TRC20 + ERC20) with clear network labels
- Warn users about wrong-network deposits (manual recovery required)
- Verify webhook signatures on deposit notifications
- Reconcile using transaction hashes as source of truth
- Implement idempotency for duplicate webhook deliveries
Updated 26 days ago