Environment Variables Reference

Complete reference for all PayWarden environment variables.

Copy-paste template

# ── Required ───────────────────────────────────────────────
VAULT_KEY=                        # openssl rand -hex 32
API_KEY=                          # openssl rand -hex 32
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/paywarden
REDIS_URL=redis://redis:6379
HOT_WALLET_ADDRESS=               # your TRON address (T...)
TRON_FULL_HOST=https://nile.trongrid.io
TRONGRID_API_KEY=                 # from trongrid.io

# ── Admin Dashboard ────────────────────────────────────────
ADMIN_PASSWORD=                   # min 12 characters
JWT_SECRET=                       # openssl rand -hex 32
HMAC_SECRET=                      # openssl rand -hex 32

# ── Optional ───────────────────────────────────────────────
PORT=3000
NODE_ENV=production
LOG_LEVEL=info
CONFIRMATIONS_REQUIRED=19
ORDER_EXPIRY_MINUTES=60
SCAN_MODE=address
SWEEP_DELAY_MINUTES=5
GAS_RESERVE_TRX=5
GAS_LOW_THRESHOLD=100
WEBHOOK_TIMEOUT_MS=5000
WEBHOOK_MAX_ATTEMPTS=10

---

Variable details

VAULT_KEY 🔴 Required

32-byte hex string. Encrypts your BIP39 mnemonic in vault.enc.

openssl rand -hex 32
# → a3f1c2d4e5b6a7f8...

Back this up immediately. Loss = cannot decrypt vault = funds locked.

---

API_KEY 🔴 Required

Authentication key for your backend's API calls. In multi-merchant mode, this becomes the default merchant's key.

openssl rand -hex 32

---

DATABASE_URL 🔴 Required

PostgreSQL connection string.

Environment	Value
Docker Compose	postgresql://postgres:postgres@postgres:5432/paywarden
External DB	postgresql://user:pass@host:5432/dbname?sslmode=require

---

REDIS_URL 🔴 Required

Redis connection string.

Environment	Value
Docker Compose	redis://redis:6379
Redis with auth	redis://:password@host:6379
Redis TLS	rediss://host:6380

---

HOT_WALLET_ADDRESS 🔴 Required

TRON address where all swept USDT is sent. Must be a wallet you control.

HOT_WALLET_ADDRESS=TXxx...your-wallet-address

---

TRON_FULL_HOST 🔴 Required

Network	Value
Mainnet	https://api.trongrid.io
Nile Testnet	https://nile.trongrid.io
Shasta Testnet	https://api.shasta.trongrid.io

---

TRONGRID_API_KEY 🔴 Required

Free API key from trongrid.io. Free tier: 100,000 requests/day.

---

ADMIN_PASSWORD 🟡 Recommended

Password for the admin dashboard at /admin. If not set, the admin dashboard is disabled.

Minimum 12 characters. Use a password manager to generate.

---

JWT_SECRET 🟡 Recommended

Signs admin session JWTs. Required if ADMIN_PASSWORD is set.

openssl rand -hex 32

---

HMAC_SECRET 🟡 Recommended

Used internally for HMAC-hashing API keys in the database. Required for multi-merchant mode.

openssl rand -hex 32

---

PORT Optional

Default: 3000

HTTP server port. Change if 3000 conflicts with another service.

---

NODE_ENV Optional

Default: development

Set to production for production deployments. Enables:

• Secure cookie flags
• Stricter CORS
• Reduced log verbosity

---

LOG_LEVEL Optional

Default: info

Value	Output
debug	Everything including internal state
info	Normal operation events
warn	Non-critical issues
error	Errors only

---

CONFIRMATIONS_REQUIRED Optional

Default: 19

Number of block confirmations before a payment is considered final. TRON produces ~1 block per 3 seconds.

Value	Time to confirm	Risk
1	~3s	High (reversible)
19	~60s	Low (standard)
27	~90s	Very low (high value)

---

ORDER_EXPIRY_MINUTES Optional

Default: 60

Minutes an unpaid order stays active before expiring.

---

SCAN_MODE Optional

Default: address

Value	Description
address	Poll each pending address individually
block	Scan every new block for USDT Transfer events

Block mode is more efficient with > 10 concurrent pending orders. See Configuration.

---

SWEEP_DELAY_MINUTES Optional

Default: 5

Minutes to wait after payment confirmation before initiating the fund sweep.

---

GAS_RESERVE_TRX Optional

Default: 5

TRX amount sent to each payment address before sweeping, to cover gas fees.

---

GAS_LOW_THRESHOLD Optional

Default: 100

Admin dashboard warning when hot wallet TRX balance drops below this value.

---

WEBHOOK_TIMEOUT_MS Optional

Default: 5000

Milliseconds to wait for your webhook endpoint to respond before marking the attempt as failed.

---

WEBHOOK_MAX_ATTEMPTS Optional

Default: 10

Maximum webhook delivery attempts before marking as failed.