OnchainBaseKit

Universal blockchain wallet SDK supporting multiple chains and wallets.

支持的钱包 (Wallets)

• MetaMask - EVM chains (使用 wagmi.js，支持自动切换网络)
• Bitget - EVM, Solana, Tron
• OKX - EVM, Solana, Bitcoin, Tron
• Phantom - Solana, EVM
• TronLink - Tron
• Coinbase - EVM chains
• WalletConnect - EVM chains

支持的链 (Chains)

• Ethereum / ERC20
• Polygon
• Arbitrum One
• BNB Smart Chain (BSC) / BEP20
• Solana
• Tron / TRC20
• Bitcoin / BRC20 / Ordinals

安装 (Installation)

npm install onchain-base-kit
# or
yarn add onchain-base-kit
# or
pnpm add onchain-base-kit

快速开始 (Quick Start)

方式一：使用简化的 Modules API (推荐)

import { 
  connect, 
  getBalance, 
  transfer, 
  disconnect,
  onChainChanged,
  onAccountsChanged
} from 'onchain-base-kit/modules'

// 1. 连接钱包（自动切换到指定网络）
const { address, chain } = await connect('metamask', 'ethereum')
console.log('Connected address:', address)

// 2. 监听网络切换
onChainChanged((data) => {
  console.log('Chain changed to:', data.chainId)
})

// 3. 监听账户切换
onAccountsChanged((data) => {
  console.log('Account changed to:', data.address)
})

// 4. 获取余额 (支持代币符号，不区分大小写)
const balance = await getBalance({
  address,
  chain: 'ethereum',
  token: 'USDT' // 可选，不传则查询主币余额
})
console.log('Balance:', balance)

// 5. 转账
const result = await transfer({
  to: '0x...',
  amount: '100',
  tokenSymbol: 'USDT' // 可选，不传则转主币
})
console.log('TX Hash:', result.txHash)

// 6. 断开连接
await disconnect()

方式二：使用 SDK 实例

import { sdk } from 'onchain-base-kit'

// 1. 连接钱包
const result = await sdk.connect({
  wallet: 'metamask',
  chain: 'ethereum'
})

console.log('Connected address:', result.address)

// 2. 获取余额
const balance = await sdk.getBalance({
  address: result.address,
  chain: 'ethereum'
})

console.log('ETH Balance:', balance.balance)

// 3. 转账
const tx = await sdk.transfer({
  to: '0x...',
  amount: '0.01',
  chain: 'ethereum'
})

console.log('TX Hash:', tx.txHash)

// 4. 断开连接
await sdk.disconnect()

API 文档

详细的 API 文档请查看：docs/API.md

在线演示

访问在线演示应用，查看所有 API 的详细文档和在线调试功能：Demo Application

cd demo-app
npm install
npm run dev

打开浏览器访问 http://localhost:3000（Next.js 默认端口），你可以：

• 📚 查看完整的 API 文档
• 🎮 在线调试所有 API 方法
• 📊 实时查看输入参数和输出结果
• 🔔 监听钱包事件（账户切换、网络切换等）

架构设计

核心概念

1. Provider（钱包层）

   • 只负责连接钱包、返回 provider 实例
   • 不处理具体的链操作

2. Chain Adapter（区块链层）

   • 只负责具体的区块链操作（余额、转账、gas 费等）
   • 接收 provider 作为参数
   • 不关心 provider 来自哪个钱包

3. SDK 主类（统一封装）

   • 组合 Provider + Chain Adapter
   • 提供统一的 API 接口
   • 自动选择对应的实现

目录结构

onchain-base-kit/
├── src/
│   ├── types/           # 类型定义
│   │   ├── wallet.ts
│   │   ├── chain.ts
│   │   ├── transaction.ts
│   │   └── index.ts
│   ├── providers/       # 钱包 Provider
│   │   ├── base.ts
│   │   ├── metamask/
│   │   ├── bitget/
│   │   ├── okx/
│   │   ├── phantom/
│   │   ├── tronlink/
│   │   ├── coinbase/
│   │   └── index.ts
│   ├── chains/          # 链 Adapter
│   │   ├── ethereum/
│   │   ├── solana/
│   │   ├── tron/
│   │   ├── bitcoin/
│   │   └── index.ts
│   └── index.ts         # SDK 主类
├── docs/
│   └── API.md           # API 文档
├── demo-app/            # Next.js 演示应用
└── examples/            # 使用示例

使用示例

示例 1: MetaMask + Ethereum

import { sdk } from 'onchain-base-kit'

// 连接 MetaMask
const { address } = await sdk.connect({
  wallet: 'metamask',
  chain: 'ethereum'
})

// 获取 ETH 余额
const balance = await sdk.getBalance({
  address,
  chain: 'ethereum'
})

// 获取 ERC20 代币余额
const tokenBalance = await sdk.getBalance({
  address,
  chain: 'ethereum',
  tokenAddress: '0x...' // USDT 合约地址
})

// 估算 Gas Fee
const gasFee = await sdk.getGasFee({
  from: address,
  to: '0x...',
  amount: '0.01',
  chain: 'ethereum'
})

// 转账
const tx = await sdk.transfer({
  to: '0x...',
  amount: '0.01',
  chain: 'ethereum'
})

示例 2: Bitget + Solana

import { sdk } from 'onchain-base-kit'

// 连接 Bitget (Solana)
const { address } = await sdk.connect({
  wallet: 'bitget',
  chain: 'solana'
})

// 获取 SOL 余额
const balance = await sdk.getBalance({
  address,
  chain: 'solana'
})

// 转账 SOL
const tx = await sdk.transfer({
  to: 'xxx...',
  amount: '0.1',
  chain: 'solana'
})

示例 3: TronLink + Tron

import { sdk } from 'onchain-base-kit'

// 连接 TronLink
const { address } = await sdk.connect({
  wallet: 'tronlink',
  chain: 'tron'
})

// 获取 TRX 余额
const balance = await sdk.getBalance({
  address,
  chain: 'tron'
})

// 转账 TRC20
const tx = await sdk.transfer({
  to: 'Txxx...',
  amount: '10',
  chain: 'tron',
  tokenAddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t' // USDT
})

特性

✅ 多钱包支持 - 支持 7 种主流钱包
✅ 多链支持 - 支持 7 条主流区块链
✅ 统一 API - 所有钱包和链使用相同的 API
✅ TypeScript - 完整的类型定义
✅ 模块化 - Provider 和 Chain 完全解耦
✅ 易扩展 - 轻松添加新钱包或新链
✅ 自动切换网络 - MetaMask 连接时自动切换到目标网络
✅ 事件监听 - 监听账户切换、网络切换、断开连接
✅ 批量操作 - 支持批量查询余额、批量连接
✅ RPC 查询 - 余额查询无需连接钱包

开发

# 安装依赖
npm install

# 构建
npm run build

# 开发模式
npm run dev

# 运行演示
cd demo-app && npm run dev

License

MIT

贡献

欢迎提交 Issue 和 Pull Request！

相关链接

• API 文档
• 在线演示
• 使用示例