オンチェーンエージェントの構築方法:ウォレット、決済、リアルタイムデータ

最終更新日: 2026年5月27日3分で読めます

ウォレット、x402決済、リアルタイムデータを使ってonchainエージェントを構築する方法

ほとんどの「AIエージェント」チュートリアルはLLMで終わる。難しいのは、エージェントがウォレットを必要とし、呼び出すサービスへの支払い手段を必要とし、自分が動かしているチェーンのライブビューを必要とするところから始まる。

オンチェーンエージェントを構築するには、エージェントに3つのプリミティブを与える。署名用のスコープ付きウォレット、x402のような決済レール、webhooks、WebSockets、gRPCによるリアルタイムデータフィードだ。モデルが判断を下し、これらのプリミティブがオンチェーンでの実行を可能にする。

コードを書くLLMはコパイロットだ。お金を保持し、トランザクションに署名し、オンチェーンイベントにリアルタイムで反応するエージェントは別物、つまり経済圏の参加者だ。インフラはすでに存在するが、ウォレット、決済、リアルタイムデータのプリミティブに散らばっている。このガイドでは実際に必要な3つを取り上げ、それらをどう組み合わせるかを説明する。Alchemy CLIと私たちのagenticプロダクトは、それぞれをそのまま使えるプリミティブとして提供している。

オンチェーンエージェントの構築では何が違うのか?

通常のAIエージェントのスタックのほとんどはオンチェーンでもそのまま使える。モデル、フレームワーク、ツール呼び出しのパターン、オーケストレーションループ、評価ハーネス、プロンプトストア。これらはすべて転用できる。Slackボット、コーディングエージェント、リサーチエージェントを構築したことがあれば、スタックの上半分はすでになじみがあるはずだ。

転用できないのは3つ、ウォレット、決済レール、リアルタイムデータフィードだ。この3つはいずれもLLMツーリングの世界にきれいな対応物がなく、より賢いモデルを選ぶことで解決するものでもなく、どれか一つでも間違えるとウォレットが枯渇したり、本番環境でエージェントが停止したりする類のミスにつながる。

IDはメールアドレスではなく秘密鍵だ。 エージェントが署名できるものは、支払えるものでもある。鍵の管理はconfigファイルの話ではなく、セキュリティモデルの話になる。
決済はプロトコルレイヤーで行われる。 Stripeは「私はエージェントです」を支払者として受け付けない。crypto rail はそれを受け付ける。HTTP 402/x402のような標準を通じてだ。
リアルタイムデータはデフォルトのモードであり、機能の一つではない。 ブロックタイムは短く、finalityが重要になる。ポーリングは予算を消費し、気にかけているイベントすべてに遅れて到着することになる。

以下の3つの構成要素は、それぞれこれらの変化の一つに対応している。

オンチェーンエージェントの3つの構成要素とは?

本番のオンチェーンエージェントには通常3つのものが必要だ。

ウォレット。エージェントはこれで署名できるが、プロンプトが侵害されても枯渇させられないようにスコープが限定されている。
決済レール。エージェントは人間を介さずに、オフチェーンAPIとオンチェーンガスの両方を支払う。
リアルタイムデータパイプ。エージェントは新しいブロック、トランザクション、コントラクトイベントが発生した瞬間に反応する。

このガイドの残りは、構成要素ごとに1セクション、そして最後にそれらを組み合わせるウォークスルーで構成されている。

鍵を漏らさずにエージェントにウォレットを与えるには?

最初に誰もが試す素朴なパターンは、秘密鍵を.envファイルに置き、dotenvでロードし、エージェントループの内側からそれで署名するというものだ。ローカルデモでは動く。本番環境ではプロンプトインジェクション一発でウォレットが空になる。

より安全なデフォルトとして、2つのパターンが定着しつつある。

1つ目のパターンは、委任署名を伴うembedded smart accounts(生の秘密鍵アカウントではなく、プログラム可能なウォレットコントラクト)だ。鍵はカストディサービス(Privy、Turnkey、multi-party computationのためのCoinbase MPC)の内部にある。エージェントはそれを一切目にしない。エージェントは署名APIを呼び出し、サービスがリクエストをポリシーに照らして検証し、署名済みトランザクションが返ってくる。エージェントは設定したルール(トランザクションあたりの最大額、許可されたコントラクト、日次上限)の範囲内でのみ署名でき、それ以外はできない。

2つ目のパターンは、開発者向けのサーフェスから承認されるセッションスコープのウォレットだ。エージェントは特定のウォレットに紐づいた、時限付きで取り消し可能なセッションを受け取る。あなたが管理するUIからそのセッションを承認する。取り消しはワンクリックだ。

パターン2の最新の実装がAlchemy CLIのagent wallet機能で、CLI自体の一部として提供される。

bashCopied
# Install the latest Alchemy CLI
npm i -g @alchemy/cli@latest
# Authenticate your CLI session
alchemy auth
# Connect the wallet your agent will use
alchemy wallet connect

alchemy wallet connectはブラウザでダッシュボードを開く。エージェントに使わせたいウォレットを選び、セッションを承認すれば、以降はCLIがエージェントに代わって署名できる。秘密鍵はPrivy側にとどまる。署名呼び出しはすべて2段階のフローを通る。私たちのバックエンドがペイロードを構築し、CLIがローカルで署名し、そのリクエストがPrivyに届く。セッションが期限切れか、取り消されているか、バインディングチェックに失敗した場合は、私たちのインフラを出る前にリクエストは拒否される。

CLIは人間だけでなく、エージェント向けのツールサーフェスとして設計されている。次のコマンドが重要だ。

bashCopied
# Run any command with structured output and no prompts
alchemy <command> --json --no-interactive
# Print the JSON manifest of every command and flag
alchemy --json --no-interactive agent-prompt
# Install Alchemy Skills for agent clients
npx skills add alchemyplatform/skills --yes

alchemy --json --no-interactive agent-promptは、これをagent-nativeにしている部分だ。LLMにCLIのサーフェスを覚えさせる代わりに、セッション開始時にJSONマニフェストを渡せば、モデルはコマンド空間全体、エラーコード、実行例を把握する。これにより「エージェントが存在しないフラグを幻覚した」という類の失敗が丸ごと消える。ライブのチェーンデータツールについてはhosted MCP serverを別途接続すればよい。

2つのパターンの使い分け方:

Pattern	Best for	Trade-off
Embedded smart account with delegated signing	Production agents acting on behalf of end users (consumer apps, agent commerce)	More setup, but per-user isolation and granular policy
Session-scoped CLI wallet	Single-developer agents, automation, internal tools, prototypes	Faster to wire up, scoped per session, revocable from one dashboard

どちらを選んでも、ルールは同じだ。エージェントは生の秘密鍵を絶対に目にしない。もし設計上、メモリ上に秘密鍵があるなら、それはエージェントではなく脆弱性を作ったということだ。

エージェントは呼び出すサービスの支払いをどう行うのか?

エージェントがウォレットを持ったとしても、まだ物事に対して支払いをする必要がある。コストには2種類ある。

オンチェーンコスト。 ガス、スワップ手数料、ブリッジ手数料など、状態変更に対してチェーンが課すもの全般。
オフチェーンコスト。 RPCリクエスト、インデックス済みデータAPI、推論など、エージェントがサーバーから必要とするもの全般。

オンチェーンコストはgas sponsorshipによって解決される。多くのaccount-abstractionプロバイダーはpaymaster APIを公開しており、paymasterとは他者に代わってガスを支払うコントラクトのことだ。エージェントはuser operation(ERC-4337におけるスマートアカウント用のトランザクション相当物)を送信し、paymasterがそれをカバーし、あなたは自分側で使用量を精算する。このパターンはすでにsmart-accountシステムで一般的だ。

オフチェーンコストはより難しい問題だ。なぜなら、エージェントはクレジットカードを登録していないし、あなたもすべてのエージェントにAPIキーを発行したくはないからだ。エコシステム全体で収束しつつあるパターンがx402だ。HTTP 402 Payment Requiredステータスコードに加えて、エージェントに支払い方法を伝える小さなペイロードを組み合わせたものだ。

全体のフローは次の通りだ。

エージェントがサービスにHTTPリクエストを送る。
サービスは価格、受け付けるトークン、チェーンを記述したJSONボディとともに402 Payment Requiredで応答する。
エージェントは支払いを構築し(Base上のUSDCが一般的なデフォルト)、自分のウォレットで署名し、支払いの証明をヘッダーに含めて元のリクエストをリトライする。
サービスがそれを検証し、決済を確定させ、データを返す。

私たちはこれをエンドツーエンドで実装している。エージェントはRPC API、Token API、Portfolio API、NFT API、Prices APIを、APIキーもダッシュボード登録も不要で叩くことができる。最初のリクエストは402を受け取り、以降のリクエストはBase上のUSDCでエンドポイントが提示した金額を支払い、データを返す。人間の介在は不要だ。

最小限のクライアント側ハンドラは次のようになる。

typescriptCopied
async function paidFetch(url: string, wallet: AgentWallet) {
  let res = await fetch(url);

  if (res.status === 402) {
    const requirement = await res.json();
    const payment = await wallet.signX402Payment(requirement);

    res = await fetch(url, {
      headers: { "X-PAYMENT": payment },
    });
  }

  return res.json();
}

エージェントは署名済みの支払いヘッダーを付けて同じURLをリトライする。エンドポイントはオンチェーンで支払いを確定させ、データを返し、エージェントは処理を続ける。このパターンはプロバイダー間で組み合わせ可能だ。x402を話すサービスであれば、カスタム認証を書かなくてもエージェントからの支払いを受け付けられる。

エージェントはどうやってチェーンと同期を保つのか?

チェーンはデフォルトではあなたのアプリにプッシュしてこない。エージェントが何が起きているかを知るために毎秒eth_blockNumberをポーリングしているなら、そのポーリング自体にコストを払いながら、気にかけているイベントすべてに遅れて到着していることになる。

リアルタイムのユースケースのほぼすべてを3つのパターンでカバーできる。詳細な比較はwebhooks vs WebSockets vs gRPCの比較にあるが、エージェント開発者向けの要点は次の通りだ。

Pattern	Use when
Webhooks	The agent runs as a service with a public URL and wants the provider to push events (new transactions, mined blocks, address activity). Cheapest to operate at low-to-medium event volume.
WebSockets	The agent runs a persistent process and needs sub-second pickup on logs and pending transactions. Best for in-process loops.
gRPC streaming	The agent is throughput-bound on Solana or another high-TPS chain. Lowest latency, highest cost to integrate.

ほとんどのエージェントでは、webhooksといくつかのData API呼び出し(token balances、transaction history、portfolio)で十分だ。webhookが発火し、エージェントが起動し、拡充された状態を問い合わせ、何をすべきか判断し、トランザクションに署名し、再び待機する。

組み合わせる: 最小限のオンチェーンエージェントアーキテクチャ

ここに、3つの構成要素すべてを組み合わせたコンパクトなアーキテクチャの概要を示す。自分自身のウォレットを監視し、何かが到着したら有料エンドポイントに問い合わせ、LLMに何をすべきか尋ね、応答トランザクションに署名する。本番環境で実行する前に、x402署名用のヘルパーをあなたのカストディプロバイダーに置き換えてほしい。

typescriptCopied
import { createPublicClient, webSocket } from "viem";
import { base } from "viem/chains";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import OpenAI from "openai";

const run = promisify(execFile);
const openai = new OpenAI();
const agentWallet = process.env.AGENT_WALLET_ADDRESS!.toLowerCase();
const client = createPublicClient({
  chain: base,
  transport: webSocket(process.env.ALCHEMY_RPC_WSS!),
});

async function signX402Payment(requirement: unknown) {
  // Plug in your x402 client and custody provider here.
  // The signer should construct the payment payload and sign it with the agent wallet.
  throw new Error("Implement x402 signing with your wallet provider");
}

// 1. Signing through the agent wallet session (no private key in process).
// Use the session approved via `alchemy wallet connect` to sign and broadcast.
async function refund(to: string, amountEth: string) {
  // Plug in your agent wallet signing provider here.
  throw new Error("Implement refund signing with your agent wallet session");
}

// 2. Paid data fetch via x402 against an Alchemy endpoint.
async function paidFetch(url: string) {
  let res = await fetch(url);
  if (res.status === 402) {
    const requirement = await res.json();
    const payment = await signX402Payment(requirement);
    res = await fetch(url, { headers: { "X-PAYMENT": payment } });
  }
  return res.json();
}

// 3. Real-time trigger: react to inbound transactions on the agent wallet.
client.watchBlocks({
  includeTransactions: true,
  onBlock: async (block) => {
    for (const tx of block.transactions) {
      if (tx.to?.toLowerCase() !== agentWallet) continue;

      const portfolio = await paidFetch(
        `https://api.g.alchemy.com/data/v1/portfolio/${tx.from}`
      );

      const decision = await openai.chat.completions.create({
        model: "gpt-4o",
        messages: [
          {
            role: "system",
            content: "You are a treasury agent. Decide whether to refund.",
          },
          {
            role: "user",
            content: JSON.stringify({ tx, sender_portfolio: portfolio }),
          },
        ],
      });

      const action = JSON.parse(decision.choices[0].message.content!);
      if (action.refund) {
        await refund(tx.from, action.amount);
      }
    }
  },
});

このアーキテクチャについて注目すべき点が3つある。

プロセス内に秘密鍵がない。 署名呼び出しはすべてCLIセッションを経由し、それがPrivyと通信する。このプロセスが侵害されても、攻撃者が得るのは取り消し可能なセッションであって、ウォレットではない。
データ呼び出しにAPIキーがない。 paidFetchはx402を話すどのエンドポイントに対しても動作する。エンドポイントはリクエストごとにUSDCで課金する。
LLMは最も小さな部分だ。 表面積のほとんどはウォレット、決済、データの配管だ。モデルはただ判断を下すだけだ。

これがこのパターンだ。トリガー(Discordメッセージ、cron、マーケットプレイスイベント)を差し替え、アクション(スワップ、投票、ブリッジ、ミント)を差し替え、モデルを差し替えれば、別のエージェントになる。

Claudeで構築する

あるいはClaudeに構築させよう。Alchemy Skillsをインストールし、hosted MCP serverを接続する:

bash

Copied

npx skills add alchemyplatform/skills --yes

# Claude Code — see the MCP server docs for other clients
claude mcp add alchemy --transport http https://mcp.alchemy.com/mcp

次に、このプロンプトをClaude Codeに貼り付ける:

text

Copied

Build a TypeScript onchain agent on Base that:
1. Watches a wallet address for incoming transactions in real time
2. When a transaction arrives, queries an x402-payable portfolio API for the sender's holdings
3. Asks an LLM whether to refund
4. Signs the refund without holding the private key in the process

Use production-grade primitives.

出力は上記のスクリプトと同じ形になる。私たちのRPCに対するviemのWebSocket、x402の背後にある私たちのPortfolio API、そしてrefundのために承認済みのagent walletセッションを通じたCLI署名だ。プロセス内に秘密鍵はない。

どのエージェントフレームワークを使うべきか?

フレームワークは上記の3つのプリミティブの上のレイヤーだ。エージェントループ、ツール登録、メモリ、(一部は)ソーシャルプラットフォームのクライアントを扱う。適切な選択は、チェーンの深さ、マルチチェーンの広さ、フルランタイムのどれを最適化したいかによる。

Framework	Best for	Chains	Notes
LangChain / LangGraph	General-purpose orchestration with any model and any tool	Any (via tool wrappers)	Most flexible, least opinionated. You wire the wallet and RPC tools yourself.
GOAT SDK by Crossmint	Multi-chain agents that need EVM and Solana under one API	EVM + Solana	Plugin model. Good fit when the agent crosses chains.
ElizaOS agent runtime	Social agents (Twitter, Discord, Farcaster) with character files	Any	Full runtime including memory and platform clients. Heavier than a library.
Solana Agent Kit by SendAI	Deepest Solana protocol coverage (Jupiter, Raydium, Drift, etc.)	Solana only	Tool library, not a runtime. Bring your own loop.
Vercel AI SDK	Streaming agent responses to a web UI	Any (via tools)	Good fit for streaming agent responses to a browser UI.

ウォレットのセットアップ、RPCの統合、Jupiterのスワップを含む、チェーンネイティブなエンドツーエンドの構築については、Solana AIエージェント構築ガイドを参照してほしい。チェーンに依存しないプロバイダー比較については、自律型オンチェーンエージェントのための最良のブロックチェーンAPIを参照してほしい。

フレームワークは、構成要素とは違って交換可能だ。LangChainからGOATへの切り替えは午後の作業で済む。エージェントの署名方法を変えるのはセキュリティレビューが必要になる話だ。

次に何を構築するか

3つの構成要素は組み合わせられる。セッションスコープのウォレットを持ち、x402でデータの支払いをし、リアルタイムイベントに反応するエージェントができたら、問いは「エージェントにこれができるか」ではなく、「エージェントに何をさせるべきか」に変わる。

私たちは3つの構成要素それぞれをプリミティブとして提供している。私たちのCLIは、Privyに支えられた取り消し可能なセッションを通じてウォレットを扱う。私たちのRPC、Token、Portfolio、NFT、Pricesの各APIは直接x402を話す。APIキーも、ダッシュボード登録も、契約も不要だ。Webhooks、WebSocket subscriptions、Solana gRPC streamingがリアルタイムデータフィードをカバーする。

npx skills add alchemyplatform/skills --yesを実行し、hosted MCP serverを接続し、LangChain、GOAT、ElizaOS、あるいはあなたのフレームワークをAlchemyのAPIに向けてほしい。npm i -g @alchemy/cli@latestとalchemy authから始めてほしい。詳しくはalchemy.com/agentsを参照してほしい。

よくある質問

オンチェーンエージェントとは何か?

オンチェーンエージェントとは、ブロックチェーンの状態を読み取り、ウォレットを保持または制御し、ポリシーやモデルの判断に基づいてトランザクションに署名できるAIエージェントのことだ。何をすべきかはモデルが判断し、ウォレット、決済レール、データフィードがそれを実行可能にする。

オンチェーンエージェントはどう構築するのか?

3つのプリミティブから始める。署名用のスコープ付きウォレット、有料APIコールのためのx402のような決済レール、webhooks、WebSockets、gRPCによるリアルタイムデータフィードだ。そのうえで、それらのプリミティブを、すでに使っているエージェントフレームワークやオーケストレーションループに接続する。

AIエージェントはどのウォレットを使うべきか?

生の秘密鍵をエージェントのプロセスの外に保つウォレットパターンを使う。委任署名を伴うembedded smart accountsはユーザー向けアプリにうまく機能し、セッションスコープのCLIウォレットは開発者向けエージェント、社内の自動化、プロトタイプにうまく機能する。

オンチェーンエージェントはどうやってAPIの支払いをするのか?

x402による支払いを使うことができる。エージェントはリクエストを送り、支払い詳細を含む402 Payment Requiredレスポンスを受け取り、ウォレットで支払いに署名し、支払いの証明を付けてリクエストをリトライする。

オンチェーンエージェントはwebhooks、WebSockets、gRPCのどれを使うべきか?

エージェントがサービスとして動作し、プッシュされたイベントを受け取れる場合はwebhooksを使う。エージェントが永続的なプロセスとして動作し、ログや保留中のトランザクションを低レイテンシーで必要とする場合はWebSocketsを使う。レイテンシーが統合の手間を正当化するほど重要な、高スループットのSolana系ワークロードにはgRPC streamingを使う。

オンチェーンエージェントに最適なフレームワークは何か?

最適なフレームワークは必要とするループによる。LangChainやLangGraphは汎用的なオーケストレーションに柔軟に対応し、GOATはマルチチェーンのツールカバレッジに有用で、ElizaOSはソーシャルエージェント向けに構築されており、Solana Agent KitはSolanaを深くカバーし、Vercel AI SDKはブラウザ向けのエージェントUIに適している。

コアインフラは構築を始められる状態にある。それを使って何をするかは、他の誰にも代わりに書けない部分だ。