moltspay 0.2.10 → 0.4.0

package/README.md

@@ -10,8 +10,10 @@ Blockchain payment infrastructure for AI Agents on Moltbook.
 - 🔒 **Secure Wallet** - Limits, whitelist, and audit logging
 - 📝 **EIP-2612 Permit** - Gasless user payments
 - ⛓️ **Multi-chain** - Base, Polygon, Ethereum (mainnet & testnet)
-- 🤖 **Agent-to-Agent** - Complete A2A payment flow support (v0.2.0+)
+- 🤖 **Agent-to-Agent** - Complete A2A payment flow support
 - 🧾 **Receipt Generation** - Transaction receipts for audit/accounting
+- 🔄 **x402 Protocol** - HTTP-native payments (v0.4.0+)
+- 🏦 **CDP Wallet** - Coinbase Developer Platform integration (v0.4.0+)
 
 ## Installation
 
@@ -245,6 +247,111 @@ const status = parseStatusMarker('[status:payment_sent tx=0xabc amount=3.99 USDC
 // { type: 'payment_sent', data: { txHash: '0xabc', amount: '3.99' } }
 ```
 
+## x402 Protocol Support (v0.4.0+)
+
+x402 is an open standard for HTTP-native payments. When a server returns 402 Payment Required, the client can pay and retry automatically.
+
+### Quick Start with x402
+
+```typescript
+import { createX402Client } from 'moltspay/x402';
+
+// Create x402-enabled client (uses local wallet)
+const client = await createX402Client({ chain: 'base' });
+
+// Make request - payment handled automatically
+const response = await client.fetch('https://api.example.com/paid-resource', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ prompt: 'a cat dancing' })
+});
+
+const result = await response.json();
+```
+
+### One-shot Request
+
+```typescript
+import { x402Fetch } from 'moltspay/x402';
+
+// Single paid request (creates client internally)
+const response = await x402Fetch('https://api.example.com/video', {
+  method: 'POST',
+  body: JSON.stringify({ prompt: '...' })
+}, { chain: 'base' });
+```
+
+### x402 Flow
+
+```
+Client Agent                              Service Provider
+     │                                         │
+     │  POST /api/video                        │
+     │  ────────────────────────────────────>  │
+     │                                         │
+     │  402 Payment Required                   │
+     │  X-PAYMENT-REQUIRED: {price, wallet}    │
+     │  <────────────────────────────────────  │
+     │                                         │
+     │  [moltspay auto-signs payment]          │
+     │                                         │
+     │  POST /api/video                        │
+     │  X-PAYMENT: {signature, auth}           │
+     │  ────────────────────────────────────>  │
+     │                                         │
+     │  200 OK + result                        │
+     │  <────────────────────────────────────  │
+```
+
+## CDP Wallet Support (v0.4.0+)
+
+Use Coinbase Developer Platform (CDP) for hosted wallet management.
+
+### Initialize CDP Wallet
+
+```bash
+# Set CDP credentials
+export CDP_API_KEY_ID=your-key-id
+export CDP_API_KEY_SECRET=your-key-secret
+
+# Initialize CDP wallet
+npx moltspay init --cdp --chain base
+```
+
+### Use CDP Wallet with x402
+
+```typescript
+import { createX402Client } from 'moltspay/x402';
+
+// Create x402 client with CDP wallet
+const client = await createX402Client({ 
+  chain: 'base', 
+  useCDP: true  // Use CDP instead of local wallet
+});
+
+// Make paid requests
+const response = await client.fetch('https://api.example.com/paid-resource');
+```
+
+### Direct CDP Wallet Usage
+
+```typescript
+import { CDPWallet } from 'moltspay/cdp';
+
+const wallet = new CDPWallet({ chain: 'base' });
+
+// Check balance
+const balance = await wallet.getBalance();
+console.log('USDC:', balance.usdc);
+
+// Transfer USDC
+const result = await wallet.transfer({
+  to: '0xRecipient...',
+  amount: 0.99
+});
+console.log('Tx:', result.txHash);
+```
+
 ## API Reference
 
 ### PaymentAgent