Onchain Agent Wallets

onchain-agent-wallets

为 AI Agent 提供一个真正的 Solana 钱包，而无需交出你的资金。

这是一个 MCP 服务，为任何 Agent 提供可支配额度，而不是私钥。资金仍留在你拥有的账户中。Agent 获得一项由 SPL Token 程序在链上设定上限的委托，并受到你控制的防护规则约束，还可以从该额度中支付 x402 API 费用。你只需一条指令即可撤销委托，并收回资金，无需征求 Agent 同意。

这里的一切都是真实的：真实的 SPL Token 委托、真实的 Solana、真实的 x402 结算。

阅读概览 · npm

此项目解决的问题

如今所有“Agent 钱包”的工作方式都一样：生成一个密钥对，交给 Agent，然后其中的一切就都归 Agent 所有。没有额度上限、没有允许列表、没有有效期，也无法收回，除非抢在 Agent 转移资金之前动手。人们只能让钱包里几乎不存钱，但这样 Agent 就什么实用的事情也做不了。

额度是一种更早出现、也更好的解决方案。资金永远不会转到 Agent 手中。Agent 只获得使用其中一部分资金的权限，而区块链会强制执行额度限制。

工作原理

   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)

两个相互独立的防护层为你提供保护：

1. 链上。 SPL Token 程序会检查 Agent 签名的每笔转账是否超过 delegated_amount，并在每次支出时扣减该额度。我们的代码无法提高额度。一次 revoke 操作即可将额度设为零。这是标准 Token 程序自带的功能，无需信任新的合约。
2. 本地。 在此服务签署任何内容之前，都会应用你的规则：单笔交易上限、滚动 24 小时支出上限、收款方允许列表、x402 主机允许列表、有效期、暂停，以及强制要求人工确认的金额阈值。

Agent 自己的密钥对中只存有少量用于支付手续费的 SOL。即使密钥泄露，风险范围也仅限于剩余额度，而 revoke_agent_wallet 可通过一笔交易将其关闭。

安装

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	Agent 密钥对、防护规则和支出记录的存储位置（权限为 0600，位于权限为 0700 的目录中）。
REQUIRE_CONFIRM	true	所有会转移价值的工具在没有 confirm:true 时都拒绝广播。

快速入门

为研究 Agent 提供 100 USDC 的支出额度，每笔交易最多 5，每天最多 20，并且只能用于一个 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

现在，Agent 可以自行支出了：

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	生成 Agent 的密钥对、创建金库、委托有上限的额度并设置护栏。一次调用即可完成。
fund_agent_wallet	将代币转入金库，并向 Agent 转入 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 签名）

工具	功能
agent_pay	在限额内向收款方发送代币。
pay_x402	调用 x402 API，并从额度中付款。

可见性

工具	功能
agent_wallet_status	实时链上状态、护栏、24 小时和 7 天支出总额及警告。
list_agent_wallets	列出所有 Agent 及其实时余额。
spend_log	支出审计记录，包括拒绝记录。

部署

工具	功能
deploy_agent_onchain	为 Agent 铸造 Metaplex Agent Registry 身份，并将其付款地址写入链上属性。
export_agent_runtime	导出在其他位置运行此 Agent 所需的 mcp.json 和身份卡。

护栏

规则	效果	执行方
allowance	Agent 在需要重新批准前可支出的总额	SPL Token 程序，链上
vault balance	Agent 无法支出不存在的资金	SPL Token 程序，链上
per_tx	单笔支出的上限	此服务
daily	每滚动 24 小时的上限，根据本地账本计算	此服务
allow_recipients	仅允许向这些地址转账。留空表示不限制	此服务
allow_hosts	仅允许通过 x402 向这些主机付款。子域名继承规则。留空表示不限制	此服务
expires_at	超过此时间戳后拒绝所有支出	此服务
confirm_over	超过此金额的支出需要明确设置 confirm:true	此服务
paused	立即、免费地拒绝所有操作	此服务

出问题时，这一区别至关重要。如果这台机器遭到入侵，本地规则可能被绕过，但链上额度仍然无法突破。因此，额度应设为足以让 Agent 工作的最小数额，并按需补充，而不是直接设为全部余额。

x402

pay_x402 会先在不付款的情况下探测端点，以便在资金转移前确定价格，并让护栏依据实际金额进行检查。随后，它会从金库中向 Agent 补入恰好所需的金额，完成付款，再让 Agent 的余额归零。

以下情况会拒绝付款：

• 使用的链不是 Solana（no_solana_option）
• 网络集群不匹配，例如使用 devnet 钱包支付 mainnet 价格（wrong_cluster）
• 付款代币与额度的计价代币不一致（asset_mismatch）
• 金额超过 max_price，即独立于现有护栏的单次调用上限（over_max_price）

如果端点不收费，内容会正常返回，且不会产生任何支出。

Agent 无法执行的操作

• 无论收到什么提示词，都不能超出额度。额度由代币程序决定，而非模型。
• 不能转移保险库、关闭保险库或更改其所有者。它不是所有者。
• 不能阻止你提现，也不能阻止撤销授权。
• 不能提高自己的额度。只有由所有者签名的 approve 才能做到这一点。
• 不能触及你钱包中的其他任何资产。保险库是一个独立账户，只持有你存入其中的资产。

此行为已在 test/token-delegation.test.mjs 中得到验证。该测试会在进程内运行真实的 SPL Token 程序，并断言：剩余额度为 60 时，尝试支出 61 会在链上失败，而保险库中仍有 460。

在 devnet 上免费演练

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

状态按网络分别保存，因此在 devnet 上演练绝不会触及你的 mainnet Agent。

将其用作库

此托管模型基于纯粹的 @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 会将 Agent 身份铸造到 Metaplex Agent Registry 中。deploy_agent_onchain 将其用作库，而其 prepare_agent_mint 则是通过浏览器钱包进行铸造的途径。
• three.ws 是这些 Agent 获得面孔、头像和家园的地方。

许可证

请参阅 LICENSE。

支持此项目

如果 onchain-agent-wallets 为你节省了时间，欢迎**在 GitHub 上为其点星**。星标能帮助其他开发者和 AI Agent 找到值得信赖的代码仓库，而且只需点击一下。

认识可能会用到它的人？在 X 上发布 · 分享到 Bluesky · 分享到 LinkedIn · 提交到 Hacker News · 分享到 Reddit

也为 AI Agent 而构建

编码 Agent 和 LLM 工具可直接读取此代码仓库：AGENTS.md、llms.txt、llms-full.txt。将 https://github.com/nirholas/onchain-agent-wallets 提供给 Agent，它就能获得所需的上下文。

同一作者的更多项目

• nirholas 的所有代码仓库：按主题分类的完整目录
• three.ws：面向 3D AI Agent 的平台，提供 Solana 钱包、技能市场和 x402 支付
• 有问题或想法？提交 issue 或发起讨论

贡献者

Star 历史记录

three.ws 的一部分

three.ws 是一个面向拥有 Solana 钱包的 3D AI Agent 的平台，提供虚拟形象、技能市场、x402 支付和七十多个 MCP 服务。@three-ws/onchain-agent-wallets 是其中的一个软件包。

• 文档站点：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 的生成镜像）
• Agent 可读取的摘要：llms.txt 和 AGENTS.md
• 问题与想法：https://github.com/nirholas/onchain-agent-wallets/issues