@sodax/wallet-sdk-react

React layer over @sodax/wallet-sdk-core — 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

• 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

pnpm add @sodax/wallet-sdk-react
# or
npm install @sodax/wallet-sdk-react
# or
yarn add @sodax/wallet-sdk-react

Peer dependencies

{
  "react": ">=19",
  "@tanstack/react-query": "5.x"
}

Quick start

import {
  SodaxWalletProvider,
  type SodaxWalletConfig,
  useXAccount,
  useXConnect,
  useXConnectors,
} from '@sodax/wallet-sdk-react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ChainKeys } from '@sodax/types';

const queryClient = new QueryClient();

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 config={config}>
        <WalletConnect />
      </SodaxWalletProvider>
    </QueryClientProvider>
  );
}

function WalletConnect() {
  const connectors = useXConnectors({ xChainType: 'EVM' });
  const { mutateAsync: connect } = useXConnect();
  const account = useXAccount({ xChainType: 'EVM' });

  if (account.address) {
    return <p>Connected: {account.address}</p>;
  }

  return (
    <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>
  );
}

Documentation

The full guide lives in docs/. Start with the topic that matches what you're building.

Topic	What it covers
Configure SodaxWalletProvider	SodaxWalletConfig shape, opt-in chain mounting, per-chain RPC + wallet defaults, breaking changes from v1
Connect Flow	Discover connectors, connect, read account, disconnect; provider-managed vs non-provider chains; persisted reconnect
Wallet Provider Bridge	useWalletProvider → typed IXxxWalletProvider for @sodax/sdk calls; useXService / useXServices
Wallet Modal	Headless state machine for multi-chain modal UIs; useConnectionFlow non-modal alternative
WalletConnect	Enterprise custody integration (Fireblocks, Ledger); qrModalOptions filtering
Batch Operations	Sequential multi-chain connect/disconnect by wallet identifier
Chain Detection	useChainGroups, useConnectedChains, useIsWalletInstalled, useEnabledChains; hydration status
Sign Message	useXSignMessage cross-chain; Bitcoin BIP-322 vs ECDSA auto-detect
EVM Switch Chain	Single wagmi connection across all configured EVM networks
Connectors	IXConnector contract, deep-import concrete classes, custom connectors
Architecture	Zustand store, Provider/Hydrator/Actions trio, persist hydration caveat
Adding a New Chain	ChainMeta extension, chain registry, sub-path export wiring

AI agent docs

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 to start — it routes to integration recipes (new consumers), migration recipes (v1 → v2), and reference tables.

> Read node_modules/@sodax/wallet-sdk-react/ai-exported/AGENTS.md and integrate
> SODAX wallet connectivity into my Next.js app.

The CI guard scripts/check-ai-exported.sh validates that every hook reference and sub-path in those docs resolves to a real export.

---

Sub-path exports

Concrete connector / service classes are not exported from the package barrel — they live behind sub-path imports to prevent accidental coupling to internals:

// ✅ Normal usage — barrel import
import { useXConnect, useXAccount, type IXConnector } from '@sodax/wallet-sdk-react';

// ✅ Advanced — concrete class via deep import
import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
if (connector instanceof XverseXConnector) {
  connector.setAddressPurpose('payment');
}

See Connectors for the full list of deep-import sub-paths.

Requirements

• Node.js >= 18.0.0

• React >= 19

• TypeScript

Development

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

Contributing

Contributions welcome — see the repo Contributing Guide. For onboarding a new chain family, follow docs/ADDING_A_NEW_CHAIN.md.

License

MIT

Support

• GitHub Issues

• Discord Community