Skip to main content

Security

web3agent is designed to give AI agents blockchain capabilities without sacrificing safety. Several layers of protection are built in by default.

Keep PRIVATE_KEY and MNEMONIC out of version control. Add .env to .gitignore before adding any credentials. Anyone with your private key has full control of the associated wallet.

Confirmation Queue

The confirmation queue is the primary safety mechanism for write operations. It's enabled by default (CONFIRM_WRITES=true).

When an AI agent calls a write tool (swap, transfer, contract write), the operation is not executed immediately. Instead:

  1. The tool returns a confirmation ID and a summary of what will happen.
  2. The operation sits in a queue with a TTL (time-to-live).
  3. A human (or an automated system) calls transaction_confirm with the ID to approve.
  4. Only then does the transaction execute.

This gives you a chance to review what the AI is about to do before funds move.

# Disable for fully autonomous agents (use with policy limits)
CONFIRM_WRITES=false

If you disable the confirmation queue, enable the policy engine to maintain spend controls.

Policy Engine

The policy engine enforces USD spend limits on financial operations. It's disabled by default and must be explicitly enabled.

POLICY_ENABLED=true
POLICY_MAX_SINGLE_TX_USD=500    # max per transaction
POLICY_MAX_DAILY_USD=2000       # max per calendar day

When a transaction would exceed either limit, the tool returns a POLICY_REJECTED error and the operation does not proceed. The policy engine tracks cumulative spend across the day, so a series of smaller transactions can still hit the daily cap.

The policy_get tool returns the current configuration and today's spend totals, which is useful for monitoring autonomous agents.

Wallet Storage

When a wallet is generated or imported via the CLI or wallet tools, the key material is stored at:

~/.web3agent/wallet.json

This file is created with restrictive permissions (readable only by the current user). It is never transmitted over the network. The MCP server reads it at startup to restore the active wallet.

Treat this file like any other credential file. Back it up securely and don't store it in shared directories.

stdout Isolation

The MCP protocol communicates exclusively over stdout. All logging goes to stderr with a [module-name] prefix. This isolation means:

  • No log output can accidentally corrupt the MCP stream.
  • Sensitive values (like partial key material in debug logs) never appear in the MCP protocol output.
  • Log aggregation tools that capture stderr can be used safely without intercepting protocol traffic.

Audit Logging

All wallet operations (key generation, activation, deactivation, signing) are written to an audit log. The log records the operation type, timestamp, and the address involved, but never the key material itself.

The audit log is stored alongside the wallet file at ~/.web3agent/. Review it periodically if you're running an autonomous agent to verify the operations it's performing.

No Type Suppression

The codebase enforces a strict no-suppression policy:

  • No @ts-ignore
  • No @ts-expect-error
  • No as any

This means TypeScript's type system is fully active throughout the codebase. Type errors surface at build time rather than at runtime, reducing the chance of unexpected behavior from incorrect type assumptions.

Third-Party Integrations

web3agent integrates with several external services (Orbs, LI.FI, Blockscout, DeFiLlama, DexScreener, CoinGecko, 0x). A few things to know:

  • Read-only tools (market data, explorer queries) send your query parameters to these services. No wallet data is included.
  • Write tools (swaps, bridges) send transaction data to the relevant protocol's API. The private key never leaves your machine; only signed transactions or intent data are transmitted.
  • API keys for third-party services are stored in environment variables and never logged or transmitted beyond the intended service.

Responsible Disclosure

If you discover a security vulnerability in web3agent, please report it through GitHub Issues at github.com/Apegurus/web3agent/issues.

For sensitive disclosures that shouldn't be public immediately, use GitHub's private vulnerability reporting feature on the repository.

Please include:

  • A description of the vulnerability
  • Steps to reproduce
  • The potential impact
  • Any suggested mitigations

Maintainers aim to acknowledge reports within 48 hours and provide a fix timeline within 7 days for critical issues.