Getting Started ​

Overview ​

Wagmi is a React Hooks library for Ethereum. You can learn more about the rationale behind the project in the Why Wagmi section.

Automatic Installation ​

For new projects, it is recommended to set up your Wagmi app using the create-wagmi command line interface (CLI). This will create a new Wagmi project using TypeScript and install the required dependencies.

pnpm create wagmi

pnpm create wagmi

npm create wagmi@latest

npm create wagmi@latest

yarn create wagmi

yarn create wagmi

bun create wagmi

bun create wagmi

Once the command runs, you'll see some prompts to complete.

Project name: wagmi-project
Select a framework: React / Vanilla
...

Project name: wagmi-project
Select a framework: React / Vanilla
...

After the prompts, create-wagmi will create a directory with your project name and install the required dependencies. Check out the README.md for further instructions (if required).

Manual Installation ​

To manually add Wagmi to your project, install the required packages.

pnpm add wagmi viem@2.x @tanstack/react-query

pnpm add wagmi viem@2.x @tanstack/react-query

npm install wagmi viem@2.x @tanstack/react-query

npm install wagmi viem@2.x @tanstack/react-query

yarn add wagmi viem@2.x @tanstack/react-query

yarn add wagmi viem@2.x @tanstack/react-query

bun add wagmi viem@2.x @tanstack/react-query

bun add wagmi viem@2.x @tanstack/react-query

• Viem is a TypeScript interface for Ethereum that performs blockchain operations.
• TanStack Query is an async state manager that handles requests, caching, and more.
• TypeScript is optional, but highly recommended. Learn more about TypeScript support.

Create Config ​

Create and export a new Wagmi config using createConfig.

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

In this example, Wagmi is configured to use the Mainnet and Sepolia chains, and injected connector. Check out the createConfig docs for more configuration options.

ts
import { useBlockNumber } from 'wagmi'
 
useBlockNumber({ chainId: 123 })
Type '123' is not assignable to type '1 | 11155111 | undefined'.2322Type '123' is not assignable to type '1 | 11155111 | undefined'.
 
declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}

ts
import { useBlockNumber } from 'wagmi'
 
useBlockNumber({ chainId: 123 })
Type '123' is not assignable to type '1 | 11155111 | undefined'.2322Type '123' is not assignable to type '1 | 11155111 | undefined'.
 
declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}

ts
import { useBlockNumber } from 'wagmi'
 
useBlockNumber({ chainId: 123, config })
Type '123' is not assignable to type '1 | 11155111 | undefined'.2322Type '123' is not assignable to type '1 | 11155111 | undefined'.

ts
import { useBlockNumber } from 'wagmi'
 
useBlockNumber({ chainId: 123, config })
Type '123' is not assignable to type '1 | 11155111 | undefined'.2322Type '123' is not assignable to type '1 | 11155111 | undefined'.

Wrap App in Context Provider ​

Wrap your app in the WagmiProvider React Context Provider and pass the config you created earlier to the value property.

import { WagmiProvider } from 'wagmi' 
import { config } from './config' 

function App() {
  return (
    <WagmiProvider config={config}> 
      {/** ... */} 
    </WagmiProvider> 
  )
}

import { WagmiProvider } from 'wagmi' 
import { config } from './config' 

function App() {
  return (
    <WagmiProvider config={config}> 
      {/** ... */} 
    </WagmiProvider> 
  )
}

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Check out the WagmiProvider docs to learn more about React Context in Wagmi.

Setup TanStack Query ​

Inside the WagmiProvider, wrap your app in a TanStack Query React Context Provider, e.g. QueryClientProvider, and pass a new QueryClient instance to the client property.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query' 
import { WagmiProvider } from 'wagmi'
import { config } from './config'

const queryClient = new QueryClient() 

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}> 
        {/** ... */} 
      </QueryClientProvider> 
    </WagmiProvider>
  )
}

import { QueryClient, QueryClientProvider } from '@tanstack/react-query' 
import { WagmiProvider } from 'wagmi'
import { config } from './config'

const queryClient = new QueryClient() 

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}> 
        {/** ... */} 
      </QueryClientProvider> 
    </WagmiProvider>
  )
}

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Check out the TanStack Query docs to learn about the library, APIs, and more.

Use Wagmi ​

Now that everything is set up, every component inside the Wagmi and TanStack Query Providers can use Wagmi React Hooks.

import { useAccount, useEnsName } from 'wagmi'

function Profile() {
  const { address } = useAccount()
  const { data, error, status } = useEnsName({ address })
  if (status === 'pending') return <div>Loading ENS name</div>
  if (status === 'error')
    return <div>Error fetching ENS name: {error.message}</div>
  return <div>ENS name: {data}</div>
}

import { useAccount, useEnsName } from 'wagmi'

function Profile() {
  const { address } = useAccount()
  const { data, error, status } = useEnsName({ address })
  if (status === 'pending') return <div>Loading ENS name</div>
  if (status === 'error')
    return <div>Error fetching ENS name: {error.message}</div>
  return <div>ENS name: {data}</div>
}

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { WagmiProvider } from 'wagmi'
import { config } from './config'

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {/** ... */}
      </QueryClientProvider>
    </WagmiProvider>
  )
}

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { WagmiProvider } from 'wagmi'
import { config } from './config'

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {/** ... */}
      </QueryClientProvider>
    </WagmiProvider>
  )
}

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Next Steps ​

For more information on what to do next, check out the following topics.

• TypeScript Learn how to get the most out of Wagmi's type-safety and inference for an enlightened developer experience.
• Connect Wallet Learn how to enable wallets to connect to and disconnect from your apps and display information about connected accounts.
• React Hooks Browse the collection of React Hooks and learn how to use them.
• Viem Learn about Viem and how it works with Wagmi.