> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canvas-protocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Every configuration value the Canvas agent server reads.

Copy `.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.

<Warning>
  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.
</Warning>

## 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.         |