@sodax/wallet-sdk-react 1.5.7-beta → 2.0.0-rc.10

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,104 @@ 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
 
-## Requirements
+The full guide lives in [`docs/`](docs/). Start with the topic that matches what you're building.
 
-- Node.js >= 18.0.0
-- React >= 19
-- TypeScript
+| 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 |
 
+## AI agent docs
 
-## API Reference
+AI-readable docs for `@sodax/wallet-sdk-react` (and the other `@sodax/*` packages) are shipped via [`@sodax/skills`](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills) — a separate npm package bundling Claude-Code SKILL.md files and a long-form knowledge tree.
 
-### Components
+**Recommended: [`skills` CLI](https://github.com/vercel-labs/skills)** — from your project root:
 
-- [`SodaxWalletProvider`](https://github.com/icon-project/sodax-frontend/tree/main/packages/wallet-sdk-react/src/SodaxWalletProvider.tsx) - Main provider component for wallet connectivity
+```bash
+npx skills@latest add icon-project/sodax-sdks/packages/skills
+```
 
-### Hooks
+**npm + `AGENTS.md` pointer** (fallback for web chats, or when you prefer a devDependency over the CLI):
 
-#### 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
+```bash
+pnpm add -D @sodax/skills
+```
 
-#### 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
+Then point your agent at `node_modules/@sodax/skills/AGENTS.md`. See [docs/ai-integration-guide.md](https://github.com/icon-project/sodax-sdks/blob/main/docs/ai-integration-guide.md) for all install modes and per-tool wiring.
 
-#### 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 >= 20.12.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 +180,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/dist/XConnector-12q0OVe5.d.ts

@@ -0,0 +1,146 @@
+import { ChainType, IXServiceBase, XToken } from '@sodax/types';
+
+type XAccount = {
+    address: string | undefined;
+    xChainType: ChainType | undefined;
+    publicKey?: string;
+};
+type XConnection = {
+    xAccount: XAccount;
+    xConnectorId: string;
+};
+
+/**
+ * Public interface for chain service implementations.
+ *
+ * Consumer code should depend on this interface instead of the concrete XService class.
+ * Extends the shared `IXServiceBase` from `@sodax/types` with wallet-sdk-react
+ * specific connector methods.
+ */
+interface IXService extends IXServiceBase {
+    getXConnectors(): IXConnector[];
+    getXConnectorById(xConnectorId: string): IXConnector | undefined;
+}
+/**
+ * Public interface for wallet connector implementations.
+ *
+ * `isInstalled` reads `window.*` at getter-call time (render time); no extra
+ * subscription is installed. Components get fresh values through normal React
+ * render triggers (store updates, parent rerenders).
+ */
+interface IXConnector {
+    readonly xChainType: ChainType;
+    readonly name: string;
+    /** Unique identifier for the connector */
+    readonly _id: string;
+    /** Optional icon URL for the wallet provider */
+    readonly _icon?: string;
+    readonly id: string;
+    readonly icon: string | undefined;
+    /** True when the wallet extension backing this connector is installed. */
+    readonly isInstalled: boolean;
+    /** URL where users can install the wallet extension if missing. */
+    readonly installUrl: string | undefined;
+    connect(): Promise<XAccount | undefined>;
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Abstract base class for blockchain service implementations.
+ *
+ * The XService class serves as a foundation for implementing blockchain-specific services
+ * in a multi-chain environment. It provides a standardized interface for:
+ * 1. Managing wallet connectors for different blockchain types
+ * 2. Querying token balances across different chains
+ *
+ * Each blockchain implementation (e.g., Solana, EVM chains) extends this class
+ * to provide chain-specific functionality while maintaining a consistent interface.
+ *
+ * @abstract
+ * @class XService
+ * @property {ChainType} xChainType - The blockchain type this service handles (e.g., 'SOLANA', 'EVM')
+ * @property {XConnector[]} xConnectors - Available wallet connectors for this chain
+ *
+ */
+declare abstract class XService implements IXServiceBase {
+    /** The blockchain type this service handles */
+    readonly xChainType: ChainType;
+    /** Available wallet connectors for this chain */
+    private xConnectors;
+    constructor(xChainType: ChainType);
+    /**
+     * Gets the balance of a specific token for an address
+     * @param address The wallet address to check
+     * @param xToken The token to get the balance for
+     * @returns Promise resolving to the token balance as a bigint
+     */
+    getBalance(address: string | undefined, xToken: XToken): Promise<bigint>;
+    /**
+     * Gets balances for multiple tokens for an address
+     * @param address The wallet address to check
+     * @param xTokens Array of tokens to get balances for
+     * @returns Promise resolving to object mapping token addresses to balances
+     */
+    getBalances(address: string | undefined, xTokens: readonly XToken[]): Promise<Record<string, bigint>>;
+    /**
+     * Gets all available connectors for this chain
+     */
+    getXConnectors(): IXConnector[];
+    /**
+     * Sets the available connectors for this chain
+     */
+    setXConnectors(xConnectors: IXConnector[]): void;
+    /**
+     * Gets a specific connector by its ID
+     * @param xConnectorId The connector ID to look up
+     * @returns The matching connector or undefined if not found
+     */
+    getXConnectorById(xConnectorId: string): IXConnector | undefined;
+}
+
+/**
+ * Base class for wallet provider connectors that handles connection management and wallet interactions
+ *
+ * @abstract
+ * @class XConnector
+ * @property {ChainType} xChainType - The blockchain type this connector supports
+ * @property {string} name - Display name of the wallet provider
+ * @property {string} _id - Unique identifier for the connector
+ * @property {string | undefined} _icon - Optional icon URL for the wallet provider
+ */
+declare abstract class XConnector implements IXConnector {
+    /** The blockchain type this connector supports */
+    readonly xChainType: ChainType;
+    /** Display name of the wallet provider */
+    readonly name: string;
+    /** Unique identifier for the connector */
+    readonly _id: string;
+    /** Optional icon URL for the wallet provider */
+    readonly _icon?: string;
+    constructor(xChainType: ChainType, name: string, id: string);
+    /**
+     * Connects to the wallet provider
+     * @returns Promise resolving to the connected account, or undefined if connection fails
+     */
+    abstract connect(): Promise<XAccount | undefined>;
+    /**
+     * Disconnects from the wallet provider
+     */
+    abstract disconnect(): Promise<void>;
+    /** Get the unique identifier for this connector */
+    get id(): string;
+    /** Get the optional icon URL for this wallet provider */
+    get icon(): string | undefined;
+    /**
+     * True when the wallet extension backing this connector is installed.
+     * Default: true (for provider-managed chains where connector presence already
+     * implies install — EVM via EIP-6963, Solana/Sui via adapter discovery).
+     * Subclasses backed by extension injection (Bitcoin, ICON, Stacks) override
+     * this with a window probe.
+     */
+    get isInstalled(): boolean;
+    /** URL to install the wallet extension when missing. Subclasses override. */
+    get installUrl(): string | undefined;
+}
+
+export { type IXConnector as I, type XAccount as X, type IXService as a, type XConnection as b, XConnector as c, XService as d };

package/dist/chunk-7V7O3Q7Y.mjs

@@ -0,0 +1,62 @@
+import { getEvmChainKeyByChainId, baseChainInfo } from '@sodax/types';
+
+// src/utils/walletRpcConfig.ts
+function getEntryDefaults(entry) {
+  if (!entry || typeof entry === "string") return void 0;
+  return entry.defaults;
+}
+function getRpcUrl(entry) {
+  if (!entry || typeof entry === "string") return void 0;
+  return entry.rpcUrl;
+}
+function resolveEvmDefaults(activeChainId, evmChains) {
+  const key = getEvmChainKeyByChainId(activeChainId);
+  if (!key || !evmChains) return void 0;
+  return evmChains[key]?.defaults;
+}
+
+// src/utils/sortConnectors.ts
+function sortConnectors(connectors, options = {}) {
+  const { preferred = [] } = options;
+  const preferredIndex = new Map(preferred.map((id, i) => [id, i]));
+  return [...connectors].map((connector, originalIndex) => ({ connector, originalIndex })).sort((a, b) => {
+    const aPref = preferredIndex.get(a.connector.id);
+    const bPref = preferredIndex.get(b.connector.id);
+    if (aPref !== bPref) {
+      if (aPref === void 0) return 1;
+      if (bPref === void 0) return -1;
+      return aPref - bPref;
+    }
+    if (a.connector.isInstalled !== b.connector.isInstalled) {
+      return a.connector.isInstalled ? -1 : 1;
+    }
+    return a.originalIndex - b.originalIndex;
+  }).map(({ connector }) => connector);
+}
+var isNativeToken = (xToken) => {
+  const nativeAddresses = [
+    "cx0000000000000000000000000000000000000000",
+    "0x0000000000000000000000000000000000000000",
+    "inj",
+    "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
+    "hx0000000000000000000000000000000000000000",
+    "11111111111111111111111111111111",
+    // solana
+    "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
+    // stellar
+    "ST000000000000000000002AMW42H.nativetoken",
+    // stacks
+    "0:0"
+    // bitcoin
+  ];
+  return nativeAddresses.includes(xToken.address);
+};
+var getWagmiChainId = (xChainId) => {
+  const chainId = baseChainInfo[xChainId].chainId;
+  if (typeof chainId !== "number") {
+    throw new Error(`[wallet-sdk-react] getWagmiChainId: expected numeric chainId, got ${typeof chainId}`);
+  }
+  return chainId;
+};
+
+export { getEntryDefaults, getRpcUrl, getWagmiChainId, isNativeToken, resolveEvmDefaults, sortConnectors };

package/dist/chunk-C6M34IVL.mjs

@@ -0,0 +1,86 @@
+import { NEAR_DEFAULT_RPC_URL } from './chunk-NAKCAL2M.mjs';
+import { XService, XConnector } from './chunk-IFXZQW4C.mjs';
+import { NearConnector } from '@hot-labs/near-connect';
+import { JsonRpcProvider } from 'near-api-js';
+
+var NearXService = class _NearXService extends XService {
+  static instance;
+  walletSelector;
+  rpcUrl;
+  /**
+   * @param rpcUrl - Used by `getBalance` via `JsonRpcProvider({ url: rpcUrl })`.
+   *   Does NOT affect `walletSelector` — `@hot-labs/near-connect` only accepts
+   *   the network preset name (`'mainnet'`/`'testnet'`) and fetches RPC internally.
+   *   Custom RPC is therefore read-only for balance queries.
+   */
+  constructor(rpcUrl = NEAR_DEFAULT_RPC_URL) {
+    super("NEAR");
+    this.rpcUrl = rpcUrl;
+    this.walletSelector = new NearConnector({
+      network: "mainnet",
+      logger: console,
+      autoConnect: true,
+      excludedWallets: ["okx-wallet"]
+    });
+  }
+  /**
+   * @param rpcUrl - Re-applied on every call (matches StacksXService semantics).
+   *   `rpcUrl` only drives `getBalance` via a per-call `JsonRpcProvider`, so it's
+   *   safe to update at runtime — no persistent chain client to rebuild.
+   */
+  static getInstance(rpcUrl) {
+    if (!_NearXService.instance) {
+      _NearXService.instance = new _NearXService(rpcUrl);
+    } else if (rpcUrl) {
+      _NearXService.instance.rpcUrl = rpcUrl;
+    }
+    return _NearXService.instance;
+  }
+  async getBalance(address, xToken) {
+    const provider = new JsonRpcProvider({ url: this.rpcUrl });
+    if (xToken.symbol === "NEAR") {
+      const account = await provider.viewAccount({ accountId: address ?? "" });
+      return BigInt(account.amount);
+    }
+    const res = await provider.callFunction({
+      contractId: xToken.address,
+      method: "ft_balance_of",
+      args: { account_id: address }
+    });
+    return BigInt(res ?? 0);
+  }
+};
+
+// src/xchains/near/NearXConnector.ts
+var NearXConnector = class extends XConnector {
+  _wallet;
+  constructor(wallet) {
+    super("NEAR", wallet.manifest.name, wallet.manifest.id);
+    this._wallet = wallet;
+  }
+  getXService() {
+    return NearXService.getInstance();
+  }
+  async connect() {
+    const walletSelector = this.getXService().walletSelector;
+    const wallet = await walletSelector.connect({ walletId: this._wallet.manifest.id });
+    const accounts = await wallet.getAccounts();
+    if (accounts.length === 0 || accounts[0] === void 0) {
+      console.warn(`[NearXConnector] connect: ${this._wallet.manifest.name} returned no accounts`);
+      return void 0;
+    }
+    return {
+      address: accounts[0].accountId,
+      xChainType: this.xChainType
+    };
+  }
+  async disconnect() {
+    const walletSelector = this.getXService().walletSelector;
+    await walletSelector.disconnect(this._wallet);
+  }
+  get icon() {
+    return this._wallet.manifest.icon;
+  }
+};
+
+export { NearXConnector, NearXService };