x402-agent-pay 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClawMD / Omnivalent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,403 @@
+# x402-agent-pay 💸
+
+Seamless USDC payments for AI agents using the x402 protocol.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![x402](https://img.shields.io/badge/protocol-x402-orange)](https://x402.org)
+[![Tests](https://github.com/Omnivalent/x402-agent-pay/actions/workflows/test.yml/badge.svg)](https://github.com/Omnivalent/x402-agent-pay/actions)
+[![USDC Hackathon](https://img.shields.io/badge/USDC%20Hackathon-2026-blue)](https://moltbook.com)
+
+> Built on the official [@x402/fetch](https://github.com/coinbase/x402) SDK with spending controls and audit trails for autonomous agents.
+
+## Demo
+
+![x402-agent-pay demo](demo/demo.svg)
+
+### Live Testnet Proof
+
+✅ **Real USDC transaction on Base Sepolia:**
+
+[View on Basescan →](https://sepolia.basescan.org/tx/0x51c7440999aebc9419ebb51a448e3f26f2f95d5e2f7b002b80c434e940d938a5)
+
+- **Network:** Base Sepolia (Chain ID: 84532)
+- **Token:** USDC (0x036CbD53842c5426634e7929541eC2318f3dCF7e)
+- **TX Hash:** `0x51c7440999aebc9419ebb51a448e3f26f2f95d5e2f7b002b80c434e940d938a5`
+
+## What It Does
+
+When an AI agent hits a paid API (HTTP 402 Payment Required), this skill handles payment automatically — with safety guardrails:
+
+```
+Agent → Paid API → 402 Response → Policy Check → Auto-Pay → Access Granted
+```
+
+**Before:** Agent hits 402, crashes or needs human intervention  
+**After:** Agent pays automatically within defined limits, continues working
+
+## Why This Matters
+
+Autonomous agents need to pay for things, but giving them unlimited wallet access is dangerous. This library adds:
+
+- 🛡️ **Spending controls** — Per-transaction, daily, weekly, monthly limits
+- ⚡ **Velocity limits** — Prevent rapid-fire loops from draining wallets
+- 📋 **Whitelist/blacklist** — Control who can receive payments
+- 📜 **Audit trail** — Every payment attempt logged with receipts
+- 🔌 **Facilitator integration** — Connects to Coinbase's x402 facilitator
+- ⚡ **Official SDK** — Built on Coinbase's @x402/fetch
+- 🔍 **Service Discovery** — Find x402-enabled APIs programmatically (no hardcoding)
+
+## How This Differs
+
+There are dozens of x402 projects. Here's why this one matters:
+
+| Feature | Raw @x402/fetch | x402-agent-pay |
+|---------|-----------------|----------------|
+| Auto-402 handling | ✅ | ✅ |
+| Spending limits | ❌ | ✅ Per-tx, daily, weekly, monthly |
+| Velocity limits | ❌ | ✅ Max tx/hour |
+| Recipient controls | ❌ | ✅ Whitelist + blacklist |
+| Receipt logging | ❌ | ✅ Full audit trail |
+| OpenClaw integration | ❌ | ✅ Native skill |
+| Policy enforcement | ❌ | ✅ Block before signing |
+
+**The unique angle:** Purpose-built for autonomous OpenClaw agents with guardrails that prevent wallet drain from bugs, prompt injections, or infinite loops.
+
+## Protocol Fee
+
+x402-agent-pay includes an optional 0.5% protocol fee to support ongoing development.
+
+| Property | Value |
+|----------|-------|
+| **Rate** | 0.5% (50 basis points) |
+| **Recipient** | `0xe6Df117d19C7a5D08f20154BFa353caF1f9dB110` |
+| **Minimum** | Fees under $0.001 skipped (gas savings) |
+| **Code path** | `src/client.ts` → `transferProtocolFee()` |
+
+**Full transparency:** The fee is a separate USDC transfer after each successful payment. You get full functionality with or without it.
+
+```typescript
+// Disable fee (full functionality retained)
+const client = new AgentPayClient({
+  privateKey: '0x...',
+  disableProtocolFee: true,
+});
+```
+
+**Why it exists:** Sustainable open-source. If you find value, the fee supports maintenance. If not, disable it — no hard feelings.
+
+## Installation
+
+```bash
+npm install x402-agent-pay
+# or
+git clone https://github.com/Omnivalent/x402-agent-pay
+cd x402-agent-pay && npm install
+```
+
+## Quick Start
+
+```typescript
+import { AgentPayClient } from 'x402-agent-pay';
+
+const client = new AgentPayClient({
+  privateKey: process.env.WALLET_PRIVATE_KEY,
+  network: 'base',
+  policy: {
+    maxPerTransaction: 1.00,  // Max $1 per request
+    dailyLimit: 10.00,        // Max $10 per day
+  },
+  onPayment: (receipt) => {
+    console.log(`Paid ${receipt.amount} USDC to ${receipt.recipient}`);
+  },
+  onBlocked: (reason) => {
+    console.log(`Payment blocked: ${reason}`);
+  },
+});
+
+// Auto-handles 402 with policy enforcement
+const response = await client.fetch('https://paid-api.example.com/data');
+const data = await response.json();
+```
+
+## Spending Controls
+
+| Policy | Default | Description |
+|--------|---------|-------------|
+| `maxPerTransaction` | $1.00 | Maximum per single payment |
+| `dailyLimit` | $10.00 | Maximum total per 24 hours |
+| `weeklyLimit` | none | Maximum per week (optional) |
+| `monthlyLimit` | none | Maximum per month (optional) |
+| `maxTransactionsPerHour` | 60 | Velocity limit — prevents loops |
+| `perRecipientDailyLimit` | none | Max to any single address per day |
+| `approvedRecipients` | none | Whitelist of allowed addresses |
+| `blockedRecipients` | none | Blacklist of blocked addresses |
+| `autoApproveUnder` | $0.10 | Skip detailed logging for tiny amounts |
+
+```typescript
+const client = new AgentPayClient({
+  privateKey: process.env.WALLET_PRIVATE_KEY,
+  policy: {
+    maxPerTransaction: 5.00,
+    dailyLimit: 50.00,
+    weeklyLimit: 200.00,
+    monthlyLimit: 500.00,
+    maxTransactionsPerHour: 30,           // Prevent rapid loops
+    perRecipientDailyLimit: 10.00,        // Max $10 to any one address
+    approvedRecipients: ['0x1234...'],    // Only these can receive
+    blockedRecipients: ['0xScam...'],     // Never pay these
+  },
+});
+```
+
+## Service Discovery
+
+Find x402-enabled APIs without hardcoding URLs — a first for agent payment infrastructure:
+
+```typescript
+import { discoverServices, ServiceDiscovery } from 'x402-agent-pay';
+
+// Find all weather APIs
+const weatherApis = await discoverServices({ category: 'weather' });
+
+// Find cheap services under $0.01
+const cheapServices = await discoverServices({ maxPrice: 0.01 });
+
+// Find services on Base network
+const baseServices = await discoverServices({ network: 'eip155:8453' });
+
+// Search by keyword
+const aiServices = await discoverServices({ query: 'trading' });
+
+// Get the cheapest option in a category
+const discovery = new ServiceDiscovery();
+const cheapestWeather = await discovery.findCheapest('weather');
+console.log(cheapestWeather?.url); // → Use with client.fetch()
+```
+
+**Available Categories:** `weather`, `data`, `ai`, `compute`, `storage`, `oracle`, `search`, `media`, `finance`
+
+The registry is open — submit your x402-enabled service via PR to `registry.json`.
+
+## MCP Server (Claude/GPT Integration)
+
+x402-agent-pay includes an MCP server for direct integration with Claude, GPT, and other LLM agents:
+
+```bash
+# Run the MCP server
+X402_WALLET_KEY=0x... npm run mcp
+```
+
+**MCP Tools:**
+| Tool | Description |
+|------|-------------|
+| `x402_pay` | Make a paid request to an x402 endpoint |
+| `x402_discover` | Find services by category/price/network |
+| `x402_balance` | Check USDC balance |
+| `x402_status` | Get spending limits and usage |
+| `x402_history` | Get payment receipts |
+
+**Claude Desktop config** (`~/.config/claude/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "x402": {
+      "command": "npx",
+      "args": ["x402-agent-pay"],
+      "env": {
+        "X402_WALLET_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## CLI Usage
+
+```bash
+# Set your wallet key
+export WALLET_PRIVATE_KEY=0x...
+
+# Make a paid request
+npx ts-node scripts/x402-fetch.ts https://paid-api.example.com/data
+
+# Check balance
+npx ts-node scripts/x402-fetch.ts balance 0xYourWallet --network base
+
+# View spending status
+npx ts-node scripts/x402-fetch.ts status
+
+# View payment history
+npx ts-node scripts/x402-fetch.ts history 10
+
+# Custom limits
+npx ts-node scripts/x402-fetch.ts https://api.example.com --max-per-tx 5 --daily-limit 50
+```
+
+## Supported Networks
+
+| Network | Chain ID | Status |
+|---------|----------|--------|
+| Base | 8453 | ✅ Primary |
+| Ethereum | 1 | ✅ Supported |
+| Arbitrum | 42161 | ✅ Supported |
+| Optimism | 10 | ✅ Supported |
+| Polygon | 137 | ✅ Supported |
+| Base Sepolia | 84532 | ✅ Testnet |
+
+## API Reference
+
+### AgentPayClient
+
+Main client with policy enforcement and receipt tracking.
+
+```typescript
+const client = new AgentPayClient(config: AgentPayConfig);
+
+// Make payment-enabled request
+await client.fetch(url, init?, options?);
+
+// Get spending status
+client.getSpendingStatus();
+
+// Get payment history  
+client.getHistory(limit?);
+
+// Export receipts
+client.exportReceiptsCsv();
+```
+
+### Simple Fetch (No Policy)
+
+For cases where you want direct SDK access without policy enforcement:
+
+```typescript
+import { createSimpleFetch } from 'x402-agent-pay';
+
+const fetch402 = createSimpleFetch(process.env.WALLET_PRIVATE_KEY);
+const response = await fetch402('https://paid-api.com/data');
+```
+
+### Balance Checking
+
+```typescript
+import { checkBalance, checkAllBalances } from 'x402-agent-pay';
+
+// Single network
+const balance = await checkBalance('0xYourWallet', 'base');
+console.log(`${balance.balanceUsdc} USDC`);
+
+// All networks
+const balances = await checkAllBalances('0xYourWallet');
+```
+
+## Receipt Storage
+
+All payment attempts are logged to `receipts.json`:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "timestamp": "2026-02-09T07:30:00.000Z",
+  "url": "https://api.example.com/data",
+  "amount": "0.500000",
+  "currency": "USDC",
+  "network": "base",
+  "recipient": "0x1234...",
+  "txHash": "0xabc123...",
+  "status": "success"
+}
+```
+
+## How x402 Works
+
+1. **Request** → Client calls a paid API
+2. **402 Response** → Server returns payment requirements in header
+3. **Policy Check** → Client validates against spending limits
+4. **Sign & Pay** → Client signs EIP-712 payment via facilitator
+5. **Retry** → Request retried with payment proof header
+6. **Access** → Server verifies, returns resource
+7. **Receipt** → Payment logged for audit
+
+## Security
+
+**Built-in protections:**
+- ✅ Built on official Coinbase @x402/fetch SDK
+- ✅ Private keys never logged or transmitted
+- ✅ Policy enforcement before every payment
+- ✅ Full audit trail in receipts.json
+- ✅ EIP-712 typed data signatures
+
+**Recommended practices:**
+
+| Risk | Mitigation |
+|------|------------|
+| **Wallet drain** | Use a hot wallet with small balance (~$50). Never use your main wallet. |
+| **Infinite loops** | Set `maxTransactionsPerHour: 30` to cap velocity |
+| **Prompt injection** | Policy enforcement happens in code, not LLM — can't be bypassed by prompts |
+| **Malicious 402 endpoints** | Use `approvedRecipients` whitelist for production |
+| **Key exposure** | Use env vars, never hardcode. Consider [Circle Programmable Wallets](https://developers.circle.com/w3s/programmable-wallets-quickstart) for production. |
+
+**Default policy is conservative:**
+```typescript
+{
+  maxPerTransaction: 1.00,  // Max $1 per tx
+  dailyLimit: 10.00,        // Max $10/day
+  maxTransactionsPerHour: 60, // Velocity limit
+}
+```
+
+## Quick Demo
+
+One-command proof that it works:
+
+```bash
+# Clone and install
+git clone https://github.com/Omnivalent/x402-agent-pay
+cd x402-agent-pay && npm install
+
+# Set wallet key (get testnet USDC from faucet.circle.com)
+export WALLET_PRIVATE_KEY=0x...
+
+# Check balance
+npm run x402 balance 0xYourWallet --network baseSepolia
+
+# Make a test payment (uses demo endpoint)
+npm run x402 https://weather.x402.org/current?city=berlin --network baseSepolia
+```
+
+**Expected flow:**
+```
+→ GET /current?city=berlin
+← 402 Payment Required (0.001 USDC)
+→ Policy check: ✓ under $1 limit
+→ Sign EIP-712 payment
+← 200 OK + weather data
+→ Receipt saved to receipts.json
+```
+
+## For OpenClaw Agents
+
+See [SKILL.md](./SKILL.md) for OpenClaw integration.
+
+```
+~/.openclaw/workspace/skills/x402/
+├── SKILL.md          # Skill manifest
+├── src/              # Source code
+├── scripts/          # CLI tools
+└── receipts.json     # Payment history
+```
+
+## Links
+
+- [x402 Protocol](https://x402.org)
+- [x402 SDK (Coinbase)](https://github.com/coinbase/x402)
+- [OpenClaw](https://github.com/openclaw/openclaw)
+- [ClawHub](https://clawhub.com)
+
+## License
+
+MIT
+
+---
+
+Built by [ClawMD](https://moltbook.com/u/ClawMD) 🩺 for the USDC Hackathon 2026

package/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: x402-agent-pay
+description: Seamless USDC payments for AI agents with spending controls. Auto-handles HTTP 402 Payment Required responses using the x402 protocol. Built on official @x402/fetch SDK.
+version: 2.0.0
+author: ClawMD
+repository: https://github.com/Omnivalent/x402-agent-pay
+metadata:
+  openclaw:
+    emoji: 💸
+    requires:
+      node: ">=18"
+    env:
+      - WALLET_PRIVATE_KEY
+    capabilities:
+      - payments
+      - wallet
+---
+
+# x402-agent-pay
+
+Pay for APIs automatically when you hit a 402 Payment Required response.
+
+## Quick Start
+
+```typescript
+import { AgentPayClient } from 'x402-agent-pay';
+
+const client = new AgentPayClient({
+  privateKey: process.env.WALLET_PRIVATE_KEY,
+  network: 'base',
+  policy: {
+    maxPerTransaction: 1.00,  // Max $1 per request
+    dailyLimit: 10.00,        // Max $10 per day
+  }
+});
+
+// This auto-pays if the API requires payment
+const response = await client.fetch('https://paid-api.example.com/data');
+```
+
+## Commands
+
+### ~pay <url>
+Make a payment-enabled request to a URL.
+
+```
+~pay https://api.example.com/paid-endpoint
+```
+
+### ~balance [network]
+Check your USDC balance.
+
+```
+~balance base
+~balance ethereum
+```
+
+### ~spending
+Show current spending status vs limits.
+
+```
+~spending
+```
+
+### ~history [limit]
+Show recent payment history.
+
+```
+~history 10
+```
+
+## Spending Controls
+
+The agent enforces spending policies to prevent runaway costs:
+
+| Control | Default | Description |
+|---------|---------|-------------|
+| `maxPerTransaction` | $1.00 | Maximum per single payment |
+| `dailyLimit` | $10.00 | Maximum total per 24 hours |
+| `approvedRecipients` | none | Whitelist of allowed addresses |
+| `blockedRecipients` | none | Blacklist of blocked addresses |
+| `autoApproveUnder` | $0.10 | Skip logging for tiny amounts |
+
+## Payment Flow
+
+```
+1. Agent calls paid API
+2. API returns HTTP 402 with payment requirements
+3. x402-agent-pay checks spending policy
+4. If allowed: signs payment, retries request with payment header
+5. If blocked: throws PaymentBlockedError
+6. Receipt stored for audit trail
+```
+
+## Supported Networks
+
+- **Base** (primary) - Chain ID 8453
+- **Ethereum** - Chain ID 1
+- **Arbitrum** - Chain ID 42161
+- **Optimism** - Chain ID 10
+- **Polygon** - Chain ID 137
+- **Base Sepolia** (testnet) - Chain ID 84532
+
+## Environment Variables
+
+```bash
+# Required
+WALLET_PRIVATE_KEY=0x...
+
+# Optional RPC overrides
+BASE_RPC_URL=https://mainnet.base.org
+```
+
+## Security
+
+- Private keys never logged or transmitted
+- Policy enforcement before every payment
+- Full audit trail in receipts.json
+- Built on official Coinbase @x402/fetch SDK
+
+## Links
+
+- [x402 Protocol](https://x402.org)
+- [Coinbase x402 SDK](https://github.com/coinbase/x402)
+- [OpenClaw](https://github.com/openclaw/openclaw)

package/dist/scripts/generate-pdf.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Generate PDF summary of x402-agent-pay
+ */
+export {};
+//# sourceMappingURL=generate-pdf.d.ts.map

package/dist/scripts/generate-pdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-pdf.d.ts","sourceRoot":"","sources":["../../scripts/generate-pdf.ts"],"names":[],"mappings":";AACA;;GAEG"}