router-widget-sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,23 @@
-# router-widget-sdk
+# Router Widget SDK
 
-Router Protocol Widget - A React component for cross-chain swaps that can be embedded in any React application.
+A production-ready React component for cross-chain swaps that can be embedded in any React application. Supports EVM chains, Solana, Bitcoin, and Sui with flexible wallet integration options.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Wallet Integration](#wallet-integration)
+  - [Internal Wallet Mode (Default)](#internal-wallet-mode-default)
+  - [External Wallet Mode (Dynamic.xyz)](#external-wallet-mode-dynamicxyz)
+  - [Solana Support](#solana-support)
+- [Configuration](#configuration)
+- [Advanced Usage](#advanced-usage)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [TypeScript Support](#typescript-support)
+- [Styling](#styling)
+- [Environment Variables](#environment-variables)
+- [Browser Support](#browser-support)
 
 ## Installation
 
@@ -12,8 +29,18 @@ pnpm add router-widget-sdk
 yarn add router-widget-sdk
 ```
 
+### Peer Dependencies
+
+The SDK requires React 18.3.1 or higher:
+
+```bash
+npm install react@^18.3.1 react-dom@^18.3.1
+```
+
 ## Quick Start
 
+### Basic Usage
+
 ```tsx
 import { RouterWidget } from 'router-widget-sdk';
 import 'router-widget-sdk/styles.css';
@@ -30,115 +57,807 @@ function App() {
 }
 ```
 
-## Configuration
+### With Initial State
 
-### Basic Usage
+```tsx
+<RouterWidget
+  config={{
+    initialState: {
+      fromChainId: '1', // Ethereum
+      fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+      toChainId: '137', // Polygon
+      toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC on Polygon
+    },
+    theme: { mode: 'dark' },
+    integrator: 'MyDApp',
+  }}
+/>
+```
+
+## Wallet Integration
+
+The SDK supports multiple wallet integration modes:
+
+### Internal Wallet Mode (Default)
+
+By default, the SDK provides its own wallet connection infrastructure:
+
+- **EVM Chains**: Uses Wagmi with AppKit for wallet connection
+- **Solana**: Uses `@solana/wallet-adapter-react` with built-in adapters
+- **Bitcoin/Sui**: Placeholder support (external providers required)
+
+```tsx
+// No additional setup needed - SDK handles everything
+<RouterWidget config={{ theme: { mode: 'dark' } }} />
+```
+
+The SDK will:
+- Show its own wallet connection modal
+- Support all EVM wallets (MetaMask, WalletConnect, Coinbase, etc.)
+- Support Solana wallets (Phantom, Solflare, Coinbase Wallet, etc.)
+- Handle wallet connection/disconnection automatically
+
+### External Wallet Mode (Dynamic.xyz)
+
+If your app already uses Dynamic.xyz or another wallet provider, the SDK will automatically detect and use it:
 
 ```tsx
+import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
+import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';
+import { SolanaWalletConnectors } from '@dynamic-labs/solana';
+import { DynamicWagmiConnector } from '@dynamic-labs/wagmi-connector';
+import { WagmiProvider } from 'wagmi';
 import { RouterWidget } from 'router-widget-sdk';
-import 'router-widget-sdk/styles.css';
 
 function App() {
   return (
+    <DynamicContextProvider
+      settings={{
+        environmentId: 'your-dynamic-env-id',
+        walletConnectors: [
+          EthereumWalletConnectors,
+          SolanaWalletConnectors,
+        ],
+      }}
+    >
+      <WagmiProvider config={wagmiConfig}>
+        <DynamicWagmiConnector>
     <RouterWidget
       config={{
-        theme: {
-          mode: 'dark', // 'light' | 'dark' | 'auto'
-          primaryColor: '#e4357a',
-          backgroundColor: '#0a0a0a',
-        },
-        integrator: 'MyDApp',
-      }}
-    />
+              theme: { mode: 'dark' },
+              wallet: {
+                onConnectClick: () => {
+                  // Open Dynamic's auth flow
+                  setShowAuthFlow(true);
+                },
+              },
+            }}
+          />
+        </DynamicWagmiConnector>
+      </WagmiProvider>
+    </DynamicContextProvider>
   );
 }
 ```
 
-### With Initial State
+**How it works:**
+- SDK detects external Wagmi context → hides internal wallet modal
+- SDK detects external Solana context → uses external Solana adapter
+- `onConnectClick` callback opens your wallet connection UI
+- SDK uses your wallet for all transactions
 
+See [examples/nextjs-dynamic-provider](./examples/nextjs-dynamic-provider) for a complete example.
+
+### Solana Support
+
+The SDK includes full Solana wallet support:
+
+#### Internal Solana Mode
+
+```tsx
+// SDK automatically provides Solana wallet infrastructure
+<RouterWidget config={{ theme: { mode: 'dark' } }} />
+```
+
+Supported wallets:
+- Phantom
+- Solflare
+- Coinbase Wallet
+- Any Wallet Standard-compatible wallet
+
+#### External Solana Mode (with Dynamic)
+
+```tsx
+import { SolanaProvider } from './components/SolanaProvider';
+import { DynamicSolanaProvider } from './components/DynamicSolanaProvider';
+
+// In your providers setup
+<ConnectionProvider endpoint={endpoint}>
+  <WalletProvider wallets={[]} autoConnect>
+    <DynamicSolanaProvider>
+      <RouterWidget config={{ theme: { mode: 'dark' } }} />
+    </DynamicSolanaProvider>
+  </WalletProvider>
+</ConnectionProvider>
+```
+
+The SDK will:
+- Detect external Solana context
+- Use Dynamic's Solana wallet for transactions
+- Automatically switch between EVM and Solana as needed
+
+## Configuration
+
+### Component Props
+
+#### `RouterWidget`
+
+The main widget component accepts a single prop:
+
+```typescript
+interface RouterWidgetProps {
+  /**
+   * Widget configuration object
+   * All properties are optional
+   */
+  config?: WidgetConfig;
+}
+```
+
+**Example:**
+```tsx
+<RouterWidget config={widgetConfig} />
+```
+
+### WidgetConfig Interface
+
+Complete configuration interface with all available options:
+
+```typescript
+interface WidgetConfig {
+  // Theme configuration
+  theme?: WidgetTheme;
+  
+  // Initial swap state
+  initialState?: InitialState;
+  
+  // Integrator identifier
+  integrator?: string;
+  
+  // Feature flags
+  features?: FeatureFlags;
+  
+  // Selected routing nodes
+  selectedNodes?: string[];
+  
+  // Wallet integration
+  wallet?: WalletConfig;
+  
+  // Widget mode flag
+  isWidget?: boolean;
+  
+  // Chain type restrictions
+  chains?: ChainConfig;
+  
+  // Custom wallet providers (advanced)
+  providers?: any[];
+}
+```
+
+### WidgetTheme
+
+Theme configuration options:
+
+```typescript
+interface WidgetTheme {
+  /**
+   * Theme mode
+   * - 'light': Light theme
+   * - 'dark': Dark theme (default)
+   * - 'auto': Follows system preference
+   * 
+   * @default 'dark'
+   */
+  mode?: 'light' | 'dark' | 'auto';
+
+  /**
+   * Primary accent color (hex format)
+   * Used for buttons, links, and highlights
+   * 
+   * @example '#e4357a'
+   */
+  primaryColor?: string;
+
+  /**
+   * Background color (hex format)
+   * Main background color for the widget
+   * 
+   * @example '#0a0a0a'
+   */
+  backgroundColor?: string;
+
+  /**
+   * Primary text color (hex format)
+   * Main text color for content
+   * 
+   * @example '#ffffff'
+   */
+  textColorPrimary?: string;
+
+  /**
+   * Secondary text color (hex format)
+   * Used for labels, hints, and less important text
+   * 
+   * @example '#a0a0a0'
+   */
+  textColorSecondary?: string;
+
+  /**
+   * Muted background color (hex format)
+   * Used for cards, inputs, and secondary backgrounds
+   * 
+   * @example '#1a1a1a'
+   */
+  mutedColor?: string;
+
+  /**
+   * Card border radius (CSS value)
+   * Only applied when isWidget: true
+   * 
+   * @example '10px' | '0.5rem' | '0'
+   */
+  cardBorderRadius?: string;
+
+  /**
+   * Button border radius (CSS value)
+   * Applied to all buttons in the widget
+   * 
+   * @example '4px' | '0.25rem' | '0'
+   */
+  buttonBorderRadius?: string;
+
+  /**
+   * Font family (CSS font-family value)
+   * Applied to all text in the widget
+   * 
+   * @example 'Inter, sans-serif' | 'system-ui'
+   */
+  fontFamily?: string;
+}
+```
+
+**Example:**
+```tsx
+<RouterWidget
+  config={{
+    theme: {
+      mode: 'dark',
+      primaryColor: '#e4357a',
+      backgroundColor: '#0a0a0a',
+      textColorPrimary: '#ffffff',
+      textColorSecondary: '#a0a0a0',
+      mutedColor: '#1a1a1a',
+      cardBorderRadius: '10px', // Only applied when isWidget: true
+      buttonBorderRadius: '4px',
+      fontFamily: 'Inter, sans-serif',
+    },
+  }}
+/>
+```
+
+### InitialState
+
+Pre-configure the swap interface with initial values:
+
+```typescript
+interface InitialState {
+  /**
+   * Source chain ID
+   * Chain ID of the source chain (e.g., '1' for Ethereum, '137' for Polygon)
+   * 
+   * @example '1' | '137' | '8453'
+   */
+  fromChainId?: string;
+
+  /**
+   * Source token address
+   * Contract address of the source token
+   * Use 'native' or '0x0000000000000000000000000000000000000000' for native token
+   * 
+   * @example '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' (USDC)
+   */
+  fromTokenAddress?: string;
+
+  /**
+   * Destination chain ID
+   * Chain ID of the destination chain
+   * 
+   * @example '137' | '42161'
+   */
+  toChainId?: string;
+
+  /**
+   * Destination token address
+   * Contract address of the destination token
+   * 
+   * @example '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174' (USDC on Polygon)
+   */
+  toTokenAddress?: string;
+}
+```
+
+**Example:**
 ```tsx
 <RouterWidget
   config={{
     initialState: {
       fromChainId: '1', // Ethereum
-      fromTokenAddress: '0x...', // USDC
+      fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
       toChainId: '137', // Polygon
-      toTokenAddress: '0x...', // USDC on Polygon
+      toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC on Polygon
+    },
+  }}
+/>
+```
+
+### FeatureFlags
+
+Control widget features and UI elements:
+
+```typescript
+interface FeatureFlags {
+  /**
+   * Show header in the swap interface
+   * 
+   * @default true
+   */
+  showHeader?: boolean;
+
+  /**
+   * Disable source chain/token selection
+   * When true, users cannot change the source chain or token
+   * 
+   * @default false
+   */
+  isSrcDisabled?: boolean;
+
+  /**
+   * Disable destination chain/token selection
+   * When true, users cannot change the destination chain or token
+   * 
+   * @default false
+   */
+  isDestDisabled?: boolean;
+}
+```
+
+**Example:**
+```tsx
+<RouterWidget
+  config={{
+    features: {
+      showHeader: true,
+      isSrcDisabled: false,
+      isDestDisabled: false,
     },
-    theme: { mode: 'dark' },
   }}
 />
 ```
 
-### Skip Providers (If Already Wrapped)
+### WalletConfig
+
+Wallet integration callbacks for external wallet providers:
 
-If your app already has the necessary providers (ThemeProvider, wallet providers, etc.), you can skip them:
+```typescript
+interface WalletConfig {
+  /**
+   * Called when user clicks "CONNECT WALLET" button
+   * Only triggered when external wallet provider is detected (e.g., Dynamic.xyz)
+   * 
+   * Use this to open your app's wallet connection UI
+   * 
+   * @example
+   * wallet: {
+   *   onConnectClick: () => {
+   *     setShowAuthFlow(true); // Open Dynamic auth flow
+   *   },
+   * }
+   */
+  onConnectClick?: () => void;
+}
+```
 
+**Example:**
 ```tsx
 <RouterWidget
-  config={{ theme: { mode: 'dark' } }}
-  skipProviders={true}
+  config={{
+    wallet: {
+      onConnectClick: () => {
+        // Open your wallet connection modal
+        setShowAuthFlow(true);
+      },
+    },
+  }}
 />
 ```
 
-## Configuration Options
+### ChainConfig
+
+Restrict which chain types are available:
+
+```typescript
+interface ChainConfig {
+  /**
+   * Allowed chain types
+   * If provided, only these chain types will be enabled
+   * 
+   * Available types:
+   * - 'evm': Ethereum Virtual Machine chains (Ethereum, Polygon, Arbitrum, etc.)
+   * - 'sol': Solana
+   * - 'btc': Bitcoin
+   * - 'sui': Sui
+   * 
+   * @example ['evm', 'sol'] // Only EVM and Solana chains
+   */
+  types?: ('evm' | 'sol' | 'btc' | 'sui')[];
+}
+```
+
+**Example:**
+```tsx
+<RouterWidget
+  config={{
+    chains: {
+      types: ['evm', 'sol'], // Only EVM and Solana chains
+    },
+  }}
+/>
+```
 
-### WidgetConfig
+### Other Config Options
 
 ```typescript
 interface WidgetConfig {
-  theme?: {
-    mode?: 'light' | 'dark' | 'auto';
-    primaryColor?: string;
-    backgroundColor?: string;
-    textColorPrimary?: string;
-    textColorSecondary?: string;
-    mutedColor?: string;
-    cardBorderRadius?: string;
-    buttonBorderRadius?: string;
-    fontFamily?: string;
-  };
-  initialState?: {
-    fromChainId?: string;
-    fromTokenAddress?: string;
-    toChainId?: string;
-    toTokenAddress?: string;
-  };
+  /**
+   * Integrator identifier
+   * Used for analytics and tracking
+   * 
+   * @example 'MyDApp' | 'MyCompany'
+   */
   integrator?: string;
-  features?: {
-    showHeader?: boolean;
-    isSrcDisabled?: boolean;
-    isDestDisabled?: boolean;
-  };
+
+  /**
+   * Selected routing nodes/bridges
+   * Array of node IDs to use for routing
+   * If not provided, default nodes are used
+   * 
+   * @example ['router', 'stargate', 'hop']
+   */
   selectedNodes?: string[];
+
+  /**
+   * Widget mode flag
+   * When true:
+   * - Applies widget-specific styling (rounded corners, etc.)
+   * - Shows wallet header in widget mode
+   * - Optimizes for embedded use case
+   * 
+   * When false:
+   * - Uses flat design (no rounded corners)
+   * - Hides widget-specific UI elements
+   * - Optimizes for full-page use case
+   * 
+   * @default false
+   */
   isWidget?: boolean;
+
+  /**
+   * Custom wallet providers (advanced)
+   * Override default providers for transaction execution
+   * 
+   * Used for custom wallet integrations beyond Dynamic.xyz
+   * 
+   * @example
+   * providers: [
+   *   createEVMProvider({ getWalletClient: async () => customWalletClient }),
+   *   createSolanaProvider({ getWalletAdapter: async () => customAdapter }),
+   * ]
+   */
+  providers?: any[];
 }
 ```
 
-## Environment Variables
+### Complete Configuration Example
 
-The widget requires certain environment variables to be set. These should be configured in your application:
+```tsx
+<RouterWidget
+  config={{
+    // Theme
+    theme: {
+      mode: 'dark',
+      primaryColor: '#e4357a',
+      backgroundColor: '#0a0a0a',
+      textColorPrimary: '#ffffff',
+      textColorSecondary: '#a0a0a0',
+      mutedColor: '#1a1a1a',
+      cardBorderRadius: '10px',
+      buttonBorderRadius: '4px',
+      fontFamily: 'Inter, sans-serif',
+    },
 
-```bash
-NEXT_PUBLIC_SUPPORTED_NETWORK=1,10,8453,137,sui,solana
-NEXT_PUBLIC_API_URL=your-grpc-api-url
-NEXT_PUBLIC_API_DISCOVERY_URL=https://api.discover.routerprotocol.com
-NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-walletconnect-project-id
-NEXT_PUBLIC_PROJECT_ID=your-project-id
+    // Initial state
+    initialState: {
+      fromChainId: '1',
+      fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+      toChainId: '137',
+      toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
+    },
+
+    // Features
+    features: {
+      showHeader: true,
+      isSrcDisabled: false,
+      isDestDisabled: false,
+    },
+
+    // Wallet integration
+    wallet: {
+      onConnectClick: () => {
+        setShowAuthFlow(true);
+      },
+    },
+
+    // Chain restrictions
+    chains: {
+      types: ['evm', 'sol'],
+    },
+
+    // Other options
+    integrator: 'MyDApp',
+    selectedNodes: ['router', 'stargate'],
+    isWidget: true,
+  }}
+/>
 ```
 
-## Features
+## Advanced Usage
+
+### Custom Wallet Providers
+
+For advanced use cases, you can provide custom wallet providers:
+
+```tsx
+import { createEVMProvider, createSolanaProvider } from 'router-widget-sdk';
+
+<RouterWidget
+  config={{
+    providers: [
+      createEVMProvider({
+        getWalletClient: async () => {
+          // Your custom EVM wallet client
+          return walletClient;
+        },
+      }),
+      createSolanaProvider({
+        getWalletAdapter: async () => {
+          // Your custom Solana adapter
+          return { signer, connection };
+        },
+      }),
+    ],
+  }}
+/>
+```
+
+### Wallet Hooks
+
+The SDK exports hooks for wallet management:
+
+```tsx
+import { useWallet } from 'router-widget-sdk';
+
+function MyComponent() {
+  const {
+    primaryWallet,
+    userWallets,
+    isConnected,
+    walletAddress,
+    connectWallet,
+    handleLogOut,
+    signMessage,
+  } = useWallet();
+
+  // Use wallet state and methods
+}
+```
+
+**Available hooks:**
+- `useWallet()` - Main wallet hook (EVM + Solana)
+- `useWalletModal()` - Wallet connection modal state
+- `useAccountConnect()` - Unified connect function
+- `useAccountDisconnect()` - Unified disconnect function
+
+### Multi-Chain Wallet Support
+
+The SDK supports connecting multiple wallets simultaneously:
+
+```tsx
+const { userWallets, primaryWallet, switchWallet } = useWallet();
+
+// userWallets contains all connected wallets (EVM + Solana)
+// primaryWallet is the active wallet
+// switchWallet() switches between wallets
+```
+
+## API Reference
+
+### Components
 
-- ✅ Multi-chain Support (EVM and non-EVM chains)
-- ✅ Wallet Integration (Dynamic wallet connection)
-- ✅ Real-time Quotes (Automatic quote fetching and refresh)
-- ✅ Customizable Themes (Light, dark, or custom colors)
-- ✅ Configurable (Extensive configuration options)
-- ✅ Responsive (Works on desktop and mobile)
+#### `RouterWidget`
+
+Main widget component. Renders the complete swap interface with all necessary providers.
+
+**Props:**
+```typescript
+interface RouterWidgetProps {
+  /**
+   * Widget configuration object
+   * All properties are optional
+   * 
+   * @see WidgetConfig for complete configuration options
+   */
+  config?: WidgetConfig;
+}
+```
+
+**Example:**
+```tsx
+<RouterWidget config={widgetConfig} />
+```
+
+**Returns:**
+- Renders the swap interface wrapped with all necessary providers
+- Automatically detects external wallet contexts (Wagmi, Solana)
+- Handles wallet connection/disconnection
+- Manages swap state and transactions
+
+### Hooks
+
+#### `useWallet()`
+
+Returns wallet state and connection methods.
+
+**Returns:**
+```typescript
+{
+  primaryWallet: Wallet | null;
+  userWallets: Wallet[];
+  isConnected: boolean;
+  walletAddress: string;
+  activeConnectorId?: string;
+  connectWallet: () => void;
+  handleLogOut: () => Promise<void>;
+  switchWallet: (walletId: string) => Promise<boolean>;
+  signMessage: (message: string) => Promise<`0x${string}` | undefined>;
+  // ... more methods
+}
+```
+
+#### `useWalletModal()`
+
+Manages wallet connection modal state.
+
+**Returns:**
+```typescript
+{
+  isOpen: boolean;
+  setIsOpen: (open: boolean) => void;
+  openModal: () => void;
+  closeModal: () => void;
+}
+```
+
+### Types
+
+#### `Wallet`
+
+```typescript
+interface Wallet {
+  address: string;
+  chainType: ChainType; // 'evm' | 'sol' | 'btc' | 'sui'
+  id: string;
+  connector?: {
+    name?: string;
+    key?: string;
+  };
+}
+```
+
+#### `ChainType`
+
+```typescript
+enum ChainType {
+  Evm = 'evm',
+  Sol = 'sol',
+  Btc = 'btc',
+  Sui = 'sui',
+}
+```
+
+### Exported Types
+
+The SDK exports the following TypeScript types:
+
+```typescript
+// Main exports
+import { RouterWidget, type WidgetConfig } from 'router-widget-sdk';
+
+// Default export
+import RouterWidget from 'router-widget-sdk';
+```
+
+**Public API Exports:**
+
+```typescript
+// Component
+export { RouterWidget };
+export default RouterWidget;
+
+// Configuration type
+export type { WidgetConfig };
+```
+
+**Note:** The `WidgetConfig` type includes all nested types (`WidgetTheme`, `InitialState`, `FeatureFlags`, `WalletConfig`, `ChainConfig`) as documented in the [Configuration](#configuration) section above. These nested types are part of the `WidgetConfig` interface and don't need to be imported separately.
+
+## Examples
+
+### Basic Next.js Example
+
+```tsx
+// app/page.tsx
+'use client';
+
+import { RouterWidget } from 'router-widget-sdk';
+import 'router-widget-sdk/styles.css';
+
+export default function Home() {
+  return (
+    <main>
+      <RouterWidget
+        config={{
+          theme: { mode: 'dark' },
+          integrator: 'MyNextJSApp',
+        }}
+      />
+    </main>
+  );
+}
+```
+
+### With Dynamic.xyz
+
+See [examples/nextjs-dynamic-provider](./examples/nextjs-dynamic-provider) for a complete example with:
+- Dynamic.xyz wallet integration
+- EVM and Solana support
+- External wallet context detection
+
+### With Custom Styling
+
+```tsx
+import 'router-widget-sdk/styles.css';
+import './custom-styles.css';
+
+// custom-styles.css
+.router-widget {
+  --primary: #e4357a;
+  --background: #0a0a0a;
+  --foreground: #ffffff;
+}
+```
 
 ## TypeScript Support
 
-The package includes TypeScript definitions:
+The SDK is written in TypeScript and includes full type definitions:
 
 ```tsx
 import { RouterWidget, type WidgetConfig } from 'router-widget-sdk';
@@ -147,26 +866,77 @@ const config: WidgetConfig = {
   theme: { mode: 'dark' },
   integrator: 'MyDApp',
 };
+
+<RouterWidget config={config} />
 ```
 
 ## Styling
 
-Import the CSS file to get the default styles:
+### Default Styles
+
+Import the CSS file to get default styles:
 
 ```tsx
 import 'router-widget-sdk/styles.css';
 ```
 
-You can override styles using CSS variables:
+### Custom Styling
+
+Override styles using CSS variables:
 
 ```css
 .router-widget {
   --primary: #e4357a;
   --background: #0a0a0a;
   --foreground: #ffffff;
+  --muted: #1a1a1a;
 }
 ```
 
+### Widget Mode Styling
+
+When `isWidget: true`, the SDK applies widget-specific styling:
+- Rounded corners on cards (`cardBorderRadius`)
+- Widget-optimized spacing
+- Container constraints
+
+When `isWidget: false`, the SDK uses flat design (no rounded corners) to match your app's design system.
+
+## Environment Variables
+
+The widget requires certain environment variables:
+
+```bash
+# Required: Supported networks (comma-separated chain IDs)
+NEXT_PUBLIC_SUPPORTED_NETWORK=1,10,8453,137,42161
+
+# Required: API endpoints
+NEXT_PUBLIC_API_URL=your-grpc-api-url
+NEXT_PUBLIC_API_DISCOVERY_URL=https://api.discover.routerprotocol.com
+
+# Optional: WalletConnect
+NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-walletconnect-project-id
+NEXT_PUBLIC_PROJECT_ID=your-project-id
+
+# Optional: Dynamic.xyz (if using external wallet mode)
+NEXT_PUBLIC_DYNAMIC_ENV_ID=your-dynamic-environment-id
+```
+
+### Supported Chain IDs
+
+**EVM Chains:**
+- `1` - Ethereum
+- `10` - Optimism
+- `137` - Polygon
+- `42161` - Arbitrum
+- `8453` - Base
+- And more...
+
+**Non-EVM Chains:**
+- `solana` - Solana Mainnet
+- `sui` - Sui Mainnet
+- `btc` - Bitcoin
+
 ## Browser Support
 
 - Chrome (latest)
@@ -174,7 +944,102 @@ You can override styles using CSS variables:
 - Safari (latest)
 - Edge (latest)
 
+## Features
+
+- ✅ **Multi-Chain Support**: EVM, Solana, Bitcoin, Sui
+- ✅ **Flexible Wallet Integration**: Internal or external wallet providers
+- ✅ **Real-time Quotes**: Automatic quote fetching and refresh
+- ✅ **Customizable Themes**: Light, dark, or custom colors
+- ✅ **TypeScript**: Full type definitions included
+- ✅ **Responsive**: Works on desktop and mobile
+- ✅ **Production Ready**: Battle-tested and optimized
+
+## Architecture
+
+### Provider Hierarchy
+
+```
+RouterWidget
+├── AppProviders
+│   ├── QueryClientProvider
+│   ├── WidgetConfigProvider
+│   ├── WalletProviderContextProvider
+│   ├── PostHogProvider
+│   ├── ThemeProvider
+│   ├── WalletProvider
+│   │   ├── EVMProvider (conditional)
+│   │   ├── SVMProvider (conditional)
+│   │   ├── UTXOProvider (placeholder)
+│   │   ├── SuiProvider (placeholder)
+│   │   ├── SDKProviders
+│   │   └── WalletModalProvider
+│   └── StoreProvider
+└── SwapInterface
+```
+
+### Wallet Detection Flow
+
+1. **EVM Detection:**
+   - Checks for external Wagmi context
+   - If found → uses external, hides internal modal
+   - If not found → uses internal Wagmi/AppKit
+
+2. **Solana Detection:**
+   - Checks for external Solana context (`ConnectionProvider`)
+   - If found → uses external adapter
+   - If not found → uses internal `SVMBaseProvider`
+
+3. **Transaction Execution:**
+   - Retrieves wallet client/adapter from registered providers
+   - Supports chain-specific transaction handling
+   - Automatic chain switching for EVM
+
+## Troubleshooting
+
+### Wallet Not Connecting
+
+1. **Check External Context Detection:**
+   - Ensure your wallet provider is properly set up
+   - Verify `onConnectClick` callback is provided
+
+2. **Check Environment Variables:**
+   - Verify `NEXT_PUBLIC_SUPPORTED_NETWORK` includes your chains
+   - Ensure API URLs are correct
+
+3. **Check Console for Errors:**
+   - Look for wallet connection errors
+   - Check for missing dependencies
+
+### Solana Wallets Not Showing
+
+1. **Verify Solana Provider Setup:**
+   - Ensure `ConnectionProvider` and `WalletProvider` are present
+   - Check that `autoConnect` is enabled if needed
+
+2. **Check Wallet Standard:**
+   - Ensure wallets implement Wallet Standard
+   - Verify wallet extensions are installed
+
+### Styling Issues
+
+1. **Import Styles:**
+   - Ensure `router-widget-sdk/styles.css` is imported
+   - Check for CSS conflicts with your app
+
+2. **Widget Mode:**
+   - Set `isWidget: true` for widget-specific styling
+   - Use `isWidget: false` for flat design
+
+## Contributing
+
+Contributions are welcome! Please see our contributing guidelines.
+
 ## License
 
 MIT
 
+## Support
+
+For issues and questions:
+- GitHub Issues: [router-protocol/blinq-ui](https://github.com/router-protocol/blinq-ui)
+- Documentation: [Router Protocol Docs](https://docs.routerprotocol.com)