Web3 Integration Assistant

An autonomous agent that integrates Web3 functionality into applications — connecting wallets, reading on-chain data, executing transactions, and handling chain switching across EVM-compatible networks.

When to Use This Agent

Choose Web3 Integration Assistant when:

• You need to add wallet connection (MetaMask, WalletConnect) to a web app
• You want to read on-chain data (balances, NFTs, token holdings) in your frontend
• You need to submit and track blockchain transactions from your application
• You are building a multi-chain application that supports network switching

Consider alternatives when:

• You need to write or audit smart contracts (use a smart contract agent)
• You need backend blockchain infrastructure (use a DevOps agent)
• You are building purely off-chain functionality

Quick Start

Copy
# .claude/agents/web3-integration.yml
name: web3-integration-assistant
description: Integrate Web3 wallet and blockchain functionality
agent_prompt: |
  You are a Web3 Integration Specialist. When integrating Web3:

  1. Set up wallet connection with wagmi/viem or ethers.js
  2. Implement proper chain detection and switching
  3. Handle transaction submission, confirmation, and errors
  4. Read contract data with proper caching and error handling
  5. Support multiple wallets and chains
  6. Implement proper loading and error states for all async operations

  Always handle: wallet not installed, wrong chain, transaction rejected,
  insufficient funds, and network errors gracefully.

Example invocation:

Copy
claude "Add MetaMask and WalletConnect support to our React app with token balance display"

Sample integration code:

Copy
// Wallet connection with wagmi v2
import { createConfig, http } from 'wagmi';
import { mainnet, polygon, arbitrum } from 'wagmi/chains';
import { injected, walletConnect } from 'wagmi/connectors';

export const config = createConfig({
  chains: [mainnet, polygon, arbitrum],
  connectors: [
    injected(),
    walletConnect({ projectId: process.env.WC_PROJECT_ID }),
  ],
  transports: {
    [mainnet.id]: http(),
    [polygon.id]: http(),
    [arbitrum.id]: http(),
  },
});

// Usage in component
function ConnectButton() {
  const { connect, connectors } = useConnect();
  const { address, isConnected } = useAccount();
  const { data: balance } = useBalance({ address });

  if (isConnected) {
    return <div>{balance?.formatted} {balance?.symbol}</div>;
  }

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

Core Concepts

Web3 Integration Architecture

Layer	Technology	Purpose
Wallet	MetaMask, WalletConnect, Coinbase	User authentication + signing
Client	wagmi, viem, ethers.js	Blockchain interaction
Provider	Alchemy, Infura, QuickNode	RPC node access
Indexer	The Graph, Moralis	Historical data queries
State	React Query / SWR	Cache + invalidation

Transaction Lifecycle Management

Copy
import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi';

function MintButton({ tokenId }) {
  const { writeContract, data: hash, isPending, error } = useWriteContract();
  const { isLoading: isConfirming, isSuccess } = useWaitForTransactionReceipt({ hash });

  const handleMint = () => {
    writeContract({
      address: NFT_CONTRACT,
      abi: nftAbi,
      functionName: 'mint',
      args: [tokenId],
      value: parseEther('0.05'),
    });
  };

  return (
    <div>
      <button onClick={handleMint} disabled={isPending || isConfirming}>
        {isPending ? 'Confirm in wallet...' :
         isConfirming ? 'Confirming...' :
         isSuccess ? 'Minted!' : 'Mint NFT'}
      </button>
      {error && <p className="text-red-500">{error.shortMessage || error.message}</p>}
      {hash && <a href={`https://etherscan.io/tx/${hash}`}>View transaction</a>}
    </div>
  );
}

Multi-Chain Configuration

Copy
// Chain-aware contract interaction
const CONTRACT_ADDRESSES = {
  1: '0x...mainnet',      // Ethereum
  137: '0x...polygon',    // Polygon
  42161: '0x...arbitrum',  // Arbitrum
};

function useContract() {
  const { chain } = useNetwork();
  const address = CONTRACT_ADDRESSES[chain?.id];

  if (!address) {
    return { error: 'Contract not deployed on this chain' };
  }

  return useReadContract({
    address,
    abi: contractAbi,
    functionName: 'totalSupply',
  });
}

Configuration

Option	Type	Default	Description
chains	string[]	["ethereum", "polygon"]	Supported chains
wallets	string[]	["metamask", "walletconnect"]	Supported wallets
clientLibrary	string	"wagmi"	Client: wagmi, ethers, web3.js
rpcProvider	string	"alchemy"	RPC provider: alchemy, infura, custom
cacheStrategy	string	"react-query"	Data caching approach
testnetMode	boolean	false	Use testnets by default

Best Practices

1. Always handle the "wallet not installed" case — Do not assume users have MetaMask installed. Detect wallet availability before showing connection buttons, and provide a "Get MetaMask" link for users who need to install it. WalletConnect works without any browser extension and should be offered as an alternative.

2. Show transaction status at every stage — Users need to know: (1) confirm in wallet, (2) transaction submitted (with tx hash link), (3) waiting for confirmation, (4) confirmed or failed. Each stage should have a distinct UI state. Never leave users wondering if their transaction went through.

3. Cache on-chain reads aggressively — Reading from the blockchain costs RPC credits and adds latency. Cache token balances, NFT metadata, and contract state with appropriate TTLs (30s for balances, 5min for metadata). Use wagmi's built-in caching or React Query for manual control.

4. Implement chain switching with clear user guidance — When a user is on the wrong chain, show a prominent banner with a "Switch to Polygon" button that calls wallet_switchEthereumChain. If the chain is not configured in their wallet, handle the wallet_addEthereumChain flow automatically.

5. Use viem or ethers for contract type safety — Generate TypeScript types from your contract ABI so that function names, parameter types, and return types are checked at compile time. This catches errors like passing a string where a BigInt is expected before they reach the blockchain.

Common Issues

Wallet connection state lost on page refresh — The app forgets the connected wallet when the user refreshes the page. Use wagmi's reconnect feature or persist the connection state in localStorage. Configure autoConnect: true in the wagmi config to automatically reconnect to the last used wallet on page load.

Transaction gas estimation fails with unhelpful error — estimateGas throws "execution reverted" without specifying which require statement failed. Call the contract function with eth_call first (simulates execution without sending a transaction) to get the revert reason. Display the decoded revert message to the user.

Token approval flow confuses users — ERC-20 token interactions require a two-step process: approve the spending contract, then execute the transaction. Users do not understand why they need two wallet confirmations. Show a clear two-step UI: "Step 1: Approve spending" → "Step 2: Confirm transaction" with explanations for each step.