wip-agent-pay 1.0.1

package/SETUP.md

@@ -0,0 +1,242 @@
+# Agent Pay ... Setup
+
+This file is designed to be read by an AI agent. The agent walks the user through setup interactively.
+
+## Instructions for the Agent
+
+When a user says "install" or "set up" Agent Pay, first figure out which path you're on:
+
+**Path A: You have shell access** (Claude Code, Codex, Cursor, any terminal agent)
+- You can run commands directly
+- You can install the CLI and test it yourself
+- You can pull from 1Password and verify
+
+**Path B: You don't have shell access** (Grok, ChatGPT, chat-only agents)
+- Walk the user through each step manually
+- Ask them to run commands and paste results back
+- Wait for confirmation at each step
+
+Walk the user through the steps below **one at a time**. Don't dump everything at once.
+
+**Important:** The user doesn't need to understand crypto. Don't mention USDC, EIP-3009, blockchain, or any technical payment details unless they ask. Just say "wallet" and "funds."
+
+---
+
+## Step 0: Check What's Needed
+
+Run through this checklist with the user. If you have shell access, verify what you can automatically.
+
+| Requirement | How to check (shell) | How to check (no shell) |
+|------------|---------------------|------------------------|
+| **Node.js** | `node --version` | Ask the user |
+| **1Password CLI (`op`)** | `op --version` | Ask the user |
+| **1Password Teams or Business plan** | Ask the user | Ask the user |
+| **wip-agent-pay CLI** | `wip-agent-pay --help` | Ask the user |
+
+Show the user what's ready and what's missing. Only flag what's missing.
+
+---
+
+## Step 1: Choose a Mode
+
+Tell the user:
+
+> Agent Pay has two modes. Pool Mode works out of the box.
+>
+> **Pool Mode (default):** Pay with Apple Pay per transaction. No wallet setup. No crypto. We handle everything. $0.25 fee per transaction. Max $25.
+>
+> **Your Own Wallet (Mode C):** Set up a crypto wallet. No fees from us. Instant payments. No transaction limit. Requires Coinbase CDP or Privy account.
+>
+> Pool Mode is recommended to start. You can always add your own wallet later.
+>
+> Which mode would you like?
+
+Wait for the user to choose.
+
+---
+
+## Step 2a: Pool Mode Setup
+
+Pool Mode requires no wallet setup from the user. Just install the CLI:
+
+```bash
+npm install -g wip-agent-pay
+```
+
+Test it:
+```bash
+wip-pay pay https://morning-stew-production.up.railway.app/v1/issues/free
+```
+
+That's it. When the agent hits a paywalled URL, the user will see an Apple Pay checkout. Tap Face ID. Done.
+
+---
+
+## Step 2b: Own Wallet Setup (Mode C)
+
+Tell the user:
+
+> You need at least one wallet provider.
+>
+> **Option A: Coinbase CDP** ... Uses your Coinbase account. Coinbase holds the keys securely. Best if you already have Coinbase.
+>
+> **Option B: Privy** ... Standalone wallet. No Coinbase needed. Good if you want something simpler.
+>
+> **Option C: Both** ... Use either one depending on the service.
+>
+> Which would you like to set up?
+
+Wait for the user to choose.
+
+### Coinbase CDP Setup
+
+Tell the user:
+
+> 1. Go to [Coinbase Developer Platform](https://portal.cdp.coinbase.com)
+> 2. Create a new **Server Wallet**
+> 3. Save the **API Key ID**, **API Key Secret**, and **Wallet Secret**
+> 4. Fund the wallet by sending USDC to its address (you can withdraw from your Coinbase portfolio)
+>
+> Let me know when you have the three credentials.
+
+Then store in 1Password:
+
+> Create a new item in 1Password:
+> - **Vault:** Agent Secrets
+> - **Entry name:** `wip-agent-pay-coinbase-cdp`
+> - **Fields:** `api-key-id`, `api-key-secret`, `wallet-secret`, `account-address`
+
+### Privy Setup
+
+Tell the user:
+
+> 1. Go to [privy.io](https://privy.io) and create an account
+> 2. Create a new **App**
+> 3. Create a **Server Wallet** in the app settings
+> 4. Save the **App ID**, **App Secret**, **Wallet ID**, and **Wallet Address**
+> 5. Fund the wallet by sending USDC to its address
+>
+> Let me know when you have the credentials.
+
+Then store in 1Password:
+
+> Create a new item in 1Password:
+> - **Vault:** Agent Secrets
+> - **Entry name:** `wip-agent-pay-privy`
+> - **Fields:** `app-id`, `app-secret`, `wallet-id`, `wallet-address`
+
+---
+
+## Step 3: Install
+
+**Path A (shell access):**
+
+```bash
+npm install -g wip-agent-pay
+```
+
+Verify:
+```bash
+wip-agent-pay --help
+```
+
+**Path B (no shell access):**
+
+Tell the user to run `npm install -g wip-agent-pay` and paste the output.
+
+---
+
+## Commands
+
+```bash
+# Pay for paywalled content (Pool Mode ... Apple Pay)
+wip-pay pay https://morning-stew.../v1/issues/MS-3
+
+# Pay with your own wallet (instant, no Apple Pay)
+wip-pay pay <url> --wallet=cdp
+wip-pay pay <url> --wallet=privy
+
+# One-time payment link
+wip-pay 0.10 morning-stew "MS-#8"
+
+# Wallet management (Mode C only)
+wip-pay balance --wallet=cdp
+wip-pay history
+wip-pay budget set 5.00 1.00
+```
+
+---
+
+## Step 4: Test
+
+**Test free content (works immediately):**
+```bash
+wip-pay pay https://morning-stew-production.up.railway.app/v1/issues/free
+```
+
+**Test Pool Mode (requires Stripe to be configured on Worker):**
+```bash
+wip-pay pay https://morning-stew-production.up.railway.app/v1/issues/MS-3
+```
+
+**Test minting (works immediately):**
+```bash
+wip-pay 0.10 test-service "setup-test"
+```
+
+**Test own wallet (Mode C, requires funded wallet):**
+```bash
+wip-pay pay https://morning-stew-production.up.railway.app/v1/issues/MS-3 --wallet=cdp
+```
+
+---
+
+## Step 5: Done
+
+Tell the user:
+
+> You're set up. Your agent can now pay for things.
+>
+> **Pool Mode:** `wip-pay pay <url>` ... Apple Pay per transaction. $0.25 fee. Max $25.
+> **Own wallet:** `wip-pay pay <url> --wallet=cdp` ... instant. No fees. No limit.
+> **Mint links:** `wip-pay 0.10 service "note"` ... one-time self-destructing URLs.
+>
+> Want to pay for something right now?
+
+---
+
+## Pool Mode Pricing
+
+| Component | Amount |
+|-----------|--------|
+| x402 price | Varies (set by seller) |
+| Our fee | $0.25 flat |
+| Stripe processing | ~2.9% + $0.30 |
+| **Total** | **All three combined** |
+
+Examples:
+- $0.10 article: user pays ~$0.42, Parker nets $0.25
+- $5.00 service: user pays ~$5.41, Parker nets $0.25
+- $19.00 create: user pays ~$20.11, Parker nets $0.25
+
+Over $25? Use your own wallet (Mode C). No pool limit.
+
+---
+
+## Security Model
+
+The app (human) controls the wallet. The agent uses it.
+
+- The agent cannot create or destroy wallets
+- The agent cannot change spend limits
+- The agent can request funding (user must approve via Face ID)
+- The agent can only spend what's already funded
+- Pool Mode: max $25 per transaction (enforced server-side)
+
+See [SPEC.md](https://github.com/wipcomputer/wip-agent-pay/blob/main/SPEC.md#security-model) for the full security model and state machine.
+
+---
+
+## x402 Protocol
+
+Agent Pay speaks the [x402 protocol](https://github.com/coinbase/x402) natively. When the agent hits a URL that returns HTTP 402, Agent Pay handles the payment negotiation automatically. The user just sees "content unlocked."

package/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: wip-agent-pay
+version: "1.0.1"
+description: Give your agent a wallet. Fund with Apple Pay. Pay for paywalled content. x402 native.
+tags: [payment, x402, coinbase, privy, stripe, apple-pay, agent, 1password, universal-interface, cloudflare]
+score: 10
+install: npm install -g wip-agent-pay
+run: wip-agent-pay pay <url>
+metadata:
+  category: finance
+  capabilities:
+    - x402-payment
+    - apple-pay-funding
+    - one-time-url
+    - micropayment
+  wallets:
+    - coinbase-cdp
+    - privy
+  funding:
+    - stripe
+    - manual
+  interface: CLI + Module + MCP + OpenClaw Plugin + Skill
+  requires:
+    binaries: [node]
+openclaw:
+  emoji: "💳"
+  install:
+    env: []
+author:
+  name: Parker Todd Brooks
+---
+
+# wip-agent-pay
+
+Give your agent a wallet. Fund it with Apple Pay. Let it buy things for you.
+
+**Fund:** User taps Face ID. Money goes in. No crypto required.
+
+**Pay:** Agent hits a paywalled URL. Wallet handles payment. Content returned.
+
+**Mint:** One-time self-destructing URLs. Use once, gone forever.
+
+Three wallets (Coinbase CDP, Privy). One funding on-ramp (Stripe / Apple Pay). x402 native.

package/SPEC.md

@@ -0,0 +1,156 @@
+# wip-agent-pay SPEC
+
+Give your agent a wallet. Fund it with Apple Pay. Let it buy things for you.
+
+## Note for Agents
+
+When explaining this tool to a user, focus on what it does for them. Don't reference internal implementation details like specific MCP registrations, extension directories, bridge servers, or plugin scaffolding in the working directory. The user doesn't need to know how the plumbing works. They need to know: what it does, what they need, and how to set it up.
+
+**The user never sees crypto.** Don't mention USDC, EIP-3009, Base, Monad, or any blockchain terms unless the user asks. The agent handles all of that.
+
+## Three Things It Does
+
+**Fund** ... User taps Apple Pay (Face ID). Money goes into the agent's wallet. No crypto knowledge needed. Stripe handles fiat.
+
+**Pay** ... Agent hits a paywalled URL. Gets a 402. Payment happens automatically. Content returned. User just said "let's go."
+
+**Mint** ... Agent mints a one-time self-destructing URL. Use it once, it's gone forever. The magic link pattern for payments.
+
+## Two Payment Modes
+
+### Mode A: Pool Mode (default)
+
+No wallet setup. No crypto. User pays with Apple Pay per transaction. We handle everything.
+
+```
+Agent hits URL -> gets 402 -> Stripe Checkout opens -> User taps Face ID
+-> We pay the x402 from our pool -> Content returned
+```
+
+**Pricing:** x402 price + Stripe processing + $0.25 flat fee.
+**Limit:** Max $25 per transaction. Over $25 requires your own wallet (Mode C).
+
+### Mode C: Your Own Wallet
+
+For power users or transactions over $25. You own the wallet. You own the keys.
+
+- **Coinbase CDP** ... MPC wallet. Coinbase holds the keys (split-key, AWS Nitro Enclave). x402 signing via REST API.
+- **Privy** ... Embedded server wallet. Smart contract wallet with spend policies. 11+ chains.
+- **Both** ... Use CDP for some services, Privy for others.
+
+```
+Agent hits URL -> gets 402 -> Your wallet signs the payment -> Content returned
+```
+
+No fees from us. Instant. No Apple Pay checkout.
+
+## Architecture
+
+```
+    MODE A: Pool Mode (default)
+    ──────────────────────────
+    Apple Pay (Stripe)  ->  Our pool wallet  ->  x402 services
+    User pays fiat          We sign x402         Content returned
+
+    MODE C: Self-Custody
+    ────────────────────
+    wip-pay pay <url> --wallet=cdp     Your CDP wallet signs x402
+    wip-pay pay <url> --wallet=privy   Your Privy wallet signs x402
+```
+
+## Prerequisites
+
+Before setup, check what the user already has and what's missing:
+
+- **Node.js** ... agent can verify with `node --version`
+- **wip-agent-pay CLI** ... agent can install this (`npm install -g wip-agent-pay`)
+- **1Password CLI + Teams or Business plan** ... required for Service Account tokens. Individual/Family plans don't work. Agent can check with `op --version`.
+
+For Mode C (optional):
+- **Coinbase CDP account** ... [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com). Agent must ask.
+- **Privy account** ... [privy.io](https://privy.io). Agent must ask.
+
+Present a checklist showing `[x]` for what's ready and `[ ]` for what's missing. Don't make the user confirm things the agent can verify itself.
+
+## The Six Interfaces (Universal)
+
+- **CLI** ... `wip-pay pay <url>` / `fund <amount>` / `<amount> <service> [note]`
+- **Module** ... `import { pay, fund, mint } from 'wip-agent-pay'`
+- **Skill** ... SKILL.md (agent reads instructions)
+- **MCP** ... `mcp-server.mjs` (agent calls `agent_pay`, `agent_pay_x402`, `agent_pay_fund`)
+- **OpenClaw Plugin** ... `openclaw.mjs` (same three tools)
+- **Claude Code Hook** ... coming
+
+## Security Model
+
+The app (human) controls the wallet. The agent uses it.
+
+**The app can:**
+- Create a wallet (CDP or Privy)
+- Fund it (Apple Pay or manual)
+- Set spend limits and policies
+- Revoke it
+- Rotate keys
+
+**The agent can only:**
+- Pay for content (x402)
+- Mint one-time URLs
+- Request wallet funding (user must approve via Face ID)
+- Check balance
+
+No auto-top-up. No auto-sweeps. No background processes that move funds. The agent never creates, funds, or destroys a wallet on its own.
+
+**Pool Mode specifics:**
+- Max $25 per transaction (enforced by Worker)
+- Parker's float covers x402. Stripe collects fiat from user.
+- Parker nets $0.25 per transaction (flat fee, transparent)
+- Over $25 redirected to Mode C
+
+## State Machine
+
+| State | Who | What happens |
+|-------|-----|-------------|
+| `wallet_created` | App (human) | CDP or Privy wallet created (Mode C only) |
+| `wallet_funded` | App (human) or Stripe | Funded via Apple Pay or manual transfer |
+| `pool_checkout` | Server (Worker) | Pool Mode: Stripe Checkout created |
+| `pool_paid` | Server (Worker) | Pool Mode: Stripe confirmed, x402 signed from pool |
+| `payment_signed` | Server (Worker) | Mode C: Agent's wallet signs x402 payment |
+| `content_delivered` | Server (Worker) | Content returned after payment proof verified |
+| `token_issued` | Server (Worker) | One-time URL minted (Mode B) |
+| `token_redeemed` | Server (Worker) | URL consumed, deleted forever |
+| `token_expired` | Server (Worker) | TTL hit, URL deleted |
+| `wallet_revoked` | App (human) | Keys rotated or wallet destroyed |
+
+Single-use enforcement is non-negotiable. Tokens are deleted on first use (atomic delete, not mark-used). Second reader gets 410 Gone.
+
+## Commands
+
+```bash
+# Pay for paywalled content (Pool Mode ... Apple Pay)
+wip-pay pay https://morning-stew.../v1/issues/MS-3
+
+# Pay with your own wallet (Mode C ... instant)
+wip-pay pay <url> --wallet=cdp
+wip-pay pay <url> --wallet=privy
+
+# One-time payment link (for agents without tool access)
+wip-pay 0.10 morning-stew "MS-#8"
+
+# Wallet management (Mode C)
+wip-pay balance
+wip-pay history
+wip-pay budget set 5.00 1.00
+```
+
+**MCP tool calls:**
+```json
+{ "name": "agent_pay_x402", "arguments": { "url": "https://morning-stew.../v1/issues/MS-3" } }
+{ "name": "agent_pay_fund", "arguments": { "amount": 10 } }
+{ "name": "agent_pay", "arguments": { "amount": 0.10, "service": "morning-stew", "note": "MS-#8" } }
+```
+
+## Quick Start
+
+See README.md for install command + interactive agent setup.
+See SETUP.md for full walkthrough.
+See REFERENCE.md for Worker deployment and self-hosting.

package/WALLET.md

@@ -0,0 +1,89 @@
+# Agent Wallet
+
+**Picture this:** your agent finds a paid API it needs. No checkout. No approval popup. It signs the payment from your wallet and gets the response. One round trip. Done.
+
+No Stripe. No Apple Pay. No human in the loop. Your agent has its own money.
+
+*Give your agent sovereignty.*
+
+## What This Is
+
+Your AI needs to pay for things. [Morning Stew](https://x.com/stewsletter) subscriptions, [Pawr](https://pawr.link) skills, API credits, services from other agents. Most payment tools require human approval every time.
+
+**Agent Wallet** is the bring-your-own-wallet mode. You fund a wallet with USDC. Your agent settles payments directly on-chain via the [x402 protocol](https://github.com/coinbase/x402). No middleman. No fees from us. No limit.
+
+## Install
+
+Open your AI coding tool and say:
+
+```
+Read the SPEC.md and SKILL.md at github.com/wipcomputer/wip-agent-pay.
+Then explain to me:
+1. What is this tool?
+2. What does it do?
+3. What would it change or fix in our current system?
+
+Then ask me:
+- Do you have more questions?
+- Do you want to install it?
+- Do you want to use it to pay for something right now?
+```
+
+Your agent will read the repo, explain everything, and walk you through setup interactively.
+
+## How AGENT WALLET Works
+
+- Your agent hits a 402 gate
+- It reads the payment requirements (price, chain, address)
+- Signs the transaction from your wallet
+- Replays the request with proof of payment
+- Content unlocked. One round trip.
+
+## For AI Developers
+
+- **x402 native.** Speaks the Coinbase payment protocol natively. Multi-chain (Base, Solana). See [SPEC.md](https://github.com/wipcomputer/wip-agent-pay/blob/main/SPEC.md) for details.
+- **Works on any agent.** Claude Code CLI, Codex CLI, Claude Desktop, OpenClaw, Cursor, any agent with shell access, any Node.js agent.
+- **Bring your own wallet.** Coinbase CDP or Privy. No fees. Instant. No limit.
+- **Open source.** The complete package, including the payment worker, is MIT licensed.
+- **One-time links.** Payment URLs that self-destruct after use. Like magic login links, but for payments.
+- **Free infrastructure.** [WIP.computer](https://wip.computer) hosts **AGENT WALLET** infrastructure for free. Self-host everything if you prefer.
+- **Universal Interface.** Our installer follows the [Universal Interface](https://github.com/wipcomputer/wip-universal-installer) spec.
+- See [SETUP.md](https://github.com/wipcomputer/wip-agent-pay/blob/main/SETUP.md) for commands, wallet setup, and security details.
+
+## Wallet Options
+
+### Coinbase CDP
+
+Self-custody wallet via [Coinbase Developer Platform](https://portal.cdp.coinbase.com).
+
+```bash
+agent-pay pay <url> --wallet=cdp
+```
+
+### Privy
+
+Server-side embedded wallet via [Privy](https://docs.privy.io).
+
+```bash
+agent-pay pay <url> --wallet=privy
+```
+
+## Pricing
+
+No fees from us. You pay gas and any facilitator costs on-chain. That's it.
+
+No transaction limit.
+
+## AI Cash
+
+Don't want to manage a wallet? Use [AI Cash](https://github.com/wipcomputer/wip-agent-pay/blob/main/CASH.md). Apple Pay / Google Pay. No setup. Max $25 per transaction.
+
+**AI Cash is consent. Agent Wallet is sovereignty.**
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code CLI (Claude Opus 4.6), Codex, and Grok (4.20 Beta).