agentpay

代表你的人从真实的网站购买东西。当您需要购买产品、完成结帐、在线订购商品或提议购买以供人工批准时使用。处理任何商家网站上的加密凭证存储、加密购买指令和无头浏览器结帐。代理人永远不会看到该卡。

# AgentPay — Secure Checkout for AI Agents

AgentPay lets you buy things from real merchant websites without ever seeing your human's payment credentials. Credentials stay encrypted on the human's machine. You propose purchases; your human approves cryptographically.

## References

- `references/cli-reference.md` — All CLI commands with examples
- `references/workflow.md` — Step-by-step purchase workflow and error handling

## Setup (one-time, human does this)

```bash
npx agentpay setup
```

The human enters their card details and sets a passphrase. Takes ~2 minutes. After this, the agent can propose purchases.

To set spending limits:

```bash
npx agentpay budget --set 500 --limit-per-tx 100
```

## Core Workflow

### 1. Propose a purchase

```bash
npx agentpay buy \
  --merchant "Amazon" \
  --description "Wireless keyboard, Logitech K380" \
  --url "https://www.amazon.com/dp/B0148NPH9I" \
  --amount "39.99"
```

This creates a pending purchase mandate. The human must approve it.

### 2. Human approves

```bash
npx agentpay pending     # list pending purchases
npx agentpay approve <txId>
```

Once approved, the headless browser handles checkout automatically. The agent never sees the card number — credentials are injected directly into the page from the encrypted vault.

### 3. Check status

```bash
npx agentpay status      # wallet status + recent transactions
npx agentpay history     # full transaction log
```

## MCP Server

AgentPay includes a built-in MCP server for direct tool integration:

```bash
npx agentpay mcp         # stdio transport (default)
npx agentpay mcp --http  # HTTP transport
```

This exposes AgentPay operations as MCP tools that any compatible agent can call directly.

## Quick Actions

| Task | Command |
|------|---------|
| Buy something | `npx agentpay buy --merchant "Store" --description "Item" --url "https://..." --amount "29.99"` |
| Check pending | `npx agentpay pending` |
| View budget | `npx agentpay budget` |
| Transaction history | `npx agentpay history` |
| Open dashboard | `npx agentpay dashboard` |

## Important Rules

- **Never** attempt to read, extract, or log payment credentials from the vault
- **Always** include `--merchant`, `--description`, and `--url` when proposing a purchase
- **Always** tell your human what you want to buy and why before proposing
- If a checkout fails, check `npx agentpay status` for error details — do not retry without telling the human
- Respect budget limits. If a purchase exceeds the per-transaction limit, inform the human instead of splitting into multiple transactions

## Ideas to Try

- "Order me a new phone charger under $20 from Amazon"
- "Restock my usual coffee beans from the same store as last time"
- "Find the cheapest flight to Madrid and book it for me"
- "Buy the textbook I need for next semester"
- "Subscribe me to that newsletter we were looking at"

---

## 中文说明

# AgentPay — 面向 AI 代理的安全结账

AgentPay 让你能够在真实的商家网站上购物，而无需看到你主人的支付凭证。凭证以加密形式保留在主人的机器上。你提出购买建议；你的主人以加密方式批准。

## 参考资料

- `references/cli-reference.md` — 所有 CLI 命令及示例
- `references/workflow.md` — 分步购买工作流与错误处理

## 设置（一次性，由主人完成）

```bash
npx agentpay setup
```

主人输入其卡片详情并设置一个口令。大约需要 2 分钟。此后，代理即可提出购买建议。

设置消费额度：

```bash
npx agentpay budget --set 500 --limit-per-tx 100
```

## 核心工作流

### 1. 提出购买建议

```bash
npx agentpay buy \
  --merchant "Amazon" \
  --description "Wireless keyboard, Logitech K380" \
  --url "https://www.amazon.com/dp/B0148NPH9I" \
  --amount "39.99"
```

这会创建一个待处理的购买授权。主人必须批准它。

### 2. 主人批准

```bash
npx agentpay pending     # list pending purchases
npx agentpay approve <txId>
```

一旦获批，无头浏览器便会自动处理结账。代理永远看不到卡号——凭证会直接从加密保险库注入到页面中。

### 3. 查看状态

```bash
npx agentpay status      # wallet status + recent transactions
npx agentpay history     # full transaction log
```

## MCP 服务器

AgentPay 内置一个 MCP 服务器，用于直接的工具集成：

```bash
npx agentpay mcp         # stdio transport (default)
npx agentpay mcp --http  # HTTP transport
```

这会将 AgentPay 操作暴露为 MCP 工具，任何兼容的代理都可以直接调用。

## 快捷操作

| 任务 | 命令 |
|------|------|
| 购买物品 | `npx agentpay buy --merchant "Store" --description "Item" --url "https://..." --amount "29.99"` |
| 查看待处理 | `npx agentpay pending` |
| 查看预算 | `npx agentpay budget` |
| 交易历史 | `npx agentpay history` |
| 打开面板 | `npx agentpay dashboard` |

## 重要规则

- **绝不**尝试从保险库读取、提取或记录支付凭证
- 提出购买建议时**务必**包含 `--merchant`、`--description` 和 `--url`
- 在提出建议之前，**务必**告知你的主人你想购买什么以及原因
- 如果结账失败，请查看 `npx agentpay status` 获取错误详情——未告知主人前不要重试
- 尊重预算额度。如果某笔购买超过单笔交易上限，请告知主人，而不要拆分成多笔交易

## 可尝试的点子

- "Order me a new phone charger under $20 from Amazon"
- "Restock my usual coffee beans from the same store as last time"
- "Find the cheapest flight to Madrid and book it for me"
- "Buy the textbook I need for next semester"
- "Subscribe me to that newsletter we were looking at"