@weracle/wallet-connect-bnb/README.md

Web3 wallet connection library for BNB Chain with Capacitor support

# @weracle/wallet-connect-bnb

🔗 **Web3 wallet connection library for BNB Chain with Capacitor support**

A TypeScript library that provides seamless wallet connectivity for BNB Chain (BSC) applications, supporting both web browsers and mobile apps built with Capacitor.

## ✨ Features

- 🌐 **Multi-Platform Support**: Works in web browsers and Capacitor mobile apps
- 🔐 **Multiple Wallet Support**: MetaMask, Binance Wallet, Trust Wallet, and WalletConnect v2
- 📱 **Mobile-First**: Optimized for mobile apps with WalletConnect integration
- ⚡ **BNB Chain Ready**: Pre-configured for BNB Mainnet and Testnet
- 🔄 **Auto-Detection**: Automatically detects environment and available wallets
- 📦 **TypeScript**: Full TypeScript support with type definitions
- 🎯 **Simple API**: Easy-to-use interface for common wallet operations

## 📦 Installation

```bash
npm install @weracle/wallet-connect-bnb
```

or

```bash
yarn add @weracle/wallet-connect-bnb
```

## 🚀 Quick Start

### Web Application

```typescript
import { WalletConnectBNB } from '@weracle/wallet-connect-bnb';

// Initialize
const wallet = new WalletConnectBNB({
  defaultChain: '0x38', // BNB Mainnet
  autoConnect: true,
});

// Connect wallet
const walletInfo = await wallet.connect();
console.log('Connected:', walletInfo.address);

// Send transaction
const txHash = await wallet.sendTransaction({
  to: '0x...',
  value: '0x38d7ea4c68000', // 0.001 BNB in wei
});

// Sign message
const signature = await wallet.signMessage('Hello BNB Chain!');
```

### Capacitor Mobile App

```typescript
import { WalletConnectBNB } from '@weracle/wallet-connect-bnb';

const wallet = new WalletConnectBNB({
  projectId: 'YOUR_WALLETCONNECT_PROJECT_ID', // Required for mobile
  defaultChain: '0x38',
  metadata: {
    name: 'My DApp',
    description: 'BNB Chain DApp',
    url: 'https://mydapp.com',
    icons: ['https://mydapp.com/icon.png'],
  },
});

// Connect using WalletConnect
const walletInfo = await wallet.connect({
  showQrModal: true,
});
```

## 📖 API Reference

### Constructor Options

```typescript
interface WalletConnectConfig {
  chains?: ChainConfig[];        // Supported chains (default: BNB Mainnet)
  defaultChain?: string;          // Default chain ID (default: '0x38')
  projectId?: string;             // WalletConnect project ID (required for mobile)
  metadata?: {                    // App metadata for WalletConnect
    name: string;
    description: string;
    url: string;
    icons: string[];
  };
  autoConnect?: boolean;          // Auto-reconnect on init (default: false)
}
```

### Methods

#### `connect(options?: ConnectOptions): Promise<WalletInfo>`
Connect to a wallet.

```typescript
const walletInfo = await wallet.connect({
  chainId: '0x38',          // Target chain
  showQrModal: true,        // Show WalletConnect QR modal
});
```

#### `disconnect(): Promise<void>`
Disconnect the wallet.

```typescript
await wallet.disconnect();
```

#### `sendTransaction(tx: TransactionRequest): Promise<string>`
Send a transaction.

```typescript
const txHash = await wallet.sendTransaction({
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEDb',
  value: '0x38d7ea4c68000', // 0.001 BNB in wei
  data: '0x',               // Optional: contract call data
});
```

#### `signMessage(message: string): Promise<string>`
Sign a message.

```typescript
const signature = await wallet.signMessage('Hello BNB Chain!');
```

#### `switchChain(chainId: string): Promise<void>`
Switch to a different chain.

```typescript
await wallet.switchChain('0x61'); // Switch to BNB Testnet
```

#### `getAccount(): Promise<string | null>`
Get the connected account address.

```typescript
const address = await wallet.getAccount();
```

#### `getChainId(): Promise<string | null>`
Get the current chain ID.

```typescript
const chainId = await wallet.getChainId();
```

#### `isConnected(): boolean`
Check if a wallet is connected.

```typescript
if (wallet.isConnected()) {
  // Wallet is connected
}
```

### Events

The library extends EventEmitter and provides these events:

```typescript
wallet.on('connect', (walletInfo) => {
  console.log('Connected:', walletInfo);
});

wallet.on('disconnect', () => {
  console.log('Disconnected');
});

wallet.on('chainChanged', (chainId) => {
  console.log('Chain changed:', chainId);
});

wallet.on('accountsChanged', (accounts) => {
  console.log('Account changed:', accounts[0]);
});

wallet.on('error', (error) => {
  console.error('Error:', error);
});
```

## 🔗 Supported Chains

| Chain | Chain ID | Hex ID |
|-------|----------|--------|
| BNB Smart Chain Mainnet | 56 | 0x38 |
| BNB Smart Chain Testnet | 97 | 0x61 |

## 🏗️ WalletConnect Setup

For mobile apps using WalletConnect, you need a project ID:

1. Go to [WalletConnect Cloud](https://cloud.walletconnect.com)
2. Create a new project
3. Copy your project ID
4. Use it in your configuration:

```typescript
const wallet = new WalletConnectBNB({
  projectId: 'YOUR_PROJECT_ID_HERE',
});
```

## 📱 Capacitor Configuration

For Capacitor apps, ensure you have the required plugins:

```bash
npm install @capacitor/app @capacitor/browser
```

Add deep link support in your `capacitor.config.json`:

```json
{
  "appId": "com.yourcompany.app",
  "appName": "Your App",
  "plugins": {
    "App": {
      "iosScheme": "yourapp",
      "androidScheme": "yourapp"
    }
  }
}
```

## 🛠️ Development

### Build the library

```bash
npm run build
```

### Run in development mode

```bash
npm run dev
```

### Run tests

```bash
npm test
```

## 📝 Examples

Check the `examples` folder for:
- Web application example
- Capacitor mobile app example

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🔧 Troubleshooting

### "No wallet found" error
- Make sure MetaMask or another Web3 wallet is installed
- For mobile apps, ensure WalletConnect is properly configured

### WalletConnect not working on mobile
- Verify your project ID is correct
- Check that deep links are properly configured in Capacitor
- Ensure the wallet app (MetaMask Mobile, Trust Wallet) is installed

### Chain switching fails
- The wallet may not have the BNB Chain network added
- The library will attempt to add it automatically, but user approval is required

## 📞 Support

For issues and questions:
- [GitHub Issues](https://github.com/miner/wallet-connect-bnb/issues)
- [Documentation](https://github.com/miner/wallet-connect-bnb#readme)

---

Made with ❤️ for the BNB Chain ecosystem