NEXUS

Hooks

Hooks are utility functions that help with modal control, wallet event subscription, smart contract interactions, and more.

useAppKit

This hook provides access to the core features of the SDK.

import { useAppKit } from '@to-nexus/sdk/react'

const appKit = useAppKit()

// Connect the user's wallet
function handleConnect() {
  appKit.connect()
}

Returns:

KeyTypeDescription
connect() => voidFunction to initiate wallet connection

useAppKitAccount

This hook gives access to account data and connection status.

import { useEffect } from 'react'
import { useAppKitAccount } from '@to-nexus/sdk/react'

/**
 * Debug component that displays all account-related information
 * from useAppKitAccount hook
 */
export function DebugAccountInfo() {
  // Destructure all available values from the hook
  const {
    allAccounts,     // Array of all connected accounts
    caipAddress,     // CAIP-10 formatted address
    address,         // Plain wallet address (EOA)
    isConnected,     // Connection status boolean
    embeddedWalletInfo, // Additional info for embedded wallet users
    status,          // Detailed connection/session status
    balance,         // Native token balance
    balanceSymbol,   // Symbol of the native token (e.g., CROSS)
    balanceLoading,  // Loading state for balance
    tokenBalance     // ERC-20 token balances
  } = useAppKitAccount()

  // Monitor and log changes in wallet connection status
  useEffect(() => {
    // Early return if wallet is not connected
    if (!isConnected) {
      console.log('Wallet not connected.')
      return
    }

    // Log basic wallet information
    console.log('Wallet connected.')
    console.log('▶ Address:', address)
    console.log('▶ CAIP Address:', caipAddress)
    console.log('▶ Status:', status)
    console.log('▶ All Accounts:', allAccounts)

    // Log balance information
    console.log('▶ Native Balance:', balance, balanceSymbol)
    console.log('▶ Balance Loading:', balanceLoading)
    console.log('▶ ERC-20 Token Balances:', tokenBalance)

    // Log embedded wallet specific information if available
    if (embeddedWalletInfo) {
      console.log('▶ Embedded Wallet Info:')
      console.log('- Auth Provider:', embeddedWalletInfo.authProvider)
      console.log('- Is Smart Account Deployed:', embeddedWalletInfo.isSmartAccountDeployed)
      console.log('- User Info:', embeddedWalletInfo.user)
      console.log('- Account Type:', embeddedWalletInfo.accountType)
    }
  }, [isConnected]) // Re-run effect when connection status changes
}

Returns:

KeyTypeDescription
isConnectedbooleanIndicates whether a wallet is currently connected
addressstring / undefinedThe connected wallet address (EOA)
caipAddressCaipAddress / undefinedCAIP-10 formatted address (e.g., eip155:1:0xabc...)
statusAccountControllerState['status']Connection/session status
balanceAccountControllerState['balance'] / undefinedNative token balance
balanceSymbolAccountControllerState['balanceSymbol'] / undefinedNative token symbol
balanceLoadingAccountControllerState['balanceLoading'] / undefinedWhether the native token balance is loading
tokenBalanceAccountControllerState['tokenBalance'] / undefinedList of ERC-20 token balances held by the user
allAccountsAccountType[]All session accounts (for multi-login scenarios)
embeddedWalletInfoobject / undefinedAvailable if the user is using an embedded wallet

embeddedWalletInfo Fields

KeyTypeDescription
userAccountControllerState['user']User metadata (e.g., name, email, etc).
authProviderAccountControllerState['socialProvider'] / 'email'Authentication method used.
accountTypeW3mFrameTypes.AccountType / undefinedAccount type (EOA or Smart Account).
isSmartAccountDeployedbooleanWhether the smart contract account is deployed on-chain.

useAppKitNetwork

This hook provides access to network data and methods.

import { useAppKitNetwork } from '@to-nexus/sdk/react'
import { crossMainnet, crossTestnet } from '@to-nexus/sdk/networks'

const { chainId, caipNetworkId, caipNetwork, switchNetwork } = useAppKitNetwork()

// Switch to testnet or mainnet based on env
async function handleSwitchNetwork() {
  try {
    const targetNetwork = import.meta.env['VITE_NODE_ENV'] === 'production'
      ? crossMainnet
      : crossTestnet

    await switchNetwork(targetNetwork)
    console.log(`Successfully switched to: ${targetNetwork.caipNetworkId}`)
  } catch (error) {
    console.error('Failed to switch network:', error)
  }
}

// Display current network info
console.log('Chain ID:', chainId)
console.log('CAIP Network ID:', caipNetworkId)

// Check and display detailed network info
if (caipNetwork) {
  const { chainNamespace, chainReference, name } = caipNetwork
  if (chainNamespace && chainReference) {
    console.log(`Current Network:`)
    console.log(`- CAIP Format: ${chainNamespace}:${chainReference}`)
    console.log(`- Network Name: ${name}`)
  }
}

Returns:

KeyTypeDescription
caipNetworkCaipNetwork / undefinedThe current active CAIP network object
chainIdnumber / string / undefinedThe current chain ID
caipNetworkIdCaipNetworkId / undefinedThe CAIP-formatted network ID
switchNetwork(network: AppKitNetwork) => voidFunction to switch between networks

useAppKitProvider

This hook gives access to the wallet provider.

import { useAppKitProvider, UniversalProvider } from '@to-nexus/sdk/react'

function WalletProviderInfo() {
  // Get all provider-related information
  const {
    walletProvider,    // The provider instance for RPC requests
    providerType,      // Current provider type (e.g., 'injected', 'walletconnect')
    isConnecting,      // Whether provider is in connecting state
    isConnected,       // Whether provider is connected
    chainId,           // Current chain ID
    accounts           // Available account addresses
  } = useAppKitProvider<UniversalProvider>('eip155')

  // Example: Making an RPC request
  async function handleProviderRequest() {
    try {
      // Check connection status
      if (!isConnected) {
        console.log('Provider not connected')
        return
      }

      // Log provider information
      console.log('Provider Type:', providerType)
      console.log('Chain ID:', chainId)
      console.log('Available Accounts:', accounts)

      // Make RPC request while handling connection state
      if (!isConnecting && walletProvider) {
        const balance = await walletProvider.request({
          method: 'eth_getBalance',
          params: [accounts[0], 'latest']
        })
        console.log('Account Balance:', balance)
      }
    } catch (error) {
      console.error('Provider request failed:', error)
    }
  }

Returns:

KeyTypeDescription
walletProvider`T extends UniversalProvider / undefinedThe wallet provider instance for making RPC requests to the connected wallet
providerTypestring / undefinedThe type identifier of the current provider (e.g., 'injected', 'walletconnect')
isConnectingbooleanIndicates whether the provider is currently in the process of connecting
isConnectedbooleanIndicates whether the provider is currently connected
chainIdnumber / undefinedThe current chain ID that the provider is connected to
accountsstring[]Array of account addresses available through the provider

© 2025 NEXUS Co., Ltd. All Rights Reserved.