Skill: kar69-96/agentpay (version 0.2.0)

--- name: agentpay description: "Buy things from real websites on behalf of your human. Use when you need to purchase a product, complete a checkout, order something online, or propose a purchase for human approval. Handles encrypted credential storage, cryptographic purchase mandates, and headless browser checkout on any merchant site. The agent never sees the card." metadata: {"openclaw":{"emoji":"💳","requires":{"anyBins":["agentpay","npx"]},"install":[{"id":"npm","kind":"node","package":"agentpay","bins":["agentpay"],"label":"Install AgentPay SDK"}]}} --- # 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"

path: references/cli-reference.md
content: # AgentPay CLI Reference

## Commands

### `agentpay setup`
Interactive setup wizard. Human enters payment credentials, sets passphrase. Creates encrypted vault at `~/.agentpay/vault.enc`.

### `agentpay budget [options]`
View or configure spending limits.

```bash
agentpay budget                        # view current budget
agentpay budget --set 500              # set total budget to $500
agentpay budget --limit-per-tx 100     # max $100 per transaction
```

### `agentpay buy [options]`
Propose, approve, and execute a purchase.

**Required flags:**
- `--merchant <name>` — merchant name (e.g. "Amazon", "Best Buy")
- `--description <desc>` — what you're buying
- `--url <url>` — product or checkout URL

**Optional flags:**
- `--amount <amount>` — purchase amount (auto-detected from page if omitted)
- `--pickup` — select in-store pickup if available

```bash
agentpay buy \
  --merchant "Amazon" \
  --description "USB-C cable, 6ft" \
  --url "https://www.amazon.com/dp/B08..." \
  --amount "12.99"
```

### `agentpay pending`
List all pending purchase proposals awaiting human approval.

### `agentpay approve <txId>`
Approve a pending purchase. Triggers headless browser checkout.

### `agentpay reject <txId> [options]`
Reject a pending purchase.

```bash
agentpay reject tx_abc123 --reason "too expensive"
```

### `agentpay status`
Show wallet status: budget remaining, recent transactions, vault health.

### `agentpay history`
Full transaction history with timestamps, amounts, merchants, and status.

### `agentpay qr [options]`
Display QR code for web-based setup (alternative to CLI setup).

```bash
agentpay qr --budget 200 --message "Scan to set up AgentPay"
```

### `agentpay dashboard [options]`
Open web dashboard for managing AgentPay.

```bash
agentpay dashboard --port 3141
```

### `agentpay mcp [options]`
Start MCP server for direct agent integration.

```bash
agentpay mcp             # stdio transport
agentpay mcp --http      # HTTP transport
```

### `agentpay reset`
Delete all AgentPay data. **Destructive — requires confirmation.**


path: references/workflow.md
content: # AgentPay Purchase Workflow

## Full Purchase Flow

```
Agent finds product → Agent proposes purchase (buy command)
→ Human reviews pending mandate → Human approves (approve command)
→ Headless browser opens merchant site → Navigates to product
→ Adds to cart → Fills checkout form → Injects credentials from vault
→ Submits order → Captures confirmation → Logs receipt
```

## Step-by-step

### 1. Agent proposes
The agent runs `agentpay buy` with merchant, description, URL, and amount. This creates a **purchase mandate** — a structured record of what the agent wants to buy.

### 2. Human reviews
The human runs `agentpay pending` to see all proposals. Each shows: merchant, item, amount, URL, timestamp, and the agent that proposed it.

### 3. Human approves
The human runs `agentpay approve <txId>`. This cryptographically signs the mandate with Ed25519, binding the approval to the specific purchase details.

### 4. Checkout executes
A headless browser (Stagehand/Browserbase):
1. Navigates to the merchant URL
2. Handles product selection and cart
3. Fills shipping/contact information
4. Injects payment credentials from the encrypted vault
5. Submits the order
6. Captures confirmation details

**The raw card number exists in the browser DOM only during form submission. Recording is disabled during credential injection.**

### 5. Receipt logged
A cryptographic receipt is written to disk: merchant, amount, items, timestamp, confirmation number, human signature. This survives context loss and reboots.

## Error Handling

| Error | Cause | Recovery |
|-------|-------|----------|
| Vault locked | Wrong passphrase or vault not set up | Human runs `agentpay setup` |
| Budget exceeded | Purchase exceeds remaining budget | Inform human, ask to increase budget |
| Per-tx limit exceeded | Single purchase too large | Inform human, ask to raise limit |
| Checkout failed | Bot detection, page changed, timeout | Check `agentpay status`, report error to human |
| Mandate expired | Human didn't approve in time | Re-propose the purchase |
| Merchant unavailable | Site down or URL invalid | Verify URL, try again later |

## Security Model

- **AES-256-GCM** encrypted vault — credentials at rest
- **Ed25519** signed mandates — human approval is cryptographic, not just "yes"
- **Local-first** — no servers, no cloud, nothing leaves the machine
- **Audit trail** — every transaction logged with verifiable receipts
- **Spending limits** — budget cap and per-transaction cap
- **Zero-knowledge agent** — the agent never sees raw credentials


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)