Configuration

web3agent is configured through environment variables. Set them in a .env file in your project root, in your shell, or in the env field of your MCP host config.

---

Environment variables

Core

Variable	Default	Required	Description
CHAIN_ID	8453	No	Default chain for all tool calls. See supported chains.
PRIVATE_KEY	—	For writes	Hex-encoded private key (0x...). Required for any tool that signs transactions.
MNEMONIC	—	For writes	BIP-39 mnemonic phrase. Alternative to PRIVATE_KEY.
RPC_URL	—	No	Custom RPC endpoint for the default chain. Overrides the built-in public RPC.

Do not commit .env files containing PRIVATE_KEY or MNEMONIC to version control. Add .env to your .gitignore. Use environment secrets in CI/CD pipelines.

Write safety

Variable	Default	Description
CONFIRM_WRITES	true	When true, all write operations (swaps, transfers, contract writes) are queued for confirmation before executing. Set to false for autonomous agents.

With CONFIRM_WRITES=true, write tools return a confirmation ID instead of executing immediately. Call transaction_confirm with that ID to release the operation.

# Disable confirmation for autonomous agents
CONFIRM_WRITES=false

Policy engine

The policy engine caps how much an autonomous agent can spend. Disabled by default.

Variable	Default	Description
POLICY_ENABLED	false	Enable the treasury policy engine.
POLICY_MAX_SINGLE_TX_USD	—	Maximum USD value for a single transaction. Transactions above this limit are rejected before hitting the chain.
POLICY_MAX_DAILY_USD	—	Maximum total USD spend per day (resets at midnight UTC). Cumulative spend is tracked across all write operations.

POLICY_ENABLED=true
POLICY_MAX_SINGLE_TX_USD=500
POLICY_MAX_DAILY_USD=2000

API keys

Variable	Required for	Description
ETHERSCAN_API_KEY	Higher Etherscan rate limits	Etherscan-compatible API key. Used for contract ABI lookups and transaction data on chains that support Etherscan.
LIFI_API_KEY	LI.FI bridge tools	API key for LI.FI bridge and swap routes. Without this, LI.FI tools use the public rate-limited endpoint.
ZEROX_API_KEY	0x swap plugin	Optional. Enables the 0x price aggregation plugin via GOAT SDK.
COINGECKO_API_KEY	Higher CoinGecko rate limits	Optional. Enables the CoinGecko Pro API for higher rate limits on market data tools.

Exchange access

Variable	Description
CCXT_CONFIG_PATH	Path to a JSON file containing CCXT exchange credentials. Used by trading tools that interact with centralized exchanges via CCXT.

The CCXT config file format:

{
  "hyperliquid": {
    "walletAddress": "0x...",
    "privateKey": "0x..."
  },
  "binance": {
    "apiKey": "...",
    "secret": "..."
  }
}

---

Example .env file

# Chain
CHAIN_ID=8453

# Wallet (use one or the other, not both)
PRIVATE_KEY=0xabc123...
# MNEMONIC=word1 word2 word3 ... word12

# Custom RPC (optional — uses public RPC if not set)
# RPC_URL=https://mainnet.base.org

# Write safety
CONFIRM_WRITES=true

# Policy engine (optional)
# POLICY_ENABLED=true
# POLICY_MAX_SINGLE_TX_USD=500
# POLICY_MAX_DAILY_USD=2000

# API keys
ETHERSCAN_API_KEY=your-etherscan-key
LIFI_API_KEY=your-lifi-key

# Optional plugins
# ZEROX_API_KEY=your-0x-key
# COINGECKO_API_KEY=your-coingecko-key

# Exchange access (optional)
# CCXT_CONFIG_PATH=./ccxt-config.json

---

Chain selection

Default chain

Set CHAIN_ID to change the default chain for all tool calls:

CHAIN_ID=1      # Ethereum mainnet
CHAIN_ID=8453   # Base (default)
CHAIN_ID=42161  # Arbitrum
CHAIN_ID=137    # Polygon

Per-call override

Every tool that operates on a specific chain accepts an optional chainId parameter. This overrides the default for that call only.

# Resolve USDC on Arbitrum, even if CHAIN_ID=8453
npx web3agent tool call resolve_token \
  --input '{"symbol":"USDC","chainId":42161}' \
  --json

In SDK code:

import { resolveToken } from "web3agent";

// Uses CHAIN_ID from env (8453)
const usdcOnBase = await resolveToken({ symbol: "USDC" });

// Overrides to Arbitrum for this call
const usdcOnArbitrum = await resolveToken({ symbol: "USDC", chainId: 42161 });

---

Passing config to MCP hosts

Most AI hosts support an env field in the MCP server config. This is the cleanest way to pass environment variables without a .env file:

{
  "mcpServers": {
    "web3agent": {
      "command": "npx",
      "args": ["web3agent"],
      "env": {
        "CHAIN_ID": "8453",
        "PRIVATE_KEY": "0xabc123...",
        "CONFIRM_WRITES": "true",
        "LIFI_API_KEY": "your-lifi-key"
      }
    }
  }
}

MCP config files are often stored in your home directory and may be readable by other processes. For production use, prefer loading secrets from a secrets manager or from environment variables set in your shell profile rather than hardcoding them in the config file.

---

Programmatic configuration

When using the SDK directly, pass config to setConfig() or to createRuntime():

import { setConfig, parseEnv } from "web3agent";

// Load from environment variables (reads process.env)
setConfig(parseEnv());

// Or set specific values
setConfig({
  chainId: 8453,
  privateKey: process.env.PRIVATE_KEY,
  confirmWrites: false,
  policyEnabled: true,
  policyMaxSingleTxUsd: 500,
  policyMaxDailyUsd: 2000,
});

For per-agent isolation with different wallets or limits:

import { createRuntime } from "web3agent/runtime";

const agentRuntime = await createRuntime({
  env: {
    CHAIN_ID: "8453",
    PRIVATE_KEY: agentPrivateKey,
    CONFIRM_WRITES: "false",
    POLICY_ENABLED: "true",
    POLICY_MAX_SINGLE_TX_USD: "100",
    POLICY_MAX_DAILY_USD: "500",
  }
});

Each runtime is fully isolated. Multiple runtimes can run in the same process with different wallets and policy limits.

---

Security checklist

• .env is in .gitignore
• PRIVATE_KEY or MNEMONIC is not hardcoded in source files
• POLICY_ENABLED=true for any autonomous agent with real funds
• POLICY_MAX_SINGLE_TX_USD and POLICY_MAX_DAILY_USD are set to reasonable limits
• CONFIRM_WRITES=true for any agent where human review is possible
• API keys are rotated if they appear in logs or error messages
• CCXT config file has restricted file permissions (chmod 600 ccxt-config.json)