🤖 Web3 Agent Kit

Build autonomous AI agents that interact with blockchains — in minutes, not months.

Feature readiness is tracked in the capability matrix.

⚡ Quick Install

pip install web3-agent-kit

Verify installation:

wak info        # Show version, modules, chains
wak doctor      # Check dependencies
wak examples    # List 21 example scripts

Check your first read-only balance:

from web3_agent_kit import Agent, Wallet, Chain

wallet = Wallet.from_key("0x...")
agent = Agent(wallet=wallet, chains=[Chain.BASE])
result = agent.run("check my balances")
print(result)

🤔 Why Web3 Agent Kit?

Building AI agents that interact with blockchains is hard. You need to juggle RPC providers, wallet management, transaction signing, gas estimation, DeFi protocol ABIs, LLM integration, and safety rails — all before writing a single line of business logic.

Web3 Agent Kit handles all of that for you.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        User / Application                          │
│              "Swap 0.1 ETH to USDC on Base"  /  `wak agent "..."`  │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          Agent Framework                            │
│  ┌───────────┐  ┌──────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │ Goal      │→ │ LLM Planner  │→ │ Tool        │→ │ Transaction│ │
│  │ Parser    │  │ (6 providers)│  │ Router      │  │ Executor   │ │
│  └───────────┘  └──────────────┘  └─────────────┘  └─────┬──────┘ │
└───────────────────────────────────────────────────────────┼────────┘
                                                            │
                               ┌────────────────────────────┼────────┐
                               │         Safety Layer       │        │
                               │  ┌─────────────────────────┼──────┐ │
                               │  │ Spend Governor          │      │ │
                               │  │ • Per-tx limits         │      │ │
                               │  │ • Daily caps            │      │ │
                               │  │ • Kill switch           │      │ │
                               │  │ • Operator confirmation │      │ │
                               │  └─────────────────────────┘      │ │
                               └────────────────────────────────────┘
                                                            │
       ┌────────────────────────────────────────────────────┼────────┐
       │                    Tool Ecosystem                    │        │
       │                                                     │        │
       │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐│        │
       │  │ DeFi     │ │ Airdrop  │ │ Security │ │ MEV    ││        │
       │  │ •Uniswap │ │ •Galxe   │ │ •Honeypot│ │ •Arb   ││        │
       │  │ •Aerodrome│ │ •Zealy   │ │ •Tax     │ │ •Liq   ││        │
       │  │ •Aave    │ │ •Layer3  │ │ •Liquidity│ │ •Flash ││        │
       │  │ •Curve   │ │ •Gleam   │ │ •Holders │ │  bots  ││        │
       │  ├──────────┤ ├──────────┤ ├──────────┤ ├────────┤│        │
       │  │ Trading  │ │ NFT      │ │ Portfolio│ │ Bridge ││        │
       │  │ •DCA Bot │ │ •Deploy  │ │ •Tracker │ │ •Li.Fi ││        │
       │  │ •Sniper  │ │ •Mint    │ │ •P&L     │ │ •Socket││        │
       │  │ •Yield   │ │ •Market  │ │ •Alerts  │ │        ││        │
       │  └──────────┘ └──────────┘ └──────────┘ └────────┘│        │
       │                                                     │        │
       │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐│        │
       │  │ Gas      │ │ Wallet   │ │ Plugins  │ │Restake ││        │
       │  │ Optimizer│ │ •Multi   │ │ •Custom  │ │•Eigen  ││        │
       │  │          │ │ •Watcher │ │ •Community│ │•Babylon││        │
       │  │          │ │ •Approval│ │          │ │•Solana ││        │
       │  └──────────┘ └──────────┘ └──────────┘ └────────┘│        │
       │                                                     │        │
       │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐│        │
       │  │ Oracle   │ │ Events   │ │Simulator │ │Acct    ││        │
       │  │•Chainlink│ │•Listener │ │•Tenderly │ │Abstract││        │
       │  │•DexScrnr │ │•Webhooks │ │•eth_call │ │•ERC4337││        │
       │  │•CoinGecko│ │•Callbacks│ │•Anvil    │ │•Paymstr││        │
       │  ├──────────┤ ├──────────┤ ├──────────┤ ├────────┤│        │
       │  │Messaging │ │Governance│ │          │ │        ││        │
       │  │•LayerZero│ │•Snapshot │ │          │ │        ││        │
       │  │•Wormhole │ │•Tally    │ │          │ │        ││        │
       │  │•CCIP     │ │•On-chain │ │          │ │        ││        │
       │  └──────────┘ └──────────┘ └──────────┘ └────────┘│        │
       └────────────────────────────────────────────────────┼────────┘
                                                            │
                               ┌────────────────────────────┼────────┐
                               │    Chain Abstraction Layer  │        │
                               │  ┌──────┐ ┌──────┐ ┌────┐ │        │
                               │  │ ETH  │ │ BASE │ │ARB │ │        │
                               │  ├──────┤ ├──────┤ ├────┤ │        │
                               │  │ OP   │ │ MATIC│ │AVAX│ │        │
                               │  ├──────┤ ├──────┤ ├────┤ │        │
                               │  │ BSC  │ │ SOL  │ │ RH 4663 │ │    │ │        │
                               │  └──────┘ └──────┘ └────┘ │        │
                               └────────────────────────────────────┘

📊 Comparison vs Alternatives

🎯 Quick Start

A small, policy-controlled starting point.

pip install web3-agent-kit
export PRIVATE_KEY="0x..."
export ANTHROPIC_API_KEY="sk-ant-..."

from web3_agent_kit import Agent, Wallet, Chain, ChainManager
from web3_agent_kit.defi import Uniswap

chain = ChainManager(chains=[Chain.BASE])
wallet = Wallet.from_env("PRIVATE_KEY", chain_manager=chain)

agent = Agent(wallet=wallet, chains=[Chain.BASE], tools=[Uniswap(chain_manager=chain)])
result = agent.run("Check my balances on Base")

This quick start demonstrates a read-only agent flow. Before enabling a transaction, bind a PreSignInterceptor with an ExecutionPolicy and an application-specific AuthorizationProvider that verifies a real, fresh, single-use authorization. A SpendGovernor or human confirmation callback alone is not sufficient.

SpendGovernor is one layer: it applies configured spend caps to agent actions. It does not replace the wallet's pre-sign gate or an authorization provider. Configure all required layers before enabling writes:

from web3_agent_kit import AgentConfig
from web3_agent_kit.utils import SpendGovernor, SpendLimits

config = AgentConfig(
    wallet=wallet,
    chains=[Chain.BASE],
    tools=[Uniswap(chain_manager=chain)],
    governor=SpendGovernor(SpendLimits(max_per_tx=1.0, daily_limit=5.0, session_limit=10.0)),
)
agent = Agent(config=config)

This config only sets spend limits. A write still fails closed until you bind a pre-sign gate with an application-specific AuthorizationProvider. Do not remove spending caps as a workaround.

Enforced pre-sign authorization

SpendGovernor decides whether an agent is allowed to act. The pre-sign gate decides what exactly gets signed, and it is the only path to a signature.

This is a wiring template, not a drop-in signer: application_authorization_provider must implement AuthorizationProvider and independently verify the principal's exact-call approval. The kit does not ship a generic provider; a confirmation prompt by itself is not authorization.

from web3_agent_kit import Wallet, Chain, ChainManager
from web3_agent_kit.execution import (
    ActionType, ExecutionPolicy, PreSignInterceptor,
)

chain = ChainManager(chains=[Chain.BASE])
wallet = Wallet.from_env("PRIVATE_KEY", chain_manager=chain)

policy = ExecutionPolicy(
    allowed_chains=frozenset({Chain.BASE}),
    allowed_actions=frozenset({ActionType.SWAP}),
    allowed_contracts=frozenset({"0x94cc0aac535ccdb3c01d6787d6413c739ae12bc4"}),
    max_native_value_wei=10**18,
    require_confirmation=True,
)

wallet.bind_enforcement(
    PreSignInterceptor(
        policy=policy,
        signer=wallet._raw_signer,
        authorization_provider=application_authorization_provider,
        confirmation_fn=lambda request, decision: operator_approves(request),
    )
)

# Only works after the application provider has verified a fresh authorization.
uniswap.swap_with_wallet(wallet, "ETH", "USDC", 0.1)

What this guarantees:

• A transaction is signed only after policy evaluation returns allowed.
• A denial raises EnforcementDenied and produces no signature at all.
• A wallet with no bound gate refuses to sign write-capable calls.
• A policy that requires confirmation fails closed when no confirmation handler is configured — unattended execution cannot silently proceed.
• The authorization fingerprint binds chain, executor, nonce, target, calldata, and native value. It does not yet bind gas limit or fee fields; an authorized transaction is not currently a complete commitment to maximum execution cost.
• The pre-sign gate applies only where callers use Wallet.sign_transaction() with a bound gate. The full write surface is still being migrated; see docs/safety-and-transaction-pipeline.md.

tools/check_signing_surface.py detects signer call sites and keeps a baseline for existing calls. A passing baseline check does not mean every write path has been migrated.

CLI? wak agent --goal "Swap 0.1 ETH to USDC" --chain base

More examples: wak examples or browse examples/ — 21 scripts (DCA bot, sniper, airdrop farmer, multi-wallet, yield optimizer, bridge agent, portfolio tracker, and more). Write-capable examples need an application-configured gate and authorization provider.

💡 Tip: Start with dry_run=True on testnet to validate before going live.

✨ Features

🤖 Core

• 🔗 Multi-chain support — Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche, BSC, Robinhood Chain, Solana
• 🧠 LLM-powered reasoning — Multi-provider cascade (OpenAI, Anthropic, Groq, DeepSeek, OpenRouter, Kimi)
• 🎯 Natural language goals — Tell the agent what to do in plain English
• 🔐 Safety controls — Spend caps and fail-closed signing primitives; write-path coverage varies by module

💰 DeFi

• 💱 Uniswap V2 swaps — Actual token swaps with quotes, approvals, slippage protection
• 🌉 Cross-chain bridges — Li.Fi + Socket aggregators for best routes
• 📊 Portfolio tracking — Real-time balances, P&L across all chains

🔫 Sniper

• 🎯 Token sniper — Monitor new liquidity pools, auto-buy safe tokens
• 🛡️ Risk assessment — Honeypot detection, liquidity checks, contract analysis
• ⚡ Live monitoring — Background thread with callback alerts

📈 DCA Bot

• 🔄 Recurring buys — Dollar-cost average into any token automatically
• ⏰ Flexible intervals — Hourly, daily, weekly, biweekly, monthly
• 🛑 Spending limits — Max buys, max total spend, auto-stop
• 📊 Cost average analysis — Track avg price, min/max, P&L
• 💾 Persistent orders — Survives restarts, stored on disk
• 🔔 Callbacks — Hook into execution events for notifications

🔐 Token Security Module

• 🍯 Honeypot detection — Check if token can be sold before buying
• 🧶 Rug pull checker — Assess rug pull risk factors
• 📝 Contract-pattern analysis — Detect hidden mint, blacklist, pause, proxy patterns
• 💰 Tax checker — Buy/sell tax analysis
• 💧 Liquidity analysis — Locked %, lock duration
• 👥 Holder analysis — Concentration, whale detection
• 📊 Safety score — 0-100 score with risk levels
• 🌐 GoPlus API — Real-time token security data when configured
• 📈 DexScreener — Liquidity data integration

🪂 Airdrop Automation (Experimental)

• 🔍 Campaign Discovery — Auto-scan 8 platforms (Galxe, Zealy, Layer3, QuestN, TaskOn, Intract, Port3, Gleam)
• ⛓️ On-chain Farming — DeFi interactions for airdrops (Base, Ethereum, Arbitrum, Optimism, Scroll, Linea, zkSync)
• ⏰ Daily Scheduler — Automate recurring tasks with retry logic
• 📊 Points Dashboard — Track points across all platforms with history
• 🔗 Referral Manager — Generate, track, and optimize referral links
• 🚰 Faucet Claimer — Auto-claim testnet tokens from 12+ faucets
• 🤖 Multi-wallet — Explicit wallet rotation primitives; platform rules and eligibility remain your responsibility
• 🔌 Plugin System — Extend with custom platform executors

🌐 REST API

The API key authenticates requests but is not transaction authorization. The built-in swap/bridge execution routes currently fail closed at wallet signing because their wallets are unbound; treat those routes as unavailable for on-chain writes until route-level authorization is wired and tested.

• 📡 37+ endpoints — HTTP API for supported modules
• 🔑 API key auth — Secure access control
• 📖 Swagger UI — Interactive API documentation
• 🔄 Auto-fallback — Multi-provider LLM cascade

🔌 Plugin System

• 📦 Plugin registry — Discover and load plugins dynamically
• 🛠️ Custom plugins — Extend with your own tools
• 🔄 Hot reload — Add plugins without restarting

🔄 Restaking

• 🏦 EigenLayer integration — Restake LSTs, delegate to operators, track rewards
• ₿ Babylon BTC restaking — Bitcoin restaking via Babylon protocol
• ☀️ Solana restaking — Solayer, Jito, Marinade support
• 📊 Yield optimizer — Cross-protocol restaking yield optimization with risk-adjusted scoring
• 🔔 Slashing monitor — Position tracking, slashing risk alerts, portfolio snapshots

📡 Oracle Aggregator (NEW!)

• 🔗 Chainlink feeds — 12+ mainnet price feeds (ETH, BTC, SOL, UNI, AAVE, etc.)
• 📈 DexScreener — Real-time DEX price data with liquidity ranking
• 🪙 CoinGecko — Free API fallback for 20+ tokens
• ⚖️ Weighted median — Multi-source aggregation with deviation detection
• 💾 Smart cache — 30s TTL, batch queries, automatic stale detection

📡 Event Listener (NEW!)

• 🔔 On-chain events — Subscribe to any contract event (Transfer, Approval, custom)
• 🌐 Webhook support — HTTP POST to any URL on event trigger
• 🧵 Background polling — Multi-subscription threaded listener
• 📦 Pre-built ABIs — ERC-20 Transfer/Approval, ERC-721 Transfer
• 📊 Status tracking — Per-subscription event count, error rate, last block

🧪 Transaction Simulator (NEW!)

• 🔍 Pre-flight verification — Simulate before broadcasting to catch reverts
• 🌐 Tenderly integration — Full state diff, events, gas profiling
• 🍴 Local fork mode — Anvil/Hardhat impersonation testing
• ⚡ eth_call mode — Fast simulation with gas estimation + safety margin
• ⚠️ Smart warnings — Balance checks, approval analysis, MEV exposure

🏦 Account Abstraction (NEW!)

• 📦 ERC-4337 support — UserOperations, EntryPoint v0.6
• 🏭 Factory deployment — SimpleAccount, Safe v1.4.3, Kernel v3
• 💰 Paymaster integration — Pimlico gas sponsorship, token paymaster
• 🔗 Multi-chain — Ethereum, Base, Arbitrum, Optimism, Polygon
• 📊 Counterfactual addresses — Pre-compute before deployment

🌉 Cross-chain Messaging (NEW!)

• 📡 LayerZero — 7 chains, endpoint registry, fee estimation
• 🐛 Wormhole — Multi-chain message relay, delivery tracking
• ⛓️ Chainlink CCIP — Chain selector registry, message verification
• 📊 Status tracking — Real-time delivery status via protocol APIs
• 💰 Fee estimation — Per-chain cost breakdown

🏛️ Governance (NEW!)

• 📊 Snapshot integration — GraphQL API, active proposal tracking
• 📈 On-chain governor — OpenZeppelin Governor, proposal lifecycle
• 🗳️ Voting power — Token-weighted voting, delegation management
• 🔍 Tally API — Delegate discovery, voting history
• 🏷️ Known DAOs — Uniswap, Aave, Arbitrum, Optimism, ENS pre-configured

🌐 REST API

HTTP API for supported modules — use it from any language (JavaScript, curl, etc):

# WEB3_API_KEY is required — the server refuses to start without it
export WEB3_API_KEY=your-secret

# Start the API server (binds to 127.0.0.1 by default)
python -m web3_agent_kit.api

# Every request must include the key
curl -H "X-API-Key: ***" http://127.0.0.1:8000/wallet/info

⚠️ Breaking change (v1.14.0+): WEB3_API_KEY is now mandatory — the server raises an error at startup and refuses to run if it's unset. The default bind host also changed from 0.0.0.0 to 127.0.0.1. To expose the API on your network, set API_HOST=0.0.0.0 explicitly (a startup warning will remind you that this exposes wallet-signing endpoints). CORS origins must be set explicitly via CORS_ALLOWED_ORIGINS (comma-separated) — no origins are allowed by default.

Endpoints:

💡 Full list of endpoints available in Swagger UI when the server is running.

Example:

# Get gas estimate
curl http://localhost:8000/gas/estimate?chain=ethereum

# Get swap quote
curl "http://localhost:8000/swap/quote?token_in=ETH&token_out=USDC&amount_in=1.0"

# Scan approvals
curl http://localhost:8000/approval/scan?chain=ethereum

🎯 Showcase

Telegram Bot

A full-featured Telegram bot built with web3-agent-kit:

cd showcase/telegram-bot
pip install -r requirements.txt
python bot.py

Features: balance check, token swap, portfolio tracking, token sniper, cross-chain bridge.

📦 Examples

🧠 LLM Integration

Multi-provider cascade with automatic fallback:

from web3_agent_kit.agent import LLM, LLMConfig

# Use any LLM provider with automatic fallback
llm = LLM(LLMConfig(
    providers=["anthropic", "openai", "groq", "deepseek"],
    model="claude-3-5-sonnet-20241022",
))

# Natural language → structured action
action = llm.parse("Swap 0.1 ETH to USDC on Base")
# → {"tool": "uniswap", "action": "swap", "params": {...}}

🔒 Security Module

Analyze tokens before interacting:

from web3_agent_kit.security import TokenAnalyzer, SecurityConfig

analyzer = TokenAnalyzer(SecurityConfig(chain="base"))

# Quick check
result = analyzer.quick_check("0x...")
print(f"Is Honeypot: {result['is_honeypot']}")

# Full analysis
report = analyzer.analyze_token("0x...")
print(f"Safety Score: {report.safety_score}/100")
print(f"Risk Level: {report.risk_level.value}")

if report.is_honeypot:
    print("🚨 HONEYPOT DETECTED!")
elif report.safety_score < 50:
    print("⚠️ HIGH RISK TOKEN")
else:
    print("✓ Safe to trade")

🪂 Airdrop Automation

Automate airdrop farming across multiple platforms:

from web3_agent_kit.airdrop import (
    CampaignDiscovery,
    OnChainAirdropFarmer,
    OnChainConfig,
    AirdropScheduler,
    PointsDashboard,
    ReferralManager,
    FaucetClaimer,
)

# Discover new campaigns
discovery = CampaignDiscovery()
campaigns = discovery.discover_all()

# On-chain farming (dry run)
farmer = OnChainAirdropFarmer(OnChainConfig(chain="base", dry_run=True))
farmer.farm_plan("base_activity")

# Schedule daily tasks
scheduler = AirdropScheduler()
scheduler.add_daily("galxe_checkin", "09:00", galxe_checkin_fn)

# Track points
dashboard = PointsDashboard(DashboardConfig(wallet="0x..."))
dashboard.sync_all()

# Generate referrals
manager = ReferralManager()
manager.generate_links(count=10)

# Claim testnet tokens
claimer = FaucetClaimer()
claimer.claim_all(wallet="0x...")

🔄 Restaking

Optimize yields across restaking protocols:

from web3_agent_kit.plugins.restaking import (
    EigenLayer,
    EigenLayerConfig,
    RestakingOptimizer,
    RestakingMonitor,
    BabylonBtcRestaking,
    SolanaRestaking,
)

# EigenLayer restaking
el = EigenLayer(EigenLayerConfig(chain="ethereum"))
result = el.restake("stETH", 10.0)
print(f"Restaked: {result.tx_hash}")

# Find best restaking yield
optimizer = RestakingOptimizer()
best = optimizer.find_best_opportunity(min_apy=3.0)
print(f"Best: {best.protocol} — {best.apy}% APY")

# Monitor positions
monitor = RestakingMonitor()
snapshot = monitor.get_portfolio_snapshot()
print(f"Total staked: ${snapshot.total_value_usd:,.2f}")
print(f"Slashing risk: {snapshot.total_risk_score}")

📊 Project Stats

• Version: 1.9.0
• Modules: 23
• Source Files: 115
• Lines of Code: 32,743
• Tests: 991
• Examples: 19
• Chains: 8
• License: MIT

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

• Uniswap — DEX protocol
• Li.Fi — Bridge aggregator
• Socket — Bridge aggregator
• GoPlus — Token security API
• DexScreener — DEX data

Made with ❤️ by @itseywacc