Configuration
All configuration is done via environment variables. Copy .env.example to .env and fill in the values.
Required variables
| Variable | Description | Example |
|---|---|---|
VAULT_KEY | 32-byte hex key for encrypting your mnemonic | openssl rand -hex 32 |
API_KEY | Secret key your backend uses to authenticate API calls | openssl rand -hex 32 |
DATABASE_URL | PostgreSQL connection string | postgresql://user:pass@host:5432/db |
REDIS_URL | Redis connection string | redis://localhost:6379 |
HOT_WALLET_ADDRESS | TRON address where swept funds are sent | TXxx... |
TRON_FULL_HOST | TronGrid API endpoint | see below |
TRONGRID_API_KEY | TronGrid API key (free tier available) | from trongrid.io |
Network endpoints
| Network | TRON_FULL_HOST |
|---|---|
| Mainnet | https://api.trongrid.io |
| Nile Testnet | https://nile.trongrid.io |
Start with Nile Testnet
Use the Nile testnet during development. Get free testnet USDT from the Nile faucet.
Optional variables
| Variable | Default | Description |
|---|---|---|
PORT | 3000 | HTTP server port |
CONFIRMATIONS_REQUIRED | 19 | Block confirmations before order is confirmed |
ORDER_EXPIRY_MINUTES | 60 | Minutes before unpaid order expires |
SCAN_MODE | address | address or block scanning mode |
WEBHOOK_TIMEOUT_MS | 5000 | Webhook delivery timeout |
LOG_LEVEL | info | Pino log level (debug/info/warn/error) |
ADMIN_PASSWORD | — | Password for the admin dashboard |
JWT_SECRET | — | Secret for admin session JWTs |
HMAC_SECRET | — | Secret for API key HMAC hashing |
Scan modes
SCAN_MODE=address (default)
- Polls TronGrid for transactions to each pending payment address individually
- Works within TronGrid free tier for low volume (< 10 concurrent orders)
- Best for: development, low-traffic production
SCAN_MODE=block
- Scans each new block for any USDT Transfer events
- More efficient at high volume (> 10 concurrent orders)
- Requires Redis to track pending addresses
- Automatically falls back to address mode after 5 consecutive failures
Admin dashboard
To enable the admin dashboard at /admin:
dotenv
ADMIN_PASSWORD=your-secure-password
JWT_SECRET=<openssl rand -hex 32>Then visit http://localhost:3000/admin and log in with your ADMIN_PASSWORD.
Generating secure values
bash
# VAULT_KEY — most critical, back this up!
openssl rand -hex 32
# API_KEY
openssl rand -hex 32
# JWT_SECRET
openssl rand -hex 32
# HMAC_SECRET
openssl rand -hex 32