agentwallet-sdk 2.5.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/README.md +432 -1
  2. package/dist/bridge/client.d.ts +17 -49
  3. package/dist/bridge/client.d.ts.map +1 -1
  4. package/dist/bridge/client.js +94 -124
  5. package/dist/bridge/client.js.map +1 -1
  6. package/dist/bridge/index.d.ts +4 -2
  7. package/dist/bridge/index.d.ts.map +1 -1
  8. package/dist/bridge/index.js +8 -2
  9. package/dist/bridge/index.js.map +1 -1
  10. package/dist/bridge/types.d.ts +100 -19
  11. package/dist/bridge/types.d.ts.map +1 -1
  12. package/dist/bridge/types.js +167 -18
  13. package/dist/bridge/types.js.map +1 -1
  14. package/dist/bridge/unified.d.ts +101 -0
  15. package/dist/bridge/unified.d.ts.map +1 -0
  16. package/dist/bridge/unified.js +284 -0
  17. package/dist/bridge/unified.js.map +1 -0
  18. package/dist/chains.d.ts +25 -0
  19. package/dist/chains.d.ts.map +1 -1
  20. package/dist/chains.js +33 -0
  21. package/dist/chains.js.map +1 -1
  22. package/dist/fiat/index.d.ts +10 -0
  23. package/dist/fiat/index.d.ts.map +1 -0
  24. package/dist/fiat/index.js +9 -0
  25. package/dist/fiat/index.js.map +1 -0
  26. package/dist/fiat/onramp.d.ts +101 -0
  27. package/dist/fiat/onramp.d.ts.map +1 -0
  28. package/dist/fiat/onramp.js +155 -0
  29. package/dist/fiat/onramp.js.map +1 -0
  30. package/dist/fiat/providers/index.d.ts +16 -0
  31. package/dist/fiat/providers/index.d.ts.map +1 -0
  32. package/dist/fiat/providers/index.js +30 -0
  33. package/dist/fiat/providers/index.js.map +1 -0
  34. package/dist/fiat/providers/moonpay.d.ts +22 -0
  35. package/dist/fiat/providers/moonpay.d.ts.map +1 -0
  36. package/dist/fiat/providers/moonpay.js +107 -0
  37. package/dist/fiat/providers/moonpay.js.map +1 -0
  38. package/dist/fiat/providers/stripe.d.ts +26 -0
  39. package/dist/fiat/providers/stripe.d.ts.map +1 -0
  40. package/dist/fiat/providers/stripe.js +135 -0
  41. package/dist/fiat/providers/stripe.js.map +1 -0
  42. package/dist/fiat/providers/transak.d.ts +26 -0
  43. package/dist/fiat/providers/transak.d.ts.map +1 -0
  44. package/dist/fiat/providers/transak.js +119 -0
  45. package/dist/fiat/providers/transak.js.map +1 -0
  46. package/dist/fiat/types.d.ts +106 -0
  47. package/dist/fiat/types.d.ts.map +1 -0
  48. package/dist/fiat/types.js +13 -0
  49. package/dist/fiat/types.js.map +1 -0
  50. package/dist/gas/index.d.ts +4 -0
  51. package/dist/gas/index.d.ts.map +1 -0
  52. package/dist/gas/index.js +3 -0
  53. package/dist/gas/index.js.map +1 -0
  54. package/dist/gas/sponsor.d.ts +70 -0
  55. package/dist/gas/sponsor.d.ts.map +1 -0
  56. package/dist/gas/sponsor.js +193 -0
  57. package/dist/gas/sponsor.js.map +1 -0
  58. package/dist/gas/types.d.ts +76 -0
  59. package/dist/gas/types.d.ts.map +1 -0
  60. package/dist/gas/types.js +21 -0
  61. package/dist/gas/types.js.map +1 -0
  62. package/dist/index.d.ts +85 -71
  63. package/dist/index.d.ts.map +1 -1
  64. package/dist/index.js +21 -3
  65. package/dist/index.js.map +1 -1
  66. package/dist/settlement/index.d.ts +4 -0
  67. package/dist/settlement/index.d.ts.map +1 -0
  68. package/dist/settlement/index.js +3 -0
  69. package/dist/settlement/index.js.map +1 -0
  70. package/dist/settlement/types.d.ts +66 -0
  71. package/dist/settlement/types.d.ts.map +1 -0
  72. package/dist/settlement/types.js +37 -0
  73. package/dist/settlement/types.js.map +1 -0
  74. package/dist/settlement/verifier.d.ts +75 -0
  75. package/dist/settlement/verifier.d.ts.map +1 -0
  76. package/dist/settlement/verifier.js +354 -0
  77. package/dist/settlement/verifier.js.map +1 -0
  78. package/dist/solana/bridge.d.ts +144 -0
  79. package/dist/solana/bridge.d.ts.map +1 -0
  80. package/dist/solana/bridge.js +352 -0
  81. package/dist/solana/bridge.js.map +1 -0
  82. package/dist/solana/index.d.ts +8 -0
  83. package/dist/solana/index.d.ts.map +1 -0
  84. package/dist/solana/index.js +6 -0
  85. package/dist/solana/index.js.map +1 -0
  86. package/dist/solana/swap.d.ts +85 -0
  87. package/dist/solana/swap.d.ts.map +1 -0
  88. package/dist/solana/swap.js +173 -0
  89. package/dist/solana/swap.js.map +1 -0
  90. package/dist/solana/types.d.ts +126 -0
  91. package/dist/solana/types.d.ts.map +1 -0
  92. package/dist/solana/types.js +10 -0
  93. package/dist/solana/types.js.map +1 -0
  94. package/dist/solana/wallet.d.ts +83 -0
  95. package/dist/solana/wallet.d.ts.map +1 -0
  96. package/dist/solana/wallet.js +164 -0
  97. package/dist/solana/wallet.js.map +1 -0
  98. package/dist/solana/x402.d.ts +69 -0
  99. package/dist/solana/x402.d.ts.map +1 -0
  100. package/dist/solana/x402.js +154 -0
  101. package/dist/solana/x402.js.map +1 -0
  102. package/dist/swap/index.d.ts +1 -0
  103. package/dist/swap/index.d.ts.map +1 -1
  104. package/dist/swap/index.js +2 -0
  105. package/dist/swap/index.js.map +1 -1
  106. package/dist/swap/router/cache.d.ts +13 -0
  107. package/dist/swap/router/cache.d.ts.map +1 -0
  108. package/dist/swap/router/cache.js +30 -0
  109. package/dist/swap/router/cache.js.map +1 -0
  110. package/dist/swap/router/flashbots.d.ts +10 -0
  111. package/dist/swap/router/flashbots.d.ts.map +1 -0
  112. package/dist/swap/router/flashbots.js +43 -0
  113. package/dist/swap/router/flashbots.js.map +1 -0
  114. package/dist/swap/router/health.d.ts +17 -0
  115. package/dist/swap/router/health.d.ts.map +1 -0
  116. package/dist/swap/router/health.js +38 -0
  117. package/dist/swap/router/health.js.map +1 -0
  118. package/dist/swap/router/index.d.ts +10 -0
  119. package/dist/swap/router/index.d.ts.map +1 -0
  120. package/dist/swap/router/index.js +10 -0
  121. package/dist/swap/router/index.js.map +1 -0
  122. package/dist/swap/router/providers/cowswap.d.ts +11 -0
  123. package/dist/swap/router/providers/cowswap.d.ts.map +1 -0
  124. package/dist/swap/router/providers/cowswap.js +79 -0
  125. package/dist/swap/router/providers/cowswap.js.map +1 -0
  126. package/dist/swap/router/providers/index.d.ts +20 -0
  127. package/dist/swap/router/providers/index.d.ts.map +1 -0
  128. package/dist/swap/router/providers/index.js +32 -0
  129. package/dist/swap/router/providers/index.js.map +1 -0
  130. package/dist/swap/router/providers/jupiter.d.ts +12 -0
  131. package/dist/swap/router/providers/jupiter.d.ts.map +1 -0
  132. package/dist/swap/router/providers/jupiter.js +73 -0
  133. package/dist/swap/router/providers/jupiter.js.map +1 -0
  134. package/dist/swap/router/providers/lifi.d.ts +11 -0
  135. package/dist/swap/router/providers/lifi.d.ts.map +1 -0
  136. package/dist/swap/router/providers/lifi.js +123 -0
  137. package/dist/swap/router/providers/lifi.js.map +1 -0
  138. package/dist/swap/router/providers/oneinch.d.ts +13 -0
  139. package/dist/swap/router/providers/oneinch.d.ts.map +1 -0
  140. package/dist/swap/router/providers/oneinch.js +71 -0
  141. package/dist/swap/router/providers/oneinch.js.map +1 -0
  142. package/dist/swap/router/providers/paraswap.d.ts +11 -0
  143. package/dist/swap/router/providers/paraswap.d.ts.map +1 -0
  144. package/dist/swap/router/providers/paraswap.js +73 -0
  145. package/dist/swap/router/providers/paraswap.js.map +1 -0
  146. package/dist/swap/router/providers/uniswap.d.ts +31 -0
  147. package/dist/swap/router/providers/uniswap.d.ts.map +1 -0
  148. package/dist/swap/router/providers/uniswap.js +116 -0
  149. package/dist/swap/router/providers/uniswap.js.map +1 -0
  150. package/dist/swap/router/providers/zerox.d.ts +13 -0
  151. package/dist/swap/router/providers/zerox.d.ts.map +1 -0
  152. package/dist/swap/router/providers/zerox.js +94 -0
  153. package/dist/swap/router/providers/zerox.js.map +1 -0
  154. package/dist/swap/router/router.d.ts +86 -0
  155. package/dist/swap/router/router.d.ts.map +1 -0
  156. package/dist/swap/router/router.js +224 -0
  157. package/dist/swap/router/router.js.map +1 -0
  158. package/dist/swap/router/rsi/engine.d.ts +60 -0
  159. package/dist/swap/router/rsi/engine.d.ts.map +1 -0
  160. package/dist/swap/router/rsi/engine.js +483 -0
  161. package/dist/swap/router/rsi/engine.js.map +1 -0
  162. package/dist/swap/router/rsi/index.d.ts +3 -0
  163. package/dist/swap/router/rsi/index.d.ts.map +1 -0
  164. package/dist/swap/router/rsi/index.js +3 -0
  165. package/dist/swap/router/rsi/index.js.map +1 -0
  166. package/dist/swap/router/rsi/types.d.ts +106 -0
  167. package/dist/swap/router/rsi/types.d.ts.map +1 -0
  168. package/dist/swap/router/rsi/types.js +3 -0
  169. package/dist/swap/router/rsi/types.js.map +1 -0
  170. package/dist/swap/router/types.d.ts +120 -0
  171. package/dist/swap/router/types.d.ts.map +1 -0
  172. package/dist/swap/router/types.js +16 -0
  173. package/dist/swap/router/types.js.map +1 -0
  174. package/dist/x402/index.d.ts +1 -1
  175. package/dist/x402/index.d.ts.map +1 -1
  176. package/dist/x402/index.js +1 -1
  177. package/dist/x402/index.js.map +1 -1
  178. package/dist/x402/types.d.ts +4 -2
  179. package/dist/x402/types.d.ts.map +1 -1
  180. package/dist/x402/types.js +12 -1
  181. package/dist/x402/types.js.map +1 -1
  182. package/package.json +8 -3
package/README.md CHANGED
@@ -16,7 +16,7 @@ Agent spent $490 today → 🛑 Next tx queued ($500/day limit hit)
16
16
  |---|---|---|---|
17
17
  | **Custody** | Non-custodial (keys on device) | Semi-custodial (TEE) | Non-custodial (claimed) |
18
18
  | **Spend Limits** | On-chain (smart contract) | API-enforced | Not documented |
19
- | **Chains** | 5 (Base, ETH, Arb, Polygon, Sepolia) | Base only | Unclear |
19
+ | **Chains** | **17** (Base, ETH, Arb, Polygon + 12 EVM + **Solana**) | Base only | Unclear |
20
20
  | **Agent Identity** | ERC-8004 + ERC-6551 | None | None |
21
21
  | **Open Source** | MIT | Partial | Closed |
22
22
  | **x402 Payments** | Native | Supported | "Compatible" |
@@ -196,6 +196,8 @@ for (const entry of history) {
196
196
 
197
197
  ## Supported Chains
198
198
 
199
+ ### Wallet / Execution Chains
200
+
199
201
  | Chain | Status | Best For |
200
202
  |-------|--------|----------|
201
203
  | **Base** | ✅ Primary | Low gas, USDC native |
@@ -204,6 +206,108 @@ for (const entry of history) {
204
206
  | **Arbitrum** | ✅ | DeFi agents |
205
207
  | **Polygon** | ✅ | Micropayments |
206
208
 
209
+ ### CCTP V2 Bridge — 17 Chains (v3.1.0)
210
+
211
+ Bridge USDC between any two supported chains via Circle's Cross-Chain Transfer Protocol V2. **0.1% platform fee.** Uses the same non-custodial, agent-native architecture.
212
+
213
+ ```typescript
214
+ import { UnifiedBridge } from 'agentwallet-sdk';
215
+
216
+ const bridge = new UnifiedBridge({ evmSigner, solanaWallet });
217
+
218
+ // Bridge 1 USDC from Solana to Base (~20s fast transfer)
219
+ const result = await bridge.bridge({
220
+ amount: 1_000_000n, // 1 USDC (6 decimals)
221
+ sourceChain: 'solana',
222
+ destinationChain: 'base',
223
+ destinationAddress: '0x...',
224
+ });
225
+ console.log('Minted on Base:', result.mintTxHash);
226
+
227
+ // Bridge from Polygon to Arbitrum
228
+ const result2 = await bridge.bridge({
229
+ amount: 5_000_000n, // 5 USDC
230
+ sourceChain: 'polygon',
231
+ destinationChain: 'arbitrum',
232
+ destinationAddress: '0x...',
233
+ });
234
+
235
+ // Get a fee quote
236
+ const quote = bridge.getQuote({
237
+ amount: 1_000_000n,
238
+ sourceChain: 'base',
239
+ destinationChain: 'sonic',
240
+ });
241
+ console.log(`Fee: ${quote.platformFee} USDC (0.1%)`);
242
+ console.log(`Est. time: ${quote.estimatedTimeSeconds}s`);
243
+ console.log(`Output: ${quote.outputAmount} USDC`);
244
+
245
+ // All 17 chains
246
+ console.log(bridge.getSupportedChains());
247
+ // ['ethereum','avalanche','optimism','arbitrum','base','polygon',
248
+ // 'unichain','linea','codex','sonic','worldchain','sei','xdc',
249
+ // 'hyperevm','ink','plume','solana']
250
+ ```
251
+
252
+ #### Supported Bridge Chains
253
+
254
+ | Chain | CCTP Domain | Chain ID | Fast Transfer |
255
+ |-------|-------------|----------|---------------|
256
+ | Ethereum | 0 | 1 | ✅ ~20s |
257
+ | Avalanche | 1 | 43114 | ⏱ ~15min |
258
+ | OP Mainnet | 2 | 10 | ✅ ~20s |
259
+ | Arbitrum | 3 | 42161 | ✅ ~20s |
260
+ | **Solana** | 5 | — | ✅ ~20s |
261
+ | Base | 6 | 8453 | ✅ ~20s |
262
+ | Polygon PoS | 7 | 137 | ⏱ ~15min |
263
+ | Unichain | 10 | 130 | ✅ ~20s |
264
+ | Linea | 11 | 59144 | ✅ ~20s |
265
+ | Codex | 12 | 812 | ✅ ~20s |
266
+ | Sonic | 13 | 146 | ⏱ ~15min |
267
+ | World Chain | 14 | 480 | ✅ ~20s |
268
+ | Sei | 16 | 1329 | ⏱ ~15min |
269
+ | XDC | 18 | 50 | ⏱ ~15min |
270
+ | HyperEVM | 19 | 999 | ⏱ ~15min |
271
+ | Ink | 21 | 57073 | ✅ ~20s |
272
+ | Plume | 22 | 98866 | ✅ ~20s |
273
+
274
+ Contract addresses verified from Circle's official docs:
275
+ - **TokenMessengerV2**: `0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d` (all EVM chains)
276
+ - **MessageTransmitterV2**: `0x81D40F21F12A8F0E3252Bccb954D722d4c464B64` (all EVM chains)
277
+
278
+ #### EVM-Only Bridge (BridgeModule)
279
+
280
+ For EVM→EVM routes you can use `BridgeModule` directly (no Solana dependency):
281
+
282
+ ```typescript
283
+ import { BridgeModule } from 'agentwallet-sdk';
284
+
285
+ const bridge = new BridgeModule(walletClient, 'base');
286
+ const result = await bridge.bridge(1_000_000n, 'polygon');
287
+ console.log('Minted on Polygon:', result.mintTxHash);
288
+ ```
289
+
290
+ #### Solana-Side Operations (SolanaCCTPBridge)
291
+
292
+ ```typescript
293
+ import { SolanaCCTPBridge } from 'agentwallet-sdk';
294
+ import { Connection, Keypair } from '@solana/web3.js';
295
+
296
+ const solanaBridge = new SolanaCCTPBridge({
297
+ connection: new Connection('https://api.mainnet-beta.solana.com'),
298
+ payer: keypair,
299
+ });
300
+
301
+ // Burn USDC on Solana → receive on Base
302
+ const burnResult = await solanaBridge.depositForBurn({
303
+ amount: 1_000_000n,
304
+ destinationChain: 'base',
305
+ destinationAddress: '0x...',
306
+ });
307
+ const attestation = await solanaBridge.waitForAttestation(burnResult.messageHash);
308
+ // ... then call receiveMessage on Base
309
+ ```
310
+
207
311
  ## x402 Protocol Support
208
312
 
209
313
  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.
@@ -393,6 +497,333 @@ const file = parseDataURI(uri);
393
497
 
394
498
  All limits enforced on-chain. No off-chain dependencies. Fully auditable.
395
499
 
500
+ ## Solana Support (v3.0.0)
501
+
502
+ Solana is now a first-class chain in the SDK. Unlike EVM chains, Solana uses Ed25519 keys, SPL tokens, and Jupiter for swaps — all fully supported.
503
+
504
+ ### Install
505
+
506
+ ```bash
507
+ npm install agentwallet-sdk @solana/web3.js @solana/spl-token
508
+ ```
509
+
510
+ ### SolanaWallet — Non-Custodial Agent Wallet
511
+
512
+ ```typescript
513
+ import { SolanaWallet, SOLANA_USDC_MINT } from 'agentwallet-sdk';
514
+
515
+ // Generate a fresh keypair (ephemeral agent wallet)
516
+ const wallet = SolanaWallet.generate('https://api.mainnet-beta.solana.com');
517
+
518
+ // Or load from existing base58 private key
519
+ const wallet2 = SolanaWallet.fromBase58(process.env.SOLANA_PRIVATE_KEY!, 'https://api.mainnet-beta.solana.com');
520
+
521
+ // Get address (base58 public key)
522
+ console.log(wallet.getAddress());
523
+
524
+ // Check SOL balance (in lamports)
525
+ const lamports = await wallet.getBalance();
526
+ console.log(`${Number(lamports) / 1e9} SOL`);
527
+
528
+ // Check USDC balance (6 decimals)
529
+ const usdc = await wallet.getBalance(SOLANA_USDC_MINT);
530
+ console.log(`${Number(usdc) / 1e6} USDC`);
531
+
532
+ // Transfer SOL
533
+ const sig = await wallet.transfer({
534
+ recipient: 'RecipientPubkey...',
535
+ amount: 500_000_000n, // 0.5 SOL in lamports
536
+ });
537
+
538
+ // Transfer USDC
539
+ const sig2 = await wallet.transfer({
540
+ recipient: 'RecipientPubkey...',
541
+ amount: 5_000_000n, // 5 USDC (6 decimals)
542
+ mint: SOLANA_USDC_MINT,
543
+ });
544
+ ```
545
+
546
+ ### JupiterSwapClient — DEX Aggregator (Solana's Uniswap)
547
+
548
+ ```typescript
549
+ import { SolanaWallet, JupiterSwapClient, SOLANA_USDC_MINT, SOL_NATIVE_MINT } from 'agentwallet-sdk';
550
+
551
+ const wallet = SolanaWallet.fromBase58(process.env.SOLANA_KEY!, 'https://api.mainnet-beta.solana.com');
552
+ const jupiter = new JupiterSwapClient({ wallet });
553
+
554
+ // Get a quote: SOL → USDC
555
+ const quote = await jupiter.getQuote(SOL_NATIVE_MINT, SOLANA_USDC_MINT, 1_000_000_000n);
556
+ console.log(`1 SOL ≈ ${Number(quote.outAmount) / 1e6} USDC`);
557
+
558
+ // Execute swap (0.875% platform fee, 0.5% default slippage)
559
+ const result = await jupiter.swapSolToUsdc(500_000_000n); // 0.5 SOL
560
+ console.log(`Swapped → tx: ${result.txSignature}`);
561
+
562
+ // Reverse: USDC → SOL
563
+ const result2 = await jupiter.swapUsdcToSol(100_000_000n); // 100 USDC
564
+ ```
565
+
566
+ ### SolanaX402Client — x402 Payments on Solana
567
+
568
+ ```typescript
569
+ import { SolanaWallet, SolanaX402Client } from 'agentwallet-sdk';
570
+
571
+ const wallet = SolanaWallet.fromBase58(process.env.SOLANA_KEY!, 'https://api.mainnet-beta.solana.com');
572
+ const x402 = new SolanaX402Client(wallet);
573
+
574
+ // Check if this client can handle a network
575
+ x402.canHandle('solana:mainnet'); // true
576
+ x402.canHandle('base:8453'); // false
577
+
578
+ // Validate payment requirements before paying
579
+ const requirements = {
580
+ scheme: 'exact',
581
+ network: 'solana:mainnet' as const,
582
+ asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
583
+ amount: '1000000', // 1 USDC
584
+ payTo: 'RecipientPubkey...',
585
+ maxTimeoutSeconds: 300,
586
+ extra: {},
587
+ };
588
+
589
+ const { valid, reason } = x402.validateRequirements(requirements, { maxAmount: 5_000_000n });
590
+ if (!valid) throw new Error(reason);
591
+
592
+ // Build signed proof (without broadcasting)
593
+ const proof = await x402.buildPaymentProof(requirements);
594
+ // proof.signedTransaction — base64 signed tx for x402 header
595
+
596
+ // Or pay directly (sign + broadcast)
597
+ const paidProof = await x402.pay(requirements);
598
+ console.log(`Paid! tx: ${paidProof.txSignature}`);
599
+ ```
600
+
601
+ ### Solana Chain Config
602
+
603
+ ```typescript
604
+ import { SOLANA_CONFIG, getSolanaConfig } from 'agentwallet-sdk';
605
+
606
+ const mainnet = getSolanaConfig('solana');
607
+ // { cluster: 'mainnet-beta', rpcUrl: '...', usdcMint: 'EPjFWdd5...', x402Network: 'solana:mainnet' }
608
+
609
+ const devnet = getSolanaConfig('solana-devnet');
610
+ ```
611
+
612
+ ---
613
+
614
+ ## Gas Sponsorship (v3.1.0)
615
+
616
+ Agents don't need to hold native gas tokens. Alchemy's ERC-4337 Gas Manager sponsors gas on their behalf.
617
+
618
+ **Requires:**
619
+ - An Alchemy API key with Gas Manager enabled
620
+ - A Gas Manager policy ID (create at [dashboard.alchemy.com/gas-manager](https://dashboard.alchemy.com/gas-manager))
621
+ - An ERC-4337 smart account for the agent (plain EOAs cannot use paymasters)
622
+
623
+ **Supported chains (6 of 17 CCTP chains):** `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `worldchain`
624
+
625
+ ```typescript
626
+ import { GasSponsor } from 'agentwallet-sdk';
627
+
628
+ const sponsor = new GasSponsor({
629
+ alchemyApiKey: process.env.ALCHEMY_API_KEY!,
630
+ policyId: process.env.ALCHEMY_GAS_POLICY_ID!, // from Alchemy dashboard
631
+ });
632
+
633
+ // Check support before attempting
634
+ if (sponsor.isSupported('base')) {
635
+ const sponsored = await sponsor.sponsorTransaction({
636
+ chain: 'base',
637
+ from: agentSmartAccountAddress, // must be ERC-4337 smart account
638
+ to: usdcContract,
639
+ data: transferCalldata,
640
+ });
641
+ // Submit sponsored.userOperation to an ERC-4337 bundler
642
+ // e.g. via eth_sendUserOperation
643
+ }
644
+
645
+ // Sponsor a bridge transaction
646
+ const sponsoredBridge = await sponsor.sponsorBridge({
647
+ chain: 'optimism',
648
+ from: agentSmartAccountAddress,
649
+ bridgeTx: {
650
+ to: TOKEN_MESSENGER_V2['optimism'],
651
+ data: depositForBurnCalldata,
652
+ value: 0n,
653
+ },
654
+ });
655
+
656
+ // List all supported chains
657
+ const chains = sponsor.getSupportedChains();
658
+ // ['ethereum', 'base', 'arbitrum', 'optimism', 'polygon', 'worldchain']
659
+ ```
660
+
661
+ ---
662
+
663
+ ## Settlement Verification (v3.1.0)
664
+
665
+ Verify that bridge transfers and x402 payments actually settled on-chain. Useful for agents that need to confirm receipt before proceeding.
666
+
667
+ ```typescript
668
+ import { SettlementVerifier } from 'agentwallet-sdk';
669
+
670
+ const verifier = new SettlementVerifier({
671
+ alchemyApiKey: process.env.ALCHEMY_API_KEY, // optional — falls back to public RPCs
672
+ });
673
+
674
+ // Verify any EVM transaction
675
+ const evmResult = await verifier.verifyEvmTransaction({
676
+ chain: 'base',
677
+ txHash: '0xabc123...',
678
+ confirmations: 1, // default: 1
679
+ });
680
+ // { status: 'confirmed', blockNumber: 12345n, confirmations: 5, gasUsed: 21000n, success: true }
681
+
682
+ // Verify a Solana transaction
683
+ const solResult = await verifier.verifySolanaTransaction({
684
+ signature: 'base58sig...',
685
+ commitment: 'finalized', // 'confirmed' | 'finalized', default: 'confirmed'
686
+ });
687
+
688
+ // Verify a CCTP bridge transfer end-to-end
689
+ const bridgeResult = await verifier.verifyBridgeSettlement({
690
+ sourceTxHash: '0xburntx...',
691
+ sourceChain: 'base', // or 'solana'
692
+ destinationChain: 'arbitrum',
693
+ expectedAmount: 1_000_000n, // 1 USDC (6 decimals)
694
+ });
695
+ // { status: 'attestation_complete_awaiting_mint', sourceTx: {...}, attestationStatus: 'complete' }
696
+
697
+ // Verify an x402 payment via ERC20 Transfer event logs
698
+ const paymentResult = await verifier.verifyX402Payment({
699
+ chain: 'base',
700
+ txHash: '0xpaymenttx...',
701
+ expectedPayee: '0xMerchantAddress',
702
+ expectedAmount: 1_000_000n, // 1 USDC
703
+ });
704
+ // { status: 'confirmed', payeeVerified: true, amountVerified: true, actualAmount: 1000000n }
705
+ ```
706
+
707
+ ### Settlement Status Types
708
+
709
+ | Status | Meaning |
710
+ |--------|---------|
711
+ | `confirmed` | Transaction mined with required confirmations |
712
+ | `pending` | Transaction in mempool or not enough confirmations |
713
+ | `failed` | Transaction reverted (status=0) |
714
+ | `not_found` | Transaction not found or RPC error |
715
+
716
+ Bridge-specific statuses:
717
+
718
+ | Status | Meaning |
719
+ |--------|---------|
720
+ | `source_confirmed_awaiting_attestation` | Burn tx confirmed, Circle attestation pending |
721
+ | `attestation_complete_awaiting_mint` | Attestation ready, destination mint not yet verified |
722
+ | `complete` | Full bridge cycle confirmed |
723
+ | `source_failed` | Source burn transaction reverted |
724
+
725
+ ---
726
+
727
+ ## Fiat Onramp (Optional — v3.2.0)
728
+
729
+ > **This module is entirely opt-in. The core SDK is fully anonymous and non-custodial.**
730
+ > Users who fund their agent wallet via direct crypto transfer, bridge, or any other method
731
+ > **never encounter KYC** and remain completely anonymous.
732
+ > KYC only occurs when you explicitly choose to use the fiat onramp feature.
733
+
734
+ The `FiatOnramp` class aggregates multiple fiat-to-crypto providers (MoonPay, Stripe, Transak)
735
+ into a single interface. It returns a `purchaseUrl` — opening this URL takes the user to the
736
+ provider's hosted KYC + payment page. **The SDK never sees, stores, or transmits any KYC data.**
737
+
738
+ ### Install
739
+
740
+ No additional packages needed — `FiatOnramp` is included in `agentwallet-sdk`.
741
+
742
+ Get API keys from the provider dashboards:
743
+
744
+ - **MoonPay:** https://dashboard.moonpay.com (publishable key)
745
+ - **Stripe:** https://dashboard.stripe.com (secret key — server-side only)
746
+ - **Transak:** https://dashboard.transak.com (API key)
747
+
748
+ ### Usage
749
+
750
+ ```typescript
751
+ import { FiatOnramp } from 'agentwallet-sdk';
752
+
753
+ // Only configure the providers you have keys for.
754
+ // Omitting all keys is valid — returns empty provider list with zero friction.
755
+ const onramp = new FiatOnramp({
756
+ moonpayApiKey: process.env.MOONPAY_API_KEY,
757
+ transakApiKey: process.env.TRANSAK_API_KEY,
758
+ });
759
+
760
+ // Get quotes from all configured providers that support base/USDC
761
+ const quotes = await onramp.getQuotes({
762
+ amount: 100,
763
+ currency: 'USD',
764
+ token: 'USDC',
765
+ chain: 'base',
766
+ walletAddress: '0xYourAgentWalletAddress',
767
+ });
768
+
769
+ // quotes[0].kycRequired is always true — KYC happens on the provider's hosted page
770
+ console.log(quotes[0].purchaseUrl); // Open this URL in a browser to complete purchase
771
+
772
+ // Or target a specific provider
773
+ const session = await onramp.createSession({
774
+ amount: 100,
775
+ currency: 'USD',
776
+ token: 'USDC',
777
+ chain: 'base',
778
+ walletAddress: '0xYourAgentWalletAddress',
779
+ provider: 'moonpay',
780
+ redirectUrl: 'https://yourapp.com/done', // optional
781
+ });
782
+
783
+ console.log(session.purchaseUrl); // MoonPay hosted KYC + payment page
784
+ console.log(session.feeAmount); // e.g., 2.50
785
+ console.log(session.feePercent); // e.g., 2.5
786
+ ```
787
+
788
+ ### Supported Chains & Tokens
789
+
790
+ | Provider | Chains | Tokens |
791
+ |----------|--------|--------|
792
+ | MoonPay | ethereum, base, solana, polygon, arbitrum, optimism | ETH, USDC, USDT, SOL, MATIC |
793
+ | Stripe | ethereum, base, solana, polygon, arbitrum, optimism | ETH, USDC, SOL, MATIC |
794
+ | Transak | ethereum, base, solana, polygon, arbitrum, optimism, avalanche, bsc | ETH, USDC, USDT, SOL, MATIC, AVAX, BNB |
795
+
796
+ ### API
797
+
798
+ ```typescript
799
+ // Get quotes from all configured providers
800
+ getQuotes(params: OnrampParams): Promise<FiatQuote[]>
801
+
802
+ // Create a session with a specific provider
803
+ createSession(params: OnrampParams & { provider: string }): Promise<FiatQuote>
804
+
805
+ // Check if a provider supports a chain/token combo
806
+ isSupported(provider: string, chain: string, token: string): boolean
807
+
808
+ // Get configured provider names
809
+ getProviders(): string[]
810
+
811
+ // Get supported chains for a provider
812
+ getSupportedChains(provider: string): string[]
813
+
814
+ // Get supported tokens on a chain for a provider
815
+ getSupportedTokens(provider: string, chain: string): string[]
816
+ ```
817
+
818
+ ### Privacy Guarantee
819
+
820
+ - The SDK **never** collects, stores, or transmits KYC data
821
+ - The SDK **never** stores payment info (no card numbers, no bank accounts)
822
+ - KYC + payment happen entirely on the provider's hosted page
823
+ - Direct crypto funding (transfer, bridge, swap) = fully anonymous, no KYC, ever
824
+
825
+ ---
826
+
396
827
  ## License
397
828
 
398
829
  MIT
@@ -1,14 +1,16 @@
1
1
  import { type Hash, type Hex, type WalletClient } from 'viem';
2
2
  import type { BridgeChain, BridgeOptions, BurnResult, BridgeResult } from './types.js';
3
- import { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD } from './types.js';
3
+ import { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, BRIDGE_RPC_URLS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD } from './types.js';
4
4
  /**
5
- * BridgeModule — CCTP V2 cross-chain USDC bridge.
5
+ * BridgeModule — CCTP V2 cross-chain USDC bridge (16 EVM chains).
6
+ *
7
+ * For EVM↔Solana bridges, use UnifiedBridge instead.
6
8
  *
7
9
  * Usage:
8
10
  * ```ts
9
- * const bridge = new BridgeModule(walletClient, 'base', { rpcUrl: '...' });
10
- * const result = await bridge.bridge(1_000_000n, 'optimism');
11
- * console.log('Minted on Optimism:', result.mintTxHash);
11
+ * const bridge = new BridgeModule(walletClient, 'base');
12
+ * const result = await bridge.bridge(1_000_000n, 'polygon');
13
+ * console.log('Minted on Polygon:', result.mintTxHash);
12
14
  * ```
13
15
  */
14
16
  export declare class BridgeModule {
@@ -20,87 +22,53 @@ export declare class BridgeModule {
20
22
  rpcUrl?: string;
21
23
  });
22
24
  /**
23
- * Bridge USDC from the source chain to the destination chain.
25
+ * Bridge USDC from the source chain to any of the 16 supported EVM destination chains.
24
26
  *
25
- * This is the primary method. It orchestrates the full CCTP V2 flow:
26
- * approve burn attest mint.
27
+ * Full CCTP V2 flow: approve burn attest mint.
28
+ * Platform fee: 0.1% of amount (collected on source chain).
27
29
  *
28
30
  * @param amount - Amount in USDC base units (6 decimals). e.g. 1_000_000n = 1 USDC
29
- * @param toChain - Destination chain ('ethereum' | 'optimism' | 'arbitrum')
31
+ * @param toChain - Destination EVM chain
30
32
  * @param options - Optional overrides (finality, fees, destination address)
31
- *
32
- * @throws BridgeError with actionable message if anything fails
33
33
  */
34
34
  bridge(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BridgeResult>;
35
35
  /**
36
36
  * Step 1 of 3: Burn USDC on the source chain.
37
- * Returns the burn result including message bytes needed for minting.
38
- * Use this for manual/split-phase bridging.
37
+ * Returns burn result for manual/split-phase bridging.
39
38
  */
40
39
  burn(amount: bigint, toChain: BridgeChain, options?: BridgeOptions): Promise<BurnResult>;
41
40
  /**
42
41
  * Step 2 of 3: Poll Circle IRIS API for attestation.
43
- * Returns the attestation bytes once Circle confirms the message.
44
42
  */
45
43
  waitForAttestation(messageHash: Hex, apiUrl?: string): Promise<Hex>;
46
44
  /**
47
45
  * Step 3 of 3: Mint USDC on the destination chain using the attestation.
48
46
  */
49
47
  mint(messageBytes: Hex, attestation: Hex, toChain: BridgeChain, destinationRpcUrl?: string): Promise<Hash>;
50
- /**
51
- * Fetch the current USDC balance on the source chain for the signer's address.
52
- */
48
+ /** Get USDC balance on the source chain */
53
49
  getUsdcBalance(): Promise<bigint>;
54
- /**
55
- * Fetch the current USDC allowance for the TokenMessengerV2 on source chain.
56
- */
50
+ /** Get USDC allowance for the TokenMessengerV2 on source chain */
57
51
  getUsdcAllowance(): Promise<bigint>;
58
- /**
59
- * Approve TokenMessengerV2 to spend USDC on behalf of the signer.
60
- * Skips if existing allowance is sufficient.
61
- */
52
+ /** Get the source chain name */
53
+ getFromChain(): BridgeChain;
62
54
  private approveUsdc;
63
- /**
64
- * Call TokenMessengerV2.depositForBurn and extract MessageSent data.
65
- */
66
55
  private depositForBurn;
67
56
  /**
68
57
  * Extract the CCTP MessageSent event from a transaction receipt.
69
- * The MessageTransmitter emits this event during depositForBurn.
70
58
  */
71
59
  private extractMessageSent;
72
- /**
73
- * Poll the Circle IRIS API until the attestation is ready.
74
- * Fast finality: ~12 seconds. Full finality: ~15 minutes on Ethereum.
75
- */
76
60
  private pollForAttestation;
77
- /**
78
- * Call MessageTransmitterV2.receiveMessage on the destination chain to mint USDC.
79
- */
80
61
  private receiveMessage;
81
62
  private validateBridgeParams;
82
63
  private sleep;
83
64
  }
84
- /**
85
- * Structured bridge error with actionable messages and error codes.
86
- */
87
65
  export declare class BridgeError extends Error {
88
66
  readonly code: string;
89
67
  constructor(code: string, message: string);
90
68
  }
91
- /**
92
- * Create a BridgeModule from an existing AgentWallet object.
93
- * Convenience wrapper for wallet.bridge() integration.
94
- *
95
- * @example
96
- * ```ts
97
- * const bridge = createBridge(wallet.walletClient, 'base', { rpcUrl: BASE_RPC });
98
- * const result = await bridge.bridge(5_000_000n, 'optimism');
99
- * ```
100
- */
101
69
  export declare function createBridge(walletClient: WalletClient, fromChain?: BridgeChain, options?: {
102
70
  rpcUrl?: string;
103
71
  }): BridgeModule;
104
72
  export type { BridgeChain, BridgeOptions, BurnResult, BridgeResult };
105
- export { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, FINALITY_THRESHOLD, };
73
+ export { CCTP_DOMAIN_IDS, BRIDGE_CHAIN_IDS, USDC_CONTRACT, TOKEN_MESSENGER_V2, MESSAGE_TRANSMITTER_V2, BRIDGE_RPC_URLS, FINALITY_THRESHOLD, };
106
74
  //# sourceMappingURL=client.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bridge/client.ts"],"names":[],"mappings":"AAYA,OAAO,EASL,KAAK,IAAI,EACT,KAAK,GAAG,EAER,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AAQd,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EAGb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAUpB;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAG9C,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAsBnC;;;;;;;;;;;OAWG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC;IAmDxB;;;;OAIG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC;IAYtB;;;OAGG;IACG,kBAAkB,CACtB,WAAW,EAAE,GAAG,EAChB,MAAM,GAAE,MAA+B,GACtC,OAAO,CAAC,GAAG,CAAC;IAIf;;OAEG;IACG,IAAI,CACR,YAAY,EAAE,GAAG,EACjB,WAAW,EAAE,GAAG,EAChB,OAAO,EAAE,WAAW,EACpB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC;IAIhB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAUvC;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAezC;;;OAGG;YACW,WAAW;IA2CzB;;OAEG;YACW,cAAc;IAuE5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA8C1B;;;OAGG;YACW,kBAAkB;IAmEhC;;OAEG;YACW,cAAc;IAsD5B,OAAO,CAAC,oBAAoB;IA6B5B,OAAO,CAAC,KAAK;CAGd;AAID;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAElB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAID;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,YAAY,CAEd;AAGD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACrE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,GACnB,CAAC"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bridge/client.ts"],"names":[],"mappings":"AAYA,OAAO,EASL,KAAK,IAAI,EACT,KAAK,GAAG,EAER,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AAYd,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,UAAU,EACV,YAAY,EAEb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAKnB,MAAM,YAAY,CAAC;AAqCpB;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAG9C,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IA6BnC;;;;;;;;;OASG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC;IAmDxB;;;OAGG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC;IAYtB;;OAEG;IACG,kBAAkB,CACtB,WAAW,EAAE,GAAG,EAChB,MAAM,GAAE,MAA+B,GACtC,OAAO,CAAC,GAAG,CAAC;IAIf;;OAEG;IACG,IAAI,CACR,YAAY,EAAE,GAAG,EACjB,WAAW,EAAE,GAAG,EAChB,OAAO,EAAE,WAAW,EACpB,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC;IAIhB,2CAA2C;IACrC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAUvC,kEAAkE;IAC5D,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAazC,gCAAgC;IAChC,YAAY,IAAI,WAAW;YAMb,WAAW;YAsCX,cAAc;IAkE5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;YAsCZ,kBAAkB;YA0DlB,cAAc;IAmD5B,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,KAAK;CAGd;AAID,qBAAa,WAAY,SAAQ,KAAK;aAElB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAID,wBAAgB,YAAY,CAC1B,YAAY,EAAE,YAAY,EAC1B,SAAS,GAAE,WAAoB,EAC/B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,YAAY,CAEd;AAGD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACrE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,GACnB,CAAC"}