otx-swap 1.2.7 → 1.2.8

package/README.md

@@ -30,26 +30,34 @@ npm install react react-dom
 ## Quick Start
 
 ```tsx
-import { SwapWidget } from "otx-swap";
-import type { ExternalWalletClient } from "otx-swap";
+import { useState, useEffect, useMemo } from "react";
+import { SwapWidget, createEvmWalletClientAsync } from "otx-swap";
+import type { ExternalWalletClient, EvmWalletAccount, Eip1193Provider } from "otx-swap";
 
 function App() {
-  // Build wallet client from your wallet provider
-  const walletClient: ExternalWalletClient = {
-    evm: {
-      address: "0x...",
-      publicKey: "0x...",
-      chain: { id: 1, name: "Ethereum", type: "EVM" },
-      sendTransaction: async (tx) => {
-        // Your wallet's sendTransaction implementation
-        return txHash;
-      },
-      getChainId: async () => 1,
-      switchChain: async (chainId) => {
-        // Your wallet's switchChain implementation
-      },
-    },
-  };
+  const [evmWallet, setEvmWallet] = useState<EvmWalletAccount | null>(null);
+
+  // Create wallet client from EIP-1193 provider (MetaMask, WalletConnect, etc.)
+  useEffect(() => {
+    const initWallet = async () => {
+      if (window.ethereum) {
+        try {
+          const wallet = await createEvmWalletClientAsync({
+            provider: window.ethereum as Eip1193Provider,
+          });
+          setEvmWallet(wallet);
+        } catch (error) {
+          console.error("Failed to create wallet:", error);
+        }
+      }
+    };
+    initWallet();
+  }, []);
+
+  const walletClient = useMemo((): ExternalWalletClient => {
+    if (!evmWallet) return {};
+    return { evm: evmWallet };
+  }, [evmWallet]);
 
   return (
     <SwapWidget
@@ -234,11 +242,107 @@ interface WalletAccount {
 }
 ```
 
+### EVM Helpers
+
+We provide two helper functions to convert any EIP-1193 provider to the required wallet interface:
+
+#### createEvmWalletClientAsync (Recommended)
+
+Async version that automatically fetches `address` and `chainId` from the provider if not provided:
+
+```tsx
+import { createEvmWalletClientAsync } from "otx-swap";
+import type { EvmWalletAccount, Eip1193Provider } from "otx-swap";
+
+// Simplest usage - just pass the provider
+const evmWallet = await createEvmWalletClientAsync({
+  provider: window.ethereum as Eip1193Provider,
+});
+
+// Or with optional overrides
+const evmWallet = await createEvmWalletClientAsync({
+  provider: window.ethereum as Eip1193Provider,
+  chainName: "Ethereum",  // Optional
+});
+```
+
+#### createEvmWalletClient (Sync)
+
+Sync version that requires all parameters:
+
+```tsx
+import { createEvmWalletClient } from "otx-swap";
+import type { ExternalWalletClient } from "otx-swap";
+
+const walletClient: ExternalWalletClient = {
+  evm: createEvmWalletClient({
+    provider: window.ethereum,  // Any EIP-1193 provider
+    address: "0x...",           // Required
+    chainId: 1,                 // Required
+    chainName: "Ethereum",      // Optional
+  }),
+};
+```
+
 ### Integration Examples
 
-#### With wagmi (EVM)
+#### With wagmi (EVM) - Recommended
+
+Using `createEvmWalletClientAsync` with wagmi's connector provider:
 
 ```tsx
+import { useState, useEffect, useMemo } from "react";
+import { useAccount, useChainId } from "wagmi";
+import { SwapWidget, createEvmWalletClientAsync } from "otx-swap";
+import type { ExternalWalletClient, EvmWalletAccount, Eip1193Provider } from "otx-swap";
+
+function SwapWithWagmi() {
+  const { isConnected, connector } = useAccount();
+  const chainId = useChainId();
+  const [evmWallet, setEvmWallet] = useState<EvmWalletAccount | null>(null);
+
+  // Create wallet client from provider (auto-fetches address & chainId)
+  useEffect(() => {
+    if (connector?.getProvider && isConnected) {
+      connector.getProvider().then(async (provider) => {
+        try {
+          const wallet = await createEvmWalletClientAsync({
+            provider: provider as Eip1193Provider,
+          });
+          setEvmWallet(wallet);
+        } catch (error) {
+          console.error("Failed to create wallet client:", error);
+          setEvmWallet(null);
+        }
+      });
+    } else {
+      setEvmWallet(null);
+    }
+  }, [connector, isConnected, chainId]); // Recreate on chain change
+
+  const walletClient = useMemo((): ExternalWalletClient => {
+    if (!isConnected || !evmWallet) return {};
+    return { evm: evmWallet };
+  }, [isConnected, evmWallet]);
+
+  return (
+    <SwapWidget
+      apiBaseUrl="https://api.optimex.io"
+      walletClient={walletClient}
+      onRequestWallet={() => {
+        // Open your wallet connect modal
+      }}
+    />
+  );
+}
+```
+
+#### With wagmi (EVM) - Using wagmi Hooks
+
+Alternative approach using wagmi's transaction hooks instead of the helper function:
+
+```tsx
+import { useMemo } from "react";
 import { useAccount, useSendTransaction, useChainId, useSwitchChain } from "wagmi";
 import { SwapWidget } from "otx-swap";
 import type { ExternalWalletClient, EvmTransactionRequest } from "otx-swap";
@@ -249,25 +353,28 @@ function SwapWithWagmi() {
   const { sendTransactionAsync } = useSendTransaction();
   const { switchChainAsync } = useSwitchChain();
 
-  const walletClient: ExternalWalletClient = {
-    evm: isConnected && address ? {
-      address,
-      publicKey: address,
-      chain: { id: chainId, name: "Ethereum", type: "EVM" },
-      sendTransaction: async (tx: unknown) => {
-        const evmTx = tx as EvmTransactionRequest;
-        return sendTransactionAsync({
-          to: evmTx.to,
-          value: evmTx.value,
-          data: evmTx.data,
-        });
-      },
-      getChainId: async () => chainId,
-      switchChain: async (id) => {
-        await switchChainAsync({ chainId: id });
+  const walletClient = useMemo((): ExternalWalletClient => {
+    if (!isConnected || !address) return {};
+    return {
+      evm: {
+        address,
+        publicKey: address,
+        chain: { id: chainId, name: "Ethereum", type: "EVM" },
+        sendTransaction: async (tx: unknown) => {
+          const evmTx = tx as EvmTransactionRequest;
+          return sendTransactionAsync({
+            to: evmTx.to,
+            value: evmTx.value,
+            data: evmTx.data,
+          });
+        },
+        getChainId: async () => chainId,
+        switchChain: async (id) => {
+          await switchChainAsync({ chainId: id });
+        },
       },
-    } : undefined,
-  };
+    };
+  }, [isConnected, address, chainId, sendTransactionAsync, switchChainAsync]);
 
   return (
     <SwapWidget
@@ -430,22 +537,42 @@ import { SwapCard, ConnectButton, useWallet } from "otx-swap";
 Full TypeScript support with exported types:
 
 ```tsx
+import {
+  // Helper functions
+  createEvmWalletClient,       // Sync version (requires address & chainId)
+  createEvmWalletClientAsync,  // Async version (auto-fetches from provider)
+} from "otx-swap";
+
 import type {
+  // Props
   SwapWidgetProps,
+
+  // Wallet types
   ExternalWalletClient,
   WalletAccount,
   EvmWalletAccount,
+  ChainInfo,
+  Eip1193Provider,
+  CreateEvmWalletClientOptions,       // For sync version
+  CreateEvmWalletClientAsyncOptions,  // For async version
+
+  // Transaction types
   EvmTransactionRequest,
   BitcoinTransactionRequest,
-  ChainInfo,
+
+  // Data types
   Token,
   Quote,
   Trade,
   TradeState,
   NetworkType,
+
+  // Theme types
   ThemeConfig,
   PartialThemeConfig,
   ThemeColors,
+
+  // Callback types
   QuoteCallbackData,
   WalletTxCallbackData,
   SubmitTxCallbackData,