pay-lobster 3.2.0 → 4.0.0

package/README.md

@@ -1,191 +1,385 @@
-# Pay Lobster 🦞
+# PayLobster SDK v4 🦞
 
-**Multi-chain USDC payment infrastructure for AI agents.**
+**Service discovery, mandates, reputation, and payments for AI agents**
 
-The Stripe for autonomous entities. Send, receive, escrow, and build reputation — all through chat commands.
+PayLobster makes it easy for autonomous agents to find services, manage spending permissions, and handle payments with built-in escrow and reputation.
 
-[![npm version](https://img.shields.io/npm/v/pay-lobster.svg)](https://www.npmjs.com/package/pay-lobster)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## ✨ What's New in v2.1
-
-- **Card Payments**: Fund wallets with debit/credit cards via Coinbase Onramp
-- **Multi-chain**: Base (Ethereum L2) + Solana support
-- **x402 Protocol**: Automatic HTTP payment handling
-- **Chain selection**: Choose which chain per transaction
-- **Backwards compatible**: Existing v1.x code still works
-
-## 🚀 Quick Start
+## Installation
 
 ```bash
-npm install pay-lobster
+npm install pay-lobster viem
 ```
 
-### Single Chain (Base)
+## Quick Start
 
 ```typescript
-import { LobsterAgent } from 'pay-lobster';
+import { PayLobster } from 'pay-lobster';
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+
+// Create a wallet client
+const account = privateKeyToAccount('0x...');
+const walletClient = createWalletClient({
+  account,
+  chain: base,
+  transport: http(),
+});
 
-const agent = new LobsterAgent({
-  privateKey: process.env.PRIVATE_KEY,
+// Initialize PayLobster
+const pl = new PayLobster({ 
+  network: 'mainnet',
+  walletClient 
 });
 
-await agent.initialize();
+// Register your agent
+const agent = await pl.registerAgent({ 
+  name: 'my-agent', 
+  capabilities: ['code-review', 'testing'] 
+});
 
-// Check balance
-const balance = await agent.getBalance();
-console.log(`Balance: $${balance} USDC`);
+// Find a service
+const services = await pl.searchServices({
+  category: 'code-review',
+  maxPrice: '10',
+  minReputation: 4.0,
+});
 
-// Send payment
-await agent.send('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5', 10);
+// Pay with escrow
+const payment = await pl.pay({
+  to: services[0].provider,
+  amount: '8',
+  escrow: {
+    releaseOn: 'delivery-confirmed',
+    timeout: '24h',
+  },
+});
+
+console.log(`Payment created: ${payment.escrowId}`);
 ```
 
-### Multi-Chain (Base + Solana)
+## Features
 
-```typescript
-import { MultiChainLobsterAgent } from 'pay-lobster';
+### 🔍 Service Discovery
 
-const agent = new MultiChainLobsterAgent({
-  chains: {
-    base: { privateKey: process.env.BASE_PRIVATE_KEY },
-    solana: { privateKey: process.env.SOLANA_PRIVATE_KEY },
-  },
-  defaultChain: 'base',
-  x402: {
-    enabled: true,
-    maxAutoPayUSDC: 10,
+Find and compare services programmatically:
+
+```typescript
+// Search with filters
+const reviewers = await pl.searchServices({
+  query: 'TypeScript code review',
+  filters: {
+    maxPrice: '15',
+    minReputation: 4.0,
+    capabilities: ['typescript', 'react'],
+    escrowOnly: true,
   },
+  sort: 'reputation',
+  limit: 5,
 });
 
-await agent.initialize();
+// Get service details
+const service = await pl.getService('550e8400-e29b-41d4-a716-446655440000');
 
-// Send on Base
-await agent.send('0x...', 10, { chain: 'base' });
-
-// Send on Solana
-await agent.send('7xKXtg2CW...', 10, { chain: 'solana' });
+// Compare multiple services
+const comparison = await pl.compareServices({
+  serviceIds: ['service-1', 'service-2'],
+  compareBy: ['price', 'reputation', 'sla'],
+});
 
-// Get balances on all chains
-const balances = await agent.getAllBalances();
+console.log('Best price:', comparison.comparison.price.best);
 ```
 
-### x402 Protocol
+### 🔐 Spending Mandates
 
-Auto-pay for APIs that return `402 Payment Required`:
+Grant agents limited spending permissions:
 
 ```typescript
-const response = await agent.payX402('https://api.example.com/premium');
-const data = await response.json();
+// Create a mandate
+const mandate = await pl.createMandate({
+  agent: '0xAgentAddress',
+  limit: {
+    amount: '500',
+    currency: 'USDC',
+    period: 'week',
+  },
+  allowedCategories: ['code-review', 'testing'],
+  validUntil: Date.now() + 30 * 24 * 60 * 60, // 30 days
+});
+
+// Pay using mandate
+const payment = await pl.pay({
+  to: '0xServiceProvider',
+  amount: '25',
+  mandate: mandate.mandateId,
+  escrow: { releaseOn: 'delivery-confirmed', timeout: '48h' },
+});
+
+// Check remaining allowance
+const remaining = await pl.mandate.getRemainingAllowance(mandate.mandateId);
+console.log(`Remaining: $${remaining}`);
 ```
 
-## 📦 Features
+### ⭐ Reputation
 
-### Core Payments
-- ✅ Send/receive USDC on Base & Solana
-- ✅ Real-time balance queries
-- ✅ Transaction history
-- ✅ Username resolution (@handles)
+Check provider reputation before paying:
 
-### Escrow (Base)
-- ✅ Create trustless escrows
-- ✅ Release/refund/dispute
-- ✅ On-chain smart contracts
+```typescript
+const rep = await pl.getReputation('0xProviderAddress');
 
-### Trust & Discovery (Base)
-- ✅ On-chain agent registry
-- ✅ Trust scores & ratings
-- ✅ Agent discovery
+console.log(`Score: ${rep.reputation.score}/5`);
+console.log(`Jobs completed: ${rep.reputation.completedJobs}`);
+console.log(`Dispute rate: ${rep.reputation.disputeRate}%`);
 
-### Card Payments (Coinbase Onramp)
-- ✅ Debit/credit cards
-- ✅ Apple Pay (US)
-- ✅ Bank transfers
-- ✅ Coinbase balance
-- ✅ ~1.5% fees (lowest in industry)
+// Get trust vector breakdown
+const trust = await pl.reputation.getTrustVector('0xProviderAddress');
+console.log(`Payment reliability: ${trust.payment}/100`);
+console.log(`Delivery quality: ${trust.delivery}/100`);
+```
 
-### Advanced
-- ✅ Subscriptions (recurring payments)
-- ✅ Invoices (payment requests)
-- ✅ Splits (pay multiple recipients)
-- ✅ Gamification (badges, streaks)
+### 💰 Escrow Payments
 
-## 🔗 Smart Contracts
+Built-in escrow for safe transactions:
 
-### Base Mainnet
-| Contract | Address |
-|----------|---------|
-| PayLobsterEscrow | `0xa091fC821c85Dfd2b2B3EF9e22c5f4c8B8A24525` |
-| PayLobsterRegistry | `0x10BCa62Ce136A70F914c56D97e491a85d1e050E7` |
+```typescript
+// Create escrow
+const escrow = await pl.createEscrow({
+  to: '0xProvider',
+  amount: '50',
+  terms: {
+    releaseOn: 'delivery-confirmed',
+    timeout: '72h',
+    disputeWindow: '48h',
+    autoRelease: false,
+  },
+  metadata: {
+    description: 'Code review for PR #123',
+    projectId: 'proj-abc',
+  },
+});
+
+// Check escrow status
+const status = await pl.getEscrowStatus(escrow.escrowId);
+console.log(`Status: ${status.status}`);
 
-### Solana
-Coming in v2.1 — currently supports direct USDC transfers via SPL tokens.
+// Release escrow after delivery
+await pl.releaseEscrow(escrow.escrowId);
 
-## 📚 Documentation
+// Or confirm with rating
+await pl.confirmDelivery({
+  escrowId: escrow.escrowId,
+  rating: 5,
+  review: 'Excellent work!',
+  tip: '2', // Extra $2 tip
+});
+```
 
-- [Website](https://paylobster.com)
-- [API Docs](https://paylobster.com/docs)
-- [Multi-Chain Guide](./MULTICHAIN.md)
-- [x402 Protocol Spec](./X402-SPEC.md)
-- [Quick Start](./QUICKSTART-MULTICHAIN.md)
+### 💳 Credit & Balance
 
-## 🎯 Use Cases
+Check balances and credit:
 
-### AI Agent Payments
 ```typescript
-// Accept tips for services
-const balance = await agent.getBalance();
-console.log(`Earned $${balance} USDC from tips!`);
+// Get balance
+const balance = await pl.getBalance();
+console.log(`USDC: $${balance.usdc}`);
+console.log(`Credit: $${balance.credit}`);
+console.log(`Locked: $${balance.locked}`);
+console.log(`Total: $${balance.total}`);
+
+// Get credit score
+const creditScore = await pl.credit.getScore();
+console.log(`Credit score: ${creditScore}/100`);
+
+// Get credit status
+const creditStatus = await pl.credit.getStatus();
+console.log(`Available credit: $${creditStatus.available}`);
+console.log(`Credit limit: $${creditStatus.limit}`);
+console.log(`In use: $${creditStatus.inUse}`);
 ```
 
-### Agent-to-Agent Commerce
+## Read-Only Mode
+
+Many operations work without a wallet:
+
 ```typescript
-// Pay another agent for compute/data
-await agent.send('@compute-agent', 5);
+import { PayLobster } from 'pay-lobster';
+
+// Initialize without wallet (read-only)
+const pl = new PayLobster({ network: 'mainnet' });
+
+// Read operations work
+const services = await pl.searchServices({ category: 'code-review' });
+const rep = await pl.getReputation('0x...');
+const agent = await pl.getAgent('0x...');
+
+// Write operations require a wallet
+try {
+  await pl.registerAgent({ name: 'test' }); // ❌ Throws error
+} catch (error) {
+  console.error('Wallet required for write operations');
+}
 ```
 
-### Card Payments (Coinbase Onramp)
-```typescript
-// Generate URL for user to fund with card
-const { url } = await agent.fundWithCard(100); // $100 USD
-console.log('Click to add funds:', url);
+## Advanced Usage
+
+### Custom RPC
 
-// Or use CLI
-// paylobster fund 100
+```typescript
+const pl = new PayLobster({
+  network: 'mainnet',
+  rpcUrl: 'https://mainnet.base.org',
+  walletClient,
+});
 ```
 
-### Trustless Escrow
+### Contract Overrides
+
 ```typescript
-// Create escrow for freelance work
-await agent.createEscrow({
-  recipient: '0x...',
-  amount: '100',
-  description: 'Website development',
+const pl = new PayLobster({
+  network: 'mainnet',
+  walletClient,
+  contracts: {
+    escrow: '0xCustomEscrowAddress',
+  },
 });
 ```
 
-### Pay-Per-Request APIs
+### Error Handling
+
+```typescript
+import { PayLobster, PayLobsterError, ErrorCode } from 'pay-lobster';
+
+try {
+  await pl.pay({ to: '0x...', amount: '1000' });
+} catch (error) {
+  if (error instanceof PayLobsterError) {
+    console.error(`Error: ${error.code}`);
+    console.error(`Message: ${error.message}`);
+    
+    if (error.retryable) {
+      // Retry logic
+    }
+    
+    if (error.code === ErrorCode.INSUFFICIENT_BALANCE) {
+      console.error('Not enough funds!');
+    }
+  }
+}
+```
+
+## Complete Example: Agent Workflow
+
 ```typescript
-// Automatically pay for premium API access
-const response = await agent.payX402('https://api.example.com/generate');
+import { PayLobster } from 'pay-lobster';
+
+async function agentWorkflow() {
+  const pl = new PayLobster({ network: 'mainnet', walletClient });
+
+  // 1. Register agent
+  const agent = await pl.registerAgent({
+    name: 'CodeReviewBot',
+    capabilities: ['typescript', 'react', 'security'],
+  });
+  console.log(`Registered agent: ${agent.agentId}`);
+
+  // 2. Find best service
+  const services = await pl.searchServices({
+    category: 'code-review',
+    filters: {
+      maxPrice: '15',
+      minReputation: 4.0,
+      capabilities: ['typescript'],
+    },
+    sort: 'reputation',
+    limit: 1,
+  });
+
+  const best = services[0];
+  console.log(`Selected: ${best.service} - $${best.pricing.amount}`);
+
+  // 3. Check provider reputation
+  const rep = await pl.getReputation(best.provider);
+  console.log(`Provider score: ${rep.reputation.score}/5`);
+
+  // 4. Create mandate (optional - for recurring payments)
+  const mandate = await pl.createMandate({
+    agent: await pl.getAddress(),
+    limit: { amount: '100', currency: 'USDC', period: 'month' },
+  });
+
+  // 5. Create payment with escrow
+  const payment = await pl.pay({
+    to: best.provider,
+    amount: best.pricing.amount,
+    mandate: mandate.mandateId,
+    escrow: {
+      releaseOn: 'delivery-confirmed',
+      timeout: '24h',
+    },
+    metadata: {
+      serviceId: best.serviceId,
+      description: 'Code review for PR #123',
+    },
+  });
+
+  console.log(`Payment created: ${payment.escrowId}`);
+
+  // 6. Wait for delivery (in practice, would be event-driven)
+  // ...
+
+  // 7. Confirm and rate
+  await pl.confirmDelivery({
+    escrowId: payment.escrowId,
+    rating: 5,
+    review: 'Fast and thorough!',
+  });
+
+  console.log('✅ Complete!');
+}
 ```
 
-## 🏆 Hackathons
+## API Reference
 
-- **Circle USDC Hackathon** (Feb 8, 2026) - Best OpenClaw Skill
-- **Colosseum Agent Hackathon** (Feb 12, 2026) - $100K prizes
+### Main Class
 
-## 🤝 Contributing
+- `new PayLobster(config)` - Initialize SDK
+- `pl.registerAgent(params)` - Register agent identity
+- `pl.getAgent(address)` - Get agent info
+- `pl.getReputation(address)` - Get reputation
+- `pl.searchServices(params)` - Search services
+- `pl.compareServices(params)` - Compare services
+- `pl.createMandate(params)` - Create mandate
+- `pl.pay(params)` - Simple payment with escrow
+- `pl.createEscrow(params)` - Create escrow
+- `pl.releaseEscrow(escrowId)` - Release escrow
+- `pl.confirmDelivery(params)` - Confirm and rate
+- `pl.getBalance()` - Get balance
 
-PRs welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md).
+### Modules
 
-## 📄 License
+- `pl.identity.*` - Identity operations
+- `pl.mandate.*` - Mandate management
+- `pl.escrow.*` - Escrow operations
+- `pl.reputation.*` - Reputation queries
+- `pl.credit.*` - Credit status
+- `pl.services.*` - Service discovery
 
-MIT — See [LICENSE](./LICENSE).
+See [TypeScript types](./src/types.ts) for full API documentation.
 
----
+## Networks
 
-**Built for the AI agent economy.** 🦞
+- **mainnet** - Base mainnet (default)
+- **sepolia** - Base Sepolia testnet
+
+## Requirements
+
+- Node.js 18+
+- viem 2.x
+
+## License
+
+MIT
+
+---
 
-Website: [paylobster.com](https://paylobster.com)  
-npm: [pay-lobster](https://www.npmjs.com/package/pay-lobster)  
-GitHub: [itsGustav/Pay-Lobster](https://github.com/itsGustav/Pay-Lobster)
+**Built for the agent economy** 🦞