🔐 Web3 Wallet SDK

一个功能完整、易于使用的 Web3 钱包连接库

快速开始 · 完整文档 · 高级指南 · 功能列表

---

✨ 特性

• 🔌 多钱包支持 - MetaMask, Coinbase Wallet, WalletConnect
• 🔄 自动连接 - 页面刷新自动重连
• 💰 余额查询 - 实时余额更新
• 🌐 多链支持 - 13+ 预定义链配置
• 💾 持久化存储 - localStorage 状态保存
• 🎨 精美 UI - 开箱即用的组件
• 🪝 丰富 Hooks - 8 个实用 React Hooks
• 📦 TypeScript - 完整的类型支持
• 🎯 零配置 - 简单的 API 设计

🚀 快速开始

安装

npm install ethers

基础使用

import { 
  WalletProvider, 
  ConnectButton,
  metaMaskWallet,
  ETHEREUM_MAINNET 
} from './wallet-sdk';
import { ethers } from 'ethers';

function App() {
  return (
    <WalletProvider
      chains={[ETHEREUM_MAINNET]}
      wallets={[metaMaskWallet]}
      autoConnect={true}
      provider={new ethers.BrowserProvider(window.ethereum)}
    >
      <ConnectButton />
    </WalletProvider>
  );
}

使用 Hooks

import { useWallet, useBalance } from './wallet-sdk';

function MyComponent() {
  const { address, isConnected } = useWallet();
  const { balance } = useBalance();

  return (
    <div>
      <p>地址: {address}</p>
      <p>余额: {balance} ETH</p>
    </div>
  );
}

📚 文档

• 📖 快速入门 - 5 分钟上手指南
• 📘 完整文档 - 详细的 API 文档
• 📙 高级指南 - 高级用法和最佳实践
• 📗 功能列表 - 所有功能的详细说明

🎯 核心功能

React Hooks

Hook	功能
useWallet()	核心钱包状态和操作
useBalance()	账户余额查询
useAccount()	账户信息
useChain()	链信息和切换
useTransaction()	发送交易
useSignMessage()	消息签名
useTokenBalance()	ERC20 代币余额
useContract()	智能合约交互

UI 组件

• ConnectButton - 功能完整的连接按钮

  • 余额显示
  • 链选择器
  • 账户下拉菜单
  • 响应式设计

• WalletModal - 钱包选择模态框

  • 精美设计
  • 动画效果
  • 错误处理

工具函数

25+ 实用工具函数，包括：

• 地址格式化
• 单位转换
• 错误处理
• 剪贴板操作
• 网络检测
• Gas 计算

预定义链

支持 13+ 主流区块链网络：

• Ethereum (主网 & 测试网)
• Polygon
• BSC
• Arbitrum
• Optimism
• Avalanche
• Fantom

📦 项目结构

wallet-sdk/
├── components/          # UI 组件
├── connectors/          # 钱包连接器
├── constants/           # 常量配置
├── examples/            # 使用示例
├── hooks/              # React Hooks
├── provider/           # Context Provider
├── utils/              # 工具函数
└── types.ts           # TypeScript 类型

🛠️ 开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 代码检查
npm run lint

🌟 示例应用

运行演示应用：

npm run dev

访问 http://localhost:5173 查看完整的演示应用。

🔧 技术栈

• React 19.1.1 - UI 框架
• TypeScript 5.9.3 - 类型安全
• ethers.js 6.15.0 - 以太坊交互
• Tailwind CSS 4.1.14 - 样式框架
• Vite 7.1.7 - 构建工具

📊 功能统计

• ✅ 8 个 React Hooks
• ✅ 25+ 工具函数
• ✅ 13+ 预定义链
• ✅ 3 个钱包连接器
• ✅ 2 个 UI 组件
• ✅ 9 个使用示例
• ✅ 5 份详细文档

🎨 使用场景

• DeFi 应用（DEX、借贷、流动性挖矿）
• NFT 市场（铸造、交易、展示）
• DAO 治理（投票、提案、代币分发）
• 游戏和元宇宙（资产交易、虚拟土地）
• 任何 Web3 应用

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎贡献！请查看 贡献指南

📞 支持

• 📖 文档
• 💬 问题反馈
• 💡 功能建议

🙏 致谢

感谢以下开源项目：

• ethers.js
• React
• Tailwind CSS
• WalletConnect

---

Built with ❤️ by the Web3 Community

⭐ 如果这个项目对你有帮助，请给一个星标！