agentwallet-sdk 6.0.4 → 6.1.0

package/README.md

@@ -1,29 +1,29 @@
 # AgentWallet SDK
 
-> **⭐ Star us during GTC Week (Mar 15-20) — NVIDIA's NemoClaw launches Monday with no payment primitive. agent-wallet-sdk is the open-source answer. Help us reach record stars during the biggest AI week of 2026.**
+> **v6.0.0** · MIT · **Patent Pending**
+>
+> USPTO Provisional filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents"
 
-Non-custodial AI agent wallet with ERC-8004 on-chain identity, ERC-6551 token-bound accounts, x402 payments, mutual stake escrow, and programmable spending guardrails.
+**Your AI agent needs to pay for things. Giving it your credit card is insane.**
 
-Agent Wallet gives AI agents autonomous spending power with hard on-chain limits. No more choosing between "agent can drain everything" and "every transaction needs manual approval."
-
-> **ERC-8004 Ready:** Maps directly to [ERC-8004 (Trustless Agents)](https://eips.ethereum.org/EIPS/eip-8004) — your agent's ERC-6551 wallet NFT doubles as its on-chain identity handle, with built-in Identity Registry, Reputation Registry, and Validation Registry clients.
+The actual problem: your agent is in a loop, it hits a paid API, and it needs to pay. The naive solution (raw wallet + private key) means one prompt injection or runaway loop drains everything. AgentWallet SDK gives your agent a wallet with hard on-chain spending limits, human approval by default, and no custody of your keys.
 
 ```
-Agent wants to spend $15 → ✅ Auto-approved (under $25 limit)
-Agent wants to spend $500 → ⏳ Queued for your approval
-Agent spent $490 today → 🛑 Next tx queued ($500/day limit hit)
+Agent wants to spend $0.50  → ✅ Auto-approved (under your $1/tx threshold)
+Agent wants to spend $50    → ⏳ Queued — you get notified to approve or reject
+Agent spent $9.50 today     → 🛑 Next tx blocked ($10/day cap hit)
 ```
 
-## Why Agent Wallet?
+The caps are enforced by smart contract. Application code — including the agent itself — cannot override them.
+
+## Why Not Just Give the Agent a Wallet?
 
 | Approach | Problem |
 |----------|---------|
-| Raw EOA wallet | Agent can drain everything. One prompt injection = rugged. |
-| Multisig (Safe) | Every tx needs human sigs. Kills agent autonomy. |
-| Custodial API (Stripe) | Centralized, KYC friction, not crypto-native. |
-| **Agent Wallet** | **Agents spend freely within limits. Everything else queues for approval.** |
-
-Built on **ERC-6551** (token-bound accounts). Your agent's wallet is tied to an NFT — portable, auditable, fully on-chain.
+| Raw EOA wallet | One prompt injection or loop bug = everything drained |
+| Multisig (Safe) | Every transaction needs manual signatures — kills the point of automation |
+| Custodial API | Centralized, KYC friction, not crypto-native |
+| **AgentWallet SDK** | **On-chain limits + human approval threshold + non-custodial. Agent spends within bounds; everything else queues.** |
 
 ## Quick Start
 
@@ -31,447 +31,504 @@ Built on **ERC-6551** (token-bound accounts). Your agent's wallet is tied to an
 npm install agentwallet-sdk viem
 ```
 
-### Create a Wallet
-
-The `chain` parameter selects which network the wallet operates on. Supported values:
-`'base'` | `'ethereum'` | `'arbitrum'` | `'polygon'` | `'optimism'` | `'avalanche'` |
-`'unichain'` | `'linea'` | `'sonic'` | `'worldchain'` | `'base-sepolia'`
+### Set Up a Wallet with Spend Caps
 
 ```typescript
-import { createWallet, setSpendPolicy, agentExecute, NATIVE_TOKEN } from 'agentwallet-sdk';
+import { createWallet, setSpendPolicy, NATIVE_TOKEN } from 'agentwallet-sdk';
 import { createWalletClient, http } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { base } from 'viem/chains';
 
-const account = privateKeyToAccount('0x...');
+const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
 const walletClient = createWalletClient({ account, chain: base, transport: http() });
 
 const wallet = createWallet({
-  accountAddress: '0xYourAgentWallet',
-  chain: 'base',  // or 'arbitrum', 'polygon', 'optimism', etc.
+  accountAddress: process.env.AGENT_WALLET_ADDRESS as `0x${string}`,
+  chain: 'base',
   walletClient,
 });
 
-// Set a $25/tx, $500/day spend policy for ETH
+// Spend policy — lives on-chain, not in your app code
+// Agent cannot spend more than this even if instructed to
 await setSpendPolicy(wallet, {
-  token: NATIVE_TOKEN,
-  perTxLimit: 25000000000000000n,  // 0.025 ETH
-  periodLimit: 500000000000000000n, // 0.5 ETH
-  periodLength: 86400,
-});
-
-// Agent executes — auto-approved if within limits, queued if over
-const result = await agentExecute(wallet, {
-  to: '0xRecipient',
-  value: 10000000000000000n, // 0.01 ETH
+  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
+  perTxLimit: 5_000_000n,    // $5 max per transaction
+  periodLimit: 50_000_000n,  // $50/day hard cap
+  periodLength: 86400,       // resets every 24 hours
 });
-console.log(result.executed ? 'Sent!' : 'Queued for approval');
 ```
 
-## Multi-Chain x402 Payments
-
-Pay any x402-gated API from any supported chain. The client automatically selects
-the correct USDC address for the network the server requests.
+### Pay for an API (the 402 Flow)
 
 ```typescript
-import { createWallet, createX402Client } from 'agentwallet-sdk';
-import { createWalletClient, http } from 'viem';
-import { privateKeyToAccount } from 'viem/accounts';
-import { arbitrum } from 'viem/chains';
-
-const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
-const walletClient = createWalletClient({ account, chain: arbitrum, transport: http() });
-
-// Wallet on Arbitrum — pays with Arbitrum USDC
-const wallet = createWallet({
-  accountAddress: '0xYourAgentWallet',
-  chain: 'arbitrum',
-  walletClient,
-});
+import { createX402Client } from 'agentwallet-sdk';
 
 const x402 = createX402Client(wallet, {
-  // Accept payment requests on any supported mainnet chain
-  supportedNetworks: ['arbitrum:42161', 'base:8453', 'optimism:10', 'polygon:137'],
-  globalDailyLimit: 10_000_000n, // 10 USDC/day cap
-  globalPerRequestMax: 1_000_000n, // 1 USDC max per request
+  supportedNetworks: ['base:8453'],
+  globalDailyLimit: 50_000_000n,    // matches spend policy
+  globalPerRequestMax: 5_000_000n,  // $5 max per request
+  requireApproval: true,            // human-in-the-loop (default)
 });
 
-// Automatically pays 402 responses with the chain's native USDC
-const response = await x402.fetch('https://api.example.com/premium-data');
+// Agent hits a premium API and gets 402 — SDK handles it
+const response = await x402.fetch('https://api.example.com/premium-report');
 const data = await response.json();
+// Cost: $0.50 USDC, auto-approved (under $5 threshold)
+// Every payment: tx hash on Base, auditable on basescan.org
 ```
 
-## Multi-Chain Swaps (Uniswap V3)
+## The Trust Layer
 
-Swap tokens on Base, Arbitrum, Optimism, or Polygon using the best Uniswap V3 pool.
+This is what makes supervised payments different from autonomous payments.
 
-```typescript
-import { createWallet } from 'agentwallet-sdk';
-import { attachSwap } from 'agentwallet-sdk/swap';
-import { BASE_TOKENS, ARBITRUM_TOKENS } from 'agentwallet-sdk';
+### Simulation Mode
 
-// Swap on Base
-const baseWallet = createWallet({ accountAddress: '0x...', chain: 'base', walletClient });
-const baseSwap = attachSwap(baseWallet, { chain: 'base' });
+Before any real payment, run in simulation to see exactly what would happen:
 
-const result = await baseSwap.swap(BASE_TOKENS.WETH, BASE_TOKENS.USDC, 1_000_000_000_000_000n, {
-  slippageBps: 50, // 0.5% slippage
+```typescript
+const x402 = createX402Client(wallet, {
+  supportedNetworks: ['base:8453'],
+  globalDailyLimit: 50_000_000n,
+  globalPerRequestMax: 5_000_000n,
+  dryRun: true,  // no funds move
 });
-console.log('Swap tx:', result.txHash);
 
-// Swap on Arbitrum
-const arbWallet = createWallet({ accountAddress: '0x...', chain: 'arbitrum', walletClient });
-const arbSwap = attachSwap(arbWallet, { chain: 'arbitrum' });
-
-const arbResult = await arbSwap.swap(ARBITRUM_TOKENS.USDC, ARBITRUM_TOKENS.WETH, 5_000_000n, {
-  slippageBps: 30,
-});
-console.log('Arbitrum swap tx:', arbResult.txHash);
+const response = await x402.fetch('https://api.example.com/premium-report');
+// Response: { simulated: true, wouldHavePaid: '0.50 USDC', withinLimits: true, dailyTotal: '2.00 USDC' }
 ```
 
-## CCTP V2 Bridge — EVM to EVM
-
-Bridge USDC between any of the 10 supported EVM chains using Circle's CCTP V2.
+### Human Approval for High-Value Payments
 
 ```typescript
-import { createBridge } from 'agentwallet-sdk';
-import { createWalletClient, http } from 'viem';
-import { base } from 'viem/chains';
+import { createWallet, agentExecute } from 'agentwallet-sdk';
 
-const walletClient = createWalletClient({
-  account: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`),
-  chain: base,
-  transport: http(),
+// Transactions above your per-tx limit queue for approval
+const result = await agentExecute(wallet, {
+  to: '0xRecipient',
+  value: 50_000_000_000_000_000n, // 0.05 ETH (~$130)
 });
 
-const bridge = createBridge(walletClient, 'base');
-
-// Bridge 100 USDC from Base to Arbitrum (~12 seconds with FAST finality)
-const result = await bridge.bridge(100_000_000n, 'arbitrum', {
-  minFinalityThreshold: 0, // FAST attestation
-});
-console.log('Burn tx:', result.burnTxHash);
-console.log('Mint tx:', result.mintTxHash);
-console.log(`Completed in ${result.elapsedMs}ms`);
+if (result.executed) {
+  console.log('Sent:', result.txHash);
+} else {
+  console.log('Queued for approval — tx ID:', result.queueId);
+  // Your approval system gets notified; agent waits or continues other work
+}
 ```
 
-## CCTP V2 Bridge — EVM to Solana
+### Explainability — Agent Must Show Its Work
 
-Bridge USDC from any EVM chain to Solana using CCTP V2 domain 5.
-The EVM burn side is handled automatically; the Solana receive is returned
-as `messageBytes` + `attestation` for submission to Solana's CCTP program.
+Before any payment above your threshold, the agent surfaces:
+- What it's paying for
+- What the expected outcome is
+- What it will do if the payment fails
 
 ```typescript
-import { bridgeEVMToSolana } from 'agentwallet-sdk';
-import { createWalletClient, http } from 'viem';
-import { base } from 'viem/chains';
+const paymentIntent = {
+  url: 'https://api.example.com/market-data',
+  amount: '2.00 USDC',
+  reason: 'Fetching historical price data for AAPL 2023-2024',
+  expectedOutcome: 'CSV with daily OHLCV data, ~500 rows',
+  fallback: 'Use cached data from 2024-01-15 (3 months old)',
+};
+
+// Human sees this before approving anything above threshold
+const approved = await requestHumanApproval(paymentIntent);
+if (!approved) {
+  return useFallback(paymentIntent.fallback);
+}
+```
 
-const walletClient = createWalletClient({
-  account: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`),
-  chain: base,
-  transport: http(),
-});
+### Safe Abort
 
-// Bridge 50 USDC from Base to Solana
-const result = await bridgeEVMToSolana(walletClient, 50_000_000n, {
-  fromChain: 'base',
-  solanaRecipient: 'YourSolanaWalletAddressInBase58',
-  minFinalityThreshold: 0, // FAST (~12s)
-});
+When a payment fails or is rejected, the agent handles it gracefully — not by retrying indefinitely:
 
-console.log('EVM burn tx:', result.burnTxHash);
-console.log('Attestation ready — submit to Solana TokenMessengerMinterV2');
-console.log('Message bytes:', result.messageBytes);
-console.log('Attestation:', result.attestation);
-// Submit result.messageBytes + result.attestation to the Solana CCTP V2 program:
-// CCTPV2Sm4AdWt5296sk4P66VBZ7bEhcARwFaaS9YPbeC (MessageTransmitterV2)
+```typescript
+const result = await x402.fetch('https://api.example.com/premium-data');
+
+if (!result.ok) {
+  switch (result.status) {
+    case 402:
+      // Payment rejected or limit hit — fall back to free alternative
+      return await fetchFreeAlternative();
+    case 'limit-exceeded':
+      // Daily cap hit — log it, stop trying today
+      console.log('Daily spend cap reached. Resuming tomorrow.');
+      return null;
+    case 'approval-rejected':
+      // Human said no — respect that
+      console.log('Payment rejected by human. Using cached data.');
+      return getCachedResult();
+  }
+}
 ```
 
-## CCTP V2 Bridge — Solana to EVM
+## Production-Ready: Failure Handling, Retries, Fallbacks
 
-Receive USDC on an EVM chain from a Solana burn transaction.
+Real agent deployments fail. Here's how to handle it.
 
-```typescript
-import { receiveFromSolanaOnEVM } from 'agentwallet-sdk';
-
-// After initiating a burn on Solana, receive on EVM:
-const result = await receiveFromSolanaOnEVM(walletClient, {
-  messageBytes: '0x...', // from Solana burn transaction
-  messageHash: '0x...',  // keccak256 of messageBytes
-  sourceDomain: 5,       // Solana CCTP domain
-}, {
-  toChain: 'arbitrum',
-  evmRecipient: '0xYourEVMAddress',
-});
+### Retry with Backoff
 
-console.log('Mint tx:', result.mintTxHash);
-console.log('Received:', result.amount, 'USDC base units on', result.toChain);
+```typescript
+import { createX402Client } from 'agentwallet-sdk';
+
+async function fetchWithRetry(
+  x402: ReturnType<typeof createX402Client>,
+  url: string,
+  maxAttempts = 3,
+): Promise<Response> {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const response = await x402.fetch(url);
+      if (response.ok) return response;
+
+      // Don't retry on rejected payments or limit hits
+      if (['limit-exceeded', 'approval-rejected'].includes(response.status as string)) {
+        throw new Error(`Payment stopped: ${response.status}`);
+      }
+    } catch (err) {
+      if (attempt === maxAttempts) throw err;
+      // Exponential backoff: 1s, 2s, 4s
+      await new Promise(resolve => setTimeout(resolve, 1000 * 2 ** (attempt - 1)));
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
 ```
 
-## ERC-8004 On-Chain Identity
+### Fallback to Free Data Sources
 
-Register your agent on the ERC-8004 Identity Registry — a portable, censorship-resistant on-chain identity using ERC-721.
+```typescript
+async function getMarketData(symbol: string): Promise<MarketData> {
+  // Try paid source first (better data quality)
+  try {
+    const response = await fetchWithRetry(x402, `https://paid-api.com/data/${symbol}`);
+    return await response.json();
+  } catch (err) {
+    console.warn(`Paid API unavailable: ${err.message}. Falling back to free source.`);
+    // Fall back to free source (rate-limited, less complete)
+    const fallback = await fetch(`https://free-api.com/data/${symbol}`);
+    return await fallback.json();
+  }
+}
+```
+
+### Budget Guard — Stop Before You Hit the Cap
 
 ```typescript
-import { ERC8004Client } from 'agentwallet-sdk';
+import { getRemainingBudget } from 'agentwallet-sdk';
+
+async function checkBudgetBeforeLoop(wallet: Wallet, estimatedCostPerCall: bigint, callCount: number) {
+  const remaining = await getRemainingBudget(wallet, '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+  const estimatedTotal = estimatedCostPerCall * BigInt(callCount);
+
+  if (estimatedTotal > remaining) {
+    const maxCalls = Number(remaining / estimatedCostPerCall);
+    console.warn(`Budget allows ${maxCalls} of ${callCount} planned calls. Adjusting.`);
+    return maxCalls;
+  }
+  return callCount;
+}
+```
 
-const identity = new ERC8004Client({ chain: 'base' });
+## Non-Custodial Architecture
 
-// Register agent
-const { txHash, agentId } = await identity.registerAgent(walletClient, {
-  name: 'MyAgent',
-  description: 'Autonomous trading agent',
-});
+Your private key never leaves your infrastructure. The SDK interacts with on-chain contracts; no third party holds or validates your keys.
 
-// Look up any agent
-const agent = await identity.lookupAgentIdentity(agentId!);
-console.log(agent.owner, agent.agentURI);
+```
+Your Infrastructure          On-Chain
+─────────────────────        ────────────────────────────────────
+  Agent process              AgentAccountV2 contract
+  ├── private key (local)    ├── SpendingPolicy (your limits)
+  ├── agentwallet-sdk        ├── Tx queue (over-limit txs)
+  └── signs transactions     └── Audit log (immutable)
+        │                          ▲
+        └──── broadcasts ──────────┘
 ```
 
-## ERC-8004 Reputation Registry
+**What this means:** If you stop using AgentWallet SDK tomorrow, your wallets, keys, and on-chain limits continue to work with any Ethereum-compatible tool. No vendor lock-in.
 
-On-chain reputation signals — scored feedback from clients, aggregated summaries, revocable.
+## Token Registry
+
+80+ verified token addresses across 11 EVM chains + Solana. No hard-coded contract addresses.
 
 ```typescript
-import { ReputationClient } from 'agentwallet-sdk';
+import { getGlobalRegistry } from 'agentwallet-sdk';
 
-const reputation = new ReputationClient({ chain: 'base' });
+const registry = getGlobalRegistry();
 
-// Leave feedback for an agent
-await reputation.giveFeedback(walletClient, {
-  agentId: 42n,
-  score: 95n,
-  category: 1,
-  comment: 'Fast execution, accurate results',
-  taskRef: 'task-abc-123',
-  verifierRef: '',
-  clientRef: '',
-  contentHash: '0x0000000000000000000000000000000000000000000000000000000000000000',
-});
+const usdc = registry.getToken('USDC', 8453); // Base chain ID
+console.log(usdc?.address); // 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
 
-// Read aggregated reputation
-const rep = await reputation.getAgentReputation(42n);
-console.log(`Score: ${rep.totalScore} from ${rep.count} reviews`);
+const baseTokens = registry.listTokens(8453);
+// ['USDC', 'USDT', 'DAI', 'WETH', 'WBTC', 'LINK', 'UNI', 'AAVE', ...]
 ```
 
-## ERC-8004 Validation Registry
-
-Request and receive on-chain validation from validator contracts (TEE attestations, capability proofs, compliance checks).
+## Multi-Token Transfers
 
 ```typescript
-import { ValidationClient } from 'agentwallet-sdk';
-import { keccak256, toBytes } from 'viem';
+import { sendToken, sendNative, getTokenBalance, getBalances } from 'agentwallet-sdk';
 
-const validation = new ValidationClient({
-  chain: 'base',
-  validationAddress: '0xYourValidationRegistry', // address required until official deployment
+// Send 100 USDC — no manual decimal math
+const txHash = await sendToken(wallet, {
+  symbol: 'USDC',
+  to: '0xRecipient',
+  amount: '100',  // → internally 100_000_000 (6 decimals)
 });
 
-// Request validation from a validator
-const requestHash = keccak256(toBytes('my-validation-request-v1'));
-await validation.requestValidation(walletClient, {
-  validator: '0xValidatorContract',
-  agentId: 42n,
-  requestURI: 'https://example.com/validation-spec.json',
-  requestHash,
-});
+// Check balances
+const usdcBalance = await getTokenBalance(wallet, 'USDC');
+console.log(usdcBalance); // "250.00"
 
-// Check validation status
-const status = await validation.getValidationStatus(requestHash);
-console.log(status.responded ? `Result: ${status.response}` : 'Pending');
+const allBalances = await getBalances(wallet);
+// [{ symbol: 'USDC', balance: '250.00', raw: 250000000n }, ...]
+```
+
+## Multi-Chain Support
 
-// Get summary for an agent
-const summary = await validation.getSummary(42n);
-console.log(`${summary.passCount} passed, ${summary.failCount} failed`);
+```typescript
+// Same API across chains — just change 'chain'
+const wallet = createWallet({
+  accountAddress: '0x...',
+  chain: 'arbitrum',  // or 'base', 'polygon', 'optimism', etc.
+  walletClient,
+});
 ```
 
-## Mutual Stake Escrow
+| Chain | x402 | Bridge | Swap |
+|-------|:----:|:------:|:----:|
+| Base (recommended) | ✅ | ✅ | ✅ |
+| Arbitrum | ✅ | ✅ | ✅ |
+| Optimism | ✅ | ✅ | ✅ |
+| Polygon | ✅ | ✅ | ✅ |
+| Ethereum | ✅ | ✅ | — |
+| Avalanche | ✅ | ✅ | — |
+| Unichain, Linea, Sonic, Worldchain | ✅ | ✅ | — |
+| Base Sepolia (testnet) | ✅ | — | — |
 
-Reciprocal collateral for agent-to-agent task settlement. Both parties stake, both lose if the task fails.
+## Uniswap V3 Swaps
 
 ```typescript
-import { MutualStakeEscrow } from 'agentwallet-sdk';
+import { attachSwap } from 'agentwallet-sdk/swap';
+import { BASE_TOKENS } from 'agentwallet-sdk';
 
-const escrow = new MutualStakeEscrow({
-  chain: 'base',
-  walletClient,
-});
+const swap = attachSwap(wallet, { chain: 'base' });
 
-// Create escrow — both agent and client stake
-const { escrowId, txHash } = await escrow.create({
-  counterparty: '0xOtherAgent',
-  token: '0xUSDC',
-  stakeAmount: 100000000n, // 100 USDC
-  taskHash: '0x...',
-  deadline: BigInt(Math.floor(Date.now() / 1000) + 86400),
+const result = await swap.swap(BASE_TOKENS.USDC, BASE_TOKENS.WETH, 100_000_000n, {
+  slippageBps: 50, // 0.5% slippage
 });
+console.log('Swap tx:', result.txHash);
+```
 
-// Counterparty funds their side
-await escrow.fund(escrowId);
+## CCTP V2 Bridging
 
-// After task completion, fulfill
-await escrow.fulfill(escrowId, proofHash);
+```typescript
+import { createBridge } from 'agentwallet-sdk';
+
+const bridge = createBridge(walletClient, 'base');
 
-// Verify and release stakes
-await escrow.verify(escrowId);
+// Bridge 100 USDC Base → Arbitrum (~12 seconds)
+const result = await bridge.bridge(100_000_000n, 'arbitrum', {
+  minFinalityThreshold: 0, // FAST attestation
+});
+console.log('Completed in', result.elapsedMs, 'ms');
+// Verified mainnet: Base → Arbitrum 0.50 USDC
+// Burn: 0xfedbfaa4b3a9fbadd36668c50c2ee7fc7e32072e2bd409e00c46020a35329129
 ```
 
-## Feature Tiers
+## Solana SPL Support
 
-### Base (Free)
+```bash
+npm install @solana/web3.js @solana/spl-token
+```
 
-| Feature | Status | Description |
-|---------|--------|-------------|
-| Agent Identity | ✅ Live | ERC-8004 Identity Registry — on-chain ERC-721 agent IDs |
-| Agent Reputation | ✅ Live | ERC-8004 Reputation Registry — scored feedback and summaries |
-| Agent Validation | ✅ Live | ERC-8004 Validation Registry — validator request/response |
-| ERC-6551 TBA | ✅ Live | NFT-bound wallets with autonomous spending |
-| Mutual Stake Escrow | ✅ Live | Reciprocal collateral task settlement |
-| Optimistic Escrow | ✅ Live | Time-locked optimistic verification |
-| x402 Payments | ✅ Live | HTTP 402 auto-pay — Base, Ethereum, Arbitrum, Polygon, Optimism, Avalanche, Unichain, Linea, Sonic, Worldchain |
-| CCTP Bridge (EVM) | ✅ Live | Circle CCTP V2 across 10 EVM chains |
-| CCTP Bridge (Solana) | ✅ Live | EVM↔Solana USDC bridging via CCTP V2 domain 5 |
-| Spend Policies | ✅ Live | Per-token, per-period on-chain spending limits |
-| Swap | ✅ Live | Uniswap V3 on Base, Arbitrum, Optimism, Polygon |
-| Fiat Onramp | ✅ Live | Opt-in fiat-to-crypto |
-| AP2 Protocol | ✅ Live | Agent-to-Agent task delegation and payment |
-| Settlement | ✅ Live | On-chain settlement finalization |
-| Gas Sponsorship | ✅ Live | ERC-4337 paymaster-based gas sponsorship |
+```typescript
+import { SolanaWallet } from 'agentwallet-sdk/tokens/solana';
 
-### Premium
+const solWallet = new SolanaWallet({
+  privateKeyBase58: process.env.SOLANA_PRIVATE_KEY!,
+});
 
-| Feature | Description |
-|---------|-------------|
-| CowSwap Solver | Batch auction solutions, earn COW tokens |
-| Flash Executor | Atomic flash loan execution |
-| MEV Protection | Private mempool via Flashbots/MEV Blocker |
-| Yield Staking | Aave V3, Compound V3, Morpho Blue strategies |
-| Tax Reporting | Cost basis and gain/loss reporting |
+const { sol } = await solWallet.getSolBalance();
+const sig = await solWallet.sendSol('RecipientBase58Address', 0.1);
 
-Premium access: [github.com/up2itnow/AgentNexus2](https://github.com/up2itnow/AgentNexus2)
+// USDC on Solana
+const usdcMint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const { amount, decimals } = await solWallet.getSplTokenBalance(usdcMint);
+```
 
-## x402 Protocol: Supported Chains and Payment Rails
+## On-Chain Identity (ERC-8004)
 
-x402 (HTTP 402 Payment Required) is the native payment protocol for agent-to-service transactions. The agent encounters a 402 response, signs a payment proof, and re-sends the request. One round trip. No accounts, no API keys, no invoices.
+```typescript
+import { ERC8004Client, ReputationClient } from 'agentwallet-sdk';
 
-As of March 2026, x402 is live on 3 chains/rails:
+const identity = new ERC8004Client({ chain: 'base' });
+const { txHash, agentId } = await identity.registerAgent(walletClient, {
+  name: 'MyAgent',
+  description: 'Autonomous research agent',
+});
+
+const reputation = new ReputationClient({ chain: 'base' });
+const rep = await reputation.getAgentReputation(agentId!);
+console.log(`Score: ${rep.totalScore} from ${rep.count} reviews`);
+```
 
-| Chain / Rail | Status | Settlement Token | Gas Cost | Notes |
-|---|---|---|---|---|
-| **Base** (Coinbase L2) | Live | USDC | Sub-cent | Primary x402 chain. 15M+ transactions in Jan 2026. |
-| **Etherlink** (Tezos L2) | Live (Mar 2026) | USDC | Sub-cent | EVM-compatible. Same x402 integration, different RPC + chain ID. |
-| **Stripe** (Fiat offramp) | Live (Feb 2026) | USDC -> USD | N/A | Vendors receive USD in Stripe dashboard. Agents pay USDC. |
+## Cross-Chain Identity (UAID)
 
-### x402 + Etherlink Quick Start
+ERC-8004 identities live on EVM chains. For agents on Solana, Hedera, or off-chain frameworks, the UAID (Universal Agent Identifier) resolver bridges identities across all chains via the [HOL Registry](https://hol.org).
 
 ```typescript
-import { createWallet, agentExecute } from 'agentwallet-sdk';
+import { UAIDResolver, ERC8004Client } from 'agentwallet-sdk';
 
-const wallet = createWallet({
-  accountAddress: '0xYourAgent',
-  chain: 'etherlink',  // new: Tezos L2 support
-  walletClient,
-});
+const resolver = new UAIDResolver();
 
-// x402 payment flow is identical across chains
-const response = await fetch('https://api.vendor.com/data');
-if (response.status === 402) {
-  const details = await response.json();
-  const proof = await wallet.createX402Proof(details);
-  const paid = await fetch('https://api.vendor.com/data', {
-    headers: { 'X-Payment': proof }
-  });
+// Resolve any agent by UAID — works across all chains
+const result = await resolver.resolve(
+  'uaid:aid:eip155:8453:0x8004...;uid=42;proto=erc8004'
+);
+if (result.resolved) {
+  console.log(result.identity?.paymentAddress); // Payment address, any chain
+  console.log(result.trustScore);               // Trust score (0-100)
 }
+
+// Convert your ERC-8004 identity to universal format
+const erc8004 = new ERC8004Client({ chain: 'base' });
+const identity = await erc8004.lookupAgentIdentity(42n);
+const universal = resolver.erc8004ToUniversal(identity, 'base');
+console.log(universal.uaid); // Cross-chain discoverable ID
+
+// Verify any agent before transacting (chain-agnostic)
+const check = await resolver.verify('uaid:aid:hedera:0.0.5678;uid=x;proto=openconvai');
+if (check.verified) { /* safe to transact */ }
+
+// Register for cross-chain discovery (requires HOL API key)
+const registrar = new UAIDResolver({ apiKey: process.env.HOL_API_KEY });
+const uaid = await registrar.registerERC8004Agent({
+  agentId: 42n, chain: 'base',
+  name: 'My Agent', description: 'Trading agent with x402 support',
+});
 ```
 
-The SDK handles chain-specific RPC endpoints, gas estimation, and USDC contract addresses automatically. Swap `chain: 'base'` to `chain: 'etherlink'` and the x402 flow works identically.
+See [`examples/cross-chain-identity.ts`](./examples/cross-chain-identity.ts) for the full walkthrough.
 
-## Cross-Chain Bridge — Verified on Mainnet
+## Decimal Helpers
 
-Live CCTP V2 bridge transfers verified on mainnet (March 15, 2026):
+```typescript
+import { toRaw, toHuman, formatBalance } from 'agentwallet-sdk';
 
-| Route | Amount | Burn Tx (Base) | Status |
-|-------|--------|---------------|--------|
-| Base → Arbitrum | 0.50 USDC | [`0xfedb...9129`](https://basescan.org/tx/0xfedbfaa4b3a9fbadd36668c50c2ee7fc7e32072e2bd409e00c46020a35329129) | ✅ Confirmed — [0.50 USDC received on Arbitrum](https://arbiscan.io/address/0xff86829393C6C26A4EC122bE0Cc3E466Ef876AdD) |
+const raw = toRaw('100.50', 6);        // → 100_500_000n
+const human = toHuman(100_500_000n, 6); // → "100.5"
+const display = formatBalance(100_500_000n, 6, 'USDC', 2); // → "100.50 USDC"
+```
 
-Bridge uses Circle CCTP V2 `depositForBurn` with fast finality (minFinalityThreshold=0). USDC is burned on the source chain and minted natively on the destination — no wrapped tokens, no liquidity pools.
+## Security Model
 
-```typescript
-import { CctpBridgeClient } from 'agentwallet-sdk';
+**What the on-chain spend policy enforces:**
 
-const bridge = new CctpBridgeClient({
-  sourceChain: 'base',
-  walletClient,
-});
+Even if an agent is compromised (prompt injection, jailbreak, runaway loop), it cannot:
+1. Spend more than the per-transaction limit you set
+2. Exceed the daily/weekly cap you configured
+3. Access funds outside its ERC-6551 token-bound account
+4. Modify its own spend policy (only the owner wallet can do that)
 
-// Bridge USDC from Base to Arbitrum
-const { txHash } = await bridge.bridge({
-  destinationChain: 'arbitrum',
-  recipient: '0xff86829393C6C26A4EC122bE0Cc3E466Ef876AdD',
-  amount: 500000n, // 0.50 USDC
-});
+**Recommendation:** Start with $1/tx, $10/day. Raise caps only after you've watched the agent run for a week and it behaves exactly as expected.
+
+Key management: your private key stays in your infrastructure. Compatible with Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, or local encrypted storage.
+
+## Enterprise Deployment
+
+The SDK runs in your infrastructure — no third-party custody, no shared key management, no data leaving your network.
+
+```bash
+# Docker deployment
+docker run \
+  -e WALLET_PRIVATE_KEY_FILE=/secrets/key \
+  -e RPC_URL=https://mainnet.base.org \
+  -v /path/to/secrets:/secrets:ro \
+  agentwallet-sdk:latest
 ```
 
-## Supported Chains
+Stateless design — wallet state lives on-chain, not in application memory. Multiple SDK instances can safely share a wallet address. Nonce management handled.
 
-### x402 Payments & Swap (USDC)
-| Chain | Network ID | x402 | Bridge | Swap |
-|-------|-----------|------|--------|------|
-| Base | 8453 | ✅ | ✅ | ✅ |
-| Ethereum | 1 | ✅ | ✅ | — |
-| Arbitrum | 42161 | ✅ | ✅ | ✅ |
-| Polygon | 137 | ✅ | ✅ | ✅ |
-| Optimism | 10 | ✅ | ✅ | ✅ |
-| Avalanche | 43114 | ✅ | ✅ | — |
-| Unichain | 130 | ✅ | ✅ | — |
-| Linea | 59144 | ✅ | ✅ | — |
-| Sonic | 146 | ✅ | ✅ | — |
-| World Chain | 480 | ✅ | ✅ | — |
-| Solana | — | — | ✅ (CCTP) | — |
-| Base Sepolia | 84532 | ✅ (testnet) | — | — |
+### Key compliance properties
+- All private keys generated and stored locally — no external key management service
+- No telemetry, analytics, or usage data transmitted to any third party
+- Every transaction on-chain with block number, timestamp, and gas cost — immutable audit log
+- SpendingPolicy changes are on-chain events — tamper-proof
+- NFT transfer = instant revocation of all agent permissions — no "forgot to deprovision" risk
 
-All USDC addresses are native Circle USDC (not bridged variants).
+## Supported Payment Rails — Three-Rail Architecture
 
-## Complete Agent Identity Stack (v5.1.0)
+AgentWallet SDK routes payments across three independent rails, selecting the optimal one based on amount, session context, autonomy level, and ecosystem preference:
 
-One npm install now gives any AI agent a wallet, email address, on-chain ID, reputation, and signed payment intents.
+| Rail | Status | Use Case | Overhead |
+|------|--------|----------|----------|
+| ✅ **x402** (Base, EVM) | **Live** | Autonomous micropayments, API access, agent-to-agent commerce | 0 bps (no protocol fee) |
+| ✅ **Stripe MPP** | **Live** | High-frequency session payments, fiat-connected merchants, dispute resolution | ~290 bps |
+| 🔜 **Google AP2** | **Roadmap** | Google-managed identity + payment bundle, enterprise SSO integration | ~100 bps (est.) |
+| 🔜 **Solana x402** | **Roadmap Q2** | Solana-native agent payments via Solana Foundation gateway | 0 bps |
 
-| Component | What It Does |
-|-----------|-------------|
-| **EmailResolver** *(NEW)* | AgentMail integration — agents get `email@agentmail.to` linked to wallet. Resolve email→wallet, send/receive with embedded x402 payment requests. |
-| **AgentIdentity** | ERC-8004 + ERC-6551: on-chain NFT identity + Token Bound Account |
-| **ReputationClient** | On-chain reputation scoring — give/read feedback, aggregate scores |
-| **VerifiableIntentClient** | Mastercard-spec signed payment intents with scope enforcement |
-| **ValidationClient** | Request/respond validation workflow (TEE attestations, compliance) |
+### How the Router Decides
 
-### EmailResolver Quick Start
+The `PaymentRouter` evaluates each transaction and selects the rail automatically:
 
-```typescript
-import { EmailResolver } from 'agentwallet-sdk';
+- **Micropayments (< $1) + autonomous agent** → x402 (zero overhead, on-chain audit)
+- **High-frequency session (5+ txns)** → MPP (batching efficiency)
+- **Larger amounts or supervised agent** → MPP (fiat rails, dispute resolution)
+- **Google ecosystem preference** → Google AP2 (when live — managed identity + payment)
+- **Solana preference** → x402-solana (when live)
 
-const resolver = new EmailResolver();
+AgentWallet SDK is the **multi-rail abstraction layer** — your agent code doesn't change when you add a new payment rail. Write once, pay on any chain or protocol.
 
-// Resolve an agent email to its wallet address
-const wallet = await resolver.resolveEmail('myagent@agentmail.to');
-console.log(wallet.address); // 0x...
+```typescript
+import { createX402Client } from 'agentwallet-sdk';
 
-// Send a payment request embedded in an email
-await resolver.sendWithPayment({
-  to: 'vendor@agentmail.to',
-  subject: 'Payment for API access',
-  amount: 5_000_000n, // 5 USDC
-  token: 'USDC',
-  chain: 'base',
+// Same API regardless of underlying rail
+const client = createX402Client(wallet, {
+  supportedNetworks: ['base:8453'],  // Solana coming soon
+  globalDailyLimit: 50_000_000n,
 });
 ```
 
+## Open Wallet Standard (OWS) Compatibility
+
+AgentWallet SDK is designed to work **on top of** [MoonPay's Open Wallet Standard](https://github.com/moonpay/open-wallet-standard) — not compete with it. OWS handles wallet key management (multi-chain signing, hardware-backed vaults, encrypted local storage). AgentWallet SDK handles everything above that: MCP integration, framework abstraction, spend-policy enforcement, payment routing, and human-in-the-loop approval.
+
+**The complete stack:**
+
+| Layer | Component | Responsibility |
+|-------|-----------|---------------|
+| Wallet & Key Management | **Open Wallet Standard (OWS)** | Multi-chain signing, hardware-backed keys (Ledger), encrypted vault, policy engine |
+| Framework & Integration | **AgentWallet SDK** | On-chain spend limits, payment routing (x402/MPP/AP2), human approval, framework adapters |
+| MCP Server | **[agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp)** | MCP-native payment tools for any MCP-compatible agent |
+
+If your agent framework or wallet provider already implements OWS, AgentWallet SDK plugs in as the payment execution and policy layer. Your agent gets supervised spending, multi-rail routing, and auditable on-chain payments without replacing your existing key management.
+
+## Market Context
+
+The agentic AI SDK market is projected to grow from **$2.4B (2025) to $16B by 2030** (Mordor Intelligence). AI agents are forecast to drive **$262B in bank sales** via embedded payments and lending by 2026. x402 alone has processed **140M+ agent payment transactions** ($43M) in 9 months, with 98.6% USDC settlement.
+
+AgentWallet SDK is [production-validated with NVIDIA NeMo](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) — demonstrating enterprise-grade agent payment integration at scale. NVIDIA reports 88% revenue impact and 87% cost reduction from AI agent deployments.
+
 ## Links
 
-- [ERC-8004 Spec](https://eips.ethereum.org/EIPS/eip-8004)
 - [GitHub](https://github.com/up2itnow0822/agent-wallet-sdk)
 - [npm](https://www.npmjs.com/package/agentwallet-sdk)
+- [ERC-8004 Spec](https://eips.ethereum.org/EIPS/eip-8004)
+- [Open Wallet Standard](https://github.com/moonpay/open-wallet-standard) — wallet key management layer
+- [HOL Registry](https://hol.org) — Cross-chain agent identity registry (UAID resolution)
+- [agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp) — MCP server wrapping this SDK
+
+## Patent Notice
+
+**Patent Pending** — USPTO provisional patent application filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents."
+
+Our provisional filing is defensive — intended to prevent hostile monopolization of open payment rails and protect builders' ability to use open standards.
+
+## Disclaimer
+
+Non-custodial developer tooling. You control your own keys and set your own spending limits. You are responsible for compliance with applicable laws in your jurisdiction. Provided as-is under the MIT license. Nothing here constitutes financial advice, custody services, or money transmission.
 
 ## License
 
 MIT
-