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

# Environment Variables

> Configuration reference for all applications

This page documents all environment variables used across ouroborai
applications. Required variables are marked with an asterisk (\*).

## API Server (`apps/api/`)

| Variable            | Required | Default           | Description                                                        |
| ------------------- | -------- | ----------------- | ------------------------------------------------------------------ |
| `PRIVATE_KEY`       | \*       | --                | Wallet private key for on-chain operations (hex, starts with `0x`) |
| `ANTHROPIC_API_KEY` | \*       | --                | Anthropic API key for the Claude-backed agent runner               |
| `ARB_RPC_URL`       | \*       | --                | Arbitrum One JSON-RPC URL (Alchemy, Infura, or public)             |
| `PORT`              |          | `3000`            | HTTP server port                                                   |
| `REDIS_URL`         |          | --                | Redis connection URL for persistent state                          |
| `PAY_TO_ADDRESS`    |          | `0x000...000`     | USDC recipient address for x402 payments                           |
| `SKIP_PAYMENT`      |          | `false`           | Set to `true` to disable x402 payment verification                 |
| `CORS_ORIGIN`       |          | `*` (all origins) | Comma-separated allowed CORS origins                               |
| `PIMLICO_API_KEY`   |          | --                | Pimlico bundler API key for ERC-4337 operations                    |
| `ALCHEMY_API_KEY`   |          | --                | Alchemy API key for NFT data and enhanced RPC                      |
| `API_KEYS`          |          | --                | Pre-seeded API keys (used in testing/staging)                      |

<Warning>
  Never commit `PRIVATE_KEY` or `ANTHROPIC_API_KEY` to version control. The
  `.env` file in `apps/api/` is excluded by `.gitignore`.
</Warning>

### x402 Payment Variables

The x402 middleware uses these variables for micropayment verification:

| Variable         | Description                             |
| ---------------- | --------------------------------------- |
| `PAY_TO_ADDRESS` | The address that receives USDC payments |
| `SKIP_PAYMENT`   | Bypass payment checks in development    |

When `REDIS_URL` is set, x402 nonces are tracked in Redis with the key
pattern `arb:nonce:{nonce}` and a 24-hour TTL to prevent replay attacks.

***

## Web App (`apps/web/`)

| Variable                     | Required | Default                 | Description                              |
| ---------------------------- | -------- | ----------------------- | ---------------------------------------- |
| `NEXT_PUBLIC_API_URL`        | \*       | `http://localhost:3000` | Backend API server URL                   |
| `NEXT_PUBLIC_DYNAMIC_ENV_ID` | \*       | --                      | Dynamic wallet connection environment ID |

Both variables use the `NEXT_PUBLIC_` prefix because they are accessed in
client-side React code.

<Note>
  The web app inlines types from `@arb-agent/sdk` to avoid importing
  Node.js-only modules into the browser bundle. The API URL is the only
  required connection between the web app and the backend.
</Note>

***

## Telegram Bot (`apps/telegram/`)

| Variable             | Required | Default                 | Description                         |
| -------------------- | -------- | ----------------------- | ----------------------------------- |
| `TELEGRAM_BOT_TOKEN` | \*       | --                      | Bot token from @BotFather           |
| `API_URL`            |          | `http://localhost:3000` | Backend API server URL              |
| `API_KEY`            |          | --                      | API key for authenticated endpoints |

***

## Twitter Bot

| Variable                | Required | Default                 | Description            |
| ----------------------- | -------- | ----------------------- | ---------------------- |
| `TWITTER_API_KEY`       | \*       | --                      | Twitter/X API key      |
| `TWITTER_API_SECRET`    | \*       | --                      | Twitter/X API secret   |
| `TWITTER_ACCESS_TOKEN`  | \*       | --                      | OAuth access token     |
| `TWITTER_ACCESS_SECRET` | \*       | --                      | OAuth access secret    |
| `API_URL`               |          | `http://localhost:3000` | Backend API server URL |

***

## CLI

| Variable  | Required | Default                 | Description                         |
| --------- | -------- | ----------------------- | ----------------------------------- |
| `API_URL` |          | `http://localhost:3000` | Backend API server URL              |
| `API_KEY` |          | --                      | API key for authenticated endpoints |

***

## MCP Server (`apps/mcp-server/`)

| Variable      | Required | Default             | Description                                |
| ------------- | -------- | ------------------- | ------------------------------------------ |
| `PRIVATE_KEY` | \*       | --                  | Wallet private key for on-chain operations |
| `ARB_RPC_URL` |          | Arbitrum public RPC | Arbitrum One JSON-RPC URL                  |

<Warning>
  The `.mcp.json` configuration file contains `PRIVATE_KEY` in plaintext.
  It is excluded from version control by `.gitignore` but exercise caution
  when sharing your project directory.
</Warning>

***

## Redis Key Prefixes

When `REDIS_URL` is configured, the API server uses these key patterns:

| Prefix                         | TTL      | Description                                    |
| ------------------------------ | -------- | ---------------------------------------------- |
| `arb:job:{id}`                 | None     | Job queue entries (pending, running, complete) |
| `arb:thread:{id}`              | None     | Conversation thread state and messages         |
| `arb:nonce:{nonce}`            | 24 hours | x402 payment nonce deduplication               |
| `arb:revenue:total`            | None     | Running total of USDC revenue                  |
| `arb:revenue:day:{YYYY-MM-DD}` | 90 days  | Daily revenue hash (count + total)             |
| `arb:revenue:recent`           | None     | Last 1000 payment records (capped list)        |
| `arb:revenue:payers`           | None     | Set of unique payer addresses                  |
| `arb:apikey:{hash}`            | None     | API key entries (hashed)                       |

***

## Example .env Files

<CodeGroup>
  ```bash apps/api/.env theme={"theme":{"light":"dracula","dark":"dracula"}}
  # Required
  PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
  ANTHROPIC_API_KEY=sk-ant-api03-XXXXXXXXXXXX
  ARB_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY

  # Optional
  REDIS_URL=redis://localhost:6379
  PORT=3000
  PAY_TO_ADDRESS=0xYourRevenueAddress
  SKIP_PAYMENT=true
  CORS_ORIGIN=http://localhost:3001
  ALCHEMY_API_KEY=YOUR_ALCHEMY_KEY
  ```

  ```bash apps/web/.env.local theme={"theme":{"light":"dracula","dark":"dracula"}}
  NEXT_PUBLIC_API_URL=http://localhost:3000
  NEXT_PUBLIC_DYNAMIC_ENV_ID=your_dynamic_env_id
  ```

  ```bash apps/telegram/.env theme={"theme":{"light":"dracula","dark":"dracula"}}
  TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxyz
  API_URL=http://localhost:3000
  ```
</CodeGroup>

<Tip>
  Copy the `.env.example` files included in each app directory as a starting
  point. They list all supported variables with placeholder values.
</Tip>