@sodax/wallet-sdk-react 1.5.6-beta → 2.0.0-rc.1

package/README.md

@@ -1,80 +1,73 @@
 # @sodax/wallet-sdk-react
 
-A comprehensive React Wallet SDK tailored for the Sodax ecosystem that provides unified wallet connectivity across multiple blockchain networks.
+React layer over [`@sodax/wallet-sdk-core`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-core/README.md) — wallet connection, signing, and account management for the SODAX cross-chain ecosystem. Hooks read from a single Zustand store; per-chain native SDKs (wagmi, `@solana/wallet-adapter`, `@mysten/dapp-kit`, …) are wrapped behind a uniform `IXService` / `IXConnector` interface.
 
 ## Features
-- Seamless wallet connectivity for all supported wallets in the Sodax network
-  - EVM Wallets: All browser extensions that support [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) (Hana Wallet, MetaMask, Phantom, etc.) ✅
-  - Sui Wallets: All browser extension that @mysten/dapp-kit supports (Hana, Sui Wallet, Suiet, etc.) ✅
-  - Solana Wallets: ✅
-  - Stellar Wallets: ✅
-  - Injective Wallets: ✅
-  - ICON Wallets: ✅ (Hana Wallet and other ICON-compatible extensions)
-
-- Address and connection state management
-  - EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM, LightLink, Ethereum, Redbelly, Kaia) ✅
-  - Sui ✅
-  - Solana ✅
-  - Stellar ✅
-  - Injective ✅
-  - ICON ✅
 
+- **Unified wallet connectivity** for 9 chain families across 20 chains
+  - EVM (Sonic hub, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia) — EIP-6963 + WalletConnect
+  - Solana, Sui, Stellar, ICON, Injective, Bitcoin, NEAR, Stacks
+- **Single-store state** — `useXAccount`, `useXConnection`, `useXAccounts` all read the same Zustand slice; persisted to `localStorage`
+- **Bridge to `@sodax/sdk`** — `useWalletProvider` returns a typed `IXxxWalletProvider` ready to plug into any SDK call
+- **Headless wallet modal** — `useWalletModal` state machine (chainSelect → walletSelect → connecting → success | error), render-agnostic
+- **Batch operations** — connect/disconnect every chain a wallet identifier covers, in sequence
+- **WalletConnect** — opt-in for enterprise custody (Fireblocks, etc.) via `config.EVM.walletConnect`
 
 ## Installation
 
 ```bash
-# Using npm
+pnpm add @sodax/wallet-sdk-react
+# or
 npm install @sodax/wallet-sdk-react
-
-# Using yarn
+# or
 yarn add @sodax/wallet-sdk-react
-
-# Using pnpm
-pnpm add @sodax/wallet-sdk-react
 ```
 
-## Peer Dependencies
-
-This package requires the following peer dependencies:
+## Peer dependencies
 
 ```json
 {
   "react": ">=19",
-  "@tanstack/react-query": "latest"
+  "@tanstack/react-query": "5.x"
 }
 ```
 
-## Quick Start
+## Quick start
 
-```typescript
-import { SodaxWalletProvider, useXConnectors, useXConnect, useXAccount } from '@sodax/wallet-sdk-react';
+```tsx
+import {
+  SodaxWalletProvider,
+  type SodaxWalletConfig,
+  useXAccount,
+  useXConnect,
+  useXConnectors,
+} from '@sodax/wallet-sdk-react';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import type { RpcConfig } from '@sodax/types';
+import { ChainKeys } from '@sodax/types';
 
-// Create a QueryClient instance
 const queryClient = new QueryClient();
 
-const rpcConfig: RpcConfig = {
-  // EVM chains
-  sonic: 'https://rpc.soniclabs.com',
-  '0xa86a.avax': 'https://api.avax.network/ext/bc/C/rpc',
-  '0xa4b1.arbitrum': 'https://arb1.arbitrum.io/rpc',
-  '0x2105.base': 'https://mainnet.base.org',
-  '0x38.bsc': 'https://bsc-dataseed1.binance.org',
-  '0xa.optimism': 'https://mainnet.optimism.io',
-  '0x89.polygon': 'https://polygon-rpc.com',
-  
-  // Other chains
-  '0x1.icon': 'https://ctz.solidwallet.io/api/v3',
-  solana: 'https://solana-mainnet.g.alchemy.com/v2/your-api-key',
-  sui: 'https://fullnode.mainnet.sui.io',
-  'injective-1': 'https://sentry.tm.injective.network:26657',
+const config: SodaxWalletConfig = {
+  EVM: {
+    ssr: true,
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
+    },
+    // Optional: add WalletConnect support (requires wc projectId)
+    // walletConnect: { projectId: '...' },
+  },
+  ICON: {
+    chains: {
+      [ChainKeys.ICON_MAINNET]: { rpcUrl: 'https://ctz.solidwallet.io/api/v3' },
+    },
+  },
 };
 
 function App() {
   return (
     <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider rpcConfig={rpcConfig}>
+      <SodaxWalletProvider config={config}>
         <WalletConnect />
       </SodaxWalletProvider>
     </QueryClientProvider>
@@ -82,132 +75,97 @@ function App() {
 }
 
 function WalletConnect() {
-  // Get available connectors for EVM chain
-  const connectors = useXConnectors('EVM');
-  
-  // Get connect mutation
+  const connectors = useXConnectors({ xChainType: 'EVM' });
   const { mutateAsync: connect } = useXConnect();
+  const account = useXAccount({ xChainType: 'EVM' });
 
-  // Get connected account info
-  const account = useXAccount('EVM');
+  if (account.address) {
+    return <p>Connected: {account.address}</p>;
+  }
 
   return (
-    <div className="space-y-4">
-      {/* Display connected wallet address if connected */}
-      {account?.address && (
-        <div className="p-4 bg-gray-100 rounded-lg">
-          <p className="text-sm text-gray-600">Connected Wallet:</p>
-          <p className="font-mono">{account.address}</p>
-        </div>
-      )}
-
-      {/* Display available connectors */}
-      <div className="space-y-2">
-        {connectors.map((connector) => (
-          <button
-            key={connector.id}
-            onClick={() => connect(connector)}
-            className="flex items-center gap-2 p-2 border rounded-lg hover:bg-gray-50"
-          >
-            <img 
-              src={connector.icon} 
-              alt={connector.name} 
-              width={24} 
-              height={24} 
-              className="rounded-md" 
-            />
-            <span>Connect {connector.name}</span>
-          </button>
-        ))}
-      </div>
+    <div>
+      {connectors.map(connector => (
+        <button key={connector.id} onClick={() => connect(connector)}>
+          {connector.icon && <img src={connector.icon} alt="" width={20} height={20} />}
+          {connector.name}
+        </button>
+      ))}
     </div>
   );
 }
 ```
 
-This example demonstrates:
-1. Setting up the required providers (`QueryClientProvider` and `SodaxWalletProvider`)
-2. Using `useXConnectors` to get available wallet connectors
-3. Using `useXConnect` to handle wallet connections
-4. Using `useXAccount` to display the connected wallet address
-5. A basic UI to display and connect to available wallets
+## Documentation
 
+The full guide lives in [`docs/`](docs/). Start with the topic that matches what you're building.
 
-## Requirements
+| Topic | What it covers |
+|-------|----------------|
+| [Configure SodaxWalletProvider](docs/CONFIGURE_PROVIDER.md) | `SodaxWalletConfig` shape, opt-in chain mounting, per-chain RPC + wallet defaults, breaking changes from v1 |
+| [Connect Flow](docs/CONNECT_FLOW.md) | Discover connectors, connect, read account, disconnect; provider-managed vs non-provider chains; persisted reconnect |
+| [Wallet Provider Bridge](docs/WALLET_PROVIDER_BRIDGE.md) | `useWalletProvider` → typed `IXxxWalletProvider` for `@sodax/sdk` calls; `useXService` / `useXServices` |
+| [Wallet Modal](docs/WALLET_MODAL.md) | Headless state machine for multi-chain modal UIs; `useConnectionFlow` non-modal alternative |
+| [WalletConnect](docs/WALLETCONNECT.md) | Enterprise custody integration (Fireblocks, Ledger); `qrModalOptions` filtering |
+| [Batch Operations](docs/BATCH_OPERATIONS.md) | Sequential multi-chain connect/disconnect by wallet identifier |
+| [Chain Detection](docs/CHAIN_DETECTION.md) | `useChainGroups`, `useConnectedChains`, `useIsWalletInstalled`, `useEnabledChains`; hydration status |
+| [Sign Message](docs/SIGN_MESSAGE.md) | `useXSignMessage` cross-chain; Bitcoin BIP-322 vs ECDSA auto-detect |
+| [EVM Switch Chain](docs/EVM_SWITCH_CHAIN.md) | Single wagmi connection across all configured EVM networks |
+| [Connectors](docs/CONNECTORS.md) | `IXConnector` contract, deep-import concrete classes, custom connectors |
+| [Architecture](docs/ARCHITECTURE.md) | Zustand store, Provider/Hydrator/Actions trio, persist hydration caveat |
+| [Adding a New Chain](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md) | `ChainMeta` extension, chain registry, sub-path export wiring |
 
-- Node.js >= 18.0.0
-- React >= 19
-- TypeScript
-
-
-## API Reference
+## AI agent docs
 
-### Components
+This package ships with AI-consumable integration & migration docs at `node_modules/@sodax/wallet-sdk-react/ai-exported/`. Point your AI coding agent at [`ai-exported/AGENTS.md`](ai-exported/AGENTS.md) to start — it routes to integration recipes (new consumers), migration recipes (v1 → v2), and reference tables.
 
-- [`SodaxWalletProvider`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/SodaxWalletProvider.tsx) - Main provider component for wallet connectivity
-
-### Hooks
-
-#### Core Wallet Hooks
-- [`useXConnectors`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/hooks/useXConnectors.ts) - Get available wallet connectors
-- [`useXConnect`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/hooks/useXConnect.ts) - Connect to a wallet
-- [`useXAccount`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/hooks/useXAccount.ts) - Get account information
-- [`useXDisconnect`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/hooks/useXDisconnect.ts) - Disconnect from a wallet
+```
+> Read node_modules/@sodax/wallet-sdk-react/ai-exported/AGENTS.md and integrate
+> SODAX wallet connectivity into my Next.js app.
+```
 
-#### Chain-Specific Hooks
-- [`useEvmSwitchChain`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/hooks/evm/useEvmSwitchChain.ts) - Switch between EVM chains
+The CI guard `scripts/check-ai-exported.sh` validates that every hook reference and sub-path in those docs resolves to a real export.
 
-#### Balance Hooks
-- [`useXBalances`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/hooks/useXBalances.ts) - Fetch token balances
+---
 
-#### Service Hooks
-- [`useXService`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/hooks/useXService.ts) - Access chain-specific service
+## Sub-path exports
 
-### Types
+Concrete connector / service classes are **not** exported from the package barrel — they live behind sub-path imports to prevent accidental coupling to internals:
 
-#### Core Types
-- [`XAccount`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/types/index.ts) - Wallet account type
-- [`XConnection`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/types/index.ts) - Wallet connection type
-- [`XConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/types/index.ts) - Wallet connector type
-- [`XToken`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/types/index.ts) - Cross-chain token type
+```typescript
+// ✅ Normal usage — barrel import
+import { useXConnect, useXAccount, type IXConnector } from '@sodax/wallet-sdk-react';
 
-### Classes
+// ✅ Advanced — concrete class via deep import
+import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
+if (connector instanceof XverseXConnector) {
+  connector.setAddressPurpose('payment');
+}
+```
 
-#### XConnector
-- [`XConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/core/XConnector.ts) - Base class for wallet connectors
-- [`EvmXConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/xchains/evm/EvmXConnector.ts) - EVM wallet connector
-- [`SolanaXConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/xchains/solana/SolanaXConnector.ts) - Solana wallet connector
-- [`SuiXConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/xchains/sui/SuiXConnector.ts) - Sui wallet connector
-- [`StellarXConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/xchains/stellar/StellarWalletsKitXConnector.ts) - Stellar wallet connector
-- [`InjectiveMetamaskXConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/xchains/injective/InjectiveMetamaskXConnector.ts) - Injective MetaMask connector
-- [`InjectiveKelprXConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/xchains/injective/InjectiveKelprXConnector.ts) - Injective Keplr connector
-- [`IconXConnector`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/xchains/icon/IconHanaXConnector.ts) - ICON wallet connector
+See [Connectors](docs/CONNECTORS.md) for the full list of deep-import sub-paths.
 
-## Contributing
+## Requirements
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+- Node.js >= 18.0.0
+- React >= 19
+- TypeScript
 
 ## Development
 
 ```bash
-# Install dependencies
-pnpm install
-
-# Build the package
-pnpm build      
-
-# Run in development mode
-pnpm dev
-
-# Run type checking
-pnpm checkTs
+pnpm install     # Install dependencies
+pnpm build       # Build the package (ESM + CJS, multi-entry)
+pnpm dev         # Watch mode
+pnpm checkTs     # Type checking
+pnpm test        # Run tests
+pnpm pretty      # Format code
+pnpm lint        # Lint code
+```
 
-# Format code
-pnpm pretty
+## Contributing
 
-# Lint code
-pnpm lint
-```
+Contributions welcome — see the repo [Contributing Guide](https://github.com/icon-project/sodax-sdks/blob/main/CONTRIBUTING.md). For onboarding a new chain family, follow [`docs/ADDING_A_NEW_CHAIN.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md).
 
 ## License
 
@@ -215,5 +173,5 @@ pnpm lint
 
 ## Support
 
-- [GitHub Issues](https://github.com/icon-project/sodax-frontend/issues)
+- [GitHub Issues](https://github.com/icon-project/sodax-sdks/issues)
 - [Discord Community](https://discord.gg/sodax-formerly-icon-880651922682560582)

package/ai-exported/AGENTS.md

@@ -0,0 +1,122 @@
+# AGENTS.md — `@sodax/wallet-sdk-react` AI Export
+
+You are a coding agent helping a developer **integrate** or **migrate** the `@sodax/wallet-sdk-react` package. This document is your entry point. Read this first, then route to the right sub-folder.
+
+The files in this `ai-exported/` directory are designed for AI consumption: short, table-heavy, self-contained recipes, and machine-checkable checklists. Human-readable narrative lives in each folder's `README.md`.
+
+---
+
+## Step 1 — Identify the task
+
+| User says... | Path | Start at |
+|---|---|---|
+| "upgrade to v2", "migrate from v1", "old hooks no longer work", "useXWagmiStore is gone" | **migration** | `migration/ai-rules.md` |
+| "add wallet connect", "set up SodaxWalletProvider", "first time using this lib" | **integration** | `integration/ai-rules.md` |
+| Looking up a v1 → v2 symbol mapping | direct | `migration/reference/*.md` |
+| Looking up a hook signature or available connector | direct | `integration/reference/*.md` |
+
+The package name **did not change** between v1 and v2 — both versions publish as `@sodax/wallet-sdk-react`. Migration is detected by import surface (`useXWagmiStore`, positional hook args, `rpcConfig` / `options` / `initialState` props on `SodaxWalletProvider`), not by package name.
+
+If both signals appear (project has v1 patterns AND wants new features), **migration first, then integration**.
+
+---
+
+## Step 2 — Load the right context
+
+**For migration tasks:**
+
+1. `migration/ai-rules.md` — DO/DON'T + workflow + stop conditions
+2. `migration/breaking-changes.md` — narrative WHY behind each change
+3. `migration/reference/*.md` — lookup tables (imports, hooks, config, components)
+4. `migration/recipes/<task>.md` — paired before/after for the specific use case
+5. `migration/checklist.md` — verification loop
+
+**For integration tasks:**
+
+1. `integration/ai-rules.md` — DO/DON'T + workflow
+2. `integration/recipes/setup.md` — always read this first (everything else depends on it)
+3. `integration/recipes/<task>.md` — task-specific guide
+4. `integration/reference/*.md` — API surface lookup
+
+---
+
+## Step 3 — Honor flow-specific stop conditions
+
+Each flow has its own list of conditions that **HARD STOP** code generation and require asking the user:
+
+- Migration stops → [`migration/ai-rules.md`](./migration/ai-rules.md) § "Stop conditions"
+- Integration stops → [`integration/ai-rules.md`](./integration/ai-rules.md) § "Stop conditions"
+
+Read the relevant list **before** applying any change. When stopping, quote the offending file/line and present the user with concrete options. Do **not** guess.
+
+Cross-flow signals (true regardless of flow):
+
+- User explicitly requests a behavior that v2 does not support (custom chain not in [`integration/reference/chain-support.md`](./integration/reference/chain-support.md), custom `XService` / `XConnector` subclass with non-trivial logic).
+- User mixes both v1 and v2 patterns in new code being written — do migration first, then integration.
+
+---
+
+## Step 4 — Verification protocol
+
+After **every** code change you make:
+
+1. Run `pnpm checkTs` from the user's app root (or the package the change touched).
+2. If errors mention `@sodax/wallet-sdk-react`, look up the symbol in `migration/reference/` or `integration/reference/`.
+3. If a symbol isn't in any reference file, **stop and ask**. Do not invent migrations.
+4. After all errors resolve, mark the relevant items in `migration/checklist.md` (for migrations) or move to the next recipe.
+
+You are **done** when:
+- `pnpm checkTs` exits clean for the user's project.
+- All items in `migration/checklist.md` are checked (migration only).
+- The user has confirmed the changed flow works in their dev environment.
+
+---
+
+## Conventions in this directory
+
+- **Recipes are self-contained.** A recipe file in `recipes/` contains everything needed to apply the change — before/after code, steps, verification. Do not jump between files.
+- **Reference files are tables.** `reference/*.md` contains markdown tables and paired code blocks marked `// v1 ❌` and `// v2 ✅`. Treat them as lookup, not narrative.
+- **Token budget**: Each file is sized to fit comfortably in your context. If you find yourself loading more than 3 files for a single task, you are probably doing it wrong — re-route via the table above.
+- **Single source of truth**: Behavioral / breaking-change *explanations* live only in `migration/breaking-changes.md`. Other files reference it but do not duplicate the prose.
+
+---
+
+## Quick symbol lookup
+
+If the user mentions a symbol you don't recognize, grep these files in order:
+
+```
+migration/reference/imports.md      — import path changes
+migration/reference/hooks.md        — hook renames + signature changes
+migration/reference/config.md       — SodaxWalletProvider config changes
+migration/reference/components.md   — component / provider renames
+integration/reference/hooks.md      — full v2 hook surface
+integration/reference/connectors.md — available wallet connectors per chain
+integration/reference/chain-support.md — supported chains + slots
+```
+
+If still not found: the symbol may be **internal** (not exported from v2) or **removed**. Ask the user to share the v1 file/line so you can decide.
+
+---
+
+## Package context
+
+- **Name**: `@sodax/wallet-sdk-react` (same package name in v1 and v2)
+- **Version target**: v2.x (current).
+- **Peer deps**: `react >= 19`, `@tanstack/react-query 5.x`
+- **Install**: `pnpm add @sodax/wallet-sdk-react @tanstack/react-query`
+- **Audience**: dApp builders integrating multi-chain wallet connectivity (9 chain types: EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks).
+
+For internal architecture (only relevant if you're modifying the package itself, not consuming it), see `../CLAUDE.md` in the parent directory.
+
+---
+
+## Pointers
+
+- [`integration/README.md`](./integration/README.md) — start here for new integrations: file index, recommended reading order, install snippet, provider-stack ordering.
+- [`migration/README.md`](./migration/README.md) — start here for v1 → v2 ports: file index, reading order, cross-cutting checklist pointer.
+- [`integration/recipes/setup.md`](./integration/recipes/setup.md) — install, mount `SodaxWalletProvider`, pick chain slots.
+- [`integration/architecture.md`](./integration/architecture.md) — mental model: provider mount tree, frozen config, EVM single-connection, `xChainType` vs `xChainId`.
+- [`integration/reference/`](./integration/reference/) — hooks, connectors, chain-support, wallet-brand identifiers lookup tables.
+- [`integration/reference/wallet-brands.md`](./integration/reference/wallet-brands.md) — known wallet brand identifiers (`'hana'`, `'phantom'`, `'xverse'`, …) for batch hooks, plus a runtime discovery snippet.
+- [`migration/breaking-changes.md`](./migration/breaking-changes.md) — full narrative of every v1 → v2 change.

package/ai-exported/integration/README.md

@@ -0,0 +1,102 @@
+# Integration: First-time setup (Human-readable overview)
+
+This folder helps you integrate `@sodax/wallet-sdk-react` into a fresh React app. It is the **human-facing** entry point for new integrations. If you are a coding agent, read [`ai-rules.md`](./ai-rules.md) first.
+
+If you are migrating from v1 instead, see `../migration/`.
+
+---
+
+## What this package does
+
+`@sodax/wallet-sdk-react` is the React layer over `@sodax/wallet-sdk-core`. It gives you:
+
+- **Multi-chain wallet connect** across 9 chain types (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks).
+- **Hooks** (`useXConnect`, `useXAccount`, `useXDisconnect`, `useXSignMessage`, etc.) backed by a Zustand store — composable and SSR-safe.
+- **Headless modal primitives** (`useWalletModal`, `useChainGroups`, `useBatchConnect`) — bring your own UI.
+- **Typed wallet providers** for hand-off to `@sodax/sdk` calls (`useWalletProvider`).
+
+---
+
+## Recommended path (in order)
+
+If this is your first time using the package:
+
+1. [`recipes/setup.md`](./recipes/setup.md) — install, wire `SodaxWalletProvider`, pick chain slots. **Always do this first**.
+2. Pick a connect UX (one, not both):
+   - [`recipes/connect-button.md`](./recipes/connect-button.md) — single chain, simplest UX.
+   - [`recipes/multi-chain-modal.md`](./recipes/multi-chain-modal.md) — chain picker + connector picker, headless.
+3. [`recipes/sign-message.md`](./recipes/sign-message.md) — sign messages cross-chain (auth flows).
+4. [`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md) — pass `walletProvider` to `@sodax/sdk` calls (swaps, lending, staking, etc.).
+5. [`recipes/switch-chain.md`](./recipes/switch-chain.md) — switch the active EVM network when source chain doesn't match.
+6. [`recipes/chain-detection.md`](./recipes/chain-detection.md) — list enabled chains, render connected list with hydration gate, install detection.
+7. Add advanced features as needed:
+   - [`recipes/walletconnect-setup.md`](./recipes/walletconnect-setup.md) — enable WalletConnect for enterprise-custody / mobile-only wallets.
+   - [`recipes/batch-operations.md`](./recipes/batch-operations.md) — batch connect / disconnect across multiple chains.
+   - [`recipes/sub-path-imports.md`](./recipes/sub-path-imports.md) — deep imports from `xchains/<chain>` for `instanceof` checks or custom connector lists.
+8. Reference docs (lookup as needed):
+   - [`reference/hooks.md`](./reference/hooks.md) — full hook surface with signatures.
+   - [`reference/connectors.md`](./reference/connectors.md) — available wallet connectors per chain.
+   - [`reference/chain-support.md`](./reference/chain-support.md) — supported chains, slots, and adapter notes.
+9. Copy-paste examples (runnable code, minimal narrative):
+   - [`examples/`](./examples/) — 4 self-contained `.tsx` files: minimal EVM setup, multi-chain modal, Next.js App Router, WalletConnect setup.
+
+---
+
+## Install
+
+```bash
+pnpm add @sodax/wallet-sdk-react @tanstack/react-query
+```
+
+Peer dependencies:
+
+```json
+{
+  "react": ">=19",
+  "@tanstack/react-query": "5.x"
+}
+```
+
+---
+
+## Pair with `@sodax/sdk` and `@sodax/dapp-kit`
+
+Most apps integrate this package together with the SDK and dapp-kit:
+
+```
+@sodax/sdk            ← business logic (swaps, lending, staking, etc.)
+@sodax/dapp-kit       ← high-level React hooks combining SDK + wallet-sdk
+@sodax/wallet-sdk-react  ← wallet connectivity (this package)
+```
+
+If you are using all three, mount providers in this order at the app root:
+
+```tsx
+<SodaxProvider config={sodaxConfig}>            {/* @sodax/dapp-kit */}
+  <QueryClientProvider client={queryClient}>
+    <SodaxWalletProvider config={walletConfig}>  {/* this package */}
+      {children}
+    </SodaxWalletProvider>
+  </QueryClientProvider>
+</SodaxProvider>
+```
+
+`SodaxProvider` (from dapp-kit) wraps the lot. `QueryClientProvider` must wrap `SodaxWalletProvider` because hooks inside use React Query.
+
+---
+
+## Conventions worth knowing
+
+- **Hooks use a single options object.** `useXConnectors({ xChainType: 'EVM' })`, not positional args.
+- **`xChainId` (chain key) and `xChainType` (family) are both accepted** by `useXAccount` and `useWalletProvider`. Pass one, not both.
+- **`useXConnect` is a React Query mutation.** Pass an `IXConnector` to `mutateAsync`.
+- **Persisted connections.** Connections survive reload via `localStorage` key `xwagmi-store`. Gate UI on `useConnectedChains().status === 'ready'` to avoid hydration flicker.
+- **EVM is one connection across all networks.** wagmi treats every configured EVM chain as part of one connector — there is no per-network connect/disconnect.
+
+---
+
+## Getting help
+
+- API surface lookup: [`reference/`](./reference/).
+- Bug or missing feature: [open an issue](https://github.com/icon-project/sodax-sdks/issues).
+- Internal architecture (only relevant for SODAX maintainers): `../CLAUDE.md` in the package root.