Wallet Hooks

Overview

GweAI provides three specialized wallet hooks built on top of Dynamic SDK for comprehensive Web3 wallet functionality.

useComprehensiveWallet

Full-featured wallet with multi-wallet support, balance tracking, and transaction management

useAgwWallet

Production-ready wallet hook with embedded wallet support and 10+ token balances

useDynamicWallet

Lightweight wallet hook for basic wallet operations

useComprehensiveWallet

Comprehensive wallet hook using Dynamic SDK with multi-wallet support, balance tracking, and transaction management.

Import

import { useComprehensiveWallet } from '@/hooks/useComprehensiveWallet';

Usage

function MyComponent() {
  const {
    connected,
    address,
    balances,
    connect,
    disconnect,
    sendTransaction,
    sendToken,
    refreshBalances,
  } = useComprehensiveWallet();

  return (
    <div>
      {connected ? (
        <>
          <p>Address: {address}</p>
          <p>ETH Balance: {balances.eth}</p>
          <p>USDC Balance: {balances.usdc}</p>
          <button onClick={disconnect}>Disconnect</button>
        </>
      ) : (
        <button onClick={connect}>Connect Wallet</button>
      )}
    </div>
  );
}

Return Values

Connection State

connected

boolean

Whether wallet is connected and authenticated

isLoggedIn

boolean

Whether user is logged in via Dynamic

boolean

Whether wallet operation is in progress

error

string | null

Error message if operation failed

sdkHasLoaded

boolean

Whether Dynamic SDK has finished loading

Wallet Information

address

string | undefined

Connected wallet address (0x…)

primaryWallet

Wallet | null

Primary wallet object from Dynamic SDK

userWallets

Wallet[]

All connected wallets (multi-wallet support)

user

User | null

User profile from Dynamic

Network Information

chainId

number

Current chain ID (defaults to Base Sepolia: 84532)

chainName

string

Current chain name (e.g., “Base Sepolia”)

network

number

Network ID from Dynamic context

networkConfigurations

NetworkConfig[]

Available network configurations

Balances

balances

WalletBalance

Token balances object containing:

eth: ETH balance (18 decimals)
usdc: USDC balance (6 decimals)
btc: BTC balance (8 decimals)
totalUSD: Total portfolio value in USD

isRefreshing

boolean

Whether balances are currently being refreshed

getAllTokenBalances

() => TokenBalance[]

Returns array of all token balances with metadata

getTokenBalance

(tokenAddress: string, decimals?: number) => Promise<string>

Fetch balance for specific ERC20 token

Token Addresses

tokenAddresses

object

Token contract addresses:

USDC: 0xBEE08798a3634e29F47e3d277C9d11507D55F66a
BTC: 0xD8a6E3FCA403d79b6AD6216b60527F51cc967D39

tokens

object

Token configurations with decimals and metadata

Methods

connect()

Open Dynamic auth flow to connect wallet.

const { connect } = useComprehensiveWallet();

await connect();

disconnect()

Disconnect wallet and clear balances.

const { disconnect } = useComprehensiveWallet();

await disconnect();

sendTransaction()

Send ETH transaction.

params

TransactionParams

required

Transaction parameters

params.to

string

required

Recipient address

params.value

string

Amount in ETH (e.g., “0.1”)

params.data

string

Transaction data (hex)

params.gasLimit

string

Gas limit (hex)

Returns: Promise<{ hash: string }>

const { sendTransaction } = useComprehensiveWallet();

const result = await sendTransaction({
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  value: '0.1', // 0.1 ETH
});

console.log('Transaction hash:', result.hash);

sendToken()

Send ERC20 tokens.

params

SendTokenParams

required

Token transfer parameters

params.tokenAddress

string

required

Token contract address

params.to

string

required

Recipient address

params.amount

string

required

Amount to send (in token units)

params.decimals

number

Token decimals (defaults to 18)

Returns: Promise<{ hash: string }>

const { sendToken, tokenAddresses } = useComprehensiveWallet();

const result = await sendToken({
  tokenAddress: tokenAddresses.USDC,
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  amount: '100',
  decimals: 6,
});

signMessage()

Sign a message with the wallet.

message

string

required

Message to sign

Returns: Promise<string> - Signature

const { signMessage } = useComprehensiveWallet();

const signature = await signMessage('Hello, Web3!');
console.log('Signature:', signature);

refreshBalances()

Manually refresh all token balances.

const { refreshBalances } = useComprehensiveWallet();

await refreshBalances();

Balances are automatically refreshed every 10 seconds when wallet is connected.

Multi-Wallet Methods

switchWallet

(walletId: string) => Promise<void>

Switch to a different connected wallet

addWallet

() => Promise<void>

Open Dynamic’s add wallet flow

openAuthFlow

() => void

Manually open Dynamic authentication modal

TypeScript Types

interface WalletBalance {
  eth: string;
  usdc: string;
  btc: string;
  totalUSD: string;
}

interface TokenBalance {
  symbol: string;
  name: string;
  balance: string;
  decimals: number;
  address?: string;
}

interface TransactionParams {
  to: string;
  value?: string;
  data?: string;
  gasLimit?: string;
}

interface SendTokenParams {
  tokenAddress: string;
  to: string;
  amount: string;
  decimals?: number;
}

useAgwWallet

Production-ready wallet hook with embedded wallet support and 10+ token balances on Base Sepolia.

Import

import { useAgwWallet } from '@/hooks/usePrivyWallet';

Usage

function DepositPage() {
  const {
    connected,
    address,
    ethBalance,
    usdcBalance,
    btcBalance,
    signIn,
    signOut,
    sendTransaction,
    sendToken,
    refreshBalance,
  } = useAgwWallet();

  if (!connected) {
    return <button onClick={signIn}>Sign In</button>;
  }

  return (
    <div>
      <p>Address: {address}</p>
      <p>ETH: {ethBalance}</p>
      <p>USDC: {usdcBalance}</p>
      <p>BTC: {btcBalance}</p>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

Return Values

State

address

string | null

Connected wallet address

connected

boolean

Whether wallet is connected

boolean

Whether operation is in progress

error

null

Error state (always null, errors shown via toast)

string | null

User email from Dynamic profile

Token Balances

balance

string

ETH balance (alias for ethBalance)

ethBalance

string

ETH balance (18 decimals)

usdcBalance

string

USDC balance (6 decimals)

btcBalance

string

BTC balance (8 decimals)

solBalance

string

SOL balance (9 decimals)

bnbBalance

string

BNB balance (18 decimals)

xrpBalance

string

XRP balance (6 decimals)

tonBalance

string

TON balance (9 decimals)

avaxBalance

string

AVAX balance (18 decimals)

tronBalance

string

TRON balance (6 decimals)

cardanoBalance

string

CARDANO balance (6 decimals)

dogeBalance

string

DOGE balance (8 decimals)

Token Addresses

USDC_ADDRESS

string

0xBEE08798a3634e29F47e3d277C9d11507D55F66a

BTC_ADDRESS

string

0x7d9E31f5cCac4b9c8566f343A6bD6f3263DFcC91

SOL_ADDRESS

string

0x241ECE6Dce0E0825F9992410B3fA5d4b8fC8d199

BNB_ADDRESS

string

0xAA9Be1a8A7f7254C1759bAa7e0f7864579c33a96

XRP_ADDRESS

string

0x01E278B5421AAC93A206C15b2933419DA19E17b3

TON_ADDRESS

string

0xC85D84a1092b81aCBA9bC75fad6063a7DA642E36

AVAX_ADDRESS

string

0x5DC449E37b6DAAD182d4Fb13C8dFE53C383C2E46

TRON_ADDRESS

string

0x45442ecB66A1a10c0F9817fb7F2B50a3bB99bd69

CARDANO_ADDRESS

string

0xcB1A4c81E7a56cbE2246DA3aE256Ba0154940648

DOGE_ADDRESS

string

0x803aD69f487536Ec1eE8a83Cd329e3d1703f8337

Methods

Open Dynamic login modal to create embedded wallet.

const { signIn } = useAgwWallet();

await signIn();

signOut() / disconnect()

Logout and clear wallet data.

const { signOut } = useAgwWallet();

await signOut();

disconnect() is an alias for signOut().

refreshBalance()

Refresh all token balances (ETH + 10 tokens).

const { refreshBalance } = useAgwWallet();

await refreshBalance();

getAddress()

Get current wallet address. Returns: string | null

const { getAddress } = useAgwWallet();

const address = getAddress();

sendTransaction()

Send ETH transaction with optional contract data.

string

required

Recipient address

value

string

required

Amount in ETH

tokenType

'ETH' | 'USDC'

Token type (defaults to ‘ETH’)

data

string

Contract call data (hex)

skipSave

boolean

Skip saving transaction to localStorage

Returns: Promise<{ hash: string, receipt: TransactionReceipt }>

const { sendTransaction } = useAgwWallet();

const result = await sendTransaction(
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  '0.05', // 0.05 ETH
  'ETH'
);

console.log('TX Hash:', result.hash);
console.log('Receipt:', result.receipt);

sendToken()

Send ERC20 tokens with automatic transaction encoding.

tokenAddress

string

required

Token contract address

string

required

Recipient address

amount

string

required

Amount to send

decimals

number

Token decimals (defaults to 6)

Returns: Promise<{ hash: string, receipt: TransactionReceipt }>

const { sendToken, USDC_ADDRESS } = useAgwWallet();

const result = await sendToken(
  USDC_ADDRESS,
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  '100', // 100 USDC
  6
);

addPasskey()

Open Dynamic user profile to add passkey MFA.

const { addPasskey } = useAgwWallet();

await addPasskey();

Requires wallet to be connected. Shows warning toast if not connected.

exportPrivateKey()

Open Dynamic settings to export private key.

const { exportPrivateKey } = useAgwWallet();

await exportPrivateKey();

Requires MFA/Passkey setup in Dynamic dashboard. Users must add passkey before exporting.

Supported Tokens

export const SUPPORTED_TOKENS = {
  BTC: { address: '0x7d9E31f5cCac4b9c8566f343A6bD6f3263DFcC91', decimals: 8, symbol: 'BTC', name: 'Bitcoin' },
  SOL: { address: '0x241ECE6Dce0E0825F9992410B3fA5d4b8fC8d199', decimals: 9, symbol: 'SOL', name: 'Solana' },
  BNB: { address: '0xAA9Be1a8A7f7254C1759bAa7e0f7864579c33a96', decimals: 18, symbol: 'BNB', name: 'BNB' },
  XRP: { address: '0x01E278B5421AAC93A206C15b2933419DA19E17b3', decimals: 6, symbol: 'XRP', name: 'Ripple' },
  TON: { address: '0xC85D84a1092b81aCBA9bC75fad6063a7DA642E36', decimals: 9, symbol: 'TON', name: 'Toncoin' },
  AVAX: { address: '0x5DC449E37b6DAAD182d4Fb13C8dFE53C383C2E46', decimals: 18, symbol: 'AVAX', name: 'Avalanche' },
  TRON: { address: '0x45442ecB66A1a10c0F9817fb7F2B50a3bB99bd69', decimals: 6, symbol: 'TRON', name: 'Tron' },
  CARDANO: { address: '0xcB1A4c81E7a56cbE2246DA3aE256Ba0154940648', decimals: 6, symbol: 'CARDANO', name: 'Cardano' },
  DOGE: { address: '0x803aD69f487536Ec1eE8a83Cd329e3d1703f8337', decimals: 8, symbol: 'DOGE', name: 'Dogecoin' },
  USDC: { address: '0xBEE08798a3634e29F47e3d277C9d11507D55F66a', decimals: 6, symbol: 'USDC', name: 'USD Coin' },
};

Performance Optimizations

Wallet Client Caching

The hook caches the wallet client to avoid repeated async calls:

// Wallet client is preloaded when wallet connects
useEffect(() => {
  if (primaryWallet) {
    primaryWallet.getWalletClient?.().then((client) => {
      walletClientRef.current = client;
    });
  }
}, [primaryWallet]);

Parallel Balance Fetching

All token balances are fetched in parallel with Promise.allSettled:

const [ethBal, usdcData, btcData, ...] = await Promise.allSettled([
  fetchEthBalance(),
  fetchTokenBalance(USDC_ADDRESS),
  fetchTokenBalance(BTC_ADDRESS),
  // ... all other tokens
]);

Request Timeout Protection

10-second timeout prevents hanging requests:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);

useDynamicWallet

Lightweight wallet hook for basic wallet operations.

Import

import { useDynamicWallet } from '@/hooks/usePrivyWallet';

Usage

function SimpleWallet() {
  const {
    isConnected,
    address,
    connect,
    disconnect,
    getBalance,
    send,
  } = useDynamicWallet();

  return (
    <div>
      {isConnected ? (
        <>
          <p>{address}</p>
          <button onClick={disconnect}>Disconnect</button>
        </>
      ) : (
        <button onClick={connect}>Connect</button>
      )}
    </div>
  );
}

Return Values

isReady

boolean

Always true (hook is ready)

isConnected

boolean

Whether wallet is connected

address

string | undefined

Connected wallet address

user

User | null

User profile from Dynamic

chainId

number

Base Sepolia chain ID (84532)

chainName

string

“Base Sepolia”

primaryWallet

Wallet | null

Primary wallet object

Methods

connect()

const { connect } = useDynamicWallet();
await connect();

disconnect()

Disconnects with 2-second timeout for faster UX.

const { disconnect } = useDynamicWallet();
await disconnect();

getBalance()

Fetch ETH balance. Returns: Promise<string>

const { getBalance } = useDynamicWallet();

const balance = await getBalance();
console.log('Balance:', balance, 'ETH');

send()

Send ETH transaction.

string

required

Recipient address

amount

string

required

Amount in ETH

Returns: Promise<{ hash: string }>

const { send } = useDynamicWallet();

const result = await send(
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  '0.01'
);

Hook Comparison

useComprehensiveWallet
useAgwWallet
useDynamicWallet

Best for: Full-featured applications requiring multi-wallet supportFeatures:

Multi-wallet management
Auto-refreshing balances (10s interval)
Token balance tracking (ETH, USDC, BTC)
Message signing
Network switching
Comprehensive error handling

Use cases:

DeFi dashboards
Portfolio trackers
Multi-chain applications

Common Patterns

Send USDC Transaction

const { sendToken, tokenAddresses } = useComprehensiveWallet();

const result = await sendToken({
  tokenAddress: tokenAddresses.USDC,
  to: recipientAddress,
  amount: '100',
  decimals: 6,
});

Check Multiple Balances

const { getAllTokenBalances } = useComprehensiveWallet();

const balances = getAllTokenBalances();
balances.forEach(token => {
  console.log(`${token.symbol}: ${token.balance}`);
});

Handle Transaction Errors

const { sendTransaction } = useAgwWallet();

try {
  const result = await sendTransaction(to, amount, 'ETH');
  console.log('Success:', result.hash);
} catch (error) {
  // Error automatically shown via toast
  console.error('Transaction failed:', error);
}

Multi-Wallet Support

const { userWallets, switchWallet, addWallet } = useComprehensiveWallet();

// List all wallets
userWallets.forEach(wallet => {
  console.log(wallet.address);
});

// Switch to different wallet
await switchWallet(walletId);

// Add new wallet
await addWallet();

TypeScript Support

All hooks are fully typed with TypeScript:

import type { ComprehensiveWallet } from '@/hooks/useComprehensiveWallet';
import type { TokenBalance, WalletBalance } from '@/hooks/useComprehensiveWallet';

const wallet: ComprehensiveWallet = useComprehensiveWallet();

File Locations

// Source: Frontend/Landingpage/src/hooks/useComprehensiveWallet.ts

Blockchain Integration

AI Services

Wallet & Auth

​Overview

useComprehensiveWallet

useAgwWallet

useDynamicWallet

​useComprehensiveWallet

​Import

​Usage

​Return Values

​Connection State

​Wallet Information

​Network Information

​Balances

​Token Addresses

​Methods

​connect()

​disconnect()

​sendTransaction()

​sendToken()

​signMessage()

​refreshBalances()

​Multi-Wallet Methods

​TypeScript Types

​useAgwWallet

​Import

​Usage

​Return Values

​State

​Token Balances

​Token Addresses

​Methods

​signIn()

​signOut() / disconnect()

​refreshBalance()

​getAddress()

​sendTransaction()

​sendToken()

​addPasskey()

​exportPrivateKey()

​Supported Tokens

​Performance Optimizations

​useDynamicWallet

​Import

​Usage

​Return Values

​Methods

​connect()

​disconnect()

​getBalance()

​send()

​Hook Comparison

​Common Patterns

​Send USDC Transaction

​Check Multiple Balances

​Handle Transaction Errors

​Multi-Wallet Support

​TypeScript Support

​File Locations

Build docs developers (and LLMs) love

Overview

useComprehensiveWallet

Import

Usage

Return Values

Connection State

Wallet Information

Network Information

Balances

Token Addresses

Methods

connect()

disconnect()

sendTransaction()

sendToken()

signMessage()

refreshBalances()

Multi-Wallet Methods

TypeScript Types

useAgwWallet

Import

Usage

Return Values

State

Token Balances

Token Addresses

Methods

signIn()

signOut() / disconnect()

refreshBalance()

getAddress()

sendTransaction()

sendToken()

addPasskey()

exportPrivateKey()

Supported Tokens

Performance Optimizations

useDynamicWallet

Import

Usage

Return Values

Methods

connect()

disconnect()

getBalance()

send()

Hook Comparison

Common Patterns

Send USDC Transaction

Check Multiple Balances

Handle Transaction Errors

Multi-Wallet Support

TypeScript Support

File Locations