agentwallet-sdk 4.0.5 → 5.0.1

package/README.md

@@ -1,224 +1,220 @@
-# agentwallet-sdk
+# AgentWallet SDK
 
-**The only non-custodial agent wallet SDK. Unlike Coinbase Agentic Wallets — your keys, your agent.**
+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.
 
-Non-custodial agent wallet SDK. Your agent holds its own keys — no custodian, no KYC, no freeze risk.
+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."
 
-[![npm](https://img.shields.io/npm/v/agentwallet-sdk?style=flat-square)](https://www.npmjs.com/package/agentwallet-sdk)
-[![Discord](https://img.shields.io/discord/1475549260140253194?label=Community&logo=discord&color=5865F2)](https://discord.gg/958AACqf7Y)
-![x402](https://img.shields.io/badge/x402-native-green?style=flat-square)
-![CCTP V2](https://img.shields.io/badge/CCTP_V2-17_chains-red?style=flat-square)
-![Tests](https://img.shields.io/badge/tests-629_passing-brightgreen?style=flat-square)
-![Swap Fee](https://img.shields.io/badge/swap_fee-0.77%25-blue?style=flat-square)
+> **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.
 
-```bash
-npm i agentwallet-sdk
 ```
-
----
-
-## Why agentwallet-sdk?
-
-Most agent wallet solutions compromise on the thing that matters most: who controls the keys.
-
-| | agentwallet-sdk | Coinbase Agentic Wallets | MoonPay Agents |
-|---|---|---|---|
-| **Key custody** | Agent holds own keys | Coinbase TEE (custodial) | MoonPay managed |
-| **Freeze risk** | None — on-chain only | Yes — platform can freeze | Yes — KYC-gated |
-| **Cross-chain** | 17 chains via CCTP V2 | Base only | Limited |
-| **Swap fee** | **0.77%** | 0.875% | N/A |
-| **x402 support** | Native (v2.0.1+) | No public x402 client | No |
-| **Spend limits** | On-chain, enforced by contract | Platform-enforced | Platform-enforced |
-| **Agent identity** | DID + Verifiable Credentials | No | No |
-| **Agent staking** | AAVE USDC yield pool | No | No |
-| **KYC required** | No | No | Yes |
-| **MCP compatible** | Yes | No | No |
-
-### 0.77% swap fee — 12% cheaper than MetaMask and Coinbase Wallet
-
-Both MetaMask and Coinbase Wallet charge **0.875%** on every swap. We charge **0.77%** — the lowest fee from any major wallet SDK. Built for agents that execute hundreds of swaps autonomously. Every basis point compounds.
-
-```typescript
-import { SwapModule } from 'agentwallet-sdk/swap';
-
-const swap = new SwapModule(publicClient, walletClient, accountAddress);
-
-// 0.77% fee — cheaper than MetaMask, cheaper than Coinbase Wallet
-const result = await swap.executeSwap(USDC_ADDRESS, WETH_ADDRESS, 1000_000000n);
+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)
 ```
 
-### True non-custody
+## Why Agent Wallet?
 
-The wallet is an ERC-6551 token-bound account on-chain. The agent's private key lives in the agent's environment, controlled by whoever runs the agent. Nobody else has it. Spend limits are enforced by the smart contract — not by a platform policy that can change overnight.
+| 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.** |
 
-```typescript
-import { createWallet, createX402Fetch, NATIVE_TOKEN } from 'agentwallet-sdk';
+Built on **ERC-6551** (token-bound accounts). Your agent's wallet is tied to an NFT — portable, auditable, fully on-chain.
 
-const wallet = createWallet({ accountAddress: '0x...', chain: 'base', walletClient });
+## Quick Start
 
-// x402 payments: agent pays APIs automatically, no human needed
-const fetch = createX402Fetch(wallet, { globalDailyLimit: 10_000_000n });
-const data = await fetch('https://api.example.com/premium');
-// Server returned 402? Payment handled. Original request retried. Human not consulted.
+```bash
+npm install agentwallet-sdk viem
 ```
 
-### Agent identity — permanent DID + Verifiable Credentials
-
-Every agent gets a permanent, self-sovereign decentralized identity derived directly from its wallet key. No external registry. No KYC. Just cryptographic proof that this agent is who it claims to be.
+### Create a Wallet
 
 ```typescript
-import { deriveAgentDID, issueCredential, verifyCredential } from 'agentwallet-sdk/identity';
+import { createWallet, setSpendPolicy, agentExecute, NATIVE_TOKEN } from 'agentwallet-sdk';
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
 
-// Permanent DID — same key always produces the same DID
-const did = deriveAgentDID(privateKey);
-// → "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+const account = privateKeyToAccount('0x...');
+const walletClient = createWalletClient({ account, chain: base, transport: http() });
 
-// Issue a signed Verifiable Credential
-const vc = issueCredential(did, privateKey, {
-  agentName: 'TradingAgent-01',
-  capabilities: ['swap', 'bridge', 'pay'],
-  owner: '0xff86...',
+const wallet = createWallet({
+  accountAddress: '0xYourAgentWallet',
+  chain: 'base',
+  walletClient,
 });
 
-// Any counterparty can verify without phoning home
-console.log(verifyCredential(vc)); // true
+// Set a $25/tx, $500/day spend policy for ETH
+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
+});
+console.log(result.executed ? 'Sent!' : 'Queued for approval');
 ```
 
-### Agent staking — earn yield on idle USDC
+## ERC-8004 On-Chain Identity
 
-Agents can deposit USDC into an AAVE V3-backed staking pool and earn yield on earnings instead of holding cash in a wallet. **Agent participants only** — verified by DID at deposit time. No human participants.
+Register your agent on the ERC-8004 Identity Registry — a portable, censorship-resistant on-chain identity using ERC-721.
 
 ```typescript
-import { AgentStakingPool } from 'agentwallet-sdk/staking';
+import { ERC8004Client } from 'agentwallet-sdk';
 
-const pool = new AgentStakingPool();
+const identity = new ERC8004Client({ chain: 'base' });
 
-// Deposit TaskBridge earnings — starts earning yield immediately
-await pool.deposit({
-  agentDID: did,
-  amountUsdc: 500_000000n,  // 500 USDC
-  walletClient,
-  chain: 'base',
+// Register agent
+const { txHash, agentId } = await identity.registerAgent(walletClient, {
+  name: 'MyAgent',
+  description: 'Autonomous trading agent',
 });
 
-// Check balance (principal + yield, minus 0.5% annual management fee)
-const balance = await pool.getBalance(did, 'base');
-console.log(balance.currentBalanceUsdc); // growing
+// Look up any agent
+const agent = await identity.lookupAgentIdentity(agentId!);
+console.log(agent.owner, agent.agentURI);
 ```
 
-### Agent verification — machine-readable trust score
+## ERC-8004 Reputation Registry
 
-Before transacting with an unknown agent, request a trust bundle. Staking balance, task history, wallet age — all signed by the agent's DID. No PII. No central authority.
+On-chain reputation signals — scored feedback from clients, aggregated summaries, revocable.
 
 ```typescript
-import { verifyAgent, verifyTrustBundle } from 'agentwallet-sdk/verify';
-
-const bundle = await verifyAgent({ privateKey, chain: 'base' });
-// {
-//   did: "did:key:z6Mk...",
-//   walletAddress: "0x...",
-//   stakingBalance: 500000000n,      // 500 USDC staked
-//   reputationScore: 87,             // 0-100
-//   taskBridgeTasksCompleted: 47,
-//   walletAgeDays: 183,
-//   signature: "..."                 // tamper-proof
-// }
-
-// Counterparty verifies before accepting payment or task
-console.log(verifyTrustBundle(bundle)); // true
+import { ReputationClient } from 'agentwallet-sdk';
+
+const reputation = new ReputationClient({ chain: 'base' });
+
+// 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',
+});
+
+// Read aggregated reputation
+const rep = await reputation.getAgentReputation(42n);
+console.log(`Score: ${rep.totalScore} from ${rep.count} reviews`);
 ```
 
-### Cross-chain without the ceremony
+## ERC-8004 Validation Registry
 
-One bridge interface across 17 chains. Coinbase Agentic Wallets are Base-only.
+Request and receive on-chain validation from validator contracts (TEE attestations, capability proofs, compliance checks).
 
 ```typescript
-import { UnifiedBridge } from 'agentwallet-sdk';
+import { ValidationClient } from 'agentwallet-sdk';
+import { keccak256, toBytes } from 'viem';
 
-const bridge = new UnifiedBridge({ evmSigner, solanaWallet });
-
-await bridge.bridge({
-  amount: 1_000_000n,
-  sourceChain: 'solana',
-  destinationChain: 'base',
-  destinationAddress: '0x...',
+const validation = new ValidationClient({
+  chain: 'base',
+  validationAddress: '0xYourValidationRegistry', // address required until official deployment
 });
-```
 
-Supported chains: Base, Ethereum, Solana, Arbitrum, Optimism, Polygon, Avalanche, Unichain, Linea, Codex, Sonic, World Chain, Sei, XDC, HyperEVM, Ink, Plume.
-
----
+// 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,
+});
 
-## Install
+// Check validation status
+const status = await validation.getValidationStatus(requestHash);
+console.log(status.responded ? `Result: ${status.response}` : 'Pending');
 
-```bash
-npm i agentwallet-sdk
+// Get summary for an agent
+const summary = await validation.getSummary(42n);
+console.log(`${summary.passCount} passed, ${summary.failCount} failed`);
 ```
 
-## Quick Start
+## Mutual Stake Escrow
 
-```typescript
-import { createWallet, setSpendPolicy, agentExecute, NATIVE_TOKEN } from 'agentwallet-sdk';
-import { createWalletClient, http } from 'viem';
-import { privateKeyToAccount } from 'viem/accounts';
+Reciprocal collateral for agent-to-agent task settlement. Both parties stake, both lose if the task fails.
 
-const walletClient = createWalletClient({
-  account: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY),
-  transport: http('https://mainnet.base.org'),
-});
+```typescript
+import { MutualStakeEscrow } from 'agentwallet-sdk';
 
-const wallet = createWallet({
-  accountAddress: '0xYOUR_AGENT_ACCOUNT',
+const escrow = new MutualStakeEscrow({
   chain: 'base',
   walletClient,
 });
 
-// Set spend limits once (owner operation)
-await setSpendPolicy(wallet, {
-  token: NATIVE_TOKEN,
-  perTxLimit: 25_000000000000000n,    // 0.025 ETH per tx
-  periodLimit: 500_000000000000000n,  // 0.5 ETH per day
-  periodLength: 86400,
+// 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),
 });
 
-// Agent executes autonomously within limits
-await agentExecute(wallet, { to: '0xSOME_SERVICE', value: 10_000000000000000n });
+// Counterparty funds their side
+await escrow.fund(escrowId);
+
+// After task completion, fulfill
+await escrow.fulfill(escrowId, proofHash);
+
+// Verify and release stakes
+await escrow.verify(escrowId);
 ```
 
-## Modules
+## Feature Tiers
+
+### Base (Free)
+
+| Feature | Description |
+|---------|-------------|
+| Agent Identity | ERC-8004 Identity Registry — on-chain ERC-721 agent IDs |
+| Agent Reputation | ERC-8004 Reputation Registry — scored feedback and summaries |
+| Agent Validation | ERC-8004 Validation Registry — validator request/response |
+| ERC-6551 TBA | NFT-bound wallets with autonomous spending |
+| Mutual Stake Escrow | Reciprocal collateral task settlement |
+| Optimistic Escrow | Time-locked optimistic verification |
+| x402 Payments | HTTP 402 auto-pay for agent-to-service payments |
+| CCTP Bridge | Circle CCTP V2 across 17 chains + Solana |
+| Spend Policies | Per-token, per-period on-chain spending limits |
+| Swap | Uniswap V3 on Base/Arbitrum/Optimism |
+| Fiat Onramp | Opt-in fiat-to-crypto |
+| AP2 Protocol | Agent-to-Agent task delegation and payment |
+| Settlement | On-chain settlement finalization |
+| Gas Sponsorship | ERC-4337 paymaster-based gas sponsorship |
+| Solana Support | Cross-chain Solana bridging via CCTP |
+
+### Premium
 
-| Module | Import | What it does |
-|---|---|---|
-| Core | `agentwallet-sdk` | Wallet creation, spend limits, agent execution |
-| x402 | `agentwallet-sdk/x402` | Automatic API payment handling (HTTP 402) |
-| Bridge | `agentwallet-sdk/bridge` | CCTP V2 cross-chain USDC (17 chains) |
-| Swap | `agentwallet-sdk/swap` | Uniswap V3 token swaps @ **0.77% fee** |
-| Policy | `agentwallet-sdk/policy` | SpendingPolicy — allowlists, rolling caps |
-| Identity | `agentwallet-sdk/identity` | Agent DID (W3C did:key) + Verifiable Credentials |
-| Staking | `agentwallet-sdk/staking` | Agent-only AAVE USDC yield pool |
-| Verify | `agentwallet-sdk/verify` | Trust bundle — DID + staking + reputation |
+| 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 |
 
-## vs. MoonPay Agents
+Premium access: [github.com/up2itnow/AgentNexus2](https://github.com/up2itnow/AgentNexus2)
 
-MoonPay entered the agent wallet space with a managed offering. Here's why builders choose `agentwallet-sdk` instead:
+## Supported Chains
 
-| | agentwallet-sdk | MoonPay Agents |
-|---|---|---|
-| **Open source** | ✅ MIT licensed | ❌ Closed enterprise product |
-| **x402-native** | ✅ Built-in (v2.0.1+) | ❌ No x402 support |
-| **Key custody** | Agent holds own keys | MoonPay managed |
-| **KYC required** | ❌ None | ✅ KYC-gated |
-| **Vendor lock-in** | ❌ On-chain, permissionless | ✅ Platform-dependent |
-| **Cross-chain** | 17 chains via CCTP V2 | Limited |
-| **DID / identity** | ✅ W3C did:key standard | ❌ No |
+Mainnet: Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, BSC, Celo, Gnosis, Linea, Mantle, Scroll, and more.
 
-The difference isn't just technical. MoonPay Agents is a closed enterprise product — your agent's payment capability depends on MoonPay's platform staying available, compliant, and willing to serve you. `agentwallet-sdk` is open-source, x402-native, and permissionless. Your agent pays because it has keys, not because a vendor approved the transaction.
+Testnet: Base Sepolia, Arbitrum Sepolia, and corresponding testnets.
 
-## Resources
+## Links
 
-- [npm package](https://www.npmjs.com/package/agentwallet-sdk)
-- [Discord community](https://discord.gg/958AACqf7Y)
-- [x402 docs](https://docs.x402.org)
+- [ERC-8004 Spec](https://eips.ethereum.org/EIPS/eip-8004)
+- [GitHub](https://github.com/agentnexus/agent-wallet-sdk)
+- [npm](https://www.npmjs.com/package/agentwallet-sdk)
 
 ## License