Environment Variables¶

Complete reference for all environment variables used by the Agent Registry. All variables are configured in the .env file in the project root.

Never commit .env files

The .env file contains private keys and secrets. It is listed in .gitignore by default. Never commit it to version control, share it in chat, or include it in Docker images. If you accidentally expose a private key, rotate it immediately.

Variable Reference¶

Deployment¶

These variables are used during contract deployment and verification. You only need them once.

Variable	Required	Default	Description
`DEPLOYER_KEY`	Yes (for deploy)	--	Private key for contract deployment. This wallet becomes the contract owner. Must be funded with ETH for gas.
`BASESCAN_KEY`	No	--	Basescan API key for contract source code verification on Base networks. Get one at basescan.org.
`ARBISCAN_KEY`	No	--	Arbiscan API key for contract verification on Arbitrum networks. Get one at arbiscan.io.

Deployed Contracts¶

Set automatically by npm run setup:deploy, or manually if connecting to an existing deployment.

Variable	Required	Default	Description
`REGISTRY_ADDRESS`	Yes	--	Deployed Agent Registry contract address. Set automatically after deployment.
`FORWARDER_ADDRESS`	Yes	--	Deployed MinimalForwarder contract address. Set automatically after deployment.
`RPC_URL`	No	`https://sepolia.base.org`	Blockchain JSON-RPC endpoint. Change this to target a different network.

Relayer Service¶

Configuration for the gasless relayer that pays gas on behalf of agents.

Variable	Required	Default	Description
`RELAYER_KEY`	Yes (for relayer)	--	Private key for the relayer wallet. This wallet pays gas fees for all gasless transactions. Must be funded with ETH.
`RELAYER_PORT`	No	`3001`	Port the relayer HTTP service listens on.
`DAILY_GAS_BUDGET`	No	`0.05`	Maximum ETH the relayer will spend per day. When exceeded, the relayer rejects new requests until the next day.

API Server¶

Configuration for the public REST API service.

Variable	Required	Default	Description
`PORT`	No	`3000`	Port the REST API HTTP service listens on.

Python SDK¶

Configuration for agents using the Python SDK.

Variable	Required	Default	Description
`REGISTRY_CHAIN`	No	--	Chain identifier for the Python SDK (e.g., `base_sepolia`, `base`, `hardhat`).
`AGENT_PRIVATE_KEY`	Yes (for SDK)	--	The agent's own private key. Used for signing registration and attestation messages.
`RELAYER_URL`	No	--	URL of the relayer service for gasless mode (e.g., `https://relay.theagentregistry.org`). If not set, the SDK will attempt to send transactions directly (requires the agent wallet to hold ETH).

Coinbase CDP Faucet¶

Credentials for automated testnet ETH claiming via the Coinbase Developer Platform.

Variable	Required	Default	Description
`CDP_API_KEY_ID`	No	--	Coinbase CDP API key ID. Get one at portal.cdp.coinbase.com.
`CDP_API_KEY_SECRET`	No	--	Coinbase CDP API key secret.
`CDP_WALLET_SECRET`	No	--	Coinbase CDP wallet secret for faucet claims.

Note

The CDP faucet credentials are only needed for automated testnet ETH claiming (npm run claim). You can fund wallets manually through web faucets instead.

Complete `.env.example`¶

Copy this file to .env and fill in the values:

.env.example

# ==================================================
#  DEPLOYMENT (one-time)
# ==================================================
DEPLOYER_KEY=0x_your_deployer_private_key
BASESCAN_KEY=your_basescan_api_key
ARBISCAN_KEY=your_arbiscan_api_key

# ==================================================
#  DEPLOYED CONTRACTS (filled after deployment)
# ==================================================
REGISTRY_ADDRESS=0x_deployed_registry_address
FORWARDER_ADDRESS=0x_deployed_forwarder_address
RPC_URL=https://sepolia.base.org

# ==================================================
#  RELAYER (pays gas so agents don't have to)
# ==================================================
RELAYER_KEY=0x_relayer_wallet_private_key
RELAYER_PORT=3001
DAILY_GAS_BUDGET=0.05

# ==================================================
#  API SERVER (public query layer)
# ==================================================
PORT=3000

# ==================================================
#  PYTHON SDK (for agents)
# ==================================================
REGISTRY_CHAIN=base_sepolia
AGENT_PRIVATE_KEY=0x_agent_private_key
RELAYER_URL=https://relay.theagentregistry.org
# ^ Set this for gasless mode. Remove/comment to pay gas directly.

# ==================================================
#  COINBASE CDP FAUCET (optional, for testnet ETH)
# ==================================================
# CDP_API_KEY_ID=your-key-id
# CDP_API_KEY_SECRET=your-key-secret
# CDP_WALLET_SECRET=your-wallet-secret

Connecting to Existing Deployments¶

To connect to the live COAI Research deployment on Base Sepolia without deploying your own contracts, use these values:

REGISTRY_ADDRESS=0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23
FORWARDER_ADDRESS=0x70c2fdD0CDada6b43195981928D76f5D32AE29e5
RPC_URL=https://sepolia.base.org

Info

When connecting to an existing deployment, you still need RELAYER_KEY (funded with ETH) to run your own relayer, or RELAYER_URL pointing to a running relayer instance for gasless SDK usage.

Network-Specific RPC URLs¶

Network	`RPC_URL` Value
Local Hardhat	`http://localhost:8545`
Base Sepolia (testnet)	`https://sepolia.base.org`
Base (mainnet)	`https://mainnet.base.org`
Arbitrum Sepolia (testnet)	`https://sepolia-rollup.arbitrum.io/rpc`
Arbitrum One (mainnet)	`https://arb1.arbitrum.io/rpc`

Key Generation¶

If you do not have wallet keys yet, generate them with:

npm run setup:keys

This creates a DEPLOYER_KEY and RELAYER_KEY in .env automatically. To view the corresponding public addresses:

npm run addresses

Security Best Practices¶

Use separate keys for each role. The deployer key (contract owner) should not be the same as the relayer key.
Minimize deployer key exposure. After deployment, the deployer key is only needed for owner-level operations (adding regulators, changing parameters). Store it securely.
Monitor relayer balance. The relayer key holds ETH and spends it on gas. Use DAILY_GAS_BUDGET to cap spending. Monitor balance via GET /status on the relayer.
Rotate keys if compromised. If a relayer key is exposed, transfer remaining ETH to a new wallet and update .env. Agent keys cannot be rotated without re-registration.
Never share agent private keys. Each agent should have its own unique private key that it controls exclusively.