Wagmi SDK — Authentication

This page explains how to handle wallet connection and disconnection using wagmi hooks with the CROSSx connector.

Connect (sign in)

When connect() is called with the CROSSx connector, the OAuth sign-in flow is triggered automatically via signInWithCreate(). This means wallet creation and migration are also handled in a single step.

import { useConnect } from 'wagmi'

function ConnectButton() {
  const { connectors, connect, isPending } = useConnect()
  const crossx = connectors.find(c => c.id === 'crossx')

  return (
    <button
      disabled={isPending}
      onClick={() => connect({ connector: crossx! })}
    >
      {isPending ? 'Connecting...' : 'Connect with CROSSx'}
    </button>
  )
}

Disconnect (sign out)

import { useDisconnect } from 'wagmi'

function DisconnectButton() {
  const { disconnect } = useDisconnect()

  return <button onClick={() => disconnect()}>Disconnect</button>
}

Connection state

import { useAccount } from 'wagmi'

function AccountInfo() {
  const { address, isConnected, isConnecting, isDisconnected } = useAccount()

  if (isConnecting) return <p>Connecting...</p>
  if (isDisconnected) return <p>Not connected</p>

  return <p>Connected: {address}</p>
}

Multi-wallet selection

When a user has two or more wallets, the CROSSx connector automatically displays a wallet selector modal during connect(). The selected wallet becomes the active account in wagmi.

Wallet count	Behavior
1	Connects directly, no selector
2+	Shows wallet selector → selected wallet is `accounts[0]`
Cancel	Falls back to default wallet (index 0)

import { useAccount } from 'wagmi'

function App() {
  // address is the wallet selected during connect
  const { address } = useAccount()

  return <p>Active wallet: {address}</p>
}

The connector places the selected wallet first in the accounts array. Since wagmi treats accounts[0] as the active account, useAccount().address always reflects the user's choice.

Auto-reconnect

wagmi handles session persistence automatically. On page reload, if a previous CROSSx session exists, wagmi will attempt to reconnect via the connector's reconnect mechanism.

Connect with Other Wallets

When showConnectOtherWallets is enabled, the CROSSx login modal displays a "Connect with Other Wallets" button below the social login options. This allows users to connect external wallets (MetaMask, WalletConnect, etc.) from within the CROSSx login flow.

Setup

import { createCROSSxSDK } from '@nexus-cross/crossx-sdk-core'
import { createCROSSxConnector } from '@nexus-cross/crossx-sdk-wagmi'

const sdk = createCROSSxSDK({
  projectId: 'YOUR_PROJECT_ID',
  appName: 'My DApp',
  showConnectOtherWallets: true,  // Enable the button
})

How it works

User clicks the CROSSx connect button
Login modal shows Apple, Google, and "Connect with Other Wallets"
If the user clicks "Connect with Other Wallets":
- SDK emits connectExternalWallet event
- Connector converts the error to UserRejectedRequestError (silent disconnect)
- wagmi stays in disconnected state — no error shown to the user

Listen to the event

import { useEffect } from 'react'
import { useConnect } from 'wagmi'

function AuthSection() {
  const { connectors, connect, error: connectError } = useConnect()

  useEffect(() => {
    return sdk.on('connectExternalWallet', () => {
      // Open external wallet connector (e.g., MetaMask)
      const injected = connectors.find(c => c.id === 'injected')
      if (injected) connect({ connector: injected })
    })
  }, [connectors, connect])

  // Filter out UserRejectedRequestError from display
  const showError = connectError && connectError.name !== 'UserRejectedRequestError'

  return (
    <>
      <button onClick={() => {
        const crossx = connectors.find(c => c.id === 'crossx')
        if (crossx) connect({ connector: crossx })
      }}>
        Connect
      </button>
      {showError && <p className="error">{connectError.message}</p>}
    </>
  )
}

Error filtering

When the user clicks "Connect with Other Wallets", the connector throws a UserRejectedRequestError. Filter this from your error display:

const { error: connectError } = useConnect()

// Don't show UserRejectedRequestError to the user
{connectError && connectError.name !== 'UserRejectedRequestError' && (
  <div className="error">{connectError.message}</div>
)}

Multiple connectors

You can combine CROSSx with other connectors:

import { createConfig, http } from 'wagmi'
import { crossxConnector } from '@nexus-cross/crossx-sdk-wagmi'
import { injected } from 'wagmi/connectors'

export const config = createConfig({
  connectors: [
    crossxConnector({ projectId: 'YOUR_PROJECT_ID', appName: 'My DApp' }),
    injected(), // MetaMask, etc.
  ],
  chains: [crossChainMainnet],
  transports: { [crossChainMainnet.id]: http() },
})

function ConnectOptions() {
  const { connectors, connect } = useConnect()

  return (
    <div>
      {connectors.map((connector) => (
        <button key={connector.id} onClick={() => connect({ connector })}>
          {connector.name}
        </button>
      ))}
    </div>
  )
}