agentwallet-sdk 1.0.0 → 2.0.0

package/README.md

@@ -178,6 +178,98 @@ for (const entry of history) {
 | **Arbitrum** | ✅ | DeFi agents |
 | **Polygon** | ✅ | Micropayments |
 
+## x402 Protocol Support
+
+Agent Wallet natively supports the [x402 protocol](https://x402.org) — the open standard for HTTP 402 machine payments. Your agent can automatically pay any x402-enabled API (Stripe, Coinbase, etc.) using USDC on Base, while respecting on-chain spend limits.
+
+### Quick Start
+
+```typescript
+import { createWallet, createX402Client } from 'agentwallet-sdk';
+
+// 1. Create your wallet
+const wallet = createWallet({ accountAddress, chain: 'base', walletClient });
+
+// 2. Create an x402-aware client
+const client = createX402Client(wallet, {
+  globalDailyLimit: 50_000_000n,  // 50 USDC/day
+  globalPerRequestMax: 5_000_000n, // 5 USDC max per request
+  serviceBudgets: [
+    { service: 'api.weather.com', maxPerRequest: 1_000_000n, dailyLimit: 10_000_000n },
+  ],
+});
+
+// 3. Use it like fetch — 402 responses are handled automatically
+const response = await client.fetch('https://api.weather.com/forecast');
+const data = await response.json();
+// If the API returned 402, the client:
+//   - Parsed payment requirements from the PAYMENT-REQUIRED header
+//   - Checked your budget (client-side + on-chain)
+//   - Paid USDC via your AgentWallet contract
+//   - Retried the request with payment proof
+```
+
+### Drop-in Fetch Replacement
+
+```typescript
+import { createX402Fetch } from 'agentwallet-sdk';
+
+const x402Fetch = createX402Fetch(wallet, { globalDailyLimit: 100_000_000n });
+
+// Use exactly like fetch()
+const res = await x402Fetch('https://any-x402-api.com/endpoint');
+```
+
+### Budget Controls
+
+```typescript
+// Check spending
+const summary = client.getDailySpendSummary();
+console.log(`Today's spend: ${summary.global} (resets at ${summary.resetsAt})`);
+
+// View transaction log
+const logs = client.getTransactionLog({ service: 'api.weather.com' });
+
+// Add budget at runtime
+client.budgetTracker.setServiceBudget({
+  service: 'new-api.com',
+  maxPerRequest: 2_000_000n,
+  dailyLimit: 20_000_000n,
+});
+```
+
+### Payment Approval Callback
+
+```typescript
+const client = createX402Client(wallet, {
+  onBeforePayment: async (req, url) => {
+    console.log(`About to pay ${req.amount} to ${req.payTo} for ${url}`);
+    return true; // return false to reject
+  },
+  onPaymentComplete: (log) => {
+    console.log(`Paid ${log.amount} via tx ${log.txHash}`);
+  },
+});
+```
+
+### How x402 Works
+
+```
+Agent → GET /api/data → Server returns 402 + PAYMENT-REQUIRED header
+  ↓
+Client parses payment requirements (amount, token, recipient, network)
+  ↓
+Budget check (client-side caps + on-chain spend limits)
+  ↓
+AgentWallet executes USDC transfer on Base
+  ↓
+Client retries request with X-PAYMENT header (payment proof)
+  ↓
+Server verifies payment → returns 200 + data
+```
+
+Your agent's keys never leave the non-custodial wallet. All payments respect on-chain spend limits set by the wallet owner.
+
 ## How It Works
 
 1. **Deploy** an AgentAccountV2 (ERC-6551 token-bound account tied to an NFT)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwallet-sdk",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "TypeScript SDK for Agent Wallet — autonomous crypto spending for AI agents with user-set limits",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",