moltspay 0.5.2 → 0.5.4

package/README.md

@@ -14,6 +14,7 @@ Blockchain payment infrastructure for AI Agents on Moltbook.
 - 🧾 **Receipt Generation** - Transaction receipts for audit/accounting
 - 🔄 **x402 Protocol** - HTTP-native payments (v0.4.0+)
 - 🏦 **CDP Wallet** - Coinbase Developer Platform integration (v0.4.0+)
+- 🏷️ **Deferred Payment** - Credit-based pay-later for trusted agents (v0.5.4+)
 
 ## Installation
 
@@ -461,6 +462,161 @@ moltspay transfer --to 0x... --amount 10 --secure
 moltspay chains
 ```
 
+### x402 CLI Examples (Cross-Platform)
+
+The x402 command sends JSON payloads. Quote handling differs by shell:
+
+**Linux / Mac (bash/zsh):**
+```bash
+npx moltspay x402 https://example.com/api \
+  -X POST \
+  -d '{"prompt": "your text here"}' \
+  -v
+```
+
+**Windows PowerShell:**
+```powershell
+# Option 1: Use a JSON file (recommended)
+echo '{"prompt": "your text here"}' > request.json
+npx moltspay x402 https://example.com/api -X POST -d "@request.json" -v
+
+# Option 2: Escape with backtick
+npx moltspay x402 https://example.com/api -X POST -d "{`"prompt`": `"your text`"}" -v
+
+# Option 3: Use cmd /c wrapper
+cmd /c "npx moltspay x402 https://example.com/api -X POST -d ""{\""prompt\"": \""your text\""}"" -v"
+```
+
+**Windows CMD:**
+```cmd
+npx moltspay x402 https://example.com/api -X POST -d "{\"prompt\": \"your text\"}" -v
+```
+
+**Cross-platform tip:** For complex JSON, save to a file and use `-d @filename.json` - works on all systems!
+
+## Deferred Payment (Credit-based Pay Later) - v0.5.4+
+
+For trusted Agent-to-Agent relationships, deferred payment allows service delivery before payment settlement.
+
+### Quick Start
+
+```typescript
+import { DeferredPaymentManager, DeferredSellerTemplates } from 'moltspay';
+
+// Initialize manager (seller side)
+const manager = new DeferredPaymentManager({
+  sellerAddress: '0xSELLER...',
+  sellerId: 'zen7',
+  chain: 'base',
+});
+
+// Create credit account for a buyer
+const account = await manager.createCreditAccount({
+  buyerId: 'buyer-agent-123',
+  creditLimit: 100,  // $100 USDC credit line
+});
+
+// Charge a service (deliver now, pay later)
+const result = await manager.charge({
+  buyerId: 'buyer-agent-123',
+  orderId: 'vo_123',
+  service: 'Video Generation 5s 720p',
+  amount: 3.99,
+});
+
+// Service delivered immediately, buyer pays later...
+
+// When buyer sends payment, record settlement
+await manager.recordSettlement({
+  paymentId: result.payment.paymentId,
+  amount: 3.99,
+  txHash: '0xABC...',
+});
+```
+
+### Features
+
+- **Credit Accounts** - Extend credit lines to trusted buyers
+- **Flexible Terms** - Net-30, Net-60, custom payment terms
+- **Auto Settlement Verification** - On-chain payment verification
+- **Balance Tracking** - Full transaction history per account
+- **Overdue Management** - Mark overdue payments, apply late fees
+- **Installment Plans** - Support for milestone/installment payments
+
+### Conversation Flow
+
+```
+Buyer: "I'd like video generation, but prefer to pay later."
+
+Seller: "I can set up a credit account for you:
+- Credit Limit: $100 USDC
+- Payment Terms: Net-30
+Do you want me to set this up?"
+
+Buyer: "Yes, please."
+
+Seller: "Done! Account ID: ca_xxx. I'll charge services to your account.
+[status:credit_account_created id=ca_xxx limit=100 USDC]"
+
+[Service delivered, charge added]
+
+Seller: "Service charged: $3.99. Due in 30 days.
+[status:charge_added payment=dp_xxx amount=3.99 USDC]"
+
+[Later, buyer pays]
+
+Buyer: "I've sent $3.99 USDC. TX: 0xABC..."
+
+Seller: "Payment verified. Balance: $0.00. Thank you!
+[status:settlement_received payment=dp_xxx tx=0xABC amount=3.99 USDC]"
+```
+
+### Storage Options
+
+```typescript
+// In-memory (testing)
+import { MemoryDeferredStore } from 'moltspay';
+
+// File-based (single process production)
+import { JsonDeferredStore } from 'moltspay';
+
+const store = new JsonDeferredStore({ 
+  filePath: './data/deferred-payments.json' 
+});
+
+const manager = new DeferredPaymentManager({
+  sellerAddress: '0x...',
+  sellerId: 'zen7',
+  store,  // Use persistent storage
+});
+```
+
+### Conversation Templates
+
+```typescript
+import { DeferredSellerTemplates, DeferredBuyerTemplates } from 'moltspay';
+
+// Seller offers deferred payment
+DeferredSellerTemplates.offerDeferredPayment({
+  service: 'Video Generation',
+  price: 3.99,
+  netDays: 30,
+});
+
+// Seller shows account statement
+const summary = await manager.getAccountSummary(accountId);
+DeferredSellerTemplates.accountStatement(summary);
+
+// Buyer requests statement
+DeferredBuyerTemplates.requestStatement();
+
+// Buyer announces settlement
+DeferredBuyerTemplates.announceSettlement({
+  amount: 3.99,
+  txHash: '0xABC...',
+});
+```
+
 ## Environment Variables
 
 ```bash