.env.example to .env and fill in the values. The four variables under Required must be set or the app will not boot; everything else is optional or has a default.
Secrets (bot token, private keys, API keys, database URL) are injected at runtime and must never be committed.
.env is gitignored. Private keys belong only in the production environment.Required
| Variable | Description |
|---|---|
DATABASE_URL | Postgres connection string. Schema self-applies on boot. |
TELEGRAM_BOT_TOKEN | Bot token from BotFather. Use a test bot locally. |
TELEGRAM_WEBHOOK_URL | Public HTTPS URL where Telegram delivers updates. |
TELEGRAM_WEBHOOK_SECRET | Shared secret validated on the webhook path. |
Core
| Variable | Default | Description |
|---|---|---|
NODE_ENV | development | Runtime mode. |
PORT | 3000 | HTTP port. |
MINI_APP_BASE_URL | webhook origin | Public base URL for Telegram Mini App buttons. |
ADMIN_TELEGRAM_ID | — | Telegram user ID that receives operational alert DMs (payout/refund failures, stuck-state sweeps). Empty disables alerts. |
Scoring
| Variable | Default | Description |
|---|---|---|
KIMI_API_KEY | — | Kimi (Moonshot AI) API key for transcript scoring. |
OPENAI_API_KEY | — | Fallback scorer when Kimi is unavailable. |
KIMI_BASE_URL, KIMI_MODEL, KIMI_PASS_THRESHOLD | code defaults | Scoring endpoint, model, and pass threshold (default threshold 0.7). Referenced by the scoring layer; defaults apply if unset. |
Chain and payments
| Variable | Default | Description |
|---|---|---|
BASE_RPC_URL | https://mainnet.base.org | Base RPC endpoint. |
USDC_BASE_ADDRESS | 0x8335…2913 | USDC token on Base. |
ESCROW_CONTRACT_ADDRESS | — | Deployed Canvas escrow address. |
DEPLOYER_PRIVATE_KEY | — | Deploy key (contract deployment only). |
RELAYER_PRIVATE_KEY | — | Relayer key — the only signer that can move escrow funds. Production only. |
COMPANY_WALLET | — | Treasury wallet that receives the platform fee. |
PLATFORM_FEE_BPS | 1000 | Platform fee in basis points (1000 = 10%). |
Bidding and deposits
| Variable | Default | Description |
|---|---|---|
MIN_BID_MICROUNITS | 10000 | Minimum bid ($0.01 in USDC micro-units). |
MIN_CAMPAIGN_QUANTITY | 1 | Minimum verifications per campaign. |
DEPOSIT_POLL_INTERVAL_MS | 30000 | Escrow deposit poll interval. |
DEPOSIT_TTL_MS | 7200000 | Deposit window (2h). |
DEPOSIT_URL_SECRET | — | Signs deposit Mini App URLs. |
PAYOUT_BATCH_INTERVAL_MS | 86400000 | Payout batch cadence (24h). <= 0 disables the scheduler. |
Optional integrations
| Variable | Description |
|---|---|
BASESCAN_API_KEY | Contract verification (npm run verify:escrow). |
BANKR_API_KEY | Bankr Agent API (optional spike script). |
SEED_ADVERTISER_TG_ID, SEED_BID, SEED_QUANTITY | Inputs for the seed:advertiser script. |