Configuration

All configuration is done via environment variables. Copy .env.example to .env and fill in the values. PayWarden validates the environment at startup with Zod and fails fast if anything is missing or invalid.

Canonical reference

This page is a short overview. The full, authoritative list of every variable — with defaults, constraints, and descriptions — lives on the Environment Variables Reference page. If anything on this page disagrees with env-vars.md, env-vars.md wins.

What you must set

At minimum, PayWarden needs the following variables to start:

• DATABASE_URL, REDIS_URL
• API_KEY, WEBHOOK_SECRET, VAULT_KEY, HMAC_SECRET
• ADMIN_PASSWORD, JWT_SECRET
• TRONGRID_API_KEY, USDT_CONTRACT

See Environment Variables Reference → Required for the constraints on each (min length, hex format, etc.) and the copy-paste .env template.

Network endpoints

Set TRON_NETWORK to pick the chain. The default is nile (testnet).

TRON_NETWORK	USDT contract
mainnet	TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
nile	TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf
shasta	(use the Shasta USDT contract)

Start with Nile Testnet

Use the Nile testnet during development. Get free testnet USDT from the Nile faucet.

Scan modes

PayWarden's chain watcher supports two modes via SCAN_MODE.

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).
• Uses Redis to track the set of pending addresses.

Admin dashboard

ADMIN_PASSWORD and JWT_SECRET are required. After starting PayWarden, visit http://localhost:3000/admin and log in with your ADMIN_PASSWORD.

Proxy, CORS, and SSRF safety

Three toggles — TRUST_PROXY, CORS_ORIGIN, ALLOW_PRIVATE_CALLBACKS — default to the safe value and should only be changed with intent. See the Proxy & Safety section of the full reference for the exact semantics and failure modes.

Fund sweeping

Sweeping is opt-in. Set both HOT_WALLET_KEY and COLD_WALLET_ADDRESS to enable it; leave either unset to disable. Sweep tuning variables (SWEEP_MODE, SWEEP_GAS_TOPUP_TRX, SWEEP_MIN_USDT, SWEEP_DELAY_MS, HOT_WALLET_ALERT_TRX) are documented in the Fund Sweep section of the full reference.

Generating secure values

# VAULT_KEY — most critical, back this up!
openssl rand -hex 32

# HMAC_SECRET / JWT_SECRET / API_KEY / WEBHOOK_SECRET
openssl rand -hex 32