OnchainKit automatically sets up Wagmi and TanStack Query providers for you. However, you can provide your own custom Wagmi configuration for advanced use cases like custom connectors, chains, or storage options.

​
Default Setup

By default, OnchainKitProvider handles all the provider setup internally: 
<OnchainKitProvider
  apiKey={process.env.NEXT_PUBLIC_ONCHAINKIT_API_KEY}
  chain={base}
>
  {children}
</OnchainKitProvider>
This automatically includes:
  • Wagmi configuration with Coinbase Wallet connector
  • TanStack Query client for caching
  • Optimized defaults for most applications

​
Custom Wagmi Configuration

For advanced control over wallet connectors, chains, or other Wagmi settings, wrap OnchainKitProvider with your own Wagmi providers: 
import { http, cookieStorage, createConfig, createStorage } from 'wagmi';
import { base, baseSepolia } from 'viem/chains';
import { coinbaseWallet, metaMask } from 'wagmi/connectors';

export function getConfig() {
  return createConfig({
    chains: [base, baseSepolia],
    connectors: [
      coinbaseWallet({
        appName: 'My OnchainKit App',
        preference: 'smartWalletOnly',
        version: '4',
      }),
      metaMask(), // Add additional connectors
    ],
    storage: createStorage({
      storage: cookieStorage,
    }),
    ssr: true,
    transports: {
      [base.id]: http(),
      [baseSepolia.id]: http(),
    },
  });
}

declare module 'wagmi' {
  interface Register {
    config: ReturnType<typeof getConfig>;
  }
}

​
When to Use Custom Configuration

Consider custom Wagmi configuration when you need:
  • Multiple chains beyond the primary chain
  • Advanced caching with custom QueryClient settings
  • SSR support with cookie-based persistence
  • Custom transports or RPC configurations

​
Common Patterns

​
Multi-chain Support

wagmi.ts
import { base, mainnet, optimism } from 'viem/chains';

export function getConfig() {
  return createConfig({
    chains: [base, mainnet, optimism],
    // ... other config
    transports: {
      [base.id]: http(),
      [mainnet.id]: http(),
      [optimism.id]: http(),
    },
  });
}

​
Custom Query Client

providers.tsx
const [queryClient] = useState(() => new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,
    },
  },
}));

​
Environment-specific Configuration

wagmi.ts
const isDevelopment = process.env.NODE_ENV === 'development';

export function getConfig() {
  return createConfig({
    chains: isDevelopment ? [baseSepolia] : [base],
    // ... development vs production settings
  });
}

​
Important Notes

  • Always place custom Wagmi and Query providers outside of OnchainKitProvider
  • OnchainKit components will use your custom Wagmi configuration automatically
  • The chain prop on OnchainKitProvider should match your primary chain
  • Custom configurations require additional setup but provide maximum flexibility