> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/getting-started/configuration.md).

# Configuration

## Gotts Config File

The `@gotts.ai/core` package manages a persistent configuration file at `~/.gotts/config.json`. This file stores wallet credentials, authentication keys, and operator preferences.

### File Location and Permissions

| Path                   | Description                             |
| ---------------------- | --------------------------------------- |
| `~/.gotts/`            | Config directory (permissions: `0o700`) |
| `~/.gotts/config.json` | Config file (permissions: `0o600`)      |

The directory and file are created automatically by `saveConfig()`. File permissions are set to owner-only read/write (`0o600`) to protect private keys.

### Config Fields

```typescript
interface GottsConfig {
  mode: "privy" | "local"; // Wallet mode
  privyAppId?: string; // Privy application ID
  webAppUrl?: string; // Portal server URL (for proxy mode)
  walletId?: string; // Privy wallet ID
  walletAddress?: string; // Wallet Ethereum address
  authPrivateKey?: string; // P-256 private key (base64 PKCS8 DER)
  authPublicKey?: string; // P-256 public key (base64 SPKI DER)
  allowedAddresses: string[]; // Addresses this wallet can send to
  privyAppSecretStorage?: "keychain" | "plaintext"; // Where app secret is stored
  createdAt?: string; // ISO 8601 timestamp
  agentId?: string; // ERC-8004 agent ID (uint256)
}
```

### Usage

```typescript
import {
  loadConfig,
  saveConfig,
  configExists,
  configPath,
} from "@gotts.ai/core";

// Check if config exists
if (configExists()) {
  const config = loadConfig(); // Returns GottsConfig | null
  console.log(config?.walletAddress);
}

// Save config (creates ~/.gotts/ if needed)
saveConfig({
  mode: "privy",
  privyAppId: "clx...",
  walletId: "...",
  walletAddress: "0x...",
  allowedAddresses: ["0x..."],
});

// Get config path
console.log(configPath()); // ~/.gotts/config.json
```

### Migration

`loadConfig()` automatically handles backward compatibility. Legacy fields from older config formats are migrated to the current schema on read. The file is not rewritten — migration happens in memory only.

### Fetch Privy App ID

If you only have a Portal server URL, you can fetch the Privy App ID:

```typescript
import { fetchPrivyAppId } from "@gotts.ai/core";

const appId = await fetchPrivyAppId("https://portal.gotts.ai");
```

## Environment Variables

### Root `.env` (Monorepo-Wide)

The monorepo uses a single root `.env` file that is loaded by all root-level scripts via `dotenv-cli`. Copy the example and fill in the values:

```bash
cp .env.example .env
```

Root scripts like `pnpm safe:dev`, `pnpm safe:inspect`, `pnpm devenv`, etc. automatically load this file — no per-package `.env` files needed. Package-level scripts (e.g., `cd packages/safe && pnpm dev`) do **not** auto-load the root `.env`; use the root-level scripts instead, or set environment variables manually.

The following environment variables are available:

| Variable                  | Description                                     |
| ------------------------- | ----------------------------------------------- |
| `ETHEREUM_RPC_URL`        | Ethereum mainnet RPC endpoint                   |
| `BASE_RPC_URL`            | Base mainnet RPC endpoint                       |
| `SEPOLIA_RPC_URL`         | Sepolia testnet RPC endpoint                    |
| `ETHERSCAN_API_KEY`       | Etherscan API key for contract verification     |
| `BASESCAN_API_KEY`        | Basescan API key for Base contract verification |
| `PRIVY_APP_ID`            | Privy application ID (wallet provider)          |
| `PRIVY_APP_SECRET`        | Privy application secret                        |
| `UNISWAP_V3_SUBGRAPH_URL` | Uniswap V3 subgraph endpoint                    |
| `UNISWAP_V4_SUBGRAPH_URL` | Uniswap V4 subgraph endpoint                    |

## Devenv Configuration

The local development environment (`packages/devenv`) uses `DEVENV_*` prefixed environment variables. Copy `.env.devenv.example` to `.env.devenv` and customize:

```bash
cd packages/devenv
cp .env.devenv.example .env.devenv
```

| Variable                 | Default                   | Description               |
| ------------------------ | ------------------------- | ------------------------- |
| `DEVENV_PORT`            | `0` (auto)                | Anvil port                |
| `DEVENV_CHAIN_ID`        | `31337`                   | Chain ID                  |
| `DEVENV_FORK_URL`        | (empty)                   | Fork URL for mainnet fork |
| `DEVENV_SEED`            | `true`                    | Seed test data            |
| `DEVENV_UI`              | `false`                   | Start debug UI            |
| `DEVENV_UI_PORT`         | `3001`                    | Debug UI port             |
| `DEVENV_VERBOSE`         | `false`                   | Verbose output            |
| `DEVENV_JSON`            | `false`                   | JSON output (for CI)      |
| `DEVENV_DEPLOYMENT_PATH` | `.devenv-deployment.json` | Where to save addresses   |

See the [Local Testnet guide](https://github.com/wpank/gotts.ai-monorepo/blob/main/docs/guides/local-testnet.md) for full usage instructions.

## Gotts Safe Configuration

Gotts Safe (`@gotts.ai/safe`) uses `GOTTS_*` prefixed environment variables. A complete `.env.example` is included in the package. Configuration is validated at startup via Zod with cross-field validation.

### Core Settings

| Variable           | Default | Description                                 |
| ------------------ | ------- | ------------------------------------------- |
| `GOTTS_PROFILE`    | `data`  | Comma-separated tool profiles to activate   |
| `GOTTS_CHAINS`     | `all`   | Comma-separated chain names or IDs          |
| `GOTTS_LOG_LEVEL`  | `info`  | Log level: `debug`, `info`, `warn`, `error` |
| `GOTTS_LOG_FORMAT` | `text`  | Log format: `text` or `json`                |
| `GOTTS_TRANSPORT`  | `stdio` | Transport: `stdio` or `http`                |

### Wallet Configuration

At least one wallet configuration is required for write profiles (`trader`, `lp`, `vault`, `fees`, `full`, `dev`). Read-only profiles (`data`, `erc8004`, `intelligence`, `dashboard`) do not require a wallet.

| Variable                       | Description                  |
| ------------------------------ | ---------------------------- |
| `GOTTS_WALLET_PRIVATE_KEY`     | Local private key (dev only) |
| `GOTTS_PRIVY_APP_ID`           | Privy application ID         |
| `GOTTS_PRIVY_APP_SECRET`       | Privy application secret     |
| `GOTTS_PRIVY_WALLET_ID`        | Privy wallet ID              |
| `GOTTS_PRIVY_AUTH_PRIVATE_KEY` | Privy auth signing key       |
| `GOTTS_SAFE_ADDRESS`           | Safe multisig address        |
| `GOTTS_SAFE_OWNER_PRIVATE_KEY` | Safe owner key               |
| `GOTTS_ZERODEV_PROJECT_ID`     | ZeroDev project ID           |
| `GOTTS_ZERODEV_SESSION_KEY`    | ZeroDev session key          |

### Safety Limits

| Variable                        | Default  | Description                       |
| ------------------------------- | -------- | --------------------------------- |
| `GOTTS_SAFETY_MAX_TX_USD`       | `10000`  | Max USD per transaction           |
| `GOTTS_SAFETY_MAX_SESSION_USD`  | `50000`  | Max USD per session               |
| `GOTTS_SAFETY_MAX_DAILY_USD`    | `100000` | Max USD per day                   |
| `GOTTS_SAFETY_MAX_SLIPPAGE_BPS` | `100`    | Max slippage in basis points (1%) |
| `GOTTS_SAFETY_TOKEN_ALLOWLIST`  | `strict` | Token allowlist mode              |
| `GOTTS_SAFETY_SKIP_SIMULATION`  | `false`  | Skip pre-flight simulation        |

### RPC Endpoints

Custom RPC endpoints for each chain. Falls back to public RPCs if not set.

| Variable              | Chain             |
| --------------------- | ----------------- |
| `GOTTS_RPC_ETHEREUM`  | Ethereum (1)      |
| `GOTTS_RPC_OPTIMISM`  | Optimism (10)     |
| `GOTTS_RPC_BNB`       | BNB Chain (56)    |
| `GOTTS_RPC_POLYGON`   | Polygon (137)     |
| `GOTTS_RPC_ZKSYNC`    | zkSync Era (324)  |
| `GOTTS_RPC_BASE`      | Base (8453)       |
| `GOTTS_RPC_ARBITRUM`  | Arbitrum (42161)  |
| `GOTTS_RPC_CELO`      | Celo (42220)      |
| `GOTTS_RPC_AVALANCHE` | Avalanche (43114) |
| `GOTTS_RPC_BLAST`     | Blast (81457)     |
| `GOTTS_RPC_UNICHAIN`  | Unichain (130)    |

### Cross-Field Validation

The config system enforces these constraints at startup:

1. **Write profiles require a wallet** — `trader`, `lp`, `vault`, `fees`, `full`, and `dev` profiles fail to start without wallet configuration
2. **Pinata requires JWT** — Setting `GOTTS_IPFS_MODE=pinata` requires `GOTTS_PINATA_JWT`
3. **Profile validation** — Each comma-separated profile value must be a valid profile name
4. **Chain validation** — Each comma-separated chain value must be a supported chain name or numeric ID

## Tool Profiles

The `GOTTS_PROFILE` environment variable controls which MCP tools are loaded by Gotts Safe. Set it to one or more comma-separated profiles:

```bash
GOTTS_PROFILE=vault
GOTTS_PROFILE=trader,vault
```

Profiles use additive inheritance — each profile includes the tools of its parent profiles:

| Profile        | Inherits From     | Description                                                              |
| -------------- | ----------------- | ------------------------------------------------------------------------ |
| `data`         | —                 | Core data tools (prices, pools, tokens)                                  |
| `trader`       | `data`            | Data + swap execution                                                    |
| `lp`           | `trader`          | Data + trading + liquidity management                                    |
| `vault`        | `data`            | Data + all vault tools (24 core + proxy)                                 |
| `fees`         | `data`            | Data + TokenJar/Firepit tools                                            |
| `erc8004`      | `data`            | Data + identity/reputation tools                                         |
| `intelligence` | `data`, `erc8004` | Data + identity + intelligence/analysis tools                            |
| `learning`     | —                 | Self-improvement + memory tools. Composable with any other profile.      |
| `dashboard`    | `data`            | Data + portfolio/P\&L + memory + observability + vault read. Composable. |
| `full`         | all               | All tools                                                                |
| `dev`          | `full`            | Full + debug tools                                                       |

## Root Commands

These commands run across all packages in the monorepo:

```bash
pnpm build       # Build all packages (tsup for TypeScript, forge for Solidity)
pnpm test        # Run all unit tests (vitest)
pnpm lint        # Lint all TypeScript (ESLint)
pnpm format      # Format all files (Prettier)
```

### Gotts Safe (root-level)

These scripts load the root `.env` automatically:

```bash
pnpm safe:dev        # Start Safe MCP server (stdio)
pnpm safe:dev:http   # Start Safe MCP server (HTTP on port 3000)
pnpm safe:inspect    # Launch MCP Inspector at http://localhost:6274
pnpm safe:build      # Build Safe package
pnpm safe:test       # Run Safe tests
```

### Devenv (root-level)

These scripts also load the root `.env`:

```bash
pnpm devenv          # Start Anvil + deploy + seed + debug UI
pnpm devenv:fresh    # Wipe state and redeploy from scratch
```

For package-specific commands, see the package README or the repository root [CLAUDE.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/CLAUDE.md).