Environment Variables

web3agent reads configuration from environment variables at startup. None are strictly required to run the MCP server, but most real-world usage needs at least a wallet key and a chain ID.

Complete Reference

Variable	Default	Required	Description
`CHAIN_ID`	`8453`	No	Default chain for all tools. Accepts any supported chain ID.
`PRIVATE_KEY`	—	No	Hex-encoded EVM private key (`0x...`). Used for write operations.
`MNEMONIC`	—	No	BIP-39 mnemonic phrase. Alternative to `PRIVATE_KEY`.
`RPC_URL`	—	No	Custom RPC endpoint for the default chain. Overrides the built-in public RPC.
`CONFIRM_WRITES`	`true`	No	When `true`, write operations are queued and require explicit confirmation before executing. Set to `false` for autonomous agents.
`POLICY_ENABLED`	`false`	No	Enables the treasury policy engine. When active, all financial operations are checked against spend limits.
`POLICY_MAX_SINGLE_TX_USD`	—	No	Maximum USD value allowed per transaction. Requires `POLICY_ENABLED=true`.
`POLICY_MAX_DAILY_USD`	—	No	Maximum total USD value allowed per calendar day. Requires `POLICY_ENABLED=true`.
`ETHERSCAN_API_KEY`	—	No	Etherscan API key. Used for ABI fetching on chains where Blockscout is unavailable.
`LIFI_API_KEY`	—	No	LI.FI API key. Without it, bridge tools use the public rate-limited tier.
`ZEROX_API_KEY`	—	No	0x Protocol API key. Required to activate the 0x swap plugin.
`COINGECKO_API_KEY`	—	No	CoinGecko API key. Required to activate the CoinGecko price plugin.
`CCXT_CONFIG_PATH`	—	No	Path to a JSON file containing exchange credentials for CEX tools.

Example `.env` File

# Chain
CHAIN_ID=8453
RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY

# Wallet (choose one)
PRIVATE_KEY=0xabc123...
# MNEMONIC=word1 word2 word3 ... word12

# Write safety
CONFIRM_WRITES=true

# Policy (optional — for autonomous agents)
POLICY_ENABLED=true
POLICY_MAX_SINGLE_TX_USD=500
POLICY_MAX_DAILY_USD=2000

# API keys (optional — activates additional plugins)
ETHERSCAN_API_KEY=your_key_here
LIFI_API_KEY=your_key_here
ZEROX_API_KEY=your_key_here
COINGECKO_API_KEY=your_key_here

Variable Details

`CHAIN_ID`

Accepts any chain ID from the supported chains list. The default is Base (8453). Individual tool calls can override this with a chainId parameter.

`PRIVATE_KEY` and `MNEMONIC`

Only one is needed. If both are set, PRIVATE_KEY takes precedence. The key is used to sign transactions for write operations (swaps, transfers, contract writes).

Wallet state is persisted to ~/.web3agent/wallet.json. The file is created automatically on first use.

`CONFIRM_WRITES`

The confirmation queue is the primary safety mechanism for write operations. When enabled (the default), every write tool call is placed in a queue and returns a confirmation ID. The operation does not execute until transaction_confirm is called with that ID.

Set to false only for fully autonomous agents where human-in-the-loop confirmation is not possible or desired.

`POLICY_ENABLED`, `POLICY_MAX_SINGLE_TX_USD`, `POLICY_MAX_DAILY_USD`

The policy engine adds a second layer of protection on top of the confirmation queue. It tracks cumulative USD spend and rejects operations that would exceed the configured limits.

# Allow up to $100 per transaction, $500 per day
POLICY_ENABLED=true
POLICY_MAX_SINGLE_TX_USD=100
POLICY_MAX_DAILY_USD=500

Both limit variables are optional even when POLICY_ENABLED=true. Omitting one means that dimension is uncapped.

`RPC_URL`

Applies only to the chain set by CHAIN_ID. For all other chains, web3agent uses its built-in public RPC endpoints. To use a private RPC for a non-default chain, you'd need to set CHAIN_ID to that chain and provide RPC_URL.

`CCXT_CONFIG_PATH`

Points to a JSON file with exchange API credentials for CEX tools. The file format follows the CCXT configuration schema:

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

Security Notes

Keep .env files out of version control. Add .env to your .gitignore before adding any credentials.

PRIVATE_KEY and MNEMONIC grant full control over the associated wallet. Treat them like passwords.
The policy engine (POLICY_ENABLED) is strongly recommended for any agent that runs autonomously with real funds.
CONFIRM_WRITES=true (the default) is the safest setting for interactive use. Only disable it when you've verified the agent's behavior and have policy limits in place.
API keys for third-party services (Etherscan, LI.FI, 0x, CoinGecko) are optional. Without them, the corresponding tools either use public rate-limited tiers or are unavailable.

Complete Reference

Example .env File

Variable Details

CHAIN_ID

PRIVATE_KEY and MNEMONIC

CONFIRM_WRITES

POLICY_ENABLED, POLICY_MAX_SINGLE_TX_USD, POLICY_MAX_DAILY_USD

RPC_URL

CCXT_CONFIG_PATH