Web3-Onboard

由 Blocknative 开发的钱包连接库，支持多种钱包和框架。

连接钱包

@web3-onboard/core

使用原生 Web3-Onboard API 连接钱包。此方法适用于原生 JS 或非 React 环境。

参数


// connectWallet() 无需参数

返回值


// 返回已连接钱包对象的数组
Array<{
  label: string;
  accounts: Array<{ address: string; ens?: { name?: string } }>;
  chains: Array<{ id: string; namespace: string; rpcUrl: string }>;
  // ...其他钱包信息
}>

示例


import Onboard from '@web3-onboard/core'
import BitGetWallet from '@web3-onboard/bitget'
import InjectedWallet from '@web3-onboard/injected-wallets'
 
const onboard = Onboard({
  wallets: [
    new BitGetWallet(),
    new InjectedWallet()
  ],
  chains: [
    {
      id: 1,
      token: 'ETH',
      label: 'Ethereum Mainnet',
      rpcUrl: 'https://api.pimlico.io/v2/1/rpc?apikey=YOUR_KEY',
    },
  ]
})
 
async function connectWallet() {
  const wallets = await onboard.connectWallet()
  console.log(wallets)
}
 
// 在你的 UI 中：
// <button onclick={connectWallet}>连接 Bitget 钱包</button>

Wallet Connect

@web3-onboard/react

Web3-Onboard 还为 React 应用提供了专用的 context 和 hooks，集成更简单。

参数


// useConnectWallet 无需参数

返回值


// useConnectWallet 返回 [state, connect, disconnect]
[
  {
    wallet: WalletState | null,
    connecting: boolean,
    // ...
  },
  connect: () => Promise<void>,
  disconnect: (wallet: WalletState) => Promise<void>
]

示例


import { useConnectWallet, Web3OnboardProvider, init } from '@web3-onboard/react'
import BitGetWallet from '@web3-onboard/bitget'
import InjectedWallet from '@web3-onboard/injected-wallets'
 
const reactOnBoard = init({
  wallets: [
    new BitGetWallet(),
    new InjectedWallet()
  ],
  chains: [
    {
      id: 1,
      token: 'ETH',
      label: 'Ethereum Mainnet',
      rpcUrl: 'https://api.pimlico.io/v2/1/rpc?apikey=YOUR_KEY',
    },
  ]
})
 
function ConnectDemo() {
  const [{ wallet, connecting }, connect, disconnect] = useConnectWallet()
  return (
    <button disabled={connecting} onClick={() => (wallet ? disconnect(wallet) : connect())}>
      {connecting ? '连接中' : wallet ? '断开连接' : '连接'}
    </button>
  )
}
 
function App() {
  return (
    <Web3OnboardProvider web3Onboard={reactOnBoard}>
      <ConnectDemo />
    </Web3OnboardProvider>
  )
}

Wallet Connect

管理网络

切换链

完整示例


import { useConnectWallet } from '@web3-onboard/react'
import { Button, Input } from 'antd'
import React from 'react'
 
function SwitchChainDemo() {
  const [{ wallet }] = useConnectWallet()
  const provider = wallet?.provider
  const [chainId, setChainId] = React.useState('0x1')
  const [result, setResult] = React.useState('')
  const [err, setErr] = React.useState('')
 
  async function handleSwitchChain() {
    setErr(''); setResult('')
    if (!provider) return setErr('没有提供者')
    try {
      await provider.request({
        method: 'wallet_switchEthereumChain',
        params: [{ chainId }],
      })
      setResult('已切换到链: ' + chainId)
    } catch (e) {
      setErr(e?.message || String(e))
    }
  }
 
  return (
    <div>
      <Input style={{ width: 200, marginRight: 8 }} value={chainId} onChange={e => setChainId(e.target.value)} placeholder="chainId (hex, 例如 0x1)" />
      <Button disabled={!provider} onClick={handleSwitchChain}>切换链</Button>
      {result && <div style={{ color: 'green' }}>{result}</div>}
      {err && <div style={{ color: 'red' }}>{err}</div>}
    </div>
  )
}

参数


interface SwitchChainParams {
  chainId: string // 十六进制字符串，例如 '0x1' 表示以太坊主网
}

返回值


// 成功时返回 null，失败时抛出错误
null

用法


await provider.request({
  method: 'wallet_switchEthereumChain',
  params: [{ chainId: '0x1' }],
})

试试看

Switch Chain

Ethereum Mainnet

添加链

示例


import { useConnectWallet } from '@web3-onboard/react'
import { Button, Input } from 'antd'
import React from 'react'
 
function AddChainDemo() {
  const [{ wallet }] = useConnectWallet()
  const provider = wallet?.provider
  const [addChainParams, setAddChainParams] = React.useState('')
  const [result, setResult] = React.useState('')
  const [err, setErr] = React.useState('')
 
  async function handleAddChain() {
    setErr(''); setResult('')
    if (!provider) return setErr('没有提供者')
    let params
    try {
      params = JSON.parse(addChainParams)
    } catch {
      setErr('链参数的 JSON 无效')
      return
    }
    try {
      await provider.request({
        method: 'wallet_addEthereumChain',
        params: [params],
      })
      setResult('已添加链: ' + params.chainId)
    } catch (e) {
      setErr(e?.message || String(e))
    }
  }
 
  return (
    <div>
      <Input style={{ width: 400, marginRight: 8 }} value={addChainParams} onChange={e => setAddChainParams(e.target.value)} placeholder='添加链参数 (JSON)' />
      <Button disabled={!provider} onClick={handleAddChain}>添加链</Button>
      {result && <div style={{ color: 'green' }}>{result}</div>}
      {err && <div style={{ color: 'red' }}>{err}</div>}
    </div>
  )
}

参数


interface AddChainParams {
  chainId: string
  chainName: string
  rpcUrls: string[]
  nativeCurrency: { name: string; symbol: string; decimals: number }
  blockExplorerUrls?: string[]
  iconUrls?: string[]
}

返回值


// 成功时返回 null，失败时抛出错误
null

用法


await provider.request({
  method: 'wallet_addEthereumChain',
  params: [chainParams],
})

试试看

Add Chain

Ethereum Mainnet

获取链 ID

完整示例


import { useConnectWallet } from '@web3-onboard/react'
import { Button } from 'antd'
import React from 'react'
 
function GetChainIdDemo() {
  const [{ wallet }] = useConnectWallet()
  const provider = wallet?.provider
  const [result, setResult] = React.useState('')
  const [err, setErr] = React.useState('')
 
  async function handleGetChainId() {
    setErr(''); setResult('')
    if (!provider) return setErr('没有提供者')
    try {
      const chainId = await provider.request({
        method: 'eth_chainId',
      })
      setResult('当前链 ID: ' + chainId)
    } catch (e) {
      setErr(e?.message || String(e))
    }
  }
 
  return (
    <div>
      <Button disabled={!provider} onClick={handleGetChainId}>获取链 ID</Button>
      {result && <div style={{ color: 'green', wordBreak: 'break-all' }}>{result}</div>}
      {err && <div style={{ color: 'red' }}>{err}</div>}
    </div>
  )
}

参数


// eth_chainId 无需参数
type GetChainIdParams = void

返回值


// 返回当前链 ID 作为十六进制字符串
string // 例如 '0x1'

用法


await provider.request({
  method: 'eth_chainId',
})

试试看

Get Chain ID

签消息

签名类型化数据

使用 eth_signTypedData_v4 签名 EIP-712 类型化数据。

参数


interface SignTypedDataParams {
  typedData: object // EIP-712 类型化数据对象（必须是有效的 JSON）
  address: string   // 用于签名的地址
}

返回值


// 返回签名字符串
type SignTypedDataResult = string // 例如 '0x...'

用法


await provider.request({
  method: 'eth_signTypedData_v4',
  params: [address, JSON.stringify(typedData)],
})

输入示例


{
  "types": {
    "EIP712Domain": [{"name": "name", "type": "string"}],
    "Person": [{"name": "name", "type": "string"}]
  },
  "primaryType": "Person",
  "domain": {"name": "Bitget"},
  "message": {"name": "Alice"}
}

试试看

Sign Typed Data

签名个人消息

使用 personal_sign 签名消息。

参数


interface SignPersonalMessageParams {
  message: string
  address: string
}

返回值


// 返回签名字符串
type SignPersonalMessageResult = string // 例如 '0x...'

用法


await provider.request({
  method: 'personal_sign',
  params: [message, address],
})

试试看

Sign Message

交易

查看余额

完整示例


import { useConnectWallet } from '@web3-onboard/react'
import { Button } from 'antd'
import React from 'react'
 
function GetBalanceDemo() {
  const [{ wallet }] = useConnectWallet()
  const provider = wallet?.provider
  const address = wallet?.accounts?.[0]?.address
  const [result, setResult] = React.useState('')
  const [err, setErr] = React.useState('')
 
  async function handleGetBalance() {
    setErr(''); setResult('')
    if (!provider || !address) return setErr('没有提供者或地址')
    try {
      const balance = await provider.request({
        method: 'eth_getBalance',
        params: [address, 'latest'],
      })
      setResult(balance)
    } catch (e) {
      setErr(e?.message || String(e))
    }
  }
 
  return (
    <div>
      <Button disabled={!provider || !address} onClick={handleGetBalance}>获取余额</Button>
      {result && <div style={{ color: 'green', wordBreak: 'break-all' }}>{result}</div>}
      {err && <div style={{ color: 'red' }}>{err}</div>}
    </div>
  )
}

参数


interface GetBalanceParams {
  address: string
  blockTag?: string // 例如 'latest'
}

返回值


// 返回余额作为十六进制字符串
string // 例如 '0x...' (wei)

用法


await provider.request({
  method: 'eth_getBalance',
  params: [address, 'latest'],
})

试试看

Get Balance

签名交易

示例


import { useConnectWallet } from '@web3-onboard/react'
import { Button, Input } from 'antd'
import React from 'react'
 
function SignTransactionDemo() {
  const [{ wallet }] = useConnectWallet()
  const provider = wallet?.provider
  const address = wallet?.accounts?.[0]?.address
  const [tx, setTx] = React.useState('{"to":"0x...","value":"0x0"}')
  const [result, setResult] = React.useState('')
  const [err, setErr] = React.useState('')
 
  async function handleSignTx() {
    setErr(''); setResult('')
    if (!provider || !address) return setErr('没有提供者或地址')
    let txObj
    try {
      txObj = JSON.parse(tx)
    } catch {
      setErr('交易的 JSON 无效')
      return
    }
    try {
      const sig = await provider.request({
        method: 'eth_signTransaction',
        params: [txObj],
      })
      setResult(sig)
    } catch (e) {
      setErr(e?.message || String(e))
    }
  }
 
  return (
    <div>
      <Input style={{ width: 400, marginRight: 8 }} value={tx} onChange={e => setTx(e.target.value)} placeholder='交易 JSON (to, value, ...)' />
      <Button disabled={!provider || !address} onClick={handleSignTx}>签名交易</Button>
      {result && <div style={{ color: 'green', wordBreak: 'break-all' }}>{result}</div>}
      {err && <div style={{ color: 'red' }}>{err}</div>}
    </div>
  )
}

参数


interface SignTransactionParams {
  to: string
  value: string // 十六进制字符串
  // ...其他交易字段 (gas, gasPrice, data, nonce, 等)
}

返回值


// 返回签名后的交易作为十六进制字符串
string // 例如 '0x...'

用法


await provider.request({
  method: 'eth_signTransaction',
  params: [txObj],
})

发送交易

示例


import { useConnectWallet } from '@web3-onboard/react'
import { Button, Input } from 'antd'
import React from 'react'
 
function SendTransactionDemo() {
  const [{ wallet }] = useConnectWallet()
  const provider = wallet?.provider
  const address = wallet?.accounts?.[0]?.address
  const [tx, setTx] = React.useState('{"to":"0x...","value":"0x0"}')
  const [result, setResult] = React.useState('')
  const [err, setErr] = React.useState('')
 
  async function handleSendTx() {
    setErr(''); setResult('')
    if (!provider || !address) return setErr('没有提供者或地址')
    let txObj
    try {
      txObj = JSON.parse(tx)
    } catch {
      setErr('交易的 JSON 无效')
      return
    }
    try {
      const txHash = await provider.request({
        method: 'eth_sendTransaction',
        params: [txObj],
      })
      setResult(txHash)
    } catch (e) {
      setErr(e?.message || String(e))
    }
  }
 
  return (
    <div>
      <Input style={{ width: 400, marginRight: 8 }} value={tx} onChange={e => setTx(e.target.value)} placeholder='交易 JSON (to, value, ...)' />
      <Button disabled={!provider || !address} onClick={handleSendTx}>发送交易</Button>
      {result && <div style={{ color: 'green', wordBreak: 'break-all' }}>{result}</div>}
      {err && <div style={{ color: 'red' }}>{err}</div>}
    </div>
  )
}

参数


interface SendTransactionParams {
  to: string
  value: string // 十六进制字符串
  // ...其他交易字段 (gas, gasPrice, data, nonce, 等)
}

返回值


// 返回交易哈希作为十六进制字符串
string // 例如 '0x...'

用法


await provider.request({
  method: 'eth_sendTransaction',
  params: [txObj],
})

Web3-Onboard

连接钱包

@web3-onboard/core

@web3-onboard/react

管理网络

切换链

添加链

获取链 ID

签消息

签名类型化数据

签名个人消息

交易

查看余额

签名交易

发送交易

API 参考