Skip to main content

Why web3agent?

Building AI agents that interact with blockchains is harder than it should be. This page explains the specific problems web3agent was built to solve and the architectural choices that address them.

The problem with blockchain tooling for AI agents

Fragmented integrations

Before web3agent, wiring an AI agent to blockchain capabilities meant integrating each service separately:

  • Orbs Protocol SDK for swaps and orders
  • LI.FI SDK for bridges
  • viem for on-chain reads and writes
  • Blockscout or Etherscan clients for indexed data
  • CoinGecko or DexScreener for market data
  • Custom wallet management code
  • Custom confirmation and safety logic

Each integration has its own authentication, its own error format, its own type system. A project that needs swaps, bridges, and market data ends up with three separate SDKs, three sets of environment variables, and three different ways things can fail.

No standard protocol for AI-blockchain interaction

AI coding agents (Claude Code, Cursor, Windsurf) communicate with tools via the Model Context Protocol (MCP). Before web3agent, there was no MCP server that exposed blockchain capabilities. Developers had to either write custom MCP servers for each integration or skip MCP entirely and hardcode tool logic into their agents.

Wallet management is risky by default

Giving an AI agent a private key with no guardrails is a real risk. Without a confirmation layer, a single misunderstood instruction could trigger an unintended transaction. Without a policy engine, there's no way to cap how much an autonomous agent can spend in a day.

Write operations need human oversight

Even well-designed agents make mistakes. A swap for the wrong token, a bridge to the wrong chain, a contract call with the wrong parameters. These aren't hypothetical. Any system that lets an AI agent sign transactions needs a mechanism for humans to review and approve writes before they execute.

How web3agent addresses these problems

One install aggregates everything

npx web3agent init

That single command configures your AI host to use web3agent as its MCP server. From that point, your agent has access to 100+ tools spanning swaps, bridges, on-chain data, market research, wallet management, and the agentic economy. No separate SDK installs. No per-integration configuration.

MCP as the standard interface

web3agent implements the MCP protocol over stdio transport. Every AI host that supports MCP (Claude Code, Cursor, Windsurf, OpenCode, Codex) discovers web3agent's tools automatically. The agent sees a flat list of named tools with typed inputs and outputs. It doesn't need to know which underlying service handles each tool.

This also means the same tool definitions work across all hosts. A tool that works in Claude Code works identically in Cursor.

Confirmation queue for write safety

By default, CONFIRM_WRITES=true. Any tool that modifies on-chain state (swaps, transfers, contract writes) gets queued for confirmation before executing. The agent prepares the operation and returns a confirmation ID. A human (or a separate approval step) calls transaction_confirm with that ID to release it.

Agent calls orbs_swap
  → Operation queued, confirmation ID returned
  → Human reviews: amount, tokens, chain, estimated output
  → Human calls transaction_confirm with ID
  → Swap executes

For autonomous agents where human-in-the-loop isn't practical, set CONFIRM_WRITES=false to skip the queue.

Policy engine for spend limits

The policy engine adds a second layer of protection for autonomous agents. Enable it with POLICY_ENABLED=true and set limits:

POLICY_ENABLED=true
POLICY_MAX_SINGLE_TX_USD=500    # no single transaction over $500
POLICY_MAX_DAILY_USD=2000       # no more than $2000 per day

The engine evaluates the USD value of every write operation before it executes. If a transaction would exceed either limit, it's rejected before hitting the chain. Spend is tracked across the day and resets at midnight UTC.

The two-layer architecture

web3agent is designed to serve two different audiences with the same underlying capabilities.

Layer 1: MCP tool layer

AI agents discover and call tools via the MCP protocol. Tools are registered in src/tools/ and exposed through the stdio server. Each tool has a name, a JSON schema for its inputs, and a handler function.

AI Agent (Claude Code / Cursor / Windsurf)
  → MCP Client (stdio)
  → Tool handler
    ├─ Validate input (Zod schema)
    ├─ Resolve chain context
    ├─ Check policy (if write + policy enabled)
    ├─ Execute operation
    └─ Queue for confirmation (if confirmWrites=true)
  → Result

Layer 2: Programmatic SDK layer

TypeScript projects import SDK functions directly. The SDK functions call the same underlying tool handlers, so behavior is identical whether you're going through MCP or calling the SDK directly.

import { getSwapQuote, prepareSwapIntent } from "web3agent";

// Same logic as the orbs_get_quote MCP tool, just called directly
const quote = await getSwapQuote({ fromToken, toToken, fromAmount, chainId });

This matters for projects like trading bots or DeFi apps that need blockchain capabilities but aren't running inside an AI coding host. They get the same battle-tested integrations without needing an MCP server.

Before and after

Before web3agent

// Swap: install @orbs-network/liquidity-hub-sdk, configure, call
// Bridge: install @lifi/sdk, configure, call
// On-chain data: install viem, set up provider, call
// Market data: install coingecko-api, configure, call
// Wallet: write custom key management, confirmation logic, audit logging
// Policy: write custom spend tracking and limit enforcement
// MCP: write a custom MCP server wrapping all of the above

Each integration has its own setup, its own error handling, its own type definitions. A full-featured agent needs weeks of integration work before it can do anything useful on-chain.

After web3agent

npx web3agent init   # configure your AI host
npx web3agent        # start the server

Your agent has swaps, bridges, on-chain reads and writes, market data, wallet management, and safety guardrails. The integrations are maintained, tested (580+ tests), and updated as upstream APIs change.

Design principles

stdout is reserved for MCP. All logging goes to stderr with a [module-name] prefix. This is non-negotiable because MCP uses stdout for protocol messages. Any logging to stdout would corrupt the protocol stream.

Zod as the single source of truth. Every tool's input and output shape is defined as a Zod schema. The same schema validates MCP tool inputs, generates JSON Schema for tool discovery, and types SDK function parameters. No duplication, no drift.

ESM only. All imports use .js extensions. No CommonJS compatibility shims. This keeps the build clean and avoids the dual-module hazard.

Consistent naming. Token parameters are always fromToken/toToken/fromAmount. Never srcToken/dstToken/inputAmount. Consistency across 100+ tools means agents don't have to remember per-tool naming conventions.

Catch unknown errors. Every catch block uses catch (e: unknown). No bare catches, no @ts-ignore. Type safety extends to error handling.