Web3agent

本番環境での動作を見る： The Arena — 11 の AI エージェントが Web3Agent を通じて実資金を取引しています。

web3agent

MCP パッケージ：web3agent | npm：https://www.npmjs.com/package/web3agent | GitHub：https://github.com/Apegurus/web3agent | お問い合わせ：[email protected]

リンク： ウェブサイト · GitHub · npm · Smithery · The Arena · X / @Web3AgentFi

AI エージェントに、EVM の実行機能と DeFi ツールを提供します。スワップ、ブリッジ、指値注文とトリガー注文、取引所での取引、市場データ、リサーチ、ウォレット管理に対応。MCP ツールは 190 種類以上。インストールは 1 回だけです。

Claude Code、Cursor、Windsurf、OpenCode、Codex ですぐに使えます。セルフカストディ型です。デフォルトでは書き込み操作は確認キューを経由するため、確認を明示的に無効にしない限り、承認なしで実行されることはありません。

EVM の実行はすでに解決済みの問題です。もう作り直す必要はありません。接続して、リリースしましょう。

---

できること

インストールすると、AI エージェントが平易な言葉で実際の DeFi 操作を実行できます。

• 「Baseで0.1 ETHをUSDCにスワップして」 — 価格を提示し、ルートを決定。確認後に実行します
• 「ArbitrumからOptimismに500 USDCをブリッジして」 — LI.FI を介したクロスチェーン操作に対応。20 以上のチェーンをサポート
• 「ETHを2,800ドルで買う指値注文またはトリガー注文を設定して」 — Orbs を介した分散型スポット注文
• 「Binanceの未決済注文をキャンセルして」 — メソッドごとのリスク分類に対応した CCXT 取引所アクセス
• 「BaseでのUSDC残高はいくら？」 — 読み取り専用の EVM および ERC-20 残高確認
• 「APYが5%を超える利回り機会を見せて」 — リサーチツール、プロトコル分析、デューデリジェンス

一般的なフローでは ABI の処理やトランザクションの構築は不要です。ABI を指定または登録する場合、あるいはエクスプローラーで ABI を検索できる場合は、汎用のコントラクト読み取り・書き込みを利用できます。エージェントがルーティング、トランザクションの準備、確認キューへの登録を処理します。承認すれば、実行されます。

---

エージェントのパワーユーザー向けクイックスタート

npx web3agent init

Claude Code、Cursor、Windsurf、OpenCode、Codex を検出し、MCP サーバーを自動的に設定します。ホストを再起動して、次のように尋ねてください。

What Web3 tools do you have available, and what chain are you configured for?

その他の MCP 対応ホストでは、次のコマンドを実行する stdio サーバーを設定してください。

npx web3agent

一般的な MCP 設定の形式は次のとおりです。

{
  "web3agent": {
    "type": "stdio",
    "command": "npx",
    "args": ["web3agent"]
  }
}

書き込み操作はデフォルトで確認が必要です。また、明示的に有効にしない限り、ウォレットの秘密情報が MCP を通じて公開されることはありません。

人間とエージェントの両方のセットアップを扱う手順ガイドについては、docs/guides/universal-access.md をご覧ください。

Smithery のローカルバンドル

Smithery で URL を公開するには、ホストされた Streamable HTTP MCP エンドポイントが必要です。Web3Agent はローカルの stdio/npm サーバーとして配布されるため、Smithery での配布には代わりに MCPB バンドルを使用します。

pnpm run mcpb:check
smithery mcp publish dist/web3agent.mcpb -n Apegurus/web3agent

生成される MCPB は、公開済みの npm パッケージを npm exec --package [email protected] で起動する、薄いローカルバンドルです。

Web3Agent を選ぶ理由

• 1 行でインストールできます。 npx web3agent init を実行すると、Claude Code、Cursor、Windsurf、OpenCode、または Codex が自動的に設定されます。対応するホストでは、設定ファイルを手動で編集する必要はありません。
• 秘密鍵を自分で管理できます。 鍵はお使いの環境内に保持され、ウォレットの秘密情報はデフォルトでエージェントから参照可能な MCP フローから除外されます。また、意図的に無効化しない限り、書き込み操作はすべて確認キューを経由します。
• 実績のあるインフラです。 GOAT SDK、LI.FI、Orbs、Blockscout、Etherscan、DexScreener など、本番運用されている Web3 インフラを基盤としています。
• 本番環境で稼働中です。 Orbzy と The Arena を支えており、AI エージェントが Web3Agent を通じて実資本を取引しています。
• 単一の MCP インターフェースです。 スワップ、ブリッジ、注文、マーケットデータ、リサーチ、トークン解決、ウォレットのライフサイクル、エージェント決済プロトコルを、1 つのサーバーから利用できます。

対象ユーザー

• プロトコル連携を一から構築せずに、Web3 の実行機能を利用したい AI エージェントのビルダー
• 社内ツール、リサーチエージェント、または取引エージェントに MCP サポートを追加したい DeFi チーム
• ウォレット対応エージェント、スワップ、ブリッジ、マーケット関連ワークフローのプロトタイプを作成したい開発者
• 読み取り専用のチェーンデータに加えて、明示的な確認を伴う書き込みフローを利用したい MCP ホストユーザー

コピーして使えるプロンプト

インストール後、すぐに利用を始めるには、以下を使用してください。

List the supported chains and tell me which Web3 tools are safest to try first.

Resolve USDC, WETH, and DEGEN on Base. Show token addresses and decimals.

Quote swapping 0.01 ETH to USDC on Base, but do not execute anything.

Show yield opportunities above 5% APY and explain the main protocol risks.

Explain this wallet's recent activity on Base: 0x0000000000000000000000000000000000000000

---

対応ホスト

ホスト	設定場所
Claude Code	~/.claude/mcp.json
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
OpenCode	.opencode/config.json
Codex	.codex/config.toml
OpenClaw	正式ガイドに沿ったエージェント経由のセルフインストール

---

対応チェーン

基本的な EVM 操作では viem のチェーンレジストリを使用しており、RPC にアクセスできる場合は、viem がサポートする任意の EVM チェーンを対象にできます。

拡張スワップおよび注文連携は、現在 Ethereum、Base、Arbitrum、Optimism、Polygon、Linea、BSC、Avalanche、Sonic、Mode、Blast、Celo、Gnosis に対応しています。トークン解決、エクスプローラー、LI.FI、マーケット／リサーチの各ツールの対応範囲はプロバイダーによって異なります。LI.FI のブリッジ見積もりと実行は、LI.FI 独自のチェーンリストを通じて 20 以上のチェーンをサポートしています。

デフォルト： Base（8453）。CHAIN_ID 環境変数で上書きするか、呼び出しごとに chainId を渡してください。

---

含まれる機能

機能	プロバイダー	備考
オンチェーン状態	ネイティブ EVM ツール	残高、コントラクトの読み取り／書き込み、ガス、ENS、マルチコール（27 個のツール）
スワップ	GOAT / Uniswap / Balancer	同一チェーン、ERC-20/721
集約スワップ	Orbs Liquidity Hub	ソルバーネットワーク経由の最適な価格
クロスチェーンブリッジ	LI.FI	20 以上のチェーン
レンディング	GOAT SDK / プロトコル連携	対応している Aave、Morpho、および主要なマネーマーケット機能
高度な注文	Orbs	スポット市場、指値、TWAP、ストップロス、テイクプロフィット、遅延注文
取引所での取引	CCXT	100 以上の取引所へのパブリック／プライベートアクセス（6 個のツール）
ブロックエクスプローラー	Blockscout + Etherscan	アドレス情報、トランザクション履歴、NFT、コントラクト ABI、ネットワーク統計（35 個のツール）
市場データ	DefiLlama / CoinGecko / Binance	TVL、価格、DEX 取引量、ステーブルコイン統計、センチメント（20 個のツール）
リサーチ	DefiLlama / オンチェーン	コントラクトのセキュリティ、利回り分析、クジラの追跡、ガバナンス（13 個のツール）
トークン解決	組み込みレジストリ + DexScreener	シンボルからアドレスへの解決、ロングテール資産
ウォレット管理	web3agent + Open Wallet Standard	CLI/MCP ライフサイクル、設定時の暗号化 OWS ボルト、レガシーフォールバック
確認キュー	組み込み	デフォルトでは、書き込み操作に明示的な承認が必要です
エージェントプロトコル	aGDP / ACP / ERC-8183 / x402 / ERC-8004	エージェントマーケットプレイス、協力、決済
価格データ	CoinGecko	COINGECKO_API_KEY が必要です
0x スワップ	0x	ZEROX_API_KEY が必要です

---

スターターテンプレート

npx web3agent create

同梱されている 3 つのテンプレートのいずれかを使って、すぐに実行できるプロジェクトのひな形を作成します。

• Vercel AI SDK — ツール呼び出しに対応したチャットエージェント
• Mastra — web3agent ツールを備えたエージェントフレームワーク
• MCP-host — 軽量 MCP クライアント

各スターターでは、MCP や CLI と同じ web3agent ライフサイクル機能を使用します。

---

使用例

ルートの使用例は npm パッケージに含まれています。

# Safe import-only previews
node examples/swap.mjs
node examples/bridge.mjs

# Read-only live quote examples
node examples/swap.mjs --quote
node examples/bridge.mjs --quote

# Prepared external-wallet flows
WEB3AGENT_EXAMPLE_ACCOUNT=0x... node examples/swap.mjs --prepare
WEB3AGENT_EXAMPLE_ACCOUNT=0x... node examples/bridge.mjs --prepare

使用例では、デフォルトで少額の USDC 建てフローを使用し、--prepare を渡した場合にのみウォレット操作を準備します。

クイックスタートの使用例

Base でスワップを準備するエージェント

import { prepareOperation, resolveCanonicalTokenSync } from "web3agent";

const chainId = 8453;
const usdc = resolveCanonicalTokenSync({ chainId, symbol: "USDC" });
const weth = resolveCanonicalTokenSync({ chainId, symbol: "WETH" });

if (!usdc || !weth) throw new Error("Missing canonical token");

const intent = await prepareOperation({
  integration: "orbs",
  kind: "swap",
  account: "0xYourWallet",
  chainId,
  fromToken: usdc.address,
  toToken: weth.address,
  fromAmount: "10000000",
  slippagePct: 0.5,
});

console.log(intent.nextActions);

Ethereum から Arbitrum へのブリッジを準備するエージェント

import { prepareOperation, resolveCanonicalTokenSync } from "web3agent";

const fromChainId = 1;
const toChainId = 42161;
const from = resolveCanonicalTokenSync({ chainId: fromChainId, symbol: "USDC" });
const to = resolveCanonicalTokenSync({ chainId: toChainId, symbol: "USDC" });

if (!from || !to) throw new Error("Missing canonical token");

const bridge = await prepareOperation({
  integration: "lifi",
  kind: "bridge",
  account: "0xYourWallet",
  fromChainId,
  toChainId,
  fromToken: from.address,
  toToken: to.address,
  fromAmount: "1000000",
});

console.log(bridge.nextActions);

ウォレットを監視するエージェント

import { getAddressInfo, getTransactionHistory, listSupportedChains } from "web3agent";

const address = "0x0000000000000000000000000000000000000000";
const chainId = 8453;

const [chains, info, history] = await Promise.all([
  listSupportedChains(),
  getAddressInfo({ address, chainId }),
  getTransactionHistory({ address, chainId, pageSize: 5 }),
]);

console.log({
  supportedChains: chains.chains.length,
  wallet: info,
  recentTransactions: history.transactions,
});

---

暗号資産チーム向け

すべてのチームがウォレット、チェーン、トークン、見積もり、エクスプローラー、確認処理を個別に再構築することなく、AI エージェントにプロトコルを発見または操作させたい場合は、web3agent をご利用ください。

統合方法：

• MCP ツール：Claude Code、Cursor、Windsurf、OpenCode、Codex、その他の MCP ホスト向け
• プログラム用 SDK：web3agent を使用し、アプリが所有するエージェントやブラウザーウォレットのフローを構築
• 準備済み操作：ユーザーやアプリによる外部署名が必要なプロトコル向け
• 確認を必須とする書き込み：デフォルトでは、明示的な承認フローを経ずに実行されることはありません

最初の統合に適した対象：

• トークン、市場、ポジションの読み取り
• 見積もりおよびシミュレーションツール
• ブラウザー／アプリでの署名用に準備されたウォレット操作
• プロトコル固有の調査またはリスク関連ツール

プロトコルのサポートや統合に関する質問は、https://github.com/Apegurus/web3agent/issues で Issue を作成するか、[email protected] までお問い合わせください。

---

使用方法

# Initialize for your host (run once)
npx web3agent init

# Start the MCP server
npx web3agent

# CLI fallback (for non-MCP hosts or scripting)
npx web3agent tools list --json
npx web3agent tools call resolve_token --input '{"symbol":"USDC","chainId":8453}' --json
npx web3agent doctor --json

# Local-only wallet secret flows (requires OWS_PASSPHRASE >= 12 chars and an interactive TTY)
OWS_PASSPHRASE='...' npx web3agent wallet generate
OWS_PASSPHRASE='...' npx web3agent wallet generate --mnemonic
OWS_PASSPHRASE='...' npx web3agent wallet activate --from-file ./secret.txt --type private-key

# Options
npx web3agent --help
npx web3agent --version

ウォレットのシークレットを扱う MCP ツールはデフォルトで無効になっているため、秘密鍵やニーモニックが AI エージェントの推論コンテキストに入ることはありません。安全に生成またはインポートするには、上記のローカル web3agent wallet ... コマンドを使用してください。エージェントからシークレットを見られるリスクを明示的に受け入れる場合は、WEB3AGENT_ALLOW_AGENT_VISIBLE_SECRETS=1 を設定すると、従来の MCP の動作を再び有効にできます。

wallet_deactivate は現在のランタイムセッションのみを無効化し、読み取り専用の一時モードに戻します。保存済みのウォレット情報を完全に削除する場合は、確認を必須とする wallet_delete を使用してください。

ウォレットのセキュリティに関するデフォルト設定

デフォルトでは、web3agent はウォレットのシークレットを MCP ツールの応答や、エージェントから見える入力に含めません。秘密鍵やニーモニックの生成またはインポートには、ローカルの web3agent wallet ... コマンドを使用することを推奨します。このコマンドは対話型 TTY を必要とし、シークレットを JSON 形式で出力しません。秘密鍵やニーモニックが MCP ホスト経由で送信され、エージェントや推論プロバイダーから見える可能性を明示的に受け入れる場合に限り、WEB3AGENT_ALLOW_AGENT_VISIBLE_SECRETS=1 を設定してください。

サーバー側でウォレットを永続化する場合、OWS_PASSPHRASE の設定は必須ではありませんが、強く推奨されます。macOS／Linux で OWS が利用可能な状態でこの変数を設定すると、web3agent は従来のファイルシステム保護によるウォレットストアの代わりに、Open Wallet Standard の暗号化された保管庫を使用します。OWS 仕様で定められた最小文字数は 12 文字です。web3agent は実行時のパスフレーズが弱い場合に警告し、ローカルでのウォレット生成／インポートでは短すぎる値を拒否します。本番環境では、16 文字以上の複雑なパスフレーズを使用してください。MCP サーバーとしての npx web3agent でも、createRuntime({ env: { OWS_PASSPHRASE: "..." } }) を使用するアプリ／サービスでも、web3agent を実行するプロセスに設定してください。

OWS_PASSPHRASE が設定されていない、空である、OWS が利用できない、プラットフォームが Windows である、または OWS_FORCE_LEGACY=1 が設定されている場合、web3agent はファイル権限のみで保護される従来のウォレットストレージにフォールバックします。従来の wallet.json を移行すると、プレーンテキストのロールバック用バックアップ wallet.json.migrated が残ります。OWS でアクセスできることを確認したら、これを削除してください。エージェントを複数使用するサービスでは、ランタイムごとのウォレット分離がサポートされるまでは、ウォレットを使用するランタイムを別々のプロセスで実行してください。

---

プログラムからの使用方法

ルート API

別のアプリやエージェント層から安定した型付きの EVM 機能を使用するには、パッケージのルートを使用してください。

import {
  getChain,
  listChainTokens,
  resolveCanonicalTokenSync,
  resolveToken,
} from "web3agent";

const chain = getChain(8453);
const usdc = resolveCanonicalTokenSync({ symbol: "USDC", chainId: 8453 });
const tokens = listChainTokens({ chainId: 8453 });
const discovered = await resolveToken({ symbol: "DEGEN", chainId: 8453 });

console.log(
  chain?.name,
  usdc?.address,
  discovered.address,
  tokens.tokens.length,
);

よく知られたレジストリトークンやネイティブトークンのエイリアスには resolveCanonicalToken() を使用してください。ロングテール資産の DexScreener 検索フォールバックも利用する場合は、resolveToken() を使用してください。

ブラウザーウォレットのフロー

アプリが署名者を管理する場合（wagmi や AppKit を介したブラウザーウォレットなど）は、ルート API を使用してください。

import {
  prepareOperation,
  resumeOperation,
  simulateTransaction,
} from "web3agent";

1. prepareOperation(...) は、次のウォレット操作と resumeState を返します
2. アプリでブラウザーウォレットを使ってそれらの操作を実行します
3. resumeOperation(...) を呼び出して、操作が完了するまで続行します

トランザクション操作は、確認済みの結果を返した場合にのみ完了と見なされます。

{ type: "transaction", txHash: "0x...", status: "confirmed" }

resumeOperation() は、次の段階へ進む前にレシートを独立して検証します。

アーキテクチャに関する注意事項：docs/architecture/browser-wallet-operations.md

ランタイム API

ツールの検出、汎用的な呼び出し、または上流へのパススルーツールが必要な場合は、web3agent/runtime を使用してください。

import { createRuntime } from "web3agent/runtime";

const runtime = await createRuntime();

try {
  console.log(runtime.getHealth());
  console.log(
    runtime
      .listTools()
      .slice(0, 5)
      .map((tool) => tool.name),
  );
  const result = await runtime.invokeTool("list_supported_chains");
  console.log(result.structuredContent);
} finally {
  await runtime.shutdown();
}

---

環境変数

環境変数の一覧は、WEB3_CONTEXT.md を参照してください。

CCXT ツールを介して認証済みの取引所にアクセスするには、名前付きアカウントと取引所の認証情報を含む JSON ファイルを CCXT_CONFIG_PATH に設定してください。

---

既知の制限事項

• Blockscout エクスプローラーツールが対応するのは、8 つのチェーンのみです（Ethereum、Polygon、Arbitrum、Optimism、Base、Gnosis、Scroll、zkSync Era）
• イールド関連ツールは読み取り専用の調査用です。ファーストクラスのツール以外でプロトコル固有の操作を行うには、ABI に基づく EVM 呼び出しを使用します
• 0x と CoinGecko のプラグインには、それぞれの API キーが必要です
• MCP ホストからブラウザーウォレットのプロンプトを直接開くことはできません。MCP では署名済みペイロードの準備、シミュレーション、送信を行えますが、署名にはアプリ側でウォレットとのやり取りを処理する必要があります

---

要件

• Node.js 22 以降
• pnpm（開発用）

---

ライセンス

MIT