Agent Wallet

面向 AI Agent 的受控支付与资金治理系统：Agent 可以提出消费意图，并在用户设定的预算、权限与审批规则内调用支付宝、Cloudflare Wallets 等真实支付能力。

当前 V0.1 只运行虚拟余额和审批账本，不连接真实银行卡、支付账户或支付平台。虚拟账本是支付执行前的安全控制层原型，不是产品终点。

产品愿景

Agent Wallet 的最终目标不是记账，而是让 Agent 能够安全地花钱。

系统在 Agent 与支付宝等真实支付渠道之间建立一层可验证、可撤销、可审计的授权边界：

Agent 消费意图 → 策略检查 → 必要时用户审批 → 支付适配器 → 回执核验与审计

未来可通过统一的 Payment Adapter 接入支付 API、测试网支付协议或 Agent 专用钱包。候选方向包括 Cloudflare Wallets / Virtual Wallets 与 x402；具体接入以服务正式开放范围、地区资格和安全评估为准。

核心原则：

• Agent 不直接持有用户的主账户凭据。
• 用户可以设置周期预算、单笔上限、商户或用途白名单。
• 高风险、超额度和异常频率交易必须暂停并请求人工确认。
• 支付请求使用幂等键，防止重试造成重复扣款。
• 支付结果以提供方回执为准，并与本地账本自动对账。
• 用户可以随时冻结授权、撤销支付适配器或关闭 Agent 支付能力。

计划中的真实支付路径

支付路径	Agent 能做什么	用户如何控制	实现状态
支付宝网页 / 手机网站支付	根据任务生成订单与支付跳转链接	支付前审批，最终付款在支付宝完成	可使用开放平台沙箱验证
支付宝当面付	生成订单二维码并跟踪支付结果	用户扫码确认，服务端验签和对账	可使用 alipay.trade.precreate 验证
支付宝签约扣款	在已签约的特定场景中发起扣款	用户先签约，可解约；同时受本系统限额与异常拦截	需要商家资质、产品准入与合规评估
Cloudflare Virtual Wallets / x402	自动购买 API、MCP 工具、数据或内容	Account Wallet 分配额度、白名单和单笔上限	等待相关生产能力正式开放

支付宝接入的首个可运行版本将采用开放平台沙箱：Agent 先形成购买意图，策略引擎检查预算，必要时请求用户审批；通过后由后端创建支付宝订单，接收异步通知并主动查询交易结果，最后将真实结果回写本地账本。私钥只保存在服务端，前端和 Agent 均不接触支付凭据。

• 支付宝电脑网站支付快速接入
• 支付宝手机网站支付快速接入
• 支付宝当面付预创建接口
• 支付宝商家扣款产品介绍

迭代路线

阶段	状态	目标
V0.1	已实现	虚拟余额、申请审批、流水、审计与安全登录
V0.2	计划中	Agent API / MCP、周期预算、单笔限额、白名单与幂等控制
V0.3	计划中	Payment Adapter 抽象层；接入支付宝开放平台沙箱，完成订单、回调验签、查询、退款与对账
V0.4	评估后实施	接入符合资质与场景要求的支付宝正式能力，以及可用的 Cloudflare Virtual Wallets / x402 支付；增加冻结与异常检测

Cloudflare 于 2026 年公布的 Wallets 设计包含供人类管理资金的 Account Wallets，以及受额度、白名单和单笔上限约束的 Agent Virtual Wallets；其公告同时说明完整支付能力将逐步开放。因此，本项目目前将 Cloudflare Wallets 视为候选适配器，而不假设相关生产 API 已经可用。

• Cloudflare Wallets 官方公告
• Cloudflare x402 与 Agents SDK 官方说明

核心流程

1. 用户为 Agent 发放虚拟工资。
2. Agent 提交购买申请，填写用途、金额和理由。
3. 用户使用审批 PIN 批准或拒绝。
4. 申请获批后才从虚拟余额扣款。
5. 所有状态变化写入审计日志。

功能

• 虚拟余额与工资入账
• Agent 消费申请
• 用户审批、拒绝与退款
• 余额不足保护
• 交易流水和追加式审计记录
• SQLite 持久化
• PIN 登录与服务端会话
• 三套可切换界面主题
• Docker Compose 部署

技术栈

• Python 3.11+
• Flask
• SQLite
• Gunicorn
• HTML / CSS / JavaScript
• Docker Compose
• Nginx

安全边界

• 不保存银行卡、支付密码、验证码或支付平台令牌。
• 金额使用整数分存储，避免浮点误差。
• 所有 API 均要求服务端认证。
• 审批操作必须校验用户 PIN。
• 禁止透支，每次状态变化都会写入审计记录。
• .env 和数据库文件已加入 .gitignore，请勿提交真实配置。
• 公网部署时应放在 HTTPS 反向代理之后。

快速启动（Docker）

复制环境变量模板，并将其中的占位值替换为本机生成的随机值：

cp .env.example .env
docker compose up -d --build
curl http://127.0.0.1:18120/health

服务仅绑定到 127.0.0.1:18120。仓库中的 Nginx 文件使用 wallet.example.com 作为示例域名，部署时请替换为自己的域名。

本地开发（Windows PowerShell）

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

$env:WALLET_DB_PATH = ".\wallet.db"
$env:WALLET_API_TOKEN = "replace-with-a-long-random-token"
$pin = "123456"
$pinBytes = [Text.Encoding]::UTF8.GetBytes($pin)
$pinHash = [Security.Cryptography.SHA256]::HashData($pinBytes)
$env:WALLET_APPROVAL_PIN_SHA256 = [Convert]::ToHexString($pinHash).ToLower()
$env:WALLET_SESSION_SECRET = "replace-with-another-long-random-secret"
$env:WALLET_COOKIE_SECURE = "false"

python app.py

打开 http://127.0.0.1:8080，使用上面 $pin 设置的六位 PIN 登录。WALLET_COOKIE_SECURE=false 仅用于本机 HTTP 演示；公网部署必须保持为 true 并启用 HTTPS。

API

每个 /api/* 请求都需要：

Authorization: Bearer <WALLET_API_TOKEN>

主要接口：

• GET /api/wallet
• GET /api/transactions
• GET /api/requests
• POST /api/salary
• POST /api/requests
• POST /api/requests/:id/approve
• POST /api/requests/:id/reject
• POST /api/refunds
• GET /api/audit

所有金额均使用整数分（amount_cents）表示。

License

Copyright © 2026 7k777. All rights reserved. 本仓库公开源码主要用于查看、学习与评估，并非以开源许可证发布。允许在署名 7k777 的前提下进行教育或研究性质的引用与讨论；除法律另有允许外，未经许可不得复制实质性源码、修改后发布、再分发、商业化或将衍生/实质复制版本部署为产品或服务。详见 LICENSE。