agentwallet-sdk 2.4.1 → 2.5.0

package/README.md

@@ -4,11 +4,24 @@
 
 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."
 
-```
+```text
 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)
-```
+```text
+
+## How We Compare
+
+| | **agentwallet-sdk** | **Coinbase Agentic Wallet** | **MoonPay Agents** |
+|---|---|---|---|
+| **Custody** | Non-custodial (keys on device) | Semi-custodial (TEE) | Non-custodial (claimed) |
+| **Spend Limits** | On-chain (smart contract) | API-enforced | Not documented |
+| **Chains** | 5 (Base, ETH, Arb, Polygon, Sepolia) | Base only | Unclear |
+| **Agent Identity** | ERC-8004 + ERC-6551 | None | None |
+| **Open Source** | MIT | Partial | Closed |
+| **x402 Payments** | Native | Supported | "Compatible" |
+
+> On-chain spend limits can't be bypassed even if the API layer is compromised. That's the difference between policy and math.
 
 ## Why Agent Wallet?
 
@@ -25,7 +38,7 @@ Built on **ERC-6551** (token-bound accounts). Your agent's wallet is tied to an
 
 ```bash
 npm install @agentwallet/sdk viem
-```
+```text
 
 ```typescript
 import {
@@ -76,11 +89,12 @@ for (const tx of pending) {
   console.log(`Pending #${tx.txId}: ${tx.amount} to ${tx.to}`);
   await approveTransaction(wallet, tx.txId);
 }
-```
+```text
 
 ## API Reference
 
 ### `createWallet(config)`
+
 Connect to an existing AgentAccountV2 contract.
 
 | Param | Type | Description |
@@ -91,6 +105,7 @@ Connect to an existing AgentAccountV2 contract.
 | `rpcUrl?` | `string` | Custom RPC URL |
 
 ### `setSpendPolicy(wallet, policy)` — Owner only
+
 Set per-token spending limits.
 
 | Field | Type | Description |
@@ -101,31 +116,39 @@ Set per-token spending limits.
 | `periodLength` | `number` | Window in seconds (default: 86400 = 24h) |
 
 ### `agentExecute(wallet, { to, value?, data? })`
+
 Execute a native ETH transaction. Auto-approves if within limits, queues if over.
 
 **Returns:** `{ executed: boolean, txHash: Hash, pendingTxId?: bigint }`
 
 ### `agentTransferToken(wallet, { token, to, amount })`
+
 Transfer ERC20 tokens, respecting spend limits.
 
 ### `checkBudget(wallet, token?)`
+
 Check remaining autonomous spending budget.
 
 **Returns:** `{ token, perTxLimit, remainingInPeriod }`
 
 ### `getPendingApprovals(wallet, fromId?, toId?)`
+
 List all pending (unexecuted, uncancelled) transactions awaiting owner approval.
 
 ### `approveTransaction(wallet, txId)` — Owner only
+
 Approve and execute a queued transaction.
 
 ### `cancelTransaction(wallet, txId)` — Owner only
+
 Cancel a queued transaction.
 
 ### `setOperator(wallet, operator, authorized)` — Owner only
+
 Add or remove an agent operator address.
 
 ### `getBudgetForecast(wallet, token?, now?)`
+
 **[MAX-ADDED]** Time-aware budget forecast — know not just what's left, but when it refills.
 
 **Returns:** `BudgetForecast` — includes `remainingInPeriod`, `secondsUntilReset`, `utilizationPercent`, full period metadata.
@@ -133,9 +156,10 @@ Add or remove an agent operator address.
 ```typescript
 const forecast = await getBudgetForecast(wallet, NATIVE_TOKEN);
 console.log(`${forecast.utilizationPercent}% used, resets in ${forecast.secondsUntilReset}s`);
-```
+```text
 
 ### `getWalletHealth(wallet, operators?, tokens?, now?)`
+
 **[MAX-ADDED]** Single-call diagnostic snapshot for agent self-monitoring.
 
 **Returns:** `WalletHealth` — address, NFT binding, operator epoch, active operator statuses, pending queue depth, budget forecasts.
@@ -144,9 +168,10 @@ console.log(`${forecast.utilizationPercent}% used, resets in ${forecast.secondsU
 const health = await getWalletHealth(wallet, [agentHotWallet], [NATIVE_TOKEN, usdcAddress]);
 if (health.pendingQueueDepth > 5) console.warn('Queue backing up!');
 if (!health.activeOperators[0].active) console.error('Agent operator deactivated!');
-```
+```text
 
 ### `batchAgentTransfer(wallet, transfers)`
+
 **[MAX-ADDED]** Execute multiple token transfers sequentially — reduces boilerplate for multi-recipient payments.
 
 ```typescript
@@ -154,9 +179,10 @@ const hashes = await batchAgentTransfer(wallet, [
   { token: USDC, to: serviceA, amount: 100n },
   { token: USDC, to: serviceB, amount: 200n },
 ]);
-```
+```text
 
 ### `getActivityHistory(wallet, { fromBlock?, toBlock? })`
+
 **[MAX-ADDED]** Query on-chain event history for self-auditing — no external indexer needed.
 
 **Returns:** `ActivityEntry[]` — sorted by block number, covers executions, queued txs, approvals, cancellations, policy updates, operator changes.
@@ -166,7 +192,7 @@ const history = await getActivityHistory(wallet, { fromBlock: 10000n });
 for (const entry of history) {
   console.log(`[${entry.type}] block ${entry.blockNumber}: ${JSON.stringify(entry.args)}`);
 }
-```
+```text
 
 ## Supported Chains
 
@@ -207,7 +233,7 @@ const data = await response.json();
 //   - Checked your budget (client-side + on-chain)
 //   - Paid USDC via your AgentWallet contract
 //   - Retried the request with payment proof
-```
+```text
 
 ### Drop-in Fetch Replacement
 
@@ -218,7 +244,7 @@ const x402Fetch = createX402Fetch(wallet, { globalDailyLimit: 100_000_000n });
 
 // Use exactly like fetch()
 const res = await x402Fetch('https://any-x402-api.com/endpoint');
-```
+```text
 
 ### Budget Controls
 
@@ -236,7 +262,7 @@ client.budgetTracker.setServiceBudget({
   maxPerRequest: 2_000_000n,
   dailyLimit: 20_000_000n,
 });
-```
+```text
 
 ### Payment Approval Callback
 
@@ -250,11 +276,11 @@ const client = createX402Client(wallet, {
     console.log(`Paid ${log.amount} via tx ${log.txHash}`);
   },
 });
-```
+```text
 
 ### How x402 Works
 
-```
+```text
 Agent → GET /api/data → Server returns 402 + PAYMENT-REQUIRED header
   ↓
 Client parses payment requirements (amount, token, recipient, network)
@@ -266,7 +292,7 @@ AgentWallet executes USDC transfer on Base
 Client retries request with X-PAYMENT header (payment proof)
   ↓
 Server verifies payment → returns 200 + data
-```
+```text
 
 Your agent's keys never leave the non-custodial wallet. All payments respect on-chain spend limits set by the wallet owner.
 
@@ -275,6 +301,7 @@ Your agent's keys never leave the non-custodial wallet. All payments respect on-
 Give your AI agent a portable, censorship-resistant identity on Ethereum via [ERC-8004 Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004).
 
 ERC-8004 provides three things:
+
 - **Identity Registry** — ERC-721 NFT that resolves to an agent's registration file (name, description, services, capabilities)
 - **Reputation Registry** — On-chain feedback signals (composable scoring)
 - **Validation Registry** — Hooks for stakers, zkML verifiers, and TEE oracles
@@ -324,21 +351,21 @@ console.log(agentData.owner);                      // NFT owner address
 // Validate a registration file before publishing
 const errors = validateRegistrationFile(agentData.registrationFile!);
 if (errors.length === 0) console.log('Valid ERC-8004 registration ✅');
-```
+```text
 
 ### Agent Registry Identifier
 
 Each agent is globally identified by a namespaced string:
 
-```
+```text
 eip155:8453:0xRegistryAddress  ← namespace:chainId:contractAddress
-```
+```text
 
 ```typescript
 import { formatAgentRegistry } from '@agentwallet/sdk';
 const id = formatAgentRegistry(8453, '0xYOUR_REGISTRY');
 // → "eip155:8453:0xYOUR_REGISTRY"
-```
+```text
 
 ### Fully On-Chain Storage (No IPFS Required)
 
@@ -351,7 +378,7 @@ const uri = buildDataURI({ name: 'MyAgent', description: '...', type: '...' });
 
 // Decode it back
 const file = parseDataURI(uri);
-```
+```text
 
 ---
 

package/dist/chains.d.ts

@@ -0,0 +1,37 @@
+import type { Address } from 'viem';
+/** Chains supported for swap + x402 + wallet operations */
+export type SupportedChain = 'base' | 'arbitrum' | 'optimism';
+export interface ChainConfig {
+    chainId: number;
+    name: string;
+    /** Public default RPC URL (no API key required) */
+    rpcUrl: string;
+    /** USDC token contract address (official Circle deployment) */
+    usdc: Address;
+    /** Uniswap V3 SwapRouter02 address */
+    uniswapRouter?: Address;
+    /** Uniswap V3 QuoterV2 address */
+    uniswapQuoter?: Address;
+    /** Wrapped native token address */
+    weth?: Address;
+    /** x402 network identifier (e.g. "base:8453") */
+    x402Network: string;
+}
+/**
+ * Chain configuration for all supported chains.
+ *
+ * Uniswap V3 addresses verified against:
+ *   https://docs.uniswap.org/contracts/v3/reference/deployments/
+ *
+ * USDC addresses verified against:
+ *   https://www.circle.com/en/multichain-usdc
+ *
+ * WETH on Base / Optimism is the canonical OP-stack bridged WETH at 0x4200...0006
+ * Arbitrum WETH is the standard bridged WETH at 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1
+ */
+export declare const CHAIN_CONFIG: Record<SupportedChain, ChainConfig>;
+/** Get chain config — throws a clear error if chain is unknown */
+export declare function getChainConfig(chain: SupportedChain): ChainConfig;
+/** Resolve a chain from chainId — returns undefined if not found */
+export declare function chainFromId(chainId: number): SupportedChain | undefined;
+//# sourceMappingURL=chains.d.ts.map

package/dist/chains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAC;IACd,sCAAsC;IACtC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kCAAkC;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mCAAmC;IACnC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,cAAc,EAAE,WAAW,CA2CnD,CAAC;AAEX,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAQjE;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAKvE"}

package/dist/chains.js

@@ -0,0 +1,75 @@
+// [MAX-ADDED] Shared chain configuration — single source of truth for multi-chain support.
+// Chains: Base, Arbitrum, Optimism (Ethereum is bridge-only, no swap support due to gas).
+/**
+ * Chain configuration for all supported chains.
+ *
+ * Uniswap V3 addresses verified against:
+ *   https://docs.uniswap.org/contracts/v3/reference/deployments/
+ *
+ * USDC addresses verified against:
+ *   https://www.circle.com/en/multichain-usdc
+ *
+ * WETH on Base / Optimism is the canonical OP-stack bridged WETH at 0x4200...0006
+ * Arbitrum WETH is the standard bridged WETH at 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1
+ */
+export const CHAIN_CONFIG = {
+    base: {
+        chainId: 8453,
+        name: 'Base',
+        rpcUrl: 'https://mainnet.base.org',
+        // Official USDC on Base (Circle native deployment)
+        usdc: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        // Uniswap V3 on Base — SwapRouter02 + QuoterV2
+        // Source: https://docs.uniswap.org/contracts/v3/reference/deployments/base-deployments
+        uniswapRouter: '0x2626664c2603336E57B271c5C0b26F421741e481',
+        uniswapQuoter: '0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a',
+        // OP-stack canonical WETH
+        weth: '0x4200000000000000000000000000000000000006',
+        x402Network: 'base:8453',
+    },
+    arbitrum: {
+        chainId: 42161,
+        name: 'Arbitrum One',
+        rpcUrl: 'https://arb1.arbitrum.io/rpc',
+        // Official USDC on Arbitrum (Circle native deployment — NOT USDC.e bridged)
+        usdc: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+        // Uniswap V3 on Arbitrum — SwapRouter02 + QuoterV2
+        // Source: https://docs.uniswap.org/contracts/v3/reference/deployments/arbitrum-deployments
+        uniswapRouter: '0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45',
+        uniswapQuoter: '0x61fFE014bA17989E743c5F6cB21bF9697530B21e',
+        // Standard bridged WETH on Arbitrum
+        weth: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
+        x402Network: 'arbitrum:42161',
+    },
+    optimism: {
+        chainId: 10,
+        name: 'OP Mainnet',
+        rpcUrl: 'https://mainnet.optimism.io',
+        // Official USDC on Optimism (Circle native deployment — NOT USDC.e bridged)
+        usdc: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85',
+        // Uniswap V3 on Optimism — SwapRouter02 + QuoterV2
+        // Source: https://docs.uniswap.org/contracts/v3/reference/deployments/optimism-deployments
+        uniswapRouter: '0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45',
+        uniswapQuoter: '0x61fFE014bA17989E743c5F6cB21bF9697530B21e',
+        // OP-stack canonical WETH
+        weth: '0x4200000000000000000000000000000000000006',
+        x402Network: 'optimism:10',
+    },
+};
+/** Get chain config — throws a clear error if chain is unknown */
+export function getChainConfig(chain) {
+    const config = CHAIN_CONFIG[chain];
+    if (!config) {
+        throw new Error(`Unsupported chain: "${chain}". Supported chains: ${Object.keys(CHAIN_CONFIG).join(', ')}`);
+    }
+    return config;
+}
+/** Resolve a chain from chainId — returns undefined if not found */
+export function chainFromId(chainId) {
+    for (const [key, cfg] of Object.entries(CHAIN_CONFIG)) {
+        if (cfg.chainId === chainId)
+            return key;
+    }
+    return undefined;
+}
+//# sourceMappingURL=chains.js.map

package/dist/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,0FAA0F;AAwB1F;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAwC;IAC/D,IAAI,EAAE;QACJ,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,0BAA0B;QAClC,mDAAmD;QACnD,IAAI,EAAE,4CAA4C;QAClD,+CAA+C;QAC/C,uFAAuF;QACvF,aAAa,EAAE,4CAA4C;QAC3D,aAAa,EAAE,4CAA4C;QAC3D,0BAA0B;QAC1B,IAAI,EAAE,4CAA4C;QAClD,WAAW,EAAE,WAAW;KACzB;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,8BAA8B;QACtC,4EAA4E;QAC5E,IAAI,EAAE,4CAA4C;QAClD,mDAAmD;QACnD,2FAA2F;QAC3F,aAAa,EAAE,4CAA4C;QAC3D,aAAa,EAAE,4CAA4C;QAC3D,oCAAoC;QACpC,IAAI,EAAE,4CAA4C;QAClD,WAAW,EAAE,gBAAgB;KAC9B;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,EAAE;QACX,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,6BAA6B;QACrC,4EAA4E;QAC5E,IAAI,EAAE,4CAA4C;QAClD,mDAAmD;QACnD,2FAA2F;QAC3F,aAAa,EAAE,4CAA4C;QAC3D,aAAa,EAAE,4CAA4C;QAC3D,0BAA0B;QAC1B,IAAI,EAAE,4CAA4C;QAClD,WAAW,EAAE,aAAa;KAC3B;CACO,CAAC;AAEX,kEAAkE;AAClE,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,uBAAuB,KAAK,wBAAwB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACtD,IAAI,GAAG,CAAC,OAAO,KAAK,OAAO;YAAE,OAAO,GAAqB,CAAC;IAC5D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}