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

package/docs/WALLET_PROVIDER_BRIDGE.md

@@ -0,0 +1,226 @@
+# Wallet Provider Bridge
+
+`@sodax/wallet-sdk-react` is the bridge between the connected browser wallet and the chain-agnostic SDK call surface in `@sodax/sdk`. After a user connects a wallet, `useWalletProvider` returns a typed `IXxxWalletProvider` (from `@sodax/sdk`) that you pass directly into any SDK method — the SDK signs and broadcasts via that provider.
+
+The canonical interfaces are defined in [`@sodax/sdk`](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/src/index.ts) (`IEvmWalletProvider`, `ISolanaWalletProvider`, …) and re-exported through `@sodax/wallet-sdk-core`.
+
+## Table of contents
+
+1. [Why a bridge layer](#why-a-bridge-layer)
+2. [`useWalletProvider` — typed provider for one chain](#usewalletprovider--typed-provider-for-one-chain)
+3. [End-to-end example](#end-to-end-example)
+4. [Service hooks (`useXService` / `useXServices`)](#service-hooks-usexservice--usexservices)
+5. [How wallet providers are populated](#how-wallet-providers-are-populated)
+6. [Disabled chains return `undefined`](#disabled-chains-return-undefined)
+7. [Bypassing the bridge — when to skip `useWalletProvider`](#bypassing-the-bridge--when-to-skip-usewalletprovider)
+
+---
+
+## Why a bridge layer
+
+`@sodax/sdk` is wallet-library-agnostic — it accepts any object implementing the per-chain `IXxxWalletProvider` interface (see [`packages/sdk/docs/WALLET_PROVIDERS.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/WALLET_PROVIDERS.md)). The implementation can come from:
+
+- **Browser dApp** — `@sodax/wallet-sdk-react` Hydrators wrap `wagmi` / `@solana/wallet-adapter` / `@mysten/dapp-kit` etc. into provider instances and store them in the Zustand store. `useWalletProvider` reads them out.
+- **Server / script / bot** — `@sodax/wallet-sdk-core` exposes the same provider classes (`EvmWalletProvider`, `SolanaWalletProvider`, …) constructed directly from a private key. No React, no wallet-sdk-react.
+
+`useWalletProvider` is the React-side bridge. It hides the per-chain construction details and gives you a typed handle that fits the SDK call slot exactly:
+
+```typescript
+// SDK call shape (signed mode)
+sodax.swaps.swap({
+  params: { srcChainKey: ChainKeys.BSC_MAINNET, /* ... */ },
+  walletProvider, // must satisfy IEvmWalletProvider for BSC
+});
+```
+
+`useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET })` returns exactly `IEvmWalletProvider | undefined` — TypeScript narrows the return type from the chain key.
+
+---
+
+## `useWalletProvider` — typed provider for one chain
+
+Two overloads, mutually exclusive: pass `xChainId` (a `SpokeChainKey`) **or** `xChainType` (a `ChainType`), never both.
+
+### By chain id — narrowest typing
+
+```typescript
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+// walletProvider: IEvmWalletProvider | undefined
+```
+
+The chain id (`BSC_MAINNET`, `SOLANA_MAINNET`, etc.) resolves to its family at compile time via `GetChainType<S>` and the return type is the matching `IXxxWalletProvider`.
+
+### By chain type — family-level typing
+
+```typescript
+const evmProvider = useWalletProvider({ xChainType: 'EVM' });
+// evmProvider: IEvmWalletProvider | undefined
+
+const solProvider = useWalletProvider({ xChainType: 'SOLANA' });
+// solProvider: ISolanaWalletProvider | undefined
+```
+
+Use this when the surrounding component is family-level (e.g. an EVM dashboard that doesn't care which specific EVM chain is active). For EVM specifically, one wagmi connection covers all configured EVM networks — the same provider is returned for every `xChainId` in the EVM family.
+
+### No-arg form
+
+```typescript
+const wp = useWalletProvider();
+// wp: undefined — no chain specified
+```
+
+Both fields are optional but at least one must be set for the hook to return anything.
+
+---
+
+## End-to-end example
+
+Connect once, then drive an SDK call with the resulting provider:
+
+```tsx
+import { useWalletProvider, useXAccount } from '@sodax/wallet-sdk-react';
+import { useSodaxContext } from '@sodax/dapp-kit'; // or hold a Sodax instance directly
+import { ChainKeys } from '@sodax/types';
+import type { CreateIntentParams } from '@sodax/sdk';
+
+function SwapButton({ params }: { params: CreateIntentParams<typeof ChainKeys.BSC_MAINNET> }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+  const account = useXAccount({ xChainId: ChainKeys.BSC_MAINNET });
+  const { sodax } = useSodaxContext();
+
+  const handleSwap = async () => {
+    if (!walletProvider) return;
+    const result = await sodax.swaps.swap({
+      params,
+      walletProvider, // typed as IEvmWalletProvider — matches BSC src chain
+    });
+    if (!result.ok) {
+      console.error('swap failed:', result.error);
+      return;
+    }
+    console.log('swap submitted:', result.value);
+  };
+
+  return (
+    <button onClick={handleSwap} disabled={!walletProvider || !account.address}>
+      Swap
+    </button>
+  );
+}
+```
+
+The same pattern works for every SDK feature service — `sodax.bridge.bridge`, `sodax.moneyMarket.supply`, `sodax.staking.stake`, `sodax.dex.deposit`, etc. See [`packages/sdk/docs/`](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/) for per-feature method signatures.
+
+---
+
+## Service hooks (`useXService` / `useXServices`)
+
+Lower-level than `useWalletProvider` — these expose the chain's `XService` instance, used for:
+
+- Reading per-chain balances (`xService.getBalance(address, xToken)`)
+- Listing connectors (`xService.getXConnectors()`)
+- Looking up a connector by id (`xService.getXConnectorById(id)`)
+- Custom integrations against the `IXService` contract
+
+```typescript
+import { useXService, useXServices } from '@sodax/wallet-sdk-react';
+
+const evmService = useXService({ xChainType: 'EVM' });
+// evmService: XService | undefined — chain-specific instance (EvmXService)
+
+const allServices = useXServices();
+// allServices: Partial<Record<ChainType, XService>>
+```
+
+For typed access, depend on the public [`IXService`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/types/interfaces.ts) interface rather than the concrete `XService` class. Concrete classes (`EvmXService`, `BitcoinXService`, …) are not exported from the package barrel; if you need a concrete class for `instanceof`, use the deep-import sub-path — see [`CONNECTORS.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md).
+
+---
+
+## How wallet providers are populated
+
+The store's `walletProviders` map is populated by two distinct mechanisms depending on chain type:
+
+### Provider-managed chains (EVM, Solana, Sui)
+
+The chain's **Hydrator** is the sole writer. It subscribes to the native SDK hooks (e.g. `useAccount` from wagmi) and writes a fresh `EvmWalletProvider` (from `@sodax/wallet-sdk-core`) into the store every time the underlying client changes:
+
+```
+wagmi connection observed  →  EvmHydrator constructs EvmWalletProvider({ walletClient, publicClient })
+                                                      │
+                                                      ↓
+                                       store.walletProviders.EVM = provider
+```
+
+`useWalletProvider({ xChainType: 'EVM' })` reads that slot — no chain-specific switch case in user code.
+
+### Non-provider chains (Bitcoin, ICON, Injective, Stellar, NEAR, Stacks)
+
+The provider is created as a side-effect of `setXConnection()` inside the store. When `useXConnect` resolves a successful connection, the store's setter constructs the chain-specific provider (`BitcoinWalletProvider`, `IconWalletProvider`, …) and writes it to `walletProviders`.
+
+In both cases, the bridge layer owns the construction — consumers never call `new EvmWalletProvider(...)` themselves in dApp code.
+
+---
+
+## Disabled chains return `undefined`
+
+If `xChainType` resolves to a chain that isn't enabled in `SodaxWalletProvider` config, `useWalletProvider` returns `undefined` and logs a one-time warning per chain:
+
+```
+[useWalletProvider] chain "BITCOIN" is not enabled in SodaxWalletProvider config.chains — returning undefined
+```
+
+This is by design — `useWalletProvider` is meant to be called unconditionally inside components, and chains can be disabled without changing the call sites. Always null-check the return value:
+
+```typescript
+const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
+if (!walletProvider) return null; // chain disabled, or no wallet connected for that chain yet
+```
+
+The warning fires only once per chain per session — repeated disabled-chain reads don't spam the console.
+
+---
+
+## Bypassing the bridge — when to skip `useWalletProvider`
+
+Skip the bridge in two cases:
+
+**Server / Node.js scripts** — no React, no wallet-sdk-react. Use `@sodax/wallet-sdk-core` directly:
+
+```typescript
+import { Sodax } from '@sodax/sdk';
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const sodax = new Sodax();
+const walletProvider = new EvmWalletProvider({
+  privateKey: process.env.PRIVATE_KEY!,
+  chainId: ChainKeys.BSC_MAINNET,
+  rpcUrl: 'https://bsc-dataseed.binance.org',
+});
+const result = await sodax.swaps.swap({ params: /* ... */, walletProvider });
+```
+
+**Raw transactions** — when you only need unsigned transaction data (for gas estimation, manual relay, or external signing). SDK methods that accept `raw: true` don't need a wallet provider:
+
+```typescript
+const result = await sodax.swaps.createIntent({
+  params,
+  raw: true, // no walletProvider — returns unsigned tx
+});
+```
+
+See [`packages/sdk/docs/SWAPS.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/SWAPS.md) for the full raw-vs-signed matrix per method.
+
+---
+
+## Related docs
+
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — chain-type slots and per-chain wallet defaults
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — discover, connect, read, disconnect
+- [Connectors](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md) — `IXConnector`, deep imports, custom connectors
+- [SDK Wallet Providers Reference](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/WALLET_PROVIDERS.md) — `IXxxWalletProvider` interfaces, custom implementations
+- [SDK Swaps](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/SWAPS.md) — example consumer of a wallet provider
+- [`@sodax/wallet-sdk-core`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-core/README.md) — Node-side provider construction

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sodax/wallet-sdk-react",
   "license": "MIT",
-  "version": "1.5.6-beta",
+  "version": "2.0.0-rc.1",
   "description": "Wallet SDK of Sodax",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -9,18 +9,33 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "README.md",
+    "docs",
+    "skills",
+    "ai-exported"
   ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./xchains/*": {
+      "types": "./dist/xchains/*/index.d.ts",
+      "import": "./dist/xchains/*/index.mjs",
+      "require": "./dist/xchains/*/index.cjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "xchains/*": [
+        "./dist/xchains/*/index.d.ts"
+      ]
     }
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/icon-project/sodax-frontend"
+    "url": "https://github.com/icon-project/sodax-sdks"
   },
   "dependencies": {
     "@stacks/connect": "8.2.6",
@@ -43,7 +58,8 @@
     "@solana/wallet-adapter-react": "0.15.35",
     "@solana/wallet-adapter-wallets": "0.19.30",
     "@solana/web3.js": "1.98.0",
-    "@stellar/stellar-sdk": "12.3.0",
+    "@stellar/stellar-sdk": "15.1.0",
+    "@walletconnect/ethereum-provider": "^2.23.9",
     "icon-sdk-js": "1.5.3",
     "immer": "10.1.1",
     "sats-connect": "^4.2.1",
@@ -51,15 +67,19 @@
     "wagmi": "2.16.9",
     "zustand": "4.5.2",
     "bs58": "6.0.0",
-    "@sodax/types": "1.5.6-beta",
-    "@sodax/wallet-sdk-core": "1.5.6-beta"
+    "@sodax/types": "2.0.0-rc.1",
+    "@sodax/wallet-sdk-core": "2.0.0-rc.1"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.1.0",
     "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "happy-dom": "^20.8.9",
     "knip": "5.30.5",
+    "react-dom": "19.1.4",
     "tsup": "8.5.0",
     "typescript": "5.5.4",
-    "vitest": "^2.1.3"
+    "vitest": "2.1.9"
   },
   "peerDependencies": {
     "@tanstack/react-query": "5.x",
@@ -69,12 +89,17 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "NODE_OPTIONS=--max-old-space-size=8192 tsup",
     "dev": "tsup --watch ./src",
     "clean": "rm -rf dist && rm -rf node_modules && rm -rf .turbo",
     "pretty": "biome format . --write",
     "checkTs": "tsc --noEmit",
+    "checkTs:examples": "tsc --noEmit -p tsconfig.examples.json",
+    "test": "vitest run",
     "knip": "knip",
-    "lint": "biome lint . --write"
+    "lint": "biome lint . --write",
+    "check:ai-exported": "bash ./scripts/check-ai-exported.sh",
+    "check:ai-links": "bash ./scripts/check-ai-links.sh",
+    "check:ai-imports": "bash ./scripts/check-ai-imports.sh"
   }
 }

package/skills/SKILLS.md

@@ -0,0 +1,84 @@
+# @sodax/wallet-sdk-react Skills
+
+Scaffolding guides that let you wire SODAX wallet connectivity into a React app in one prompt. Built for and tested with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — point it at a skill file and it generates the correct providers, hooks, and types.
+
+## Quick Start
+
+Skills ship with the npm package. After installing `@sodax/wallet-sdk-react`:
+
+**1. Set up providers** (do this first)
+
+> Read `node_modules/@sodax/wallet-sdk-react/skills/setup.md` and wire `SodaxWalletProvider` into my app.
+
+**2. Pick a connect UX**
+
+> Read `node_modules/@sodax/wallet-sdk-react/skills/connect-button.md` and add a single-chain connect button.
+
+> Read `node_modules/@sodax/wallet-sdk-react/skills/multi-chain-modal.md` and add a multi-chain wallet modal.
+
+**3. Add advanced features as needed**
+
+> Read `node_modules/@sodax/wallet-sdk-react/skills/evm-only-walletconnect.md` and enable WalletConnect for enterprise custody (Fireblocks, etc.).
+
+> Read `node_modules/@sodax/wallet-sdk-react/skills/bridge-to-sdk.md` and pass the connected wallet provider to a `@sodax/sdk` swap call.
+
+The pattern is always: `Read node_modules/@sodax/wallet-sdk-react/skills/<skill>.md` + what you want to build.
+
+### Tips
+
+- One skill per prompt gets better results than asking for everything at once.
+- Always do setup before any other skill.
+- Pair `connect-button.md` (one chain at a time) OR `multi-chain-modal.md` (chain picker + connector picker) — they're alternatives, not additive.
+
+---
+
+*Internal devs working in this monorepo: use `skills/<skill>.md` instead of the `node_modules` path, and reference sibling docs in `docs/` for the underlying API.*
+
+## Dependency Graph
+
+```
+setup
+  ├── connect-button         (single-chain connect/disconnect)
+  ├── multi-chain-modal      (modal-driven multi-chain UX)
+  ├── evm-only-walletconnect (Fireblocks / custody opt-in)
+  └── bridge-to-sdk          (pass walletProvider to @sodax/sdk calls)
+```
+
+## Skill Index
+
+| Skill | File | Description | Depends On |
+|-------|------|-------------|------------|
+| Setup | [setup.md](setup.md) | Install + wire `SodaxWalletProvider` with chain-type slots | None |
+| Connect Button | [connect-button.md](connect-button.md) | `useXConnectors` + `useXConnect` + `useXDisconnect` for one chain | `setup` |
+| Multi-chain Modal | [multi-chain-modal.md](multi-chain-modal.md) | `useWalletModal` headless state machine + `useChainGroups` | `setup` |
+| EVM-only WalletConnect | [evm-only-walletconnect.md](evm-only-walletconnect.md) | Enable WalletConnect for Fireblocks / Ledger / mobile-only wallets | `setup` |
+| Bridge to SDK | [bridge-to-sdk.md](bridge-to-sdk.md) | `useWalletProvider` → typed `IXxxWalletProvider` for `@sodax/sdk` calls | `setup`, one of `connect-button` / `multi-chain-modal` |
+
+## Conventions
+
+### Single object parameter
+
+Every hook in `@sodax/wallet-sdk-react` accepts one options object:
+
+```typescript
+useXConnectors({ xChainType: 'EVM' });
+useXAccount({ xChainId: ChainKeys.BSC_MAINNET });
+useWalletProvider({ xChainType: 'EVM' });
+```
+
+`useXAccount` / `useWalletProvider` accept either `xChainId` (chain key) **or** `xChainType` (family) — never both.
+
+### Mutation pattern (`useXConnect`)
+
+`useXConnect` is a React Query mutation. Pass an `IXConnector` to `mutate` / `mutateAsync`:
+
+```typescript
+const { mutateAsync: connect } = useXConnect();
+await connect(connector);
+```
+
+For provider-managed chains (EVM/Solana/Sui), the resolved value is `undefined` — read the connected account via `useXAccount` after the mutation lands. See [Connect Flow caveat](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md#provider-managed-chains-caveat).
+
+### Persisted connections
+
+Connections survive page reloads via `localStorage` (key `xwagmi-store`). Gate UI on hydration to avoid flicker — `useConnectedChains().status === 'ready'` is the official signal.

package/skills/bridge-to-sdk.md

@@ -0,0 +1,148 @@
+# Skill: Bridge to SDK
+
+Pass the user's connected wallet to `@sodax/sdk` calls — `useWalletProvider` returns a typed `IXxxWalletProvider` ready to plug into any SDK method.
+
+**Depends on:** [setup.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/setup.md), one of [connect-button.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/connect-button.md) / [multi-chain-modal.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/multi-chain-modal.md)
+
+## Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useWalletProvider({ xChainId })` | Typed `IXxxWalletProvider` (chain-narrowed by chain id) |
+| `useWalletProvider({ xChainType })` | Family-level provider (same shape for every chain id in family) |
+| `useXAccount({ xChainId })` | Read connected address |
+| `useXService({ xChainType })` | Lower-level — chain `XService` instance for advanced reads |
+
+Pass either `xChainId` (a `SpokeChainKey`) or `xChainType` (a `ChainType`), never both.
+
+## Pattern — drive an SDK swap from a connected wallet
+
+```tsx
+import { useWalletProvider, useXAccount } from '@sodax/wallet-sdk-react';
+import { Sodax, ChainKeys } from '@sodax/sdk';
+import type { CreateIntentParams } from '@sodax/sdk';
+
+const sodax = new Sodax(); // or hold one in context / pass via @sodax/dapp-kit
+
+export function SwapButton({ params }: { params: CreateIntentParams<typeof ChainKeys.BSC_MAINNET> }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+  const account = useXAccount({ xChainId: ChainKeys.BSC_MAINNET });
+
+  const handleSwap = async () => {
+    if (!walletProvider) return;
+    const result = await sodax.swaps.swap({
+      params,
+      walletProvider, // typed as IEvmWalletProvider — must match BSC src chain
+    });
+    if (!result.ok) {
+      console.error('swap failed:', result.error);
+      return;
+    }
+    console.log('swap submitted:', result.value);
+  };
+
+  return (
+    <button onClick={handleSwap} disabled={!walletProvider || !account.address}>
+      Swap
+    </button>
+  );
+}
+```
+
+The pattern works for every SDK feature service:
+
+```typescript
+sodax.swaps.swap({ params, walletProvider });
+sodax.bridge.bridge({ params, walletProvider });
+sodax.moneyMarket.supply({ params, walletProvider });
+sodax.staking.stake({ params, walletProvider });
+sodax.dex.deposit({ params, walletProvider });
+```
+
+See [`packages/sdk/docs/`](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/) for per-feature method signatures.
+
+## TypeScript narrowing
+
+```typescript
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+// By chain id — narrowest typing
+const evm = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+// evm: IEvmWalletProvider | undefined
+
+const sol = useWalletProvider({ xChainId: ChainKeys.SOLANA_MAINNET });
+// sol: ISolanaWalletProvider | undefined
+
+// By chain type — family-level (one wagmi connection covers all EVM chains)
+const evmFamily = useWalletProvider({ xChainType: 'EVM' });
+// evmFamily: IEvmWalletProvider | undefined
+```
+
+The chain-narrowing is automatic — passing the wrong wallet provider type to an SDK call (e.g. `ISolanaWalletProvider` to a `srcChainKey: BSC_MAINNET` swap) is a **compile error**.
+
+## EVM — single connection across all networks
+
+`useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET })` and `useWalletProvider({ xChainId: ChainKeys.ARBITRUM_MAINNET })` return the **same** `EvmWalletProvider` instance — wagmi maintains one connection across all configured EVM networks. To switch the **active** EVM network, see [`useEvmSwitchChain`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/EVM_SWITCH_CHAIN.md):
+
+```tsx
+import { useEvmSwitchChain } from '@sodax/wallet-sdk-react';
+
+const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
+  xChainId: ChainKeys.BSC_MAINNET,
+});
+
+if (isWrongChain) {
+  return <button onClick={handleSwitchChain}>Switch to BSC</button>;
+}
+```
+
+## Disabled chains return `undefined`
+
+If `xChainType` resolves to a chain not enabled in `SodaxWalletProvider` config, `useWalletProvider` returns `undefined` and logs a one-time warning:
+
+```
+[useWalletProvider] chain "BITCOIN" is not enabled in SodaxWalletProvider config.chains — returning undefined
+```
+
+Always null-check before passing to an SDK call.
+
+## Raw transactions — skip the bridge
+
+If you only need unsigned transaction data (manual relay, gas estimation, external signing), pass `raw: true` to the SDK and skip `walletProvider`:
+
+```typescript
+const result = await sodax.swaps.createIntent({
+  params,
+  raw: true, // walletProvider must be absent — compile error if passed
+});
+// result.value.tx is an EvmRawTransaction
+```
+
+See [`packages/sdk/docs/SWAPS.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/SWAPS.md) for the full raw-vs-signed matrix per method.
+
+## Server / scripts — use `@sodax/wallet-sdk-core` directly
+
+For Node.js scripts / bots, skip wallet-sdk-react entirely:
+
+```typescript
+import { Sodax } from '@sodax/sdk';
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const sodax = new Sodax();
+const walletProvider = new EvmWalletProvider({
+  privateKey: process.env.PRIVATE_KEY!,
+  chainId: ChainKeys.BSC_MAINNET,
+  rpcUrl: 'https://bsc-dataseed.binance.org',
+});
+const result = await sodax.swaps.swap({ params, walletProvider });
+```
+
+## Reference docs
+
+- [Wallet Provider Bridge](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_PROVIDER_BRIDGE.md) — `useWalletProvider` + `useXService` reference
+- [SDK Wallet Providers Reference](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/WALLET_PROVIDERS.md) — per-chain `IXxxWalletProvider` interfaces
+- [SDK Swaps](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/SWAPS.md) — example consumer of a wallet provider
+- [EVM Switch Chain](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/EVM_SWITCH_CHAIN.md) — switch active EVM network
+- [`packages/dapp-kit`](https://github.com/icon-project/sodax-sdks/blob/main/packages/dapp-kit/README.md) — higher-level React hooks that wrap SDK calls + `useWalletProvider`

package/skills/connect-button.md

@@ -0,0 +1,116 @@
+# Skill: Connect Button
+
+Single-chain connect/disconnect button — pick a connector, connect, read the account, disconnect.
+
+**Depends on:** [setup.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/setup.md)
+
+## Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useXConnectors({ xChainType })` | List available connectors for the chain family |
+| `useXConnect()` | React Query mutation — `mutate(connector)` |
+| `useXAccount({ xChainType })` | Read connected account (always returns object — `address` is `undefined` when disconnected) |
+| `useXDisconnect()` | Returns `(args) => Promise<void>` |
+| `sortConnectors(list, { preferred })` | Optional — rank installed/preferred wallets first |
+
+## Connect button
+
+```tsx
+import {
+  useXConnectors,
+  useXConnect,
+  useXAccount,
+  useXDisconnect,
+  sortConnectors,
+  type IXConnector,
+} from '@sodax/wallet-sdk-react';
+
+const PREFERRED = ['hana', 'metamask'] as const;
+
+export function EvmConnectButton() {
+  const raw = useXConnectors({ xChainType: 'EVM' });
+  const connectors = sortConnectors(raw, { preferred: PREFERRED });
+  const { mutateAsync: connect, isPending, error } = useXConnect();
+  const account = useXAccount({ xChainType: 'EVM' });
+  const disconnect = useXDisconnect();
+
+  if (account.address) {
+    return (
+      <div>
+        <code>{account.address}</code>
+        <button onClick={() => disconnect({ xChainType: 'EVM' })}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {connectors.map((connector) => (
+        <button
+          key={connector.id}
+          onClick={() => connect(connector).catch(() => {})}
+          disabled={isPending}
+        >
+          {connector.icon && <img src={connector.icon} alt="" width={20} height={20} />}
+          {connector.name}
+          {!connector.isInstalled && ' (not installed)'}
+        </button>
+      ))}
+      {error && <p style={{ color: 'red' }}>{error.message}</p>}
+    </div>
+  );
+}
+```
+
+## Install CTA for missing wallets
+
+```tsx
+{connectors.map((connector) =>
+  connector.isInstalled ? (
+    <button key={connector.id} onClick={() => connect(connector)}>
+      {connector.name}
+    </button>
+  ) : (
+    <a key={connector.id} href={connector.installUrl} target="_blank" rel="noreferrer">
+      Install {connector.name}
+    </a>
+  ),
+)}
+```
+
+`isInstalled` reads `window.*` at render time (no extra subscription). For batch install detection across wallet brands, use [`useIsWalletInstalled`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CHAIN_DETECTION.md#useiswalletinstalled--install-detection).
+
+## Caveat — provider-managed chains resolve with `undefined`
+
+For EVM, Solana, and Sui, `connect(connector)` resolves with `undefined` because connection state is set by the chain's Hydrator after the native SDK reports `connected`. Always read the account via `useXAccount`, not the mutation's return value:
+
+```typescript
+const { mutateAsync: connect } = useXConnect();
+const account = useXAccount({ xChainType: 'EVM' });
+
+await connect(connector); // resolves with undefined for EVM
+// account.address is populated on the next render
+```
+
+Non-provider chains (Bitcoin, ICON, Injective, Stellar, NEAR, Stacks) return the resolved `XAccount` from `connect()` — but reading via `useXAccount` works for both, so default to it.
+
+## Multiple chains, one button
+
+For a "connect EVM + Solana + Bitcoin in one click" pattern, use [`useBatchConnect`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/BATCH_OPERATIONS.md):
+
+```tsx
+import { useBatchConnect } from '@sodax/wallet-sdk-react';
+
+const { run, status } = useBatchConnect({ connectors: ['hana'] });
+// Connects every chain Hana supports — sequential, errors collected.
+<button onClick={run} disabled={status === 'running'}>
+  Connect Hana on all chains
+</button>;
+```
+
+## Reference docs
+
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — full lifecycle reference + error handling
+- [Connectors](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md) — `IXConnector` shape, deep imports for concrete classes
+- [Batch Operations](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/BATCH_OPERATIONS.md) — multi-chain connect by wallet identifier