uvd-x402-sdk 2.0.3 → 2.2.0

package/README.md

@@ -2,17 +2,19 @@
 
 > Gasless crypto payments across 14 blockchain networks using the x402 protocol.
 
-The x402 SDK enables any application to accept USDC payments without requiring users to pay gas fees. Users sign a message or transaction, and the Ultravioleta facilitator handles on-chain settlement.
+The x402 SDK enables any application to accept stablecoin payments (USDC, EURC, AUSD, PYUSD, GHO, crvUSD) without requiring users to pay gas fees. Users sign a message or transaction, and the Ultravioleta facilitator handles on-chain settlement.
 
 ## Features
 
 - **14 Supported Networks**: EVM chains, Solana, Fogo, Stellar, and NEAR
+- **Multi-Stablecoin**: USDC, EURC, AUSD, PYUSD, GHO, crvUSD support on EVM chains
 - **x402 v1 & v2**: Full support for both protocol versions with automatic detection
 - **Gasless Payments**: Users never pay gas - the facilitator covers all network fees
 - **Multi-Network**: Accept payments on multiple networks simultaneously
 - **Type-Safe**: Comprehensive TypeScript definitions
 - **Framework Agnostic**: Works with any JavaScript framework
 - **React Hooks**: First-class React integration
+- **Wagmi/RainbowKit**: Dedicated adapter for wagmi-based apps
 - **Modular**: Import only what you need
 
 ## Quick Start
@@ -126,6 +128,117 @@ const result = await client.createPayment({
 
 ---
 
+## Wagmi / RainbowKit Integration
+
+If you're using wagmi with RainbowKit, ConnectKit, or other wagmi-based wallet libraries, use the dedicated wagmi adapter:
+
+```typescript
+import { useWalletClient } from 'wagmi';
+import { createPaymentFromWalletClient } from 'uvd-x402-sdk/wagmi';
+
+function PayButton() {
+  const { data: walletClient } = useWalletClient();
+
+  const handlePay = async () => {
+    const paymentHeader = await createPaymentFromWalletClient(walletClient, {
+      recipient: '0xD3868E1eD738CED6945A574a7c769433BeD5d474',
+      amount: '10.00',
+      chainName: 'base', // optional, defaults to 'base'
+    });
+
+    // Use in your API request
+    await fetch('/api/purchase', {
+      headers: { 'X-PAYMENT': paymentHeader },
+      method: 'POST',
+    });
+  };
+
+  return <button onClick={handlePay}>Pay $10 USDC</button>;
+}
+```
+
+### With the Helper Hook
+
+```typescript
+import { useWalletClient } from 'wagmi';
+import { useX402Wagmi } from 'uvd-x402-sdk/wagmi';
+
+function PayButton() {
+  const { data: walletClient } = useWalletClient();
+  const { createPayment, isReady } = useX402Wagmi(walletClient);
+
+  const handlePay = async () => {
+    const paymentHeader = await createPayment({
+      recipient: '0xD3868E1eD738CED6945A574a7c769433BeD5d474',
+      amount: '10.00',
+    });
+
+    await fetch('/api/purchase', {
+      headers: { 'X-PAYMENT': paymentHeader },
+    });
+  };
+
+  return (
+    <button onClick={handlePay} disabled={!isReady}>
+      Pay $10 USDC
+    </button>
+  );
+}
+```
+
+### Full Example with RainbowKit
+
+```tsx
+import { ConnectButton } from '@rainbow-me/rainbowkit';
+import { useWalletClient, useAccount } from 'wagmi';
+import { createPaymentFromWalletClient } from 'uvd-x402-sdk/wagmi';
+
+function App() {
+  const { data: walletClient } = useWalletClient();
+  const { isConnected } = useAccount();
+
+  const handlePurchase = async () => {
+    if (!walletClient) return;
+
+    try {
+      const paymentHeader = await createPaymentFromWalletClient(walletClient, {
+        recipient: '0xD3868E1eD738CED6945A574a7c769433BeD5d474',
+        amount: '5.00',
+        chainName: 'base',
+      });
+
+      const response = await fetch('/api/purchase', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-PAYMENT': paymentHeader,
+        },
+        body: JSON.stringify({ item: 'premium-feature' }),
+      });
+
+      if (response.ok) {
+        alert('Purchase successful!');
+      }
+    } catch (error) {
+      console.error('Payment failed:', error);
+    }
+  };
+
+  return (
+    <div>
+      <ConnectButton />
+      {isConnected && (
+        <button onClick={handlePurchase}>
+          Buy Premium ($5 USDC)
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
 ## Network Examples
 
 ### EVM Chains (10 Networks)
@@ -557,6 +670,118 @@ const options = generatePaymentOptions(chains, '10.00');
 
 ---
 
+## Multi-Stablecoin Support (EVM)
+
+EVM chains support multiple stablecoins beyond USDC. Token availability varies by chain.
+
+### Supported Tokens
+
+| Token | Description | Decimals | Chains |
+|-------|-------------|----------|--------|
+| USDC | USD Coin (Circle) | 6 | All EVM chains |
+| EURC | Euro Coin (Circle) | 6 | Ethereum, Base, Avalanche |
+| AUSD | Agora USD | 6 | Ethereum, Avalanche, Polygon, Arbitrum, Monad |
+| PYUSD | PayPal USD | 6 | Ethereum |
+| GHO | Aave GHO | 18 | Ethereum, Base, Arbitrum |
+| crvUSD | Curve USD | 18 | Ethereum, Arbitrum |
+
+### Basic Usage
+
+```typescript
+import { X402Client } from 'uvd-x402-sdk';
+
+const client = new X402Client({ defaultChain: 'base' });
+await client.connect('base');
+
+// Pay with EURC instead of USDC
+const result = await client.createPayment({
+  recipient: '0xD3868E1eD738CED6945A574a7c769433BeD5d474',
+  amount: '10.00',
+  tokenType: 'eurc', // 'usdc' | 'eurc' | 'ausd' | 'pyusd' | 'gho' | 'crvusd'
+});
+```
+
+### Check Token Availability
+
+```typescript
+import {
+  getSupportedTokens,
+  isTokenSupported,
+  getTokenConfig,
+  getChainsByToken,
+} from 'uvd-x402-sdk';
+
+// Get all tokens supported on a chain
+const tokens = getSupportedTokens('ethereum');
+// Returns: ['usdc', 'eurc', 'ausd', 'pyusd', 'gho', 'crvusd']
+
+const baseTokens = getSupportedTokens('base');
+// Returns: ['usdc', 'eurc', 'gho']
+
+// Check if a specific token is supported
+if (isTokenSupported('base', 'eurc')) {
+  console.log('EURC available on Base');
+}
+
+// Get token configuration (address, decimals, name)
+const eurcConfig = getTokenConfig('ethereum', 'eurc');
+// Returns: { address: '0x1aBa...', decimals: 6, name: 'EURC', version: '2' }
+
+// Find all chains that support a token
+const ghoChains = getChainsByToken('gho');
+// Returns: [baseConfig, ethereumConfig, arbitrumConfig]
+```
+
+### Check Token Balance
+
+```typescript
+import { EVMProvider } from 'uvd-x402-sdk';
+import { getChainByName } from 'uvd-x402-sdk';
+
+const evm = new EVMProvider();
+await evm.connect();
+
+const chainConfig = getChainByName('ethereum')!;
+
+// Check USDC balance (default)
+const usdcBalance = await evm.getBalance(chainConfig);
+
+// Check EURC balance
+const eurcBalance = await evm.getBalance(chainConfig, 'eurc');
+
+// Check GHO balance
+const ghoBalance = await evm.getBalance(chainConfig, 'gho');
+```
+
+### Wagmi/RainbowKit with Multi-Token
+
+```typescript
+import { useWalletClient } from 'wagmi';
+import { createPaymentFromWalletClient } from 'uvd-x402-sdk/wagmi';
+
+function PayWithEURC() {
+  const { data: walletClient } = useWalletClient();
+
+  const handlePay = async () => {
+    const paymentHeader = await createPaymentFromWalletClient(walletClient, {
+      recipient: '0xD3868E1eD738CED6945A574a7c769433BeD5d474',
+      amount: '10.00',
+      chainName: 'base',
+      tokenType: 'eurc', // Pay with EURC
+    });
+
+    await fetch('/api/purchase', {
+      headers: { 'X-PAYMENT': paymentHeader },
+      method: 'POST',
+    });
+  };
+
+  return <button onClick={handlePay}>Pay 10 EURC</button>;
+}
+```
+
+---
+
 ## React Integration
 
 ```tsx
@@ -612,18 +837,18 @@ function PaymentPage() {
 
 ### EVM Networks (10)
 
-| Network | Chain ID | USDC Decimals | Status |
-|---------|----------|---------------|--------|
-| Base | 8453 | 6 | Enabled |
-| Ethereum | 1 | 6 | Enabled |
-| Polygon | 137 | 6 | Enabled |
-| Arbitrum | 42161 | 6 | Enabled |
-| Optimism | 10 | 6 | Enabled |
-| Avalanche | 43114 | 6 | Enabled |
-| Celo | 42220 | 6 | Enabled |
-| HyperEVM | 999 | 6 | Enabled |
-| Unichain | 130 | 6 | Enabled |
-| Monad | 143 | 6 | Enabled |
+| Network | Chain ID | Tokens | Status |
+|---------|----------|--------|--------|
+| Ethereum | 1 | USDC, EURC, AUSD, PYUSD, GHO, crvUSD | Enabled |
+| Base | 8453 | USDC, EURC, GHO | Enabled |
+| Avalanche | 43114 | USDC, EURC, AUSD | Enabled |
+| Arbitrum | 42161 | USDC, AUSD, GHO, crvUSD | Enabled |
+| Polygon | 137 | USDC, AUSD | Enabled |
+| Monad | 143 | USDC, AUSD | Enabled |
+| Optimism | 10 | USDC | Enabled |
+| Celo | 42220 | USDC | Enabled |
+| HyperEVM | 999 | USDC | Enabled |
+| Unichain | 130 | USDC | Enabled |
 
 ### SVM Networks (2)
 
@@ -667,8 +892,8 @@ interface X402ClientConfig {
 | `connect(chainName?)` | Connect wallet to specified chain |
 | `disconnect()` | Disconnect current wallet |
 | `switchChain(chainName)` | Switch to different EVM chain |
-| `createPayment(paymentInfo)` | Create payment authorization |
-| `getBalance()` | Get USDC balance on current chain |
+| `createPayment(paymentInfo)` | Create payment authorization (supports `tokenType` in paymentInfo) |
+| `getBalance(tokenType?)` | Get token balance on current chain (defaults to USDC) |
 | `getState()` | Get current wallet state |
 | `isConnected()` | Check if wallet is connected |
 | `on(event, handler)` | Subscribe to events |
@@ -686,9 +911,23 @@ import {
   isSVMChain,
   getExplorerTxUrl,
   getExplorerAddressUrl,
+  // Multi-token utilities
+  getTokenConfig,
+  getSupportedTokens,
+  isTokenSupported,
+  getChainsByToken,
 } from 'uvd-x402-sdk';
 ```
 
+### Token Utilities
+
+| Function | Description |
+|----------|-------------|
+| `getTokenConfig(chain, tokenType)` | Get token config (address, decimals, name, version) |
+| `getSupportedTokens(chain)` | Get array of supported token types for a chain |
+| `isTokenSupported(chain, tokenType)` | Check if token is available on chain |
+| `getChainsByToken(tokenType)` | Get all chains that support a specific token |
+
 ### x402 Utilities
 
 ```typescript
@@ -705,6 +944,34 @@ import {
 } from 'uvd-x402-sdk';
 ```
 
+### Wagmi Adapter
+
+```typescript
+import {
+  createPaymentFromWalletClient,
+  createPaymentWithResult,
+  useX402Wagmi,
+} from 'uvd-x402-sdk/wagmi';
+```
+
+| Function | Description |
+|----------|-------------|
+| `createPaymentFromWalletClient(walletClient, options)` | Create payment header using wagmi's WalletClient |
+| `createPaymentWithResult(walletClient, options)` | Same as above but returns full PaymentResult |
+| `useX402Wagmi(walletClient)` | Helper hook returning `{ createPayment, isReady }` |
+
+#### Options
+
+```typescript
+interface WagmiPaymentOptions {
+  recipient: string;        // Recipient address
+  amount: string;           // Amount in token (e.g., "10.00")
+  chainName?: string;       // Chain name (default: 'base')
+  tokenType?: TokenType;    // Token type (default: 'usdc')
+  validitySeconds?: number; // Signature validity window (default: 300)
+}
+```
+
 ---
 
 ## Error Handling

package/dist/adapters/index.d.mts

@@ -0,0 +1,139 @@
+import { f as PaymentResult } from '../index-BHwtdJrt.mjs';
+
+/**
+ * uvd-x402-sdk - Wagmi/Viem Adapter
+ *
+ * Provides integration with wagmi/viem for projects using RainbowKit,
+ * ConnectKit, or other wagmi-based wallet connection libraries.
+ *
+ * @example
+ * ```tsx
+ * import { useWalletClient } from 'wagmi';
+ * import { createPaymentFromWalletClient } from 'uvd-x402-sdk/wagmi';
+ *
+ * function PayButton() {
+ *   const { data: walletClient } = useWalletClient();
+ *
+ *   const handlePay = async () => {
+ *     const paymentHeader = await createPaymentFromWalletClient(walletClient, {
+ *       recipient: '0x...',
+ *       amount: '1.00',
+ *       chainName: 'base',
+ *     });
+ *
+ *     // Use in your API request
+ *     await fetch('/api/paid-endpoint', {
+ *       headers: { 'X-PAYMENT': paymentHeader }
+ *     });
+ *   };
+ *
+ *   return <button onClick={handlePay}>Pay $1.00</button>;
+ * }
+ * ```
+ */
+
+/**
+ * Viem WalletClient interface (minimal type to avoid viem dependency)
+ */
+interface WalletClient {
+    account: {
+        address: `0x${string}`;
+    };
+    signTypedData: (args: {
+        domain: {
+            name: string;
+            version: string;
+            chainId: number;
+            verifyingContract: `0x${string}`;
+        };
+        types: Record<string, Array<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }) => Promise<`0x${string}`>;
+}
+/**
+ * Payment options for wagmi adapter
+ */
+interface WagmiPaymentOptions {
+    /** Recipient address */
+    recipient: string;
+    /** Amount in USDC (e.g., "1.00", "10.50") */
+    amount: string;
+    /** Chain name (default: 'base') */
+    chainName?: string;
+    /** Validity window in seconds (default: 300 = 5 minutes) */
+    validitySeconds?: number;
+}
+/**
+ * Create an x402 payment header using a wagmi/viem WalletClient
+ *
+ * This function allows you to use the x402 SDK with wagmi-based wallet
+ * connections (RainbowKit, ConnectKit, etc.) instead of the built-in
+ * wallet connection.
+ *
+ * @param walletClient - The WalletClient from wagmi's useWalletClient hook
+ * @param options - Payment options (recipient, amount, chainName)
+ * @returns Base64-encoded payment header ready for X-PAYMENT HTTP header
+ *
+ * @example
+ * ```tsx
+ * import { useWalletClient } from 'wagmi';
+ * import { createPaymentFromWalletClient } from 'uvd-x402-sdk/wagmi';
+ *
+ * const { data: walletClient } = useWalletClient();
+ *
+ * const paymentHeader = await createPaymentFromWalletClient(walletClient, {
+ *   recipient: '0xRecipientAddress',
+ *   amount: '5.00',
+ *   chainName: 'base',
+ * });
+ * ```
+ */
+declare function createPaymentFromWalletClient(walletClient: WalletClient | undefined | null, options: WagmiPaymentOptions): Promise<string>;
+/**
+ * Create payment with full result object (includes metadata)
+ *
+ * Same as createPaymentFromWalletClient but returns a PaymentResult
+ * object with additional metadata.
+ *
+ * @param walletClient - The WalletClient from wagmi
+ * @param options - Payment options
+ * @returns PaymentResult with paymentHeader and metadata
+ */
+declare function createPaymentWithResult(walletClient: WalletClient | undefined | null, options: WagmiPaymentOptions): Promise<PaymentResult>;
+/**
+ * React hook helper for wagmi integration
+ *
+ * Returns a function that creates payments using the connected wallet.
+ * This is a simple wrapper - for more control, use createPaymentFromWalletClient directly.
+ *
+ * @example
+ * ```tsx
+ * import { useWalletClient } from 'wagmi';
+ * import { useX402Wagmi } from 'uvd-x402-sdk/wagmi';
+ *
+ * function PayButton() {
+ *   const { data: walletClient } = useWalletClient();
+ *   const { createPayment, isReady } = useX402Wagmi(walletClient);
+ *
+ *   return (
+ *     <button
+ *       disabled={!isReady}
+ *       onClick={() => createPayment({ recipient: '0x...', amount: '1.00' })}
+ *     >
+ *       Pay
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useX402Wagmi(walletClient: WalletClient | undefined | null): {
+    isReady: boolean;
+    createPayment: (options: WagmiPaymentOptions) => Promise<string>;
+    createPaymentFull: (options: WagmiPaymentOptions) => Promise<PaymentResult>;
+};
+
+export { type WagmiPaymentOptions, type WalletClient, createPaymentFromWalletClient, createPaymentWithResult, useX402Wagmi };

package/dist/adapters/index.d.ts

@@ -0,0 +1,139 @@
+import { f as PaymentResult } from '../index-BHwtdJrt.js';
+
+/**
+ * uvd-x402-sdk - Wagmi/Viem Adapter
+ *
+ * Provides integration with wagmi/viem for projects using RainbowKit,
+ * ConnectKit, or other wagmi-based wallet connection libraries.
+ *
+ * @example
+ * ```tsx
+ * import { useWalletClient } from 'wagmi';
+ * import { createPaymentFromWalletClient } from 'uvd-x402-sdk/wagmi';
+ *
+ * function PayButton() {
+ *   const { data: walletClient } = useWalletClient();
+ *
+ *   const handlePay = async () => {
+ *     const paymentHeader = await createPaymentFromWalletClient(walletClient, {
+ *       recipient: '0x...',
+ *       amount: '1.00',
+ *       chainName: 'base',
+ *     });
+ *
+ *     // Use in your API request
+ *     await fetch('/api/paid-endpoint', {
+ *       headers: { 'X-PAYMENT': paymentHeader }
+ *     });
+ *   };
+ *
+ *   return <button onClick={handlePay}>Pay $1.00</button>;
+ * }
+ * ```
+ */
+
+/**
+ * Viem WalletClient interface (minimal type to avoid viem dependency)
+ */
+interface WalletClient {
+    account: {
+        address: `0x${string}`;
+    };
+    signTypedData: (args: {
+        domain: {
+            name: string;
+            version: string;
+            chainId: number;
+            verifyingContract: `0x${string}`;
+        };
+        types: Record<string, Array<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }) => Promise<`0x${string}`>;
+}
+/**
+ * Payment options for wagmi adapter
+ */
+interface WagmiPaymentOptions {
+    /** Recipient address */
+    recipient: string;
+    /** Amount in USDC (e.g., "1.00", "10.50") */
+    amount: string;
+    /** Chain name (default: 'base') */
+    chainName?: string;
+    /** Validity window in seconds (default: 300 = 5 minutes) */
+    validitySeconds?: number;
+}
+/**
+ * Create an x402 payment header using a wagmi/viem WalletClient
+ *
+ * This function allows you to use the x402 SDK with wagmi-based wallet
+ * connections (RainbowKit, ConnectKit, etc.) instead of the built-in
+ * wallet connection.
+ *
+ * @param walletClient - The WalletClient from wagmi's useWalletClient hook
+ * @param options - Payment options (recipient, amount, chainName)
+ * @returns Base64-encoded payment header ready for X-PAYMENT HTTP header
+ *
+ * @example
+ * ```tsx
+ * import { useWalletClient } from 'wagmi';
+ * import { createPaymentFromWalletClient } from 'uvd-x402-sdk/wagmi';
+ *
+ * const { data: walletClient } = useWalletClient();
+ *
+ * const paymentHeader = await createPaymentFromWalletClient(walletClient, {
+ *   recipient: '0xRecipientAddress',
+ *   amount: '5.00',
+ *   chainName: 'base',
+ * });
+ * ```
+ */
+declare function createPaymentFromWalletClient(walletClient: WalletClient | undefined | null, options: WagmiPaymentOptions): Promise<string>;
+/**
+ * Create payment with full result object (includes metadata)
+ *
+ * Same as createPaymentFromWalletClient but returns a PaymentResult
+ * object with additional metadata.
+ *
+ * @param walletClient - The WalletClient from wagmi
+ * @param options - Payment options
+ * @returns PaymentResult with paymentHeader and metadata
+ */
+declare function createPaymentWithResult(walletClient: WalletClient | undefined | null, options: WagmiPaymentOptions): Promise<PaymentResult>;
+/**
+ * React hook helper for wagmi integration
+ *
+ * Returns a function that creates payments using the connected wallet.
+ * This is a simple wrapper - for more control, use createPaymentFromWalletClient directly.
+ *
+ * @example
+ * ```tsx
+ * import { useWalletClient } from 'wagmi';
+ * import { useX402Wagmi } from 'uvd-x402-sdk/wagmi';
+ *
+ * function PayButton() {
+ *   const { data: walletClient } = useWalletClient();
+ *   const { createPayment, isReady } = useX402Wagmi(walletClient);
+ *
+ *   return (
+ *     <button
+ *       disabled={!isReady}
+ *       onClick={() => createPayment({ recipient: '0x...', amount: '1.00' })}
+ *     >
+ *       Pay
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useX402Wagmi(walletClient: WalletClient | undefined | null): {
+    isReady: boolean;
+    createPayment: (options: WagmiPaymentOptions) => Promise<string>;
+    createPaymentFull: (options: WagmiPaymentOptions) => Promise<PaymentResult>;
+};
+
+export { type WagmiPaymentOptions, type WalletClient, createPaymentFromWalletClient, createPaymentWithResult, useX402Wagmi };