or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

account.mdadvanced.mdbatch.mdblockchain.mdcontracts.mdens.mdgas-fees.mdindex.mdsigning.mdtransactions.mdwatch.md
tile.json

tessl/npm-wagmi

React Hooks for Ethereum providing reactive primitives for wallet connections, smart contract interactions, and blockchain data

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/wagmi@2.16.x

To install, run

npx @tessl/cli install tessl/npm-wagmi@2.16.0

index.mddocs/

Wagmi

Wagmi is a React Hooks library for Ethereum that provides a collection of composable hooks for interacting with wallets, contracts, and blockchain data. It offers reactive primitives for wallet connections, smart contract interactions, and comprehensive blockchain data access with full TypeScript support.

Package Information

  • Package Name: wagmi
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install wagmi viem @tanstack/react-query

Core Imports

import { 
  WagmiProvider, 
  useAccount, 
  useConnect, 
  useReadContract, 
  useSendTransaction 
} from "wagmi";
import { createConfig, http } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";

For actions (imperative API):

import { connect, disconnect, readContract } from "wagmi/actions";

For connectors:

import { metaMask, walletConnect, coinbaseWallet } from "wagmi/connectors";

For query utilities:

import { useQuery, useMutation, useInfiniteQuery } from "wagmi/query";

For experimental features:

import { useCallsStatus, useSendCalls } from "wagmi/experimental";

For code generation:

import { createUseReadContract, createUseWriteContract } from "wagmi/codegen";

Basic Usage

import { WagmiProvider, createConfig, http, useAccount, useConnect } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { metaMask, walletConnect } from "wagmi/connectors";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// 1. Create wagmi config
const config = createConfig({
  chains: [mainnet, sepolia],
  connectors: [
    metaMask(),
    walletConnect({ projectId: "YOUR_PROJECT_ID" }),
  ],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
});

// 2. Create query client
const queryClient = new QueryClient();

// 3. Wrap app with providers
function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <ConnectWallet />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

// 4. Use wagmi hooks
function ConnectWallet() {
  const { address, isConnected } = useAccount();
  const { connect, connectors } = useConnect();

  if (isConnected) {
    return <div>Connected to {address}</div>;
  }

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

Architecture

Wagmi is built around several key architectural components:

  • Configuration System: Centralized config with chains, connectors, and transports
  • React Context: WagmiProvider manages global state and configuration access
  • TanStack Query Integration: Built-in caching, background refetching, and optimistic updates
  • Type Safety: Full TypeScript support with generic types preserving chain and connector information
  • Connector System: Pluggable wallet connection interfaces (MetaMask, WalletConnect, etc.)
  • Transport Layer: Configurable RPC transports for different chains using Viem
  • Hydration Support: SSR/SSG compatibility with initial state management

Capabilities

Account Management

Wallet connection, disconnection, and account switching functionality with full connector lifecycle management.

function useAccount<config = Config>(
  parameters?: UseAccountParameters<config>
): UseAccountReturnType<config>;

function useConnect<config = Config, context = unknown>(
  parameters?: UseConnectParameters<config, context>
): UseConnectReturnType<config, context>;

function useDisconnect<config = Config, context = unknown>(
  parameters?: UseDisconnectParameters<config, context>
): UseDisconnectReturnType<config, context>;

Account Management

Blockchain Data

Access to blocks, chain information, balances, and general blockchain state with real-time updates.

function useBlockNumber<config = Config, selectData = UseBlockNumberReturnType>(
  parameters?: UseBlockNumberParameters<config, selectData>
): UseBlockNumberReturnType<selectData>;

function useBalance<config = Config, selectData = UseBalanceReturnType>(
  parameters: UseBalanceParameters<config, selectData>
): UseBalanceReturnType<selectData>;

function useChainId<config = Config>(
  parameters?: UseChainIdParameters<config>
): UseChainIdReturnType<config>;

Blockchain Data

Smart Contracts

Contract interaction hooks for reading from and writing to smart contracts with full type safety.

function useReadContract<config = Config, selectData = UseReadContractReturnType>(
  parameters: UseReadContractParameters<config, selectData>
): UseReadContractReturnType<selectData>;

function useWriteContract<config = Config, context = unknown>(
  parameters?: UseWriteContractParameters<config, context>
): UseWriteContractReturnType<config, context>;

function useSimulateContract<config = Config, selectData = UseSimulateContractReturnType>(
  parameters: UseSimulateContractParameters<config, selectData>
): UseSimulateContractReturnType<selectData>;

Smart Contracts

ENS Integration

Ethereum Name Service functionality for resolving names, addresses, avatars, and text records.

function useEnsAddress<config = Config, selectData = UseEnsAddressReturnType>(
  parameters: UseEnsAddressParameters<config, selectData>
): UseEnsAddressReturnType<selectData>;

function useEnsName<config = Config, selectData = UseEnsNameReturnType>(
  parameters: UseEnsNameParameters<config, selectData>
): UseEnsNameReturnType<selectData>;

function useEnsAvatar<config = Config, selectData = UseEnsAvatarReturnType>(
  parameters: UseEnsAvatarParameters<config, selectData>
): UseEnsAvatarReturnType<selectData>;

ENS Integration

Transaction Management

Transaction lifecycle management including sending, monitoring, and receipt handling.

function useSendTransaction<config = Config, context = unknown>(
  parameters?: UseSendTransactionParameters<config, context>
): UseSendTransactionReturnType<config, context>;

function useTransaction<config = Config, selectData = UseTransactionReturnType>(
  parameters: UseTransactionParameters<config, selectData>
): UseTransactionReturnType<selectData>;

function useTransactionReceipt<config = Config, selectData = UseTransactionReceiptReturnType>(
  parameters: UseTransactionReceiptParameters<config, selectData>
): UseTransactionReceiptReturnType<selectData>;

Transaction Management

Gas & Fee Estimation

Gas price monitoring and transaction fee estimation with support for EIP-1559 fee markets.

function useEstimateGas<config = Config, selectData = UseEstimateGasReturnType>(
  parameters: UseEstimateGasParameters<config, selectData>
): UseEstimateGasReturnType<selectData>;

function useGasPrice<config = Config, selectData = UseGasPriceReturnType>(
  parameters?: UseGasPriceParameters<config, selectData>
): UseGasPriceReturnType<selectData>;

function useEstimateFeesPerGas<config = Config, selectData = UseEstimateFeesPerGasReturnType>(
  parameters?: UseEstimateFeesPerGasParameters<config, selectData>
): UseEstimateFeesPerGasReturnType<selectData>;

Gas & Fee Estimation

Message Signing & Verification

Cryptographic signing of messages and typed data with EIP-712 support for secure authentication.

function useSignMessage<config = Config, context = unknown>(
  parameters?: UseSignMessageParameters<config, context>
): UseSignMessageReturnType<config, context>;

function useSignTypedData<config = Config, context = unknown>(
  parameters?: UseSignTypedDataParameters<config, context>
): UseSignTypedDataReturnType<config, context>;

function useVerifyMessage<config = Config, selectData = UseVerifyMessageReturnType>(
  parameters: UseVerifyMessageParameters<config, selectData>
): UseVerifyMessageReturnType<selectData>;

Message Signing & Verification

Real-time Data Watching

Event listeners and watchers for real-time blockchain data updates and contract events.

function useWatchBlockNumber<config = Config>(
  parameters?: UseWatchBlockNumberParameters<config>
): UseWatchBlockNumberReturnType;

function useWatchContractEvent<config = Config>(
  parameters: UseWatchContractEventParameters<config>
): UseWatchContractEventReturnType;

function useWatchBlocks<config = Config>(
  parameters?: UseWatchBlocksParameters<config>
): UseWatchBlocksReturnType;

Real-time Data Watching

Atomic Batch Transactions

EIP-5792 atomic batch transaction support for executing multiple operations as a single unit.

function useSendCalls<config = Config, context = unknown>(
  parameters?: UseSendCallsParameters<config, context>
): UseSendCallsReturnType<config, context>;

function useCallsStatus<config = Config, selectData = UseCallsStatusReturnType>(
  parameters: UseCallsStatusParameters<config, selectData>
): UseCallsStatusReturnType<selectData>;

function useCapabilities<config = Config, selectData = UseCapabilitiesReturnType>(
  parameters?: UseCapabilitiesParameters<config, selectData>
): UseCapabilitiesReturnType<selectData>;

Atomic Batch Transactions

Advanced Features

Advanced functionality including proof generation, SSR hydration, and error handling.

function useProof<config = Config, selectData = UseProofReturnType>(
  parameters: UseProofParameters<config, selectData>
): UseProofReturnType<selectData>;

interface WagmiProviderProps {
  config: ResolvedRegister['config'];
  initialState?: State;
  reconnectOnMount?: boolean;
}

interface HydrateProps {
  config: ResolvedRegister['config'];
  initialState?: State;
  reconnectOnMount?: boolean;
}

Advanced Features

Core Types

type Config = {
  chains: readonly Chain[];
  connectors: Connector[];
  transports: Record<number, Transport>;
  state: State;
  storage?: Storage;
  ssr?: boolean;
  syncConnectedChain?: boolean;
  multiInjectedProviderDiscovery?: boolean;
};

interface State {
  chainId: number;
  connections: Map<string, Connection>;
  current?: string;
  status: 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
}

interface Connection {
  accounts: readonly Address[];
  chainId: number;
  connector: Connector;
}

interface UseAccountReturnType {
  address?: Address;
  addresses?: readonly Address[];
  chain?: Chain;
  chainId?: number;
  connector?: Connector;
  isConnected: boolean;
  isConnecting: boolean;
  isDisconnected: boolean;
  isReconnecting: boolean;
  status: 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
}

Deprecated Hook Aliases

Some hooks have deprecated aliases that are still available for backward compatibility:

// Provider aliases
WagmiContext (formerly Context)
WagmiProvider (formerly WagmiConfig)

// Hook aliases (deprecated - use new names)
useEstimateFeesPerGas (formerly useFeeData)
useInfiniteReadContracts (formerly useContractInfiniteReads)
useReadContract (formerly useContractRead)
useReadContracts (formerly useContractReads)
useWriteContract (formerly useContractWrite)
useToken (deprecated - use useReadContracts instead)