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

package/ai-exported/integration/reference/api-surface.md

@@ -0,0 +1,175 @@
+# Reference: API Surface
+
+The complete public export surface of `@sodax/wallet-sdk-react` v2. This is the **single source of truth** for "what can I import". If a symbol is not listed here, it is not part of the public API.
+
+The check script `scripts/check-ai-exported.sh` validates that every symbol referenced in `ai-exported/**/*.md` appears either in this file or in `reference/connectors.md` / `reference/hooks.md`.
+
+---
+
+## Barrel exports — `import { X } from '@sodax/wallet-sdk-react'`
+
+### Components
+
+| Symbol | Kind | Source |
+|---|---|---|
+| `SodaxWalletProvider` | React component | `SodaxWalletProvider.tsx` |
+| `SodaxWalletProviderProps` | type | `SodaxWalletProvider.tsx` |
+| `WalletConfigProvider` | React component (advanced — internal context) | `context/WalletConfigContext` |
+
+### Hooks
+
+See [`hooks.md`](./hooks.md) for full signatures. Names only:
+
+- `useXAccount`, `useXAccounts`
+- `useXConnect`, `useXDisconnect`
+- `useXConnection`, `useXConnections`
+- `useXConnectors`, `useXConnectorsByChain`
+- `useIsWalletInstalled`
+- `useChainGroups`, `useConnectedChains`
+- `useConnectionFlow`
+- `useBatchConnect`, `useBatchDisconnect`
+- `useWalletModal`
+- `useWalletProvider`
+- `useXService`, `useXServices`
+- `useEnabledChains`
+- `useEvmSwitchChain`
+- `useXSignMessage`
+
+### Abstract classes (advanced — extend only when implementing a new chain)
+
+| Symbol | Kind | Source |
+|---|---|---|
+| `XService` | abstract class | `core/XService` |
+| `XConnector` | abstract class | `core/XConnector` |
+
+### Imperative actions
+
+| Symbol | Kind | Source |
+|---|---|---|
+| `getXChainType` | function | `actions/getXChainType` |
+| `getXService` | function | `actions/getXService` |
+
+### Utilities
+
+| Symbol | Notes |
+|---|---|
+| `sortConnectors` | Stable-sort connectors by `preferred[]` then install state. See [`connectors.md`](./connectors.md). |
+| `getEntryDefaults`, `getRpcUrl`, `resolveEvmDefaults` | Read defaults / RPC URL out of `SodaxWalletConfig` (advanced — for custom Hydrator-like code). |
+| `isNativeToken`, `getWagmiChainId` | Small helpers — native-token check and `ChainKey` → wagmi numeric chain id. |
+
+### Public interfaces
+
+| Symbol | Kind | Source |
+|---|---|---|
+| `IXService` | interface | `types/interfaces` |
+| `IXConnector` | interface | `types/interfaces` |
+| `IWalletProvider` | re-export from `@sodax/types` | `types/index` |
+
+### Account / connection types
+
+| Symbol | Kind |
+|---|---|
+| `XAccount` | type |
+| `XConnection` | type |
+
+### Config types
+
+Top-level:
+
+| Symbol | Kind |
+|---|---|
+| `SodaxWalletConfig` | type |
+| `ChainTypeConfig<T>` | generic type |
+| `ChainEntry<K>` | generic type |
+| `ChainMeta` | type |
+| `ChainTypeOf<K>` | generic type |
+| `WalletDefaultsByKey<K>` | generic type |
+
+Per-chain aliases follow two naming patterns — one alias per chain family (9 each):
+
+- `<Chain>TypeConfig` — per-slot config (e.g. `EvmTypeConfig`, `SolanaTypeConfig`)
+- `<Chain>ChainEntry` — per-chain-key entry (e.g. `EvmChainEntry`, `BitcoinChainEntry`)
+
+Replace `<Chain>` with `Evm | Solana | Sui | Bitcoin | Stellar | Injective | Icon | Near | Stacks`. Most consumers can derive these from `ChainTypeConfig<T>` / `ChainEntry<K>` instead of importing the per-chain alias directly.
+
+Adapter-field types (only chains with React adapters):
+
+| Symbol | Kind |
+|---|---|
+| `EvmAdapterFields` | type |
+| `SolanaAdapterFields` | type |
+| `SuiAdapterFields` | type |
+
+### Hook option / result types
+
+Every hook also exports its options / result types alongside it. Naming pattern is `Use<Name>Options`, `Use<Name>Result` (or `Use<Name>Return`), and any inline value types in `PascalCase` (e.g. `ChainGroup`, `ConnectedChain`, `WalletModalState`, `ConnectionStatus`). See [`hooks.md`](./hooks.md) for the signature each pair belongs to.
+
+---
+
+## Sub-path exports — `import { X } from '@sodax/wallet-sdk-react/xchains/<chain>'`
+
+Concrete chain classes live behind sub-paths. Default to barrel imports; opt into these only when you need `instanceof`, want to extend a class, or are wiring a custom connector list via `ChainTypeConfig.connectors`.
+
+### Default pattern (most chains)
+
+`/xchains/{evm, icon, injective, near, solana, sui}` re-export the chain's `XService` + `XConnector` classes — `EvmXService`/`EvmXConnector`, `SolanaXService`/`SolanaXConnector`, etc. Icon also exports `IconHanaXConnector` (the connector for the Hana wallet).
+
+```ts
+import { EvmXService, EvmXConnector } from '@sodax/wallet-sdk-react/xchains/evm';
+import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
+```
+
+### Chains with extra exports
+
+| Sub-path | Beyond `XService`/`XConnector` |
+|---|---|
+| `/xchains/bitcoin` | `XverseXConnector`, `UnisatXConnector`, `OKXXConnector` (3 wallet connectors), hook `useBitcoinXConnectors`, type `BtcWalletAddressType` |
+| `/xchains/evm` | `createWagmiConfig` (function — also exported as alias `createWagmi`) |
+| `/xchains/icon` | `CHAIN_INFO` (value), `SupportedChainId` (enum) |
+| `/xchains/stacks` | `STACKS_PROVIDERS` (value), hook `useStacksXConnectors`, type `StacksProviderConfig` |
+
+### Special case
+
+| Sub-path | Notes |
+|---|---|
+| `/xchains/stellar` | **No concrete classes re-exported.** Stellar uses `@creit.tech/stellar-wallets-kit` directly via an `XConnector` registered through the chain registry — no public class to `instanceof`-check. |
+
+If unsure what a sub-path exports, check the published `dist/`:
+
+```bash
+grep -E '^export' node_modules/@sodax/wallet-sdk-react/dist/xchains/<chain>/index.d.ts
+```
+
+---
+
+## Peer dependencies (consumer must install)
+
+| Package | Version |
+|---|---|
+| `react` | `>= 19` |
+| `@tanstack/react-query` | `5.x` |
+
+`@tanstack/react-query` is required at runtime — `<QueryClientProvider>` must wrap `<SodaxWalletProvider>`. v1 mounted one internally; v2 does not.
+
+---
+
+## Not exported (deliberately internal)
+
+These exist in the source but are **not** part of the public API. Do not import from `@sodax/wallet-sdk-react/dist/...` to reach them.
+
+- `useEthereumChainId` — read EVM chain id via wagmi's `useAccount().chainId` instead.
+- `useInitChainServices` — used by `<SodaxWalletProvider>` only.
+- `useXWalletStore` — Zustand store hook. Public hooks are the supported surface; if you need store access, file an issue describing the use case.
+
+---
+
+## What the v2 barrel does NOT re-export (vs v1)
+
+For migration context only — these were on v1's barrel:
+
+- All concrete `XService` / `XConnector` classes (now sub-path imports)
+- `useXBalances` (moved to `@sodax/dapp-kit` with a new signature — see `migration/breaking-changes.md` § 10)
+- `XWagmiProviders` (renamed to `SodaxWalletProvider`)
+- `useXWagmiStore` (the store hook — v2 doesn't export the store hook under any name; use public hooks like `useXServices` / `useXConnections` instead)
+
+See [`../../migration/reference/imports.md`](../../migration/reference/imports.md) for the full v1→v2 import map.

package/ai-exported/integration/reference/chain-support.md

@@ -0,0 +1,78 @@
+# Reference: Chain Support
+
+Chains supported by `@sodax/wallet-sdk-react` v2 — their `ChainType` family and per-slot config shape. Use this when picking which slots to include in `walletConfig`.
+
+---
+
+## Chain families (`ChainType`)
+
+9 chain families. Each is a top-level slot on `SodaxWalletConfig`:
+
+| ChainType | Networks (examples) | React adapter mounted |
+|---|---|---|
+| `EVM` | Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia | wagmi |
+| `SOLANA` | Solana mainnet | `@solana/wallet-adapter-react` |
+| `SUI` | Sui mainnet/testnet | `@mysten/dapp-kit` |
+| `BITCOIN` | Bitcoin mainnet | (none — direct extension probes) |
+| `STELLAR` | Stellar mainnet | (none) |
+| `ICON` | ICON mainnet | (none) |
+| `INJECTIVE` | Injective mainnet | (none) |
+| `NEAR` | NEAR mainnet | (none) |
+| `STACKS` | Stacks mainnet | (none) |
+
+EVM is the only family with multiple networks under one connection — wagmi maintains a single connection that spans every configured EVM network. See [`../architecture.md`](../architecture.md) § "EVM is one connection".
+
+---
+
+## Per-slot config shape
+
+| Slot | Config fields | Notes |
+|---|---|---|
+| `EVM` | `ssr?, walletConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
+| `SOLANA` | `autoConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
+| `SUI` | `network?, connectors?, chains?` | `network: 'mainnet' \| 'testnet'` |
+| `BITCOIN` | extends `BitcoinRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
+| `STELLAR` | extends `StellarRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
+| `INJECTIVE` | extends `InjectiveRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
+| `ICON` | `connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
+| `NEAR` | `connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
+| `STACKS` | preset name (string) **or** `StacksNetworkLike & { defaults?, connectors? }` | `'mainnet'` / `'testnet'` preset accepted |
+
+The single source of truth for the per-chain shape is `ChainMeta` in `src/types/config.ts` — `SodaxWalletConfig`, `ChainEntry<K>`, `WalletDefaultsByKey<K>` derive from it.
+
+---
+
+## ChainKey constants
+
+`ChainKey` is the chain-id enum exported from `@sodax/types`. Use it in `walletConfig.<SLOT>.chains[<ChainKey>]` and in hooks that take `xChainId`.
+
+```ts
+import { ChainKeys } from '@sodax/types';
+
+ChainKeys.SONIC_MAINNET;       // EVM
+ChainKeys.ETHEREUM_MAINNET;    // EVM
+ChainKeys.SOLANA_MAINNET;      // SOLANA
+ChainKeys.BITCOIN_MAINNET;     // BITCOIN
+// …etc
+```
+
+Naming pattern: `<NETWORK>_MAINNET`. EVM has 12 entries (Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia); the other 8 families each have one. Inspect `@sodax/types` for the authoritative list.
+
+---
+
+## Slot opt-in behavior
+
+- **Omit a slot** to skip mounting that adapter entirely. The chain won't appear in `useXConnectors`, `useChainGroups`, or `useEnabledChains`.
+- **Pass `{}`** to mount with SDK defaults. Useful for chains where you don't need to override RPC or connectors.
+- **Provide a partial config** (`{ chains: {...} }`) to override only what you need; everything else uses defaults.
+
+```ts
+const walletConfig: SodaxWalletConfig = {
+  EVM: { ssr: true, chains: { [ChainKeys.SONIC_MAINNET]: { rpcUrl: '...' } } }, // explicit
+  BITCOIN: {},                                                                    // defaults
+  SOLANA: { autoConnect: false, chains: { [ChainKeys.SOLANA_MAINNET]: {} } },     // partial
+  // STELLAR not included → not mounted
+};
+```
+
+For per-hook fallback behavior when a slot is omitted, see [`hooks.md`](./hooks.md) § "Behavior when the chain slot is not in walletConfig".

package/ai-exported/integration/reference/connectors.md

@@ -0,0 +1,74 @@
+# Reference: Connectors
+
+A connector is the adapter between a specific wallet (Hana, MetaMask, Phantom, Xverse…) and the SODAX store. Every connector implements `IXConnector`, the public contract every hook in `wallet-sdk-react` consumes.
+
+Concrete connector classes live behind sub-path imports — see [`api-surface.md`](./api-surface.md) § "Sub-path exports" for the per-chain map.
+
+---
+
+## `IXConnector` interface
+
+```typescript
+export interface IXConnector {
+  readonly xChainType: ChainType;
+  readonly name: string;            // 'Hana', 'MetaMask', 'Xverse', …
+  readonly id: string;              // unique connector id (e.g. 'io.metamask')
+  readonly icon: string | undefined;
+  readonly isInstalled: boolean;    // wallet extension presence (read at getter call time)
+  readonly installUrl: string | undefined;
+  connect(): Promise<XAccount | undefined>;
+  disconnect(): Promise<void>;
+}
+```
+
+Consumer code should depend on **`IXConnector`** (the interface), not the concrete `XConnector` class — keeps your code chain-implementation-agnostic and allows custom connectors to slot in without inheriting from the abstract base.
+
+`isInstalled` reads `window.*` at getter-call time — no extra subscription is installed. Components get fresh values through normal React render triggers.
+
+---
+
+## Listing connectors at runtime
+
+Don't import concrete classes to discover what's available — use the hook:
+
+```ts
+const connectors = useXConnectors({ xChainType: 'EVM' });
+// IXConnector[] — already filtered to enabled chain
+```
+
+For the per-chain class names (only needed for `instanceof` or custom-connector-list use cases), see [`api-surface.md`](./api-surface.md) § "Sub-path exports" and the worked example in [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md). Bitcoin's `BitcoinXConnector` is the only abstract base — its concrete subclasses (Unisat, Xverse, OKX) override per-wallet signing methods (see [`sign-message.md`](../recipes/sign-message.md)).
+
+---
+
+## `sortConnectors` — display ordering
+
+Pure utility for ranking connectors in lists. Stable sort by:
+
+1. Position in `preferred[]` (earlier wins)
+2. `isInstalled === true`
+3. Original index
+
+```typescript
+import { useXConnectors, sortConnectors } from '@sodax/wallet-sdk-react';
+
+const PREFERRED = ['hana', 'metamask'];
+
+function ConnectorList() {
+  const raw = useXConnectors({ xChainType: 'EVM' });
+  const sorted = sortConnectors(raw, { preferred: PREFERRED });
+  // Hana first if present, then MetaMask, then any other installed wallets, then uninstalled.
+}
+```
+
+`preferred` matches by exact `connector.id`. For substring/case-insensitive matching across chains, use `useIsWalletInstalled` instead — see [`batch-operations.md`](../recipes/batch-operations.md).
+
+---
+
+## Custom connectors
+
+Two ways to plug in a wallet the SDK doesn't ship:
+
+1. **Extend `XConnector`** (abstract base, exported from the barrel) — implement `connect()` / `disconnect()` / `isInstalled` / `installUrl`. Pass via `SodaxWalletConfig.<CHAIN>.connectors` to replace the registry defaults for that chain.
+2. **Implement `IXConnector` directly** — skip the abstract base. The SDK never does `instanceof XConnector` on user-supplied connectors; it only relies on the interface.
+
+For a worked example with code, see [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md) § "Custom connector list". For chains with extra signing methods (Bitcoin's `signBip322Message`, Injective specifics), implement the chain-specific extras — the SDK detects them via type guards at dispatch time.

package/ai-exported/integration/reference/hooks.md

@@ -0,0 +1,204 @@
+# Reference: Hooks
+
+Full hook surface of `@sodax/wallet-sdk-react` v2. All hooks accept an options object — never positional args. Pair this with [`connectors.md`](./connectors.md) for connector shape and [`chain-support.md`](./chain-support.md) for chain identifiers.
+
+> **All hooks are client-only.** They depend on `<SodaxWalletProvider>` and `<QueryClientProvider>`, which only mount on the client. Next.js App Router consumers must mark every file calling these hooks with `'use client'`. Server Components cannot read connection state directly — pass it down from a client boundary.
+
+---
+
+## Behavior when the chain slot is not in `walletConfig`
+
+Hooks do **not** throw when their chain isn't enabled — each picks its own no-op fallback. UI code can call them unconditionally and branch on the return value.
+
+| Hook | Behavior when chain absent |
+|---|---|
+| `useXAccount`, `useXAccounts` | Returns shape with `address: undefined` |
+| `useXConnection`, `useXConnections` | Returns `undefined` / empty record |
+| `useXConnectors` | Returns `[]`. **One-time `console.warn`** per chain type to surface config mistakes. |
+| `useXConnectorsByChain` | Returns empty record. No warning. |
+| `useWalletProvider` | Returns `undefined` |
+| `useXService`, `useXServices` | Returns `undefined` / empty record |
+| `useEvmSwitchChain` | Returns `{ isWrongChain: false, handleSwitchChain: () => {} }` (no-op) |
+| `useEnabledChains` | Returns the list of slots actually present (does not include the disabled one) |
+| `useChainGroups`, `useConnectedChains` | Excludes the chain from output |
+| `useXConnect`, `useXDisconnect`, `useXSignMessage` | Mutation rejects when invoked with an unsupported `xChainType` |
+
+Rule of thumb: read-hooks degrade silently to "empty"; mutation-hooks reject. Both cases are safe to call unconditionally.
+
+---
+
+## Connect / disconnect
+
+| Hook | Signature | Returns |
+|---|---|---|
+| `useXConnect` | `useXConnect(): UseMutationResult<XAccount \| undefined, Error, IXConnector>` | React Query mutation. **Resolves to `undefined` for provider-managed chains** (EVM/Solana/Sui) — read the connected account via `useXAccount` after the mutation lands. |
+| `useXDisconnect` | `useXDisconnect(): (args: UseXDisconnectArgs) => Promise<void>` where `UseXDisconnectArgs = { xChainType: ChainType }` | Async function — never throws |
+| `useConnectionFlow` | `useConnectionFlow(): { status, error, connect, retry, activeConnector }` | Status object |
+| `useBatchConnect` | `useBatchConnect({ connectors, skipConnected?, onProgress? })` | `{ run, status, result, reset }` |
+| `useBatchDisconnect` | `useBatchDisconnect({ connectors?, onProgress? })` | `{ run, status, result, reset }` |
+
+```ts
+const { mutateAsync: connect } = useXConnect();
+await connect(connector);
+
+const disconnect = useXDisconnect();
+await disconnect({ xChainType: 'EVM' });
+```
+
+---
+
+## Read account / connection state
+
+| Hook | Signature | Returns |
+|---|---|---|
+| `useXAccount` | `useXAccount({ xChainType }) \| useXAccount({ xChainId })` | `XAccount` (always populated; `address` undefined when disconnected) |
+| `useXAccounts` | `useXAccounts()` | `Partial<Record<ChainType, XAccount>>` (only enabled chains; entries are populated, `address` undefined when disconnected) |
+| `useXConnection` | `useXConnection({ xChainType })` | `XConnection \| undefined` |
+| `useXConnections` | `useXConnections()` | `Partial<Record<ChainType, XConnection>>` |
+| `useConnectedChains` | `useConnectedChains({ order? })` | `{ status: 'loading' \| 'ready', chains: ConnectedChain[], total: number }` |
+
+```ts
+import { ChainKeys } from '@sodax/types';
+
+const { address } = useXAccount({ xChainType: 'EVM' });
+const { address } = useXAccount({ xChainId: ChainKeys.BSC_MAINNET });
+```
+
+---
+
+## Connector discovery
+
+| Hook | Signature | Returns |
+|---|---|---|
+| `useXConnectors` | `useXConnectors({ xChainType })` | `IXConnector[]` (returns `[]` and logs a one-time warning if `xChainType` isn't enabled in `walletConfig`) |
+| `useXConnectorsByChain` | `useXConnectorsByChain()` | `Partial<Record<ChainType, IXConnector[]>>` (no per-chain warnings) |
+| `useIsWalletInstalled` | `useIsWalletInstalled({ connectors?, chainType? })` | `boolean` (at least one of `connectors`/`chainType` required) |
+| `sortConnectors` | `sortConnectors(list, { preferred }): IXConnector[]` | Pure utility — installed first |
+
+```ts
+const connectors = useXConnectors({ xChainType: 'EVM' });
+const sorted = sortConnectors(connectors, { preferred: ['hana', 'metamask'] });
+
+const isInstalled = useIsWalletInstalled({ connectors: ['hana'] });
+```
+
+---
+
+## Wallet provider bridge (for `@sodax/sdk` calls)
+
+| Hook | Signature | Returns |
+|---|---|---|
+| `useWalletProvider` | `useWalletProvider({ xChainId })` | Chain-narrowed `IXxxWalletProvider \| undefined` |
+| `useWalletProvider` | `useWalletProvider({ xChainType })` | Family-level `IXxxWalletProvider \| undefined` |
+| `useWalletProvider` | `useWalletProvider()` | `IWalletProvider \| undefined` |
+
+```ts
+import { ChainKeys } from '@sodax/types';
+
+const evm = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+// evm: IEvmWalletProvider | undefined
+```
+
+See [`bridge-to-sdk.md`](../recipes/bridge-to-sdk.md) for usage with SDK calls.
+
+---
+
+## Modal / multi-chain UI
+
+| Hook | Signature | Returns |
+|---|---|---|
+| `useWalletModal` | `useWalletModal({ onConnected? })` | `{ state, open, close, back, selectChain, selectWallet, retry }` |
+| `useChainGroups` | `useChainGroups({ order? })` | `ChainGroup[]` (one per enabled chain family) |
+
+State machine kinds: `closed`, `chainSelect`, `walletSelect`, `connecting`, `success`, `error`.
+
+See [`multi-chain-modal.md`](../recipes/multi-chain-modal.md).
+
+---
+
+## Sign message
+
+| Hook | Signature | Returns |
+|---|---|---|
+| `useXSignMessage` | `useXSignMessage()` | React Query mutation — `{ xChainType, message }` → `` `0x${string}` \| Uint8Array \| string \| undefined `` |
+
+```ts
+const sign = useXSignMessage();
+const sig = await sign.mutateAsync({ xChainType: 'EVM', message: 'hello' });
+```
+
+See [`sign-message.md`](../recipes/sign-message.md) for per-chain matrix.
+
+---
+
+## EVM-specific
+
+| Hook | Signature | Returns |
+|---|---|---|
+| `useEvmSwitchChain` | `useEvmSwitchChain({ xChainId }: { xChainId: SpokeChainKey })` | `{ isWrongChain: boolean, handleSwitchChain: () => void }`. Compares the connected EVM chain to `xChainId` and exposes wrong-network state. Also handles Injective + MetaMask (auto-switches to Ethereum mainnet). Returns no-op values when `EVM` is not in `walletConfig`. |
+
+```ts
+import { ChainKeys } from '@sodax/types';
+
+const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
+  xChainId: ChainKeys.BSC_MAINNET,
+});
+
+if (isWrongChain) handleSwitchChain();
+```
+
+> **No top-level `useEthereumChainId` in v2.** The raw EVM chain ID is internal — read it via wagmi's `useAccount().chainId` instead. v2 folds the Injective+MetaMask "wrong network" UX into `useEvmSwitchChain` above.
+
+---
+
+## Service-level (advanced)
+
+| Hook | Signature | Returns |
+|---|---|---|
+| `useXService` | `useXService({ xChainType })` | `IXService \| undefined` |
+| `useXServices` | `useXServices()` | `Partial<Record<ChainType, IXService>>` |
+| `useEnabledChains` | `useEnabledChains()` | `ChainType[]` |
+| `useInitChainServices` | (internal — handled by `SodaxWalletProvider`) | — |
+
+---
+
+## Hook return-shape glossary
+
+```ts
+type XAccount = {
+  address: string | undefined;
+  xChainType: ChainType | undefined;
+  publicKey?: string;
+};
+
+type XConnection = {
+  xAccount: XAccount;
+  xConnectorId: string;
+};
+
+type IXConnector = {
+  readonly xChainType: ChainType;
+  readonly name: string;
+  readonly id: string;
+  readonly icon: string | undefined;
+  readonly isInstalled: boolean;
+  readonly installUrl: string | undefined;
+  connect(): Promise<XAccount | undefined>;
+  disconnect(): Promise<void>;
+};
+```
+
+---
+
+## "Exactly one of" rule for chain identifiers
+
+Hooks that accept both `xChainId` and `xChainType` enforce **exactly one** — passing both, neither, or `undefined` for both throws at runtime (and is a type error):
+
+```ts
+useXAccount({ xChainType: 'EVM' });                           // ✅
+useXAccount({ xChainId: ChainKeys.BSC_MAINNET });             // ✅
+useXAccount({ xChainType: 'EVM', xChainId: ChainKeys.BSC_MAINNET }); // ❌ throws
+useXAccount({});                                              // ❌ throws
+```
+
+The chain-id form gives narrowest TypeScript inference (e.g. `xChainId: ChainKeys.BSC_MAINNET` → `IEvmWalletProvider`); the chain-type form is family-level.

package/ai-exported/integration/reference/wallet-brands.md

@@ -0,0 +1,106 @@
+# Reference: Wallet Brand Identifiers
+
+`useBatchConnect`, `useBatchDisconnect`, and `useIsWalletInstalled` accept a `connectors: readonly string[]` of **wallet brand identifiers** — short strings that match by **case-insensitive substring** against `connector.id` and `connector.name` (see [`../recipes/batch-operations.md`](../recipes/batch-operations.md)).
+
+The identifiers are **open**: any string works. The table below lists every brand the package ships connectors for so you can pick an identifier short enough to match across chain families. To target a specific connector (not a brand), bypass this API and use `useXConnectors({ xChainType }).find(c => c.id === '…')` directly — see [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md).
+
+---
+
+## Known wallet brands
+
+| Identifier | Chains it matches | Underlying connector id / name |
+|---|---|---|
+| `'hana'` | EVM, ICON, Sui, Stellar | EVM via EIP-6963 RDNS (e.g. `io.havah.hana`); ICON id `hana`; Sui/Stellar — connector names containing "Hana" |
+| `'phantom'` | EVM, Solana | EVM RDNS `app.phantom`; Solana adapter name `Phantom` |
+| `'metamask'` | EVM, Injective | EVM RDNS `io.metamask`; Injective `Wallet.Metamask` strategy |
+| `'xverse'` | Bitcoin, Stacks | Bitcoin id `xverse`; Stacks id `XverseProviders.BitcoinProvider` |
+| `'unisat'` | Bitcoin | id `unisat` |
+| `'okx'` | Bitcoin | id `okx-bitcoin` |
+| `'leather'` | Stacks | id `LeatherProvider` |
+| `'asigna'` | Stacks | id `AsignaProvider` |
+| `'fordefi'` | Stacks | id `FordefiProviders.UtxoProvider` |
+| `'solflare'`, `'backpack'`, `'coinbase'`, `'trust'`, `'ledger'`, … | Solana | Adapter names from `@solana/wallet-adapter-wallets` |
+| `'freighter'`, `'albedo'`, `'lobstr'`, `'xbull'`, … | Stellar | Names from `@creit.tech/stellar-wallets-kit` |
+
+EVM (via EIP-6963), Solana, Sui, Stellar, and Injective surface connectors **dynamically** — the actual ids depend on what's installed in the user's browser. The table reflects names the upstream libraries ship by default.
+
+---
+
+## Picking a short identifier
+
+Substring match is greedy. `'hana'` matches `Hana`, `io.havah.hana`, `hana-anything`. Trade-offs:
+
+- **Shorter = broader.** `'hana'` matches everywhere Hana appears across chain families. Good for batch ops targeting a brand across many chains.
+- **Longer = narrower.** `'io.metamask'` only matches the EIP-6963 RDNS — not Injective's MetaMask connector (which uses a different name string). Use when you specifically want one connector and nothing else.
+- **`< 3 chars`** triggers a dev-mode warning — substring matching on 1–2 char identifiers (e.g. `'ok'`) hits unintended connectors. The package will keep working but logs once per identifier.
+
+---
+
+## Runtime discovery — list what's actually installed
+
+The table above is a guide, not authoritative. Browser extensions evolve and RDNS strings change. To inspect the real environment:
+
+```tsx
+'use client';
+
+import { useXConnectors } from '@sodax/wallet-sdk-react';
+import type { ChainType } from '@sodax/types';
+
+const CHAINS: ChainType[] = ['EVM', 'SOLANA', 'SUI', 'BITCOIN', 'STELLAR', 'ICON', 'INJECTIVE', 'NEAR', 'STACKS'];
+
+export function DevConnectorLister() {
+  return (
+    <table>
+      <thead>
+        <tr><th>Chain</th><th>id</th><th>name</th><th>installed</th></tr>
+      </thead>
+      <tbody>
+        {CHAINS.flatMap((chainType) => (
+          <ChainRow key={chainType} chainType={chainType} />
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+function ChainRow({ chainType }: { chainType: ChainType }) {
+  const connectors = useXConnectors({ xChainType: chainType });
+  return (
+    <>
+      {connectors.map((c) => (
+        <tr key={`${chainType}-${c.id}`}>
+          <td>{chainType}</td>
+          <td><code>{c.id}</code></td>
+          <td>{c.name}</td>
+          <td>{c.isInstalled ? '✓' : '—'}</td>
+        </tr>
+      ))}
+    </>
+  );
+}
+```
+
+Drop this component into your app during integration to print the live connector roster. Pick a short identifier from the `id` or `name` columns and feed it into `useBatchConnect({ connectors: [...] })`.
+
+For one-off inspection (no UI):
+
+```tsx
+useEffect(() => {
+  const all = CHAINS.flatMap((chainType) =>
+    useXConnectors({ xChainType: chainType }).map((c) => ({ chainType, id: c.id, name: c.name, isInstalled: c.isInstalled })),
+  );
+  console.table(all);
+}, []);
+```
+
+---
+
+## When brand identifiers are the wrong tool
+
+Reach for `useXConnectors({ xChainType }).find(c => c.id === '…')` + `useXConnect` directly when:
+
+- **The brand list and chain list don't align.** e.g. "Connect Hana on EVM only, even though Hana also covers ICON" — the brand identifier API targets the wallet, not a chain/wallet pair.
+- **You need to disambiguate two wallets with overlapping names.** `'wallet'` would match every wallet-named connector.
+- **You're building a chain picker UI**, not a one-shot batch. Per-chain selection naturally uses `useXConnectors` per chain anyway.
+
+See [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md) for the worked code path.