agentwallet

AgentWallet MCP 服务

面向 AI Agent 的免许可钱包基础设施。可在任意 EVM 链和 Solana 上创建钱包、签署交易并广播上链。内置防护机制。无需 KYC。唯一接受加密货币支付自身 API 费用的 AI Agent 钱包。

你的密钥可以保留在自己的机器上。 设置一个环境变量，所有签名都会在你自己的进程中完成。没有服务器能看到密钥，没有公司能冻结钱包；你可以阅读 src/local-wallet.ts，或在将 API 指向一个关闭的端口后运行服务，来验证这一点。

无需 KYC。无需 KYT。无需审批流程。无需交易监控。没人能封锁你的钱包。使用 USDC 在链上支付，无需信用卡。

两种模式

	本地（自托管）	托管（由服务方保管）
谁持有密钥	你，在自己的进程中	加密后存储在 AgentWallet 服务器上
设置	一个环境变量，无需账户	API 密钥
链	EVM + Solana	EVM + Solana
是否有人能冻结钱包	不能	能，这正是暂停功能的用途
支出防护	AGENTWALLET_MAX_TX_NATIVE、AGENTWALLET_MAX_TX_TOKEN、AGENTWALLET_MAX_TX_SOL、AGENTWALLET_MAX_AUTOPAY	服务端限额、暂停、速率限制
付费墙、用量、账单	也需要 API 密钥	已包含

随时运行 wallet_mode，服务会告诉你当前使用的模式，以及它控制的地址。

在一个变量中配置本地签名

{
  "mcpServers": {
    "agentwallet": {
      "command": "npx",
      "args": ["-y", "agentwallet-mcp"],
      "env": {
        "AGENTWALLET_PRIVATE_KEY": "0xyour_key",
        "AGENTWALLET_RPC_8453": "https://your-own-rpc",
        "AGENTWALLET_MAX_TX_NATIVE": "0.05"
      }
    }
  }
}

如果你希望将密钥保留在 shell 配置之外，也可以改用 AGENTWALLET_KEYFILE=/path/to/key（二选一：两者同时设置时，服务会拒绝启动）。密钥只读取一次，不会写入磁盘、记录到日志，也不会出现在错误消息中。

AGENTWALLET_RPC_<chainId>（或用于所有链的 AGENTWALLET_RPC_URL）指向你信任的端点（https；仅 localhost 上允许使用普通 http）。如果未设置，则会使用公共 RPC，而公共 RPC 可以看到你查询的地址。注册表之外代币的小数位数由该 RPC 提供，且最多接受 18 位；其他情况请用 AGENTWALLET_TOKEN_DECIMALS 固定设置。

AGENTWALLET_MAX_TX_NATIVE 是以原生代币为单位（ETH、MATIC 等）的单笔交易上限。在托管模式下，服务会强制执行限额；在本地模式下没有服务端，因此这些保护措施就是唯一的限制。请设置它们。

AGENTWALLET_MAX_TX_TOKEN 是 ERC-20 转账的对应上限，单位为代币的人类可读单位。如果你持有稳定币，也请设置此项。 原生代币上限无法监测代币转账：ERC-20 转账的 value = 0，金额位于 calldata 中，因此仅设置 AGENTWALLET_MAX_TX_NATIVE 无法限制 USDC 余额。AGENTWALLET_MAX_TX_TOKEN 会限制 transfer、transferFrom、approve、increaseAllowance、Permit2 approve，以及链自身包装原生代币合约上的 deposit() / withdraw(uint256)（因此 wrap_eth 和 unwrap_eth 在上限内仍可正常工作）；这些授权也会受限，因为不设上限的授权随时可能导致资金被掏空。设置上限时会拒绝 ERC-721 和 ERC-1155 calldata（setApprovalForAll、safeTransferFrom），因为无法为 NFT 定价；未设置上限时，这些调用会像任意金额的 ERC-20 转账一样放行，但操作员授权属于无限授权，默认情况下无论何时都会拒绝（参见 AGENTWALLET_ALLOW_UNLIMITED_APPROVAL）。设置上限时，发送到代币合约或 Permit2 的任何其他 calldata 都会被拒绝，因为保护措施无法为其定价；可通过设置 AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS=1 明确允许此类调用。increaseAllowance 会依据增加后的总额进行判断：它会先读取当前授权额度；如果无法读取，就会拒绝调用，因此多个合规的增额操作无法将常驻授权额度叠加到超过上限。发往其他合约（路由器、桥）的调用会放行，因为它们只能提取已由授权允许的金额；只有在能明确确认某合约拒绝 decimals() 时，它才会被视为“其他”合约，因此对异常或格式错误的回答，或无法访问的 RPC，都会导致拒绝，而非放行。小数位数会先从受信任的本地注册表解析，再读取代币自身的 decimals()；若两种方式都无法解析代币，则按 0 位小数处理，这是唯一不会造成保护失效开放的取值。对于注册表之外的代币，RPC 是小数位数的唯一来源；你无法控制的 RPC 可能会同时缩放金额和上限。请用 AGENTWALLET_TOKEN_DECIMALS 固定此类代币的设置（例如 8453:0x<token>=6），固定值会用于所有原本需要采用 RPC 回答的情况。

Solana 本地签名

"env": {
  "AGENTWALLET_SOLANA_KEY": "[12,34...]",
  "AGENTWALLET_SOLANA_RPC": "https://your-own-rpc",
  "AGENTWALLET_MAX_TX_SOL": "1",
  "AGENTWALLET_MAX_TX_TOKEN": "25"
}

支持你已有的任意格式：solana-keygen 的 id.json 数组、Phantom 导出的 base58 密钥，或 base64。也可以使用 AGENTWALLET_SOLANA_KEYFILE 指定文件。原生 SOL 和 SPL 代币转账都会在本地签名；如果收款方缺少关联代币账户，则会自动创建。

可设置任意一个密钥，也可以两个都设置。它们彼此独立：EVM 使用本地签名而 Solana 使用托管签名，或者反过来。

没有对应本地密钥的操作会被拒绝，不会悄悄转交给托管签名器。 如果你已配置 EVM 密钥，却在没有 Solana 密钥的情况下请求 Solana 转账，服务会停止并告知你缺少哪个变量。在你以为自己掌控资产的情况下，却悄悄将资金转到你不持有密钥的地址，这是此服务最不该做的事。

关于依赖树

本地签名使用 viem 处理 EVM，使用 @solana/web3.js 处理 Solana，并使用 bs58 解析密钥。SPL 指令是手动构建的，而不是使用 @solana/spl-token，因为该包会引入 bigint-buffer，而它存在一项高严重性缓冲区溢出安全公告。钱包没必要为了省下十几行指令编码代码而引入这个包。

截至 1.13.5，npm audit 未报告任何安全公告；package.json 中的覆盖项修复了 @solana/web3.js 的 jayson 依赖中的两项安全公告。更早的版本在 @modelcontextprotocol/sdk 的 HTTP 传输依赖中存在安全公告。本服务使用 stdio 通信，因此不会加载那段代码，而且本包无法修补该 SDK。欢迎自行运行审计。发布一个可供你检查的依赖树，正是我们的目的。

功能

• 40 个 MCP 工具：创建钱包、发送交易、授权代币、包装 ETH、转移 SPL 代币、查询报价、发现、支付和接受 x402 付款、验证托管模式等
• 支出策略：滚动计算的每日和每月预算、单个主机支出上限、主机和收款方名单、通过 MCP elicitation 获取人工批准，以及工具允许列表，全部保存在一个 JSON 文件中，并通过哈希链账本强制执行。密钥仍由你掌控，Agent 也无法超额支出。
• EVM + Solana：Ethereum、Base、Polygon、BSC、Arbitrum、Optimism、Avalanche、Zora、PulseChain、Solana，以及其他任何兼容 EVM 的链
• SOL + SPL 代币：原生 SOL 转账和 SPL 代币（USDC、USDT 等）转账，并自动创建账户
• 内置防护：在托管模式下，默认由服务端强制执行每日支出限额、Gas 价格保护、紧急暂停和速率限制。在本地模式下，你的保护措施是自己设置的单笔交易上限（AGENTWALLET_MAX_TX_NATIVE、AGENTWALLET_MAX_TX_TOKEN、AGENTWALLET_MAX_TX_SOL、AGENTWALLET_MAX_AUTOPAY）。无论采用哪种模式，都会启用 x402 重放保护和链上验证
• x402 付款：自动支付启用了 x402 的 API 费用，或在你自己的端点上接受 x402 付款（EVM 和 Solana）
• 自托管选项：使用本地模式运行，密钥绝不会离开你的设备。在托管模式下，密钥会在静态存储时加密，仅在签名期间解密，并随即从内存中清零。无论采用哪种模式，你都可以导出密钥并随时离开。
• 无需许可：无需 KYC。无需 KYT。无需身份验证。无需审批流程。没有合规审查门槛。注册、获取 API 密钥后即可立即开始交易。
• 30 秒即可完成设置：只需三行配置。无需安装 SDK。无需管理依赖项。

定价

• 每次操作 $0.00345
• 每月免费 6,000 次操作
• 每次 x402 验证 $0.0005
• 每月免费 1,000 次 x402 验证
• 通过 x402 使用 USDC 链上付款，无需信用卡
• 无月费、无套餐等级，按用量付费

竞品对比信息及其最近核实日期请见 hifriendbot.com/wallet/#pricing。这些信息放在那里而非此处，是因为已发布的 npm README 无法在他人调整价格时及时更正。

快速开始

前往 hifriendbot.com/wallet 获取免费的 API 密钥，无需信用卡、无需 KYC，也无需等待审批。

Claude Desktop / OpenClaw

添加到配置中：

{
  "mcpServers": {
    "agentwallet": {
      "command": "npx",
      "args": ["-y", "agentwallet-mcp"],
      "env": {
        "AGENTWALLET_USER": "your_username",
        "AGENTWALLET_PASS": "your_api_key",
        "AGENTWALLET_WALLET_ID": "1"
      }
    }
  }
}

AGENTWALLET_WALLET_ID 是可选项。设置此项即可启用 x402 自动付款：当你未绑定信用卡且超出免费额度时，MCP 服务会自动从此钱包支付操作费用，使用 USDC 付款。只有按量计费的路由（创建钱包、签名、发送）会以此方式付费，每小时最多 AGENTWALLET_MAX_AUTOPAY_PER_HOUR 次（默认值为 20），每笔自动付款都会在工具结果的 autopay_payment 字段中报告。其他任何路由返回的 402 都只会报告，不会自动付款。

自动付款安全上限。 AGENTWALLET_MAX_AUTOPAY（可选，默认值为 1）是单笔 x402 付款可授权的最高金额，以稳定币单位计：1 表示 1 美元。此上限仅适用于注册表中的稳定币（受支持链上的 USDC、USDT、USDbC、DAI，以及 Solana 上的 USDC 和 USDT）。如果付款要求使用链的原生资产或其他代币，系统会拒绝，因为以 ETH 计量的「1」价值数千美元；将此类资产添加到 AGENTWALLET_AUTOPAY_ASSETS（以逗号分隔的地址或铸币地址，或单词 native）即可允许使用，上限则按该资产自身的单位计算。超过上限的付款要求会被拒绝，不会执行付款，因此格式错误或遭篡改的付款要求无法掏空钱包。此自动付款路径仅结算 exact 要求；如果 API 提供 upto 报价，系统会在调用钱包前拒绝，因为预先支付使用量上限并不符合该报价的含义（请改用 pay_x402，它会为此签署 Permit2 授权）。该上限是运营者设定的上限：max_payment 参数可以降低单次调用的上限，但不能提高。只有确实需要支付更大金额时，才提高此变量的值（例如，设为 "5"，表示单次调用最多支付 5 USDC）。

Claude Code

claude mcp add agentwallet \
  -e AGENTWALLET_USER=your_username \
  -e AGENTWALLET_PASS=your_api_key \
  -e AGENTWALLET_WALLET_ID=1 \
  -- npx -y agentwallet-mcp

VS Code

添加到设置中：

{
  "mcp": {
    "servers": {
      "agentwallet": {
        "command": "npx",
        "args": ["-y", "agentwallet-mcp"],
        "env": {
          "AGENTWALLET_USER": "your_username",
          "AGENTWALLET_PASS": "your_api_key",
          "AGENTWALLET_WALLET_ID": "1"
        }
      }
    }
  }
}

工具

工具	描述
create_wallet	创建新的 EVM 或 Solana 钱包
list_wallets	列出你的所有钱包
get_wallet	根据 ID 获取钱包详情
get_balance	查询任意链上的原生代币余额
get_token_balance	查询 ERC-20 或 SPL 代币余额
get_token_info	获取 ERC-20 代币名称、符号和小数位数
transfer	发送原生代币（ETH、SOL、POL、BNB 等）
transfer_token	发送 ERC-20 或 SPL 代币（USDC、USDT 等）
send_transaction	签署并广播原始交易
sign_transaction	签署交易，但不广播
call_contract	只读合约调用（eth_call）
approve_token	授权 DeFi 使用 ERC-20 代币
get_allowance	查询 ERC-20 代币授权额度
wrap_eth	将原生代币包装为 WETH/WAVAX 等
unwrap_eth	将 WETH 解包回原生代币
pay_x402	支付 x402 账单（固定金额通过 EIP-3009 支付，最高不超过指定金额通过 Permit2 支付），超过上限的授权需另行批准
quote_x402	查询 x402 端点的收费，以及上限、策略和预算是否允许支付；不会签署任何内容
discover_x402	在公开的 x402 索引（Bazaar）中按主题查找收费的 x402 API
list_payments	查看账本中的支出及其结果，按时间从新到旧排列
export_receipts	将账本导出为 CSV 或 JSONL，用于费用记录
spend_policy	查看当前生效的策略、其 sha256、已用和剩余预算以及账本完整性
simulate_transaction	对 EVM 交易进行试运行：检查防护措施和策略、预估 Gas 和费用、查看返回数据；不会签署任何内容
check_approval	查看因 pay_x402 超出上限而创建的人类审批状态
approve_permit2	为 upto 端点向 Permit2 进行一次性代币授权
check_token_risk	查看代币的蜜罐、税费、所有者权限和持有者集中度风险标记
create_paywall	创建 x402 付费墙，以便对资源收费
list_paywalls	列出你的所有 x402 付费墙
get_paywall	根据 ID 获取付费墙详情
update_paywall	更新付费墙的定价、资源或状态
delete_paywall	删除付费墙
get_paywall_payments	查看付费墙的支付历史
get_x402_revenue	汇总所有付费墙的收入统计数据
wallet_mode	报告签名是在本地进行（自托管）还是由托管服务进行，以及当前使用的地址
export_wallet_key	了解如何导出托管钱包密钥并转为自托管
buy_verification_credits	使用链上的 USDC 购买 x402 验证额度
get_usage	查询你的月度用量和账单
get_chains	列出所有支持的链
pause_wallet	紧急暂停钱包
unpause_wallet	恢复已暂停的钱包
delete_wallet	删除钱包

支持的链

链	ID	原生代币	稳定币
Ethereum	1	ETH	USDC
Base	8453	ETH	USDC
Polygon	137	POL	USDC
BSC	56	BNB	USDT
Arbitrum	42161	ETH	USDC
Optimism	10	ETH	USDC
Avalanche	43114	AVAX	USDC
Zora	7777777	ETH	USDC
PulseChain	369	PLS	USDC
Solana	900	SOL	USDC
Solana Devnet	901	SOL	USDC

使用场景：GuessMarket

搭配 guessmarket-mcp，让你的 AI Agent 交易预测市场：

1. 在 Base 上创建钱包
2. 授权使用 USDC
3. 买入预测市场的 YES/NO 份额
4. 提供流动性并赚取交易手续费
5. 领取收益

所有操作都在链上完成。全部通过 MCP 完成。无需前端。

x402 支付

AgentWallet 按照规范定义的方式支持 x402 开放支付标准。当你的 AI Agent 访问一个返回 HTTP 402 的 API 时，pay_x402 会完成整个流程：

1. 获取 URL，并读取付款要求：v2 的 PAYMENT-REQUIRED 标头或 v1 的 JSON 正文。
2. 选择一个 exact 选项（可通过 prefer_chain 指定偏好）。
3. 为恰好对应的金额签署 EIP-3009 TransferWithAuthorization。不会广播任何交易，付款方也无需支付 Gas；端点的协调器会在链上完成结算。
4. 使用付款标头重试请求（v2 使用 PAYMENT-SIGNATURE，v1 使用 X-PAYMENT）。
5. 返回响应、结算回执（PAYMENT-RESPONSE / X-PAYMENT-RESPONSE），以及端点拒绝请求时在 retry_error 中提供的原因。

已通过 Coinbase 的公开协调器验证（v1 和 v2 载荷的 isValid: true），并在 Base 上的实时 x402 服务中测试。支持两种托管模式：本地密钥在进程内签名；托管钱包通过 POST /wallets/{id}/x402/authorize 签名。该专用端点只会对这一个结构签名，并执行与转账相同的暂停和代币上限检查。

pay_x402(
  url="https://api.example.com/premium-data",
  wallet_id=1,
  max_payment="1.00"
)

max_payment 可降低单次调用的上限，但不能提高上限：AGENTWALLET_MAX_AUTOPAY（默认值为 1）是运营方设置的上限；高于该值的 max_payment 会被忽略，并通过 max_payment_ignored 报告，因此恶意的 402 端点或遭提示词注入的 Agent 都无法授权超出运营方许可的金额。托管钱包只能通过所有者的电子邮件审批（见下文）突破此上限；本地模式则通过提高该变量来突破上限。在本地模式下，AGENTWALLET_MAX_TX_TOKEN 同样适用于授权，因为授权会由他人执行转账。无论端点要求的有效期多长，授权最长有效时间均为 AGENTWALLET_X402_MAX_TIMEOUT 秒（默认值为 3600）；在此时间窗口内，对相同端点、金额和收款方重复调用 pay_x402 时，会重新发送先前的签名，而不会再次签名（其 nonce 只能使用一次，因此，若服务器结算后仍未提供资源，就无法再次付款；传入 fresh_authorization=true 可强制生成新的授权）。显示的资产名称来自注册表或区块链，不会取自 402 正文。

方案。 优先使用 exact（EIP-3009，付款方无需支付 Gas），且 AgentWallet 所知的所有 EVM 链均支持此方案。upto（卖方按实际使用量结算的 Permit2 上限）会签署绑定到端点协调器的 PermitWitnessTransferFrom；每种代币都需要一次性调用 approve_permit2（或设置 AGENTWALLET_PERMIT2_AUTO_APPROVE=1）。如果 upto 选项缺少 extra.facilitatorAddress，则会拒绝该选项，绝不会改用预先转账。原生资产和 Solana 请求，以及 AgentWallet 自身的付费墙，均通过链上转账付款并以交易哈希作为证明，这是这些服务验证付款的方式。

超出上限的审批。 托管钱包的付款超出上限时，不一定会失败。启用 request_approval（默认开启；设置 AGENTWALLET_APPROVALS=0 可关闭）后，钱包所有者会收到一封包含批准和拒绝链接的电子邮件，pay_x402 会返回一个 approval_id，待 check_approval 显示已批准后，Agent 即可使用该 ID 重试。审批仅适用于一个钱包、链、资产、收款方和最高金额，有效期为 24 小时，且只能用于一次签名。本地模式没有审批渠道：环境中设置的上限就是策略，传入 approval_id 会被拒绝。

资产风险。 check_token_risk（以及每次 approve_token 的结果）都会报告 GoPlus Security 提供的蜜罐、税费、所有者权限、源码已验证、持有人集中度和流动性标记，并在链上进行后备检查。这些仅是供调用者权衡的警告，不会阻止操作。 证明。 真实结算记录列于 PAYMENTS.md；首笔是在 Base 上支付 0.02 USDC 的 exact 付款，手续费由 facilitator 支付。带有 Basescan 链接的相同列表可在 hifriendbot.com/wallet/payments 查看；从安装到完成真实结算的五分钟演示可在 hifriendbot.com/wallet/quickstart 查看。安全策略、固定披露信息和版本发布历史见：hifriendbot.com/security 和 hifriendbot.com/changelog。

通过 Claude 分三步支付任意 x402 API

1. 添加服务（使用快速入门中的任一代码片段）。自行托管：将 AGENTWALLET_PRIVATE_KEY 设置为持有 Base 上 USDC 的密钥。托管模式：使用 hifriendbot.com/wallet 提供的 AGENTWALLET_USER 和 AGENTWALLET_PASS。
2. 提出请求：“使用 pay_x402 向 https://api.ozdreamtools.de/api/holidays 发送 POST 请求，请求正文为 {"year":2026,"state":"BY"}，并将 max_payment 设为 0.05。”
3. 查看结果：payment_made: true、金额、payment_method，以及链上哈希 settlement.transaction。使用 exact 无需 ETH：端点的 facilitator 会支付手续费。

代币域。 EIP-712 域依次取自端点的 extra.name / extra.version、简短的 USDC 部署注册表，最后取自代币合约自身的 name() / version()。如果这些来源都无法提供信息，系统会拒绝付款，而不会猜测域后再签名。

委托付款方。 如果付款地址是 EIP-7702 委托账户，pay_x402 会通过 payer_delegation 报告相关信息（委托方以及其是否响应 ERC-1271）。不支持 ERC-1271 的委托方会被那些在恢复签名者前检查账户代码的 facilitator 拒绝，而它们返回的原因看起来像是签名错误；警告信息会指出真正原因。为确保结算可靠，请使用普通 EOA 付款。

x402 收款

AgentWallet 还支持收取 x402 付款。创建付费墙，将其指向任意资源，即可获得一个能自动向 Agent 收费的公开 URL：

create_paywall(
  wallet_id=1,
  name="Premium API",
  amount="0.01",
  token_name="USDC",
  token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  chain_id=8453,
  resource_url="https://your-api.com/data"
)

当 Agent 访问付费墙 URL 时：

1. 收到包含付款要求的 HTTP 402 响应
2. 使用 pay_x402（或任何兼容 x402 的客户端）在链上付款
3. 携带付款证明重试
4. 收到受保护的内容

链上验证可确保每笔付款都真实有效。重放保护可防止重复支出。收入追踪会显示付款人、金额和付款时间。每月提供 1,000 次免费验证，之后每次收费 $0.0005。具体费用对比请参阅定价对比。

对比

功能	Coinbase CDP	AgentWallet
设置时间	安装 SDK + 配置	3 行配置
审批流程	需要身份验证	无需审批，即时访问
需要 KYC	是	否
KYT / 交易监控	是	否
可以封锁你的钱包	是	否
内置防护机制	是（需要设置）	是（托管模式：默认启用；本地模式：由你设置环境变量上限）
每月免费操作次数	5,000	6,000
每次操作费用	$0.005	$0.00345
x402 验证费用	$0.001	$0.0005
每月免费 x402 验证次数	1,000	1,000
x402 收款（付费墙）	否	是
使用加密货币支付 API 费用	否（仅限信用卡）	是（通过 x402 使用 USDC）
支持的链	8 条 EVM 链 + Solana	任意 EVM 链 + Solana
代币工具	是	ERC-20 + SPL（34 个工具）
MCP 服务	是	是

使用加密货币支付，无需信用卡

AgentWallet 是唯一允许使用加密货币支付自身 API 费用的 AI Agent 钱包基础设施。所有竞争对手，包括 Coinbase CDP、Circle、MoonPay、Crossmint 和 Turnkey，都需要信用卡或按月开票。使用 AgentWallet，Agent 可以通过 x402 协议使用链上 USDC 支付操作费用。无需信用卡，无需发票，也无需账单门户。只需链上支付。

当 Agent 超出免费额度（每月 6,000 次操作），且未配置信用卡时，API 会返回包含 USDC 支付说明的 HTTP 402。Agent 在链上完成支付，携带支付凭证重试，然后操作即可执行。整个流程通过 MCP 服务全自动完成。

你也可以使用 buy_verification_credits 工具，通过 USDC 预购 x402 验证额度，让支付墙在每月免费的 1,000 次验证额度用尽后继续运行，无需信用卡。

内置防护机制

适用哪些防护机制，取决于密钥由谁持有。

托管模式（密钥由服务持有）：以下所有防护机制均默认启用，无需配置。

• 静态加密：私钥在存储前加密，且绝不会离开服务
• 内存清零：每次签名操作完成后，立即从内存中清除密钥
• 每日支出限额：为每个钱包设置每日美元支出上限，由服务在每笔交易中强制执行
• Gas 价格保护：当 Gas 价格飙升至安全阈值以上时，阻止交易
• 紧急暂停：一键立即冻结任意钱包或所有钱包
• 速率限制：限制每分钟的 API 请求数，防止滥用和暴力攻击

本地模式（密钥由你持有）：签名流程中不经过服务，因此服务端无法查看或阻止上述限制和暂停机制覆盖不到的本地签名交易；任何人（包括我们）都无法冻结本地钱包。你的保护措施是在签名前，由你自己的进程强制执行的单笔交易限额。请在为钱包注资前设置这些限额；未设置限额即表示不设上限。

• AGENTWALLET_MAX_TX_NATIVE：每笔交易的原生代币金额上限（ETH、MATIC 等）

• AGENTWALLET_MAX_FEE_NATIVE：单笔交易可消耗的最高手续费，即 gas x 每单位 gas 的最高费用，以原生代币计价（默认值为 0.01）。仅设置金额上限无法限制手续费：如果节点返回异常高的小费或 gas 估算值，符合金额上限的转账也可能将全部余额作为优先费消耗。调用方提供的 gas_limit / max_fee / priority_fee 会被采纳，但仍受此上限约束

• AGENTWALLET_MAX_TX_TOKEN：每笔 ERC-20 转账或授权的上限，以代币的人类可读单位计价

• AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS：设为 1，允许无法按代币上限定价的 calldata 调用代币合约或 Permit2（设置上限时默认拒绝）

• AGENTWALLET_ALLOW_UNLIMITED_APPROVAL：设为 1，在未设置支出策略时，允许无限 ERC-20 授权（approve_token 使用 "max"、approve_permit2 未指定金额）或 NFT 操作员授权（setApprovalForAll）（默认拒绝；在支出策略下始终拒绝）

• AGENTWALLET_TOKEN_DECIMALS：为注册表之外的代币固定小数位数（8453:0x<token>=6,<mint>=9）；金额和上限将使用固定值，而不是向 RPC 查询

• AGENTWALLET_MAX_TX_SOL：每笔原生 SOL 转账的上限（也计入 SPL 转账需创建收款方代币账户的租金）。此上限不适用于 SPL 代币金额：无论在 Solana 还是 EVM 上，SPL 代币金额都受 AGENTWALLET_MAX_TX_TOKEN 限制

• AGENTWALLET_MAX_AUTOPAY：每笔 x402 自动付款的稳定币上限（默认值为 1）；设置 AGENTWALLET_AUTOPAY_ASSETS 可允许使用原生代币或非稳定币资产；AGENTWALLET_X402_MAX_TIMEOUT 限制已签名授权的有效时长（默认 3600 秒）

• AGENTWALLET_SOLANA_RPC_<chainId>（或用于所有集群的 AGENTWALLET_SOLANA_RPC）：发送任何内容前，都会将 RPC 的 genesis hash 与 chain id 进行校验；EVM RPC 的 eth_chainId 也会进行相同校验，确保同一个 URL 不会悄然服务于与请求网络不同的网络

• AGENTWALLET_TOKEN_RISK=0：跳过 approve_token 执行的 GoPlus 查询（这是一个会暴露你即将授权哪个代币的第三方调用）

• AGENTWALLET_CHAIN_ID：调用未指定 EVM 链时使用的链（默认值为 8453）

• AGENTWALLET_LEGACY_PAYWALL_ORIGINS：以逗号分隔的 https 来源列表；这些来源的旧格式 402 可通过链上转账并以哈希证明的方式结算；其他所有主机都需要签名授权

• AGENTWALLET_POLICY：支出策略文件（见下文），用于限制总额、主机、收款方、链、资产和工具；AGENTWALLET_LEDGER 用于指定强制执行策略的账本

• AGENTWALLET_KEYFILE_PASSPHRASE 或 AGENTWALLET_KEYFILE_PASSPHRASE_FILE：用于打开加密密钥文件（见下文）

• AGENTWALLET_WEBHOOK_URL（https，或 localhost 上的 http）和 AGENTWALLET_WEBHOOK_SECRET：账本中的每一行都会以 JSON 形式通过 POST 发送；设置密钥后，消息会附带签名 X-AgentWallet-Signature: sha256=<hmac>；webhook 不会延迟或导致签名失败

每个 AGENTWALLET_* 变量都会在启动时进行校验：格式错误的上限会导致服务停止，而不会被视为“无限制”；无法识别的名称（例如拼错的上限变量）也会导致服务停止。wallet_mode 会报告每项保护措施及其解析后的值。工具参数严格校验：未知的参数名称（例如拼错的 max_payment）会导致错误，不会被静默忽略。pay_x402 会为每项资源签署一份有效授权；对于同一资源，若第一份授权尚未过期，后续不同的要求会被拒绝，除非传入 fresh_authorization。需要 Node.js 22.19 或更高版本。

支出策略：限制总额，而不只是单笔付款

单笔交易上限可以限制一份签名，却无法识别在上限为 1 时，第五百笔 0.99 付款已经是第五百笔。支出策略可以做到这一点。将 AGENTWALLET_POLICY 指向一个 JSON 文件：

{
  "version": 1,
  "name": "research agent",
  "budget": { "daily": "5", "monthly": "50" },
  "native_budget": { "8453": { "daily": "0.01" } },
  "hosts": { "allow": ["*.example.com", "api.ozdreamtools.de"], "deny": ["evil.example.com"] },
  "per_host": { "*.example.com": { "daily": "2", "per_payment": "0.25" } },
  "recipients": { "deny": ["0x0000000000000000000000000000000000000000"] },
  "chains": { "allow": [8453, 900] },
  "approval": { "above": "0.50", "max": "20" },
  "tools": { "allow": ["pay_x402", "quote_x402", "discover_x402", "get_balance", "list_payments", "spend_policy", "wallet_mode"] }
}

• budget：滚动美元预算（过去 24 小时、过去 30 天、累计），覆盖所有链，并计入 x402 支付、稳定币转账以及注册表中稳定币的授权。如果预算无法为某笔支出定价（代币不在注册表中），则只要设置了预算，就会拒绝该支出，除非 "unpriced_spends": "allow"。SPL 转账按铸币的自身小数位定价；如果 token_decimals 提示与铸币的小数位不一致，则会在发起任何请求之前拒绝。
• native_budget：按链分别设置，以该链自身的币种计价，并计入原生币转账以及发送到任何合约的原生币价值（wrap_eth、带有 value 和 calldata 的 send_transaction），包括通过代币转账或授权调用携带的价值（可支付代币合约会保留这笔价值，因此这是对该合约的第二笔支出）；在本地 Solana 模式下，还会计入 SPL 转账为创建收款方代币账户支付的租金（该账户归收款方所有，收款方可以关闭账户以取回 lamports；账本会将其记录为单独一笔、方法为 rent、收款方为该收款方的支出，且无需在 assets.allow 中为其列出 native）。
• 授权也是支出。 ERC-20 额度（approve_token、approve_permit2、increaseAllowance、approveAndCall、Permit2 approve，或通过 send_transaction 发送相同 calldata）决定了花费方日后可以取走的金额，因此在授予时就会计价、检查并在账本上预留；还会根据收款方列表检查花费方。无限额授权（2^128 个基本单位或更多）会被拒绝，因为任何预算都无法计算这类金额；请授予精确金额。NFT 操作者授权（setApprovalForAll、ERC-777 authorizeOperator）从设计上就是无上限的，也会以相同方式被拒绝；ERC-721 或 ERC-1155 转账则是向收款方转移集合资产，任何预算都无法为其定价，因此在美元预算下会被拒绝，除非 unpriced_spends 为 "allow"；无论哪种情况，都会检查收款方。向任何其他合约（路由器、桥）发起的零价值调用都不会预留资金：它只能提取先前已授权的金额。
• hosts、per_host：pay_x402 可以向哪些端点付款，以及每个主机每日、每月和每笔付款的额度。被拒绝的主机绝不会被联系，连报价也不会请求。主机按规范 DNS 名称匹配（小写，并移除根标签末尾的点），因此 api.example.com. 及其百分号编码形式，对所有列表和账本的每主机汇总都视为 api.example.com。
• recipients：资金可以流向何处（转账、x402 payTo、授权花费方、接收原生币价值的合约）。允许列表涵盖这些资金接收目的地；零价值调用所针对的合约（被授权的代币、路由器）则会根据拒绝列表和链列表进行检查。
• chains、assets：允许列表；资产条目可以限定为 "8453:0x..."，也可以是单词 native。
• approval：超过 above 后，每笔 x402 支付都会通过 elicitation 提交给 MCP 客户端上的用户（客户端会显示金额、代币、收款方和资源，并询问是否同意；声明不支持 elicitation 的客户端无法作答，因此支付会被拒绝）。在本地模式下，获准的回答可以允许支付超过单笔支付上限，但不超过 max。任何人的批准都不会提高预算上限。
• tools：模型可以看到的工具。仅付款方部署会公开七个工具；其余工具不会注册。wallet_mode 和 spend_policy 始终存在，以便操作者查看服务的运行状态。

遇到未知键时，服务会停止，因此拼错的 budgets 不会导致无限制运行。spend_policy 会报告文件、文件的 sha256（请与审核过的文件进行比对）、每项预算已花费和剩余的金额，以及策略隐藏了哪些工具。quote_x402 可以在签名任何内容之前，针对 URL 回答“是否会付款？”。 账本。 预算由仅追加、哈希链式 JSONL 文件强制执行（AGENTWALLET_LEDGER、策略中的 ledger，或者在预算需要账本时，使用策略文件旁的 agentwallet-ledger.jsonl）。签名生成前，支出会先在账本中预留；如果签名失败，后续记录会将预留作废；随后，端点或链的响应会记入账本。对于可能已经发出的支出（例如，字节已离开本地但广播失败，或托管请求已被 API 主机接收后又丢弃），会继续计为 unknown，而不会作废；在任何内容离开此进程之前发生的失败（包括策略拒绝或本地模式拒绝）始终会作废，绝不会占用预算。每次读取都会验证账本的哈希链；如果账本未通过验证，在操作员检查之前，所有支出都会被拒绝。多个 agentwallet-mcp 进程可以共用一个账本（例如，两个 MCP 客户端使用同一个钱包）：每次检查前都会重新读取文件，并且检查和追加步骤会跨进程持有独占锁文件（<ledger>.lock），因此无论有多少进程执行预算控制，预算都只有一份；超过 30 秒的锁会被视为由已终止的进程遗留。尚未广播的已签名交易（sign_transaction）也会像发送交易一样预留并计入预算，因为持有它的人可以广播交易。一次调用如果会转移两项资产（例如，代币转账同时携带原生代币），就会依次生成两条记录；如果其中任一项被拒绝，两项预留都会一并释放。list_payments 会读取账本，export_receipts 会将其导出为 CSV 或 JSONL，而每条写入记录都会发送到 AGENTWALLET_WEBHOOK_URL。

加密密钥文件

Shell 配置或文件中的明文密钥，任何能读取磁盘的对象都能访问。请将其加密：

npx agentwallet-mcp encrypt-keyfile ./plain.key ./agent.keyfile

密码短语会在终端中提示输入（脚本化使用时，也可以从 AGENTWALLET_KEYFILE_PASSPHRASE 获取）；scrypt 会派生密钥，AES-256-GCM 会加密密钥材料，全程使用 Node 自带的 crypto，不会引入新依赖。将 AGENTWALLET_KEYFILE 或 AGENTWALLET_SOLANA_KEYFILE 指向生成的文件，设置 AGENTWALLET_KEYFILE_PASSPHRASE 或 AGENTWALLET_KEYFILE_PASSPHRASE_FILE，通过 wallet_mode 确认显示的是同一地址，然后删除明文密钥。

无论哪种模式，对于通过托管 API 使用的 x402 付费墙：

• 防重放保护：每笔 x402 支付都会在链上验证，并进行唯一交易跟踪
• 链上验证：直接在区块链上验证 x402 支付，并使用 finalized 确认级别

漏洞赏金计划：负责任地披露漏洞，可获 50 至 500 美元奖励（详情）。

链接

• 网站： hifriendbot.com/wallet
• npm： agentwallet-mcp
• 安全： [email protected]，策略和披露历史记录见 SECURITY.md

安全性

pay_x402 会在每次发送请求前以及每次重定向跳转时再次验证目标 URL。IP 字面量会经过规范化处理（包括 [::ffff:127.0.0.1] 这类 IPv4 映射 IPv6 地址），主机名也会经过解析；环回、私有、链路本地、运营商级 NAT、多播和云元数据目标均会被拒绝。

验证和连接使用同一份 DNS 解析结果。每次跳转只解析一次，套接字会固定到该结果中的一个地址，因此主机名无法在验证时解析到公网地址、在连接时却解析到私有地址。主机名仍用于 Host 标头，以及 TLS SNI 和证书验证，因此合法端点不会察觉地址固定。

凭据只会发送到最初提供它们的源。如果端点将 pay_x402 重定向到不同源，调用方提供的 Authorization、Cookie 和 X-PAYMENT 标头以及所有其他自定义标头，都会在下一跳之前被移除；只有内容协商标头（Accept、Accept-Language、Accept-Encoding、User-Agent、Content-Type）会保留。如果重定向将 POST 转为 GET，正文标头也会一并移除。同源重定向会保留所有内容，与浏览器的行为相同。

请将安全问题私下发送至 [email protected]。

许可证

MIT