Onchain Agent Wallets

onchain-agent-wallets

資金を渡さずに、AI エージェントに本物の Solana ウォレットを持たせましょう。

秘密鍵の代わりに、あらゆるエージェントに支出枠を付与する MCP サーバーです。資金はあなたが所有するアカウントに残ります。エージェントには、SPL Token プログラムがオンチェーンで上限を適用する委任と、あなたが管理する安全策、さらにその支出枠から x402 API に支払う機能が与えられます。1 つの命令で委任を取り消し、エージェントに確認を求めることなく資金を取り戻せます。

ここにあるものはすべて実際に動作します。本物の SPL Token 委任、本物の Solana、本物の x402 決済です。

概要を読む · npm

このツールが解決する問題

現在の「エージェントウォレット」はどれも同じ仕組みです。キーペアを生成してエージェントに渡すと、エージェントは中にあるすべてのものを使えるようになります。上限も、許可リストも、有効期限もなく、エージェントより先に資金を移動させる以外に取り戻す方法もありません。そのため、ほとんど資金を入れないことで対処する人もいますが、それではエージェントは役に立つ作業ができません。

より古く、より優れた方法は、支出枠を使うことです。資金がエージェントに移ることはありません。エージェントにはその一部を使う権限だけが与えられ、その範囲をブロックチェーンが強制します。

仕組み

   YOU (Phantom, Solflare, Ledger)
    │  owns the vault, holds the money, can revoke or withdraw at any time
    ▼
  ┌──────────────────────────────────────────┐
  │  vault token account                     │   derived from your address:
  │  owner    = you                          │   createWithSeed(you, "oaw1:<agent>")
  │  balance  = 500 USDC                     │
  │  delegate = the agent  ← capped at 100   │   SPL Token enforces this number
  └──────────────────────────────────────────┘
    ▲
    │  may spend up to the cap, and not one unit more
   AGENT (its own keypair, holds only fee SOL)

独立した 2 つのレイヤーで保護します。

1. オンチェーン。 SPL Token プログラムは、エージェントが署名したすべての送金について delegated_amount と照合し、支出のたびにその額を減らします。私たちのコードで額を増やすことはできません。revoke を 1 回実行すると、額はゼロになります。これは標準のトークンプログラムの機能であり、新たに信頼する必要のあるコントラクトではありません。
2. ローカル。 このサーバーが何かに署名する前に、1 回の取引ごとの上限、直近 24 時間の上限、送金先の許可リスト、x402 ホストの許可リスト、有効期限、一時停止、さらに人間の確認を必須にする確認しきい値といったルールを適用します。

エージェント自身のキーペアに保持されるのは、手数料用の少量の SOL だけです。漏えいした場合の被害範囲は残りの支出枠に限られ、revoke_agent_wallet を使えば 1 回のトランザクションで無効化できます。

インストール

npm install -g @three-ws/onchain-agent-wallets
# or run it ad hoc
npx -y @three-ws/onchain-agent-wallets

セットアップ

Claude Code：

claude mcp add onchain-agent-wallets -- npx -y @three-ws/onchain-agent-wallets

Cursor、または任意の MCP クライアント（mcp.json）：

{
	"mcpServers": {
		"onchain-agent-wallets": {
			"command": "npx",
			"args": ["-y", "@three-ws/onchain-agent-wallets"],
			"env": {
				"OAW_NETWORK": "mainnet"
			}
		}
	}
}

開始時に鍵は必要ありません。オーナー操作では、ウォレットで署名するための未署名トランザクションが返され、その後 send_signed_transaction でブロードキャストします。このサーバーに代わりに署名させる場合は、OWNER_SECRET_KEY を設定してください。

変数	デフォルト	説明
OWNER_SECRET_KEY	未設定	base58 または JSON バイト配列形式のオーナー鍵です。任意です。設定しない場合は、Phantom で署名します。
OAW_NETWORK	mainnet	mainnet または devnet です。状態はネットワークごとに保持されます。
SOLANA_RPC_URL	パブリックエンドポイント	独自の RPC です。パブリックエンドポイントには厳しいレート制限があります。https が必須です。
OAW_STATE_DIR	~/.onchain-agent-wallets	エージェントのキーペア、安全策、支出台帳の保存先です（0700 のディレクトリ内に 0600 で保存）。
REQUIRE_CONFIRM	true	値を移動するすべてのツールは、confirm:true がないとブロードキャストを拒否します。

クイックスタート

調査エージェントに100 USDCの利用権限を与え、1回の取引につき最大5、1日につき最大20に制限し、1つのAPIだけに利用できるようにします。

create_agent_wallet
  id: "researcher"
  allowance: "100"
  per_tx: "5"
  daily: "20"
  allow_hosts: ["api.example.com"]
  confirm: true

fund_agent_wallet  id: "researcher"  amount: "500"  sol: "0.02"  confirm: true

エージェントはこれで、自律的に支払いを行います。

pay_x402  id: "researcher"  url: "https://api.example.com/premium"  confirm: true
agent_pay id: "researcher"  to: "<address>"  amount: "2.50"  confirm: true

管理権限は引き続きあなたにあります。

agent_wallet_status  id: "researcher"      # live balances, remaining allowance, warnings
spend_log            id: "researcher"      # every spend AND every refusal, with reasons
set_guardrails       id: "researcher"  paused: true      # instant, free, no transaction
revoke_agent_wallet  id: "researcher"  withdraw: true  confirm: true   # on-chain kill switch

拒否された場合、どのルールが適用されたかが正確にわかります。

{
	"ok": false,
	"error": "over_daily",
	"message": "20.5 would exceed the 20 daily cap (18 already spent)",
	"checks": [
		{ "check": "per_tx", "ok": true, "detail": "2.5 is within the 5 per-transaction cap" },
		{ "check": "daily", "ok": false, "detail": "20.5 would exceed the 20 daily cap (18 already spent)" }
	]
}

ツール

カストディ（あなたが署名）

ツール	機能
create_agent_wallet	エージェントのキーペアを生成し、Vaultを作成して、上限付きの利用枠を委任し、ガードレールを設定します。これらを1回の呼び出しで行います。
fund_agent_wallet	トークンをVaultに移し、手数料用のSOLをエージェントに送金します。
approve_agent_allowance	オンチェーンの上限を引き上げ、引き下げ、または補充します。以前の利用枠は置き換えられます。
withdraw_from_vault	資金を引き戻します。有効な委任があってもなくても利用できます。
revoke_agent_wallet	緊急停止スイッチです。同じトランザクションで残高を自分のウォレットに戻すこともできます。
send_signed_transaction	あなたのウォレットで署名したトランザクションをブロードキャストします。

ガードレール

ツール	機能
set_guardrails	per_tx、daily、allow_recipients、allow_hosts、expires_at、confirm_over、pausedを設定します。即時反映され、無料で、トランザクションは不要です。

支出（エージェントが署名）

ツール	機能
agent_pay	制限内で受取人にトークンを送金します。
pay_x402	x402 APIを呼び出し、利用枠から支払います。

可視性

ツール	機能
agent_wallet_status	オンチェーンのリアルタイム状態、ガードレール、過去24時間と7日間の合計、および警告を表示します。
list_agent_wallets	各エージェントのリアルタイム残高を表示します。
spend_log	拒否された支出も含む監査ログを表示します。

デプロイ

ツール	機能
deploy_agent_onchain	オンチェーン属性に支払いアドレスを含むMetaplex Agent Registryのアイデンティティをエージェントに発行します。
export_agent_runtime	このエージェントを別の場所で実行するために必要なmcp.jsonとアイデンティティカードを出力します。

ガードレール

ルール	効果	適用元
allowance	新たな承認を受けるまでにエージェントが支出できる合計額	SPL Tokenプログラム、オンチェーン
vault balance	エージェントはVaultにない資金を支出できません	SPL Tokenプログラム、オンチェーン
per_tx	1回あたりの支出上限	このサーバー
daily	ローカル台帳から算出される、ローリング24時間あたりの支出上限	このサーバー
allow_recipients	指定したアドレスのみが資金を受け取れます。空の場合は制限なしです	このサーバー
allow_hosts	x402経由の支払いが許可されるホストです。サブドメインにも適用されます。空の場合は制限なしです	このサーバー
expires_at	このタイムスタンプ以降の支出はすべて拒否されます	このサーバー
confirm_over	この金額を超える支出には、明示的なconfirm:trueが必要です	このサーバー
paused	すべての支出が即時かつ無料で拒否されます	このサーバー

問題が発生したときは、この違いが重要になります。このマシンが侵害された場合、ローカルルールは回避される可能性がありますが、オンチェーンの利用枠は回避できません。そのため、利用枠は残高全額ではなく、エージェントが動作できる最小限の額に設定し、必要に応じて補充してください。

x402

pay_x402は、まず支払いを行わずにエンドポイントを確認するため、資金が動く前に価格がわかり、ガードレールは実際の金額を確認できます。その後、Vaultからエージェントにその金額だけを補充して支払いを行い、再びエージェントの残高を空にします。

次の場合、支払いは拒否されます。

• Solana以外のチェーンの場合（no_solana_option）
• クラスターが異なる場合。たとえば、devnetウォレットでmainnetの価格が指定されている場合（wrong_cluster）
• 利用枠の通貨と異なるトークンの場合（asset_mismatch）
• 常時適用されるガードレールとは独立した、呼び出しごとの上限であるmax_priceを超える場合（over_max_price）

エンドポイントが課金しない場合は、コンテンツが返され、支出は発生しません。

エージェントにできないこと

• 指示されても、許可額を超えて支出することはできません。上限を決めるのはモデルではなく、トークンプログラムです。
• ボールトを移動したり、閉じたり、所有者を変更したりすることはできません。エージェントは所有者ではありません。
• 引き出しを止めたり、取り消しを止めたりすることはできません。
• 自分の許可額を引き上げることはできません。引き上げられるのは、所有者が署名した approve のみです。
• ウォレット内のほかのものに触れることはできません。ボールトは独立したアカウントで、入金したものだけを保持します。

実証は test/token-delegation.test.mjs で行っています。このテストでは、SPL Tokenプログラムをプロセス内で実行し、残りの許可額が60の状態で61を支出しようとすると、オンチェーンで失敗することを検証します。ボールトには460が残っています。

devnetで無料でリハーサルする

OAW_NETWORK=devnet npx -y @three-ws/onchain-agent-wallets

状態はネットワークごとに保持されるため、devnetでのリハーサルがmainnetのエージェントに影響することはありません。

ライブラリとして使う

カストディモデルには標準的な @solana/web3.js と @solana/spl-token を使用しており、MCPなしでも利用できます。

import { createVaultInstructions, readVault, spendableUnits } from '@three-ws/onchain-agent-wallets/lib/vault';

const { vault, instructions } = await createVaultInstructions({
	connection,
	owner: ownerPubkey,
	agentId: 'researcher',
	mint: usdcMint,
	delegate: agentPubkey,
	allowance: 100_000_000n, // 100 USDC
	decimals: 6,
});
// sign `instructions` with the owner, then:
const state = await readVault({ connection, vault });
console.log(spendableUnits(state)); // what the agent may spend right now

@three-ws/onchain-agent-wallets/lib/policy はガードレールエンジンを単独でエクスポートします。同じルールを別のランタイムで使いたい場合に利用できます。

テスト

npm test

ガードレールのユニットテスト、x402の選択テスト、および実際のSPL Tokenプログラムを使った委任の統合テストを実行します。

関連プロジェクト

• @three-ws/metaplex-agent-mcp は、エージェントのアイデンティティをMetaplex Agent Registryにミントします。deploy_agent_onchain はこれをライブラリとして使用し、その prepare_agent_mint はブラウザーウォレットを使ってミントするための手段です。
• three.ws は、これらのエージェントが顔やアバター、居場所を得る場所です。

ライセンス

LICENSE を参照してください。

プロジェクトを応援する

onchain-agent-walletsが役に立ったら、GitHubでスターを付けてください。スターがあると、ほかの開発者やAIエージェントが信頼できるリポジトリを見つけやすくなります。クリックひとつで応援できます。

使ってくれそうな人を知っていますか？ Xに投稿 · Blueskyで共有 · LinkedInで共有 · Hacker Newsに投稿 · Redditで共有

AIエージェントにも対応

コーディングエージェントやLLMツールから、このリポジトリを直接参照できます。AGENTS.md、llms.txt、llms-full.txt をご覧ください。エージェントに https://github.com/nirholas/onchain-agent-wallets を指定すれば、必要なコンテキストを取得できます。

同じ作者によるその他のプロジェクト

• nirholasの全リポジトリ：トピック別に分類された全カタログ
• three.ws：Solanaウォレット、スキルマーケットプレイス、x402決済に対応する3D AIエージェントのプラットフォーム
• 質問やアイデア：issueを作成するか、ディスカッションを開始してください。

コントリビューター

Star 履歴

three.ws の一部

three.ws は、Solana ウォレットを備えた 3D AI エージェント向けのプラットフォームです。アバター、スキルマーケットプレイス、x402 決済、70 を超える MCP サーバーなどを提供しています。@three-ws/onchain-agent-wallets はそのパッケージの 1 つです。

• ドキュメントサイト：https://nirholas.github.io/onchain-agent-wallets/
• npm：https://www.npmjs.com/package/@three-ws/onchain-agent-wallets
• 正規ソース：https://github.com/nirholas/three.ws（このリポジトリは packages/onchain-agent-wallets から生成されたミラーです）
• エージェント向け要約：llms.txt と AGENTS.md
• 問題やアイデア：https://github.com/nirholas/onchain-agent-wallets/issues