SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbtc-connect

btc-connect

Coding & development

View repository

Updated 10-16 00:30

About this skill

BTC-Connect Professional Integration Skill

Skill Overview

btc-connect is a wallet connection toolkit designed specifically for Bitcoin Web3 applications, providing a unified connection interface, event listening, and adapter layer. This skill supports complete integration of the latest version of btc-connect (v0.5.0+) in React, Vue, Next.js, and Nuxt 3 projects, enabling connection to UniSat and OKX wallets, network switching, state management, and resolving SSR environment compatibility issues.

Latest Features (v0.5.0): Unified Hook API design, intelligent theme detection system, comprehensive code quality optimization, improved type safety, enhanced build performance, complete test coverage.

Use Cases

Use this skill in the following situations:

  • Need to integrate Bitcoin wallet connection functionality in a React/Vue project
  • Need to configure btc-connect in a Next.js/Nuxt 3 SSR project
  • Need to implement Bitcoin network switching (mainnet/testnet/regtest)
  • Need to integrate UniSat or OKX wallet
  • Encountering btc-connect API integration or configuration issues
  • Need to troubleshoot wallet connection failures or SSR compatibility issues
  • Need to upgrade to the latest version of the btc-connect package (v0.4.0+)

Core Features

1. Dependency Installation and Version Management

  • Automatically install the latest versions of @btc-connect/core, @btc-connect/react, and @btc-connect/vue
  • Minimum version requirement v0.4.0+, automatically select the latest stable version
  • Version compatibility checking and intelligent validation
  • Dependency relationship validation and conflict resolution
  • Bun package manager optimization

2. Framework Integration Configuration

  • React project configuration and Hooks usage (Context Provider pattern)
  • Vue project configuration and Composables usage (plugin system)
  • Next.js SSR environment configuration (client component pattern)
  • Nuxt 3 SSR environment configuration (client plugin pattern)

3. 🆕 Network Switching Functionality (v0.3.11+)

  • Supports mainnet (livenet), testnet (testnet), and regtest (regtest)
  • UniSat wallet fully supports programmatic network switching
  • OKX wallet network switching guidance
  • Network change event listening and handling

4. Wallet Adapters and Enhanced Detection

  • UniSat wallet integration and complete API usage
  • OKX wallet integration and adapter handling
  • 🆕 Enhanced wallet detection mechanism (polling every 300ms for delayed injection within 20 seconds)
  • Wallet state management and event listening
  • Multi-wallet compatibility handling

5. Error Troubleshooting and Performance Optimization

  • Connection failure diagnosis and solutions
  • SSR environment issue troubleshooting and fixes
  • Version compatibility issue resolution
  • 🆕 Performance optimization (caching system, error handling, connection optimization)

Usage Workflow

1. Project Assessment and Environment Check

First check the project type and current environment:

  • Check the project framework type (React/Vue/Next.js/Nuxt 3)
  • Check existing dependencies and configuration (ensure no version conflicts)
  • Determine the SSR or CSR environment
  • Check Node.js version (requires >= 18) and Bun package manager

2. Dependency installation and version management

Install the corresponding packages according to the project type:

# 使用 Bun（推荐）
bun add @btc-connect/core @btc-connect/react  # React 项目
bun add @btc-connect/core @btc-connect/vue   # Vue 项目

# 或使用 npm
npm install @btc-connect/core @btc-connect/react

Version requirements：

  • @btc-connect/core: v0.4.0+ (automatically installs the latest version)
  • @btc-connect/react: v0.4.0+ (automatically installs the latest version)
  • @btc-connect/vue: v0.4.0+ (architecture-optimized version, automatically installs the latest version)

💡 Installation strategy: The installation script automatically selects the latest stable version, ensuring the minimum version requirement is v0.4.0+

3. Framework integration configuration

Configure according to the framework and environment:

React configuration：

  • Configure BTCWalletProvider to wrap the application
  • Use Hooks such as useWallet, useNetwork, useAccount, etc.
  • In SSR environments, use the 'use client' directive or dynamic imports

Vue configuration：

  • Configure the BTCWalletPlugin plugin system
  • Use Composables such as useWallet, useNetwork, useAccount, etc.
  • 🆕 v0.4.0+ unified API usage useWallet()

SSR environment configuration：

  • Next.js: client component pattern + dynamic imports
  • Nuxt 3: client plugin pattern + onMounted lifecycle

4. 🆕 Network switching feature configuration

Implement Bitcoin network switching:

// React Hook 使用
const { network, switchNetwork } = useNetwork()
await switchNetwork('testnet')  // 切换到测试网

// Vue Composable 使用
const { network, switchNetwork } = useNetwork()
await switchNetwork('mainnet')  // 切换到主网

Supported networks: livenet (mainnet), testnet (testnet), regtest (regression testnet)

5. Wallet integration and detection

Select and integrate the target wallet:

  • UniSat wallet: fully supports programmatic operations and network switching
  • OKX wallet: basic connection and signing, network switching requires manual operation
  • 🆕 Enhanced detection: automatically detects delayed-injected wallets (polling within 20 seconds)

6. Troubleshooting and performance optimization

If you encounter issues, troubleshoot according to the following steps:

  1. Check version compatibility (ensure you are using the latest version)
  2. Verify configuration files and framework integration
  3. Test wallet connection and network switching
  4. Check SSR environment error logs
  5. Check the caching system and performance optimization settings

Framework integration guide

React integration (latest version v0.4.0+)

  1. Install dependencies：@btc-connect/core + @btc-connect/react
  2. Configure Provider: Use BTCWalletProvider to wrap the application
  3. Use Hooks: useWallet, useNetwork, useAccount, useAutoConnect, etc.
  4. Network switching: Use the useNetwork Hook to implement network switching
  5. SSR note: Use the 'use client' directive or dynamic imports

Quick example：

'use client'
import { BTCWalletProvider, useWallet } from '@btc-connect/react'

function App() {
  return (
    <BTCWalletProvider>
      <WalletComponent />
    </BTCWalletProvider>
  )
}

function WalletComponent() {
  const { isConnected, connect, account, network } = useWallet()
  // 实现钱包连接逻辑
}

Vue integration (latest version v0.4.0+ architecture optimization)

  1. Install dependencies：@btc-connect/core + @btc-connect/vue (v0.4.0+)
  2. Configure plugin: Use BTCWalletPlugin
  3. 🆕 Unified API: Use useWallet() to get all features
  4. Component usage: ConnectButton, WalletModal, etc.
  5. Network switching: built-in network switching feature

Quick example：

<template>
  <div>
    <ConnectButton @connect="handleConnect" />
    <!-- v0.4.0+ 已集成模态框到 ConnectButton -->
  </div>
</template>

<script setup>
import { ConnectButton, useWallet } from '@btc-connect/vue'

const wallet = useWallet() // 🆕 统一 API
const handleConnect = (walletId) => {
  console.log('连接到钱包:', walletId)
}
</script>

Next.js SSR integration (fully compatible)

  1. Dynamic imports: wallet components must be dynamically imported
  2. Client components: Mark with the 'use client' directive
  3. State synchronization: Avoid SSR/client state mismatch
  4. Error boundary: Configure client-side error handling

Key configuration：

// components/WalletConnect.tsx
'use client'
import { useWallet } from '@btc-connect/react'

export default function WalletConnect() {
  const { connect, isConnected } = useWallet()
  // 钱包连接逻辑
}

// pages/index.tsx
import dynamic from 'next/dynamic'
const WalletConnect = dynamic(() => import('./WalletConnect'), {
  ssr: false
})

Nuxt 3 SSR integration (full support)

  1. Client plugin: Create a client-only plugin
  2. Lifecycle: Use onMounted to ensure client-side execution
  3. Runtime configuration: Configure client-side environment variables
  4. Component protection: Wrap with the ClientOnly component

Key configuration：

// plugins/btc-connect.client.ts
import { BTCWalletPlugin } from '@btc-connect/vue'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(BTCWalletPlugin)
})

<template>
  <ClientOnly>
    <ConnectButton />
  </ClientOnly>
</template>

Wallet-specific handling

UniSat wallet (full support)

  • ✅ Full programmatic network switching: Supports mainnet, testnet, and regtest
  • ✅ Full API support: Message signing, PSBT signing, Bitcoin sending
  • ✅ Complete event listening: Account changes, network changes, connection status
  • ✅ Enhanced detection mechanism: Automatic detection of delayed injection (polling within 20 seconds)
  • ✅ Performance optimization: Caching system, error handling, connection optimization

Network switching example：

// 完全支持程序化切换
await switchNetwork('testnet')  // 立即切换到测试网
await switchNetwork('mainnet')  // 立即切换到主网

OKX wallet (partial support)

  • ⚠️ Limited network switching: Usually requires the user to switch manually in the wallet
  • ✅ Basic connection and signing: Supports wallet connection and basic signing functionality
  • ✅ Account management: Supports multiple accounts and balance queries
  • ⚠️ Special error handling: Requires error handling logic specific to OKX
  • ⚠️ User experience prompts: Requires guiding users to perform manual operations

Network switching guidance：

// OKX 钱包网络切换需要用户手动操作
try {
  await switchNetwork('testnet')
} catch (error) {
  // 提示用户在 OKX 钱包中手动切换网络
  console.log('请在 OKX 钱包中手动切换到测试网')
}

🆕 Detailed explanation of network switching functionality (v0.3.11+)

Supported network types

  • livenet/mainnet: Bitcoin mainnet
  • testnet: Bitcoin testnet
  • regtest: Regtest

Core package network switching

import { BTCWalletManager } from '@btc-connect/core'

const manager = new BTCWalletManager()
await manager.switchNetwork('testnet')

// 监听网络变化
manager.on('networkChange', ({ walletId, network }) => {
  console.log(`钱包 ${walletId} 切换到 ${network} 网络`)
})

React Hook network switching

import { useNetwork } from '@btc-connect/react'

function NetworkSwitcher() {
  const { network, switchNetwork, isSwitching } = useNetwork()

  const handleSwitch = async () => {
    try {
      await switchNetwork('mainnet')
      console.log('切换到主网成功')
    } catch (error) {
      console.error('切换失败:', error.message)
    }
  }

  return (
    <div>
      <p>当前网络: {network}</p>
      <button onClick={handleSwitch} disabled={isSwitching}>
        {isSwitching ? '切换中...' : '切换到主网'}
      </button>
    </div>
  )
}

Vue Composable network switching

<template>
  <div class="network-switcher">
    <p>当前网络: {{ network.name }}</p>
    <button @click="switchToTestnet" :disabled="isSwitching">
      {{ isSwitching ? '切换中...' : '切换到测试网' }}
    </button>
  </div>
</template>

<script setup>
import { useNetwork } from '@btc-connect/vue'

const { network, switchNetwork, isSwitching } = useNetwork()

const switchToTestnet = async () => {
  try {
    await switchNetwork('testnet')
  } catch (error) {
    console.error('切换失败:', error.message)
  }
}
</script>

Troubleshooting common issues

Connection issues

  • Wallet detection failure: Check whether the wallet is correctly installed and enabled
  • Delayed injection handling: Use the enhanced detection mechanism (poll every 300ms within 20 seconds)
  • User cancels connection: Correctly handle the case where the user cancels the connection
  • Network permissions: Ensure the wallet has permission to access the target network

SSR issues

  • Dynamic import: Use dynamic import to avoid server-side errors
  • Window object: Check the availability of the window object
  • State synchronization: Handle SSR/client state mismatch issues
  • Client plugin: Use a client-only plugin in Nuxt 3

Version compatibility issues

  • Version matching: Ensure the core, react, and vue package versions are compatible
  • API changes: Note the architectural changes in the Vue package in v0.4.0+
  • Type definitions: Configure correct TypeScript types
  • Dependency conflicts: Check for dependency version conflicts

Performance issues

  • Caching system: Use intelligent caching to improve performance
  • Connection optimization: Avoid unnecessary repeated connections
  • Event management: Properly clean up event listeners
  • Memory leaks: Check resource cleanup when components are unmounted

Best practices

  1. Version consistency: Use the installation script to automatically install the latest version and ensure the minimum version requirements (core v0.4.0+, vue v0.4.0+)
  2. Error handling: Implement complete error handling and user feedback mechanisms
  3. State management: Correctly handle wallet connection status and network status changes
  4. User experience: Provide clear status indicators and operation guidance
  5. Security: Verify the security of wallet connections and transaction requests
  6. Performance optimization: Use the caching system and enhanced detection mechanisms to optimize performance
  7. SSR compatibility: Correctly configure client components in SSR projects
  8. Network switching: Provide a suitable network switching experience for different wallets