react@sodax/wallet-sdk-react

React layer over @sodax/wallet-sdk-corearrow-up-right — 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 stateuseXAccount, useXConnection, useXAccounts all read the same Zustand slice; persisted to localStorage

  • Bridge to @sodax/sdkuseWalletProvider returns a typed IXxxWalletProvider ready to plug into any SDK call

  • Headless wallet modaluseWalletModal 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

Quick start

Documentation

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

Topic
What it covers

SodaxWalletConfig shape, opt-in chain mounting, per-chain RPC + wallet defaults, breaking changes from v1

Discover connectors, connect, read account, disconnect; provider-managed vs non-provider chains; persisted reconnect

useWalletProvider → typed IXxxWalletProvider for @sodax/sdk calls; useXService / useXServices

Headless state machine for multi-chain modal UIs; useConnectionFlow non-modal alternative

Enterprise custody integration (Fireblocks, Ledger); qrModalOptions filtering

Sequential multi-chain connect/disconnect by wallet identifier

useChainGroups, useConnectedChains, useIsWalletInstalled, useEnabledChains; hydration status

useXSignMessage cross-chain; Bitcoin BIP-322 vs ECDSA auto-detect

Single wagmi connection across all configured EVM networks

IXConnector contract, deep-import concrete classes, custom connectors

Zustand store, Provider/Hydrator/Actions trio, persist hydration caveat

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

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:

See Connectorsarrow-up-right for the full list of deep-import sub-paths.

Requirements

  • Node.js >= 18.0.0

  • React >= 19

  • TypeScript

Development

Contributing

Contributions welcome — see the repo Contributing Guidearrow-up-right. For onboarding a new chain family, follow docs/ADDING_A_NEW_CHAIN.mdarrow-up-right.

License

MITarrow-up-right

Support

Last updated