uvd-x402-sdk 2.0.2 → 2.1.0

package/README.md

@@ -69,9 +69,66 @@ npm install react
 
 ---
 
+## WalletConnect Integration
+
+The SDK works with any EVM wallet that injects into `window.ethereum`, including:
+
+- **Browser extensions**: MetaMask, Rainbow, Rabby, Coinbase Wallet
+- **Mobile wallets**: Rainbow, MetaMask Mobile, Trust Wallet (via WalletConnect)
+
+### Using WalletConnect (Mobile Wallets)
+
+For mobile wallet support (Rainbow, MetaMask Mobile, etc.), initialize WalletConnect before using the SDK:
+
+```typescript
+import { EthereumProvider } from '@walletconnect/ethereum-provider';
+import { X402Client } from 'uvd-x402-sdk';
+
+// 1. Initialize WalletConnect
+const walletConnectProvider = await EthereumProvider.init({
+  projectId: 'YOUR_WALLETCONNECT_PROJECT_ID', // Get from cloud.walletconnect.com
+  chains: [8453], // Base mainnet
+  optionalChains: [1, 137, 42161, 10], // ETH, Polygon, Arbitrum, Optimism
+  showQrModal: true,
+});
+
+// 2. Connect wallet (shows QR code for mobile wallet to scan)
+await walletConnectProvider.connect();
+
+// 3. Use the SDK normally
+const client = new X402Client({ defaultChain: 'base' });
+const address = await client.connect('base');
+
+// 4. Create payment
+const result = await client.createPayment({
+  recipient: '0xD3868E1eD738CED6945A574a7c769433BeD5d474',
+  amount: '10.00',
+});
+```
+
+### Using Browser Extensions (Rainbow, MetaMask, etc.)
+
+Browser extension wallets work automatically - no extra setup needed:
+
+```typescript
+import { X402Client } from 'uvd-x402-sdk';
+
+const client = new X402Client({ defaultChain: 'base' });
+
+// Connects to whatever wallet is installed (Rainbow, MetaMask, Rabby, etc.)
+const address = await client.connect('base');
+
+const result = await client.createPayment({
+  recipient: '0xD3868E1eD738CED6945A574a7c769433BeD5d474',
+  amount: '10.00',
+});
+```
+
+---
+
 ## Network Examples
 
-### EVM Chains (11 Networks)
+### EVM Chains (10 Networks)
 
 All EVM chains use EIP-712 typed data signing with ERC-3009 TransferWithAuthorization.
 

package/dist/adapters/index.d.mts

@@ -0,0 +1,139 @@
+import { e as PaymentResult } from '../index-MTBgC_SL.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 { e as PaymentResult } from '../index-MTBgC_SL.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 };