Farcaster Mini App Wagmi Connector

A complete example implementation of @farcaster/miniapp-wagmi-connector that demonstrates secure wallet interactions within Farcaster Mini Apps. This example shows how to properly integrate Ethereum wallet functionality without complex wallet selection dialogs or connection issues.

🌟 What This Demonstrates

• ✅ Automatic Wallet Connection: No "select your wallet" dialogs needed
• ✅ Single Transactions: Send ETH with user confirmation preview
• ✅ Batch Transactions (EIP-5792): Multiple operations in one confirmation
• ✅ Token Operations: Approve and transfer ERC-20 tokens
• ✅ Security: All transactions scanned and previewed for users
• ✅ Error Handling: Proper error states and user feedback
• ✅ TypeScript: Full type safety throughout the integration

🏗️ Architecture

This example uses the official Farcaster Mini App stack:

• @farcaster/miniapp-sdk - Core Mini App functionality
• @farcaster/miniapp-wagmi-connector - Wagmi integration for wallets
• Wagmi - React hooks for Ethereum interactions
• Viem - TypeScript interface for Ethereum

🚀 Quick Start

Prerequisites

• Node.js 22.11.0 or higher
• A Farcaster account for testing

Installation

1. Clone the repository

   git clone https://github.com/jumpboxtech/farcaster-miniapp-wagmi-connector
   cd farcaster-miniapp-wagmi-connector

2. Install dependencies

   npm install
   # or
   pnpm install
   # or
   yarn install

3. Start development server

   npm run dev

4. Test in Farcaster

   During development, you'll need to expose your local server:

   # Using ngrok (recommended)
   npx ngrok http 5173

   Then use the ngrok URL in the Farcaster Mini App Preview Tool.

📁 Project Structure

├── src/
│   ├── App.tsx                           # Main app component with providers
│   ├── FarcasterWalletDemo.tsx          # Core wallet demo component
│   ├── EnhancedSecurityWalletDemo.tsx   # Enhanced security version
│   ├── wagmi.config.ts                  # Wagmi configuration
│   └── main.tsx                         # Entry point
├── public/
│   └── .well-known/
│       └── farcaster.json               # Mini App manifest (for production)
└── package.json

🔐 Enhanced Security Version

This repository includes two versions of the wallet demo:

• Basic Version (FarcasterWalletDemo.tsx) - Clean, simple, and secure implementation
• Enhanced Security Version (EnhancedSecurityWalletDemo.tsx) - Additional security features including input validation, rate limiting, and enhanced error handling

To use the enhanced version instead of the basic one, you would update your App.tsx:

// Replace this line:
import { FarcasterWalletDemo } from './FarcasterWalletDemo';

// With this:
import { EnhancedSecurityWalletDemo } from './EnhancedSecurityWalletDemo';

// And update the component in the JSX:
<EnhancedSecurityWalletDemo />

Enhanced Security Features

• ✅ Input Validation: Address format validation and amount bounds checking
• ✅ Rate Limiting: 5-second cooldown between transactions to prevent spam
• ✅ Safety Limits: Maximum transaction amounts and minimum thresholds
• ✅ Enhanced Error Handling: Specific error messages and real-time feedback
• ✅ Input Sanitization: Automatic address formatting and validation

🔧 Implementation Guide

1. Set up Wagmi Configuration

The key to Farcaster Mini App wallet integration is using the official connector:

import { http, createConfig } from 'wagmi';
import { base } from 'wagmi/chains';
import { farcasterMiniApp as miniAppConnector } from '@farcaster/miniapp-wagmi-connector';

export const config = createConfig({
  chains: [base],
  transports: {
    [base.id]: http(),
  },
  connectors: [
    miniAppConnector() // This handles Farcaster wallet connections
  ]
});

2. Wrap Your App with Providers

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

const queryClient = new QueryClient();

export const App = () => (
  <WagmiProvider config={config}>
    <QueryClientProvider client={queryClient}>
      <YourAppContent />
    </QueryClientProvider>
  </WagmiProvider>
);

3. Initialize the Mini App SDK

import { sdk } from '@farcaster/miniapp-sdk';

useEffect(() => {
  const initializeApp = async () => {
    // This hides the splash screen and shows your app
    await sdk.actions.ready();
  };
  initializeApp();
}, []);

4. Handle Wallet Connections

import { useAccount, useConnect } from 'wagmi';

const { isConnected, address } = useAccount();
const { connect, connectors } = useConnect();

// Auto-connect or manual connection
const handleConnect = () => {
  if (connectors[0]) {
    connect({ connector: connectors[0] });
  }
};

5. Send Transactions

Single Transaction:

import { useSendTransaction } from 'wagmi';
import { parseEther } from 'viem';

const { sendTransaction } = useSendTransaction();

const sendEth = () => {
  sendTransaction({
    to: '0x...',
    value: parseEther('0.01')
  });
};

Batch Transactions (EIP-5792):

import { useSendCalls } from 'wagmi';

const { sendCalls } = useSendCalls();

const batchTransactions = () => {
  sendCalls({
    calls: [
      { to: '0x...', value: parseEther('0.01') },
      { to: '0x...', value: parseEther('0.02') }
    ]
  });
};

🔐 Security Features

• Transaction Scanning: All transactions are automatically scanned by Blockaid
• User Confirmation: Users see detailed previews before confirming
• No Private Keys: Your app never handles private keys directly
• Secure Connection: Built-in protection against common Web3 vulnerabilities

🧪 Testing Your Integration

1. Local Development: Use ngrok to expose your local server
2. Preview Tool: Test using Farcaster's preview tool
3. Live Testing: Share your app in Farcaster to test the full user experience

📋 Supported Features

Feature	Status	Description
✅ Wallet Connection	Supported	Automatic connection without wallet selection
✅ Send ETH	Supported	Basic ETH transfers with confirmation
✅ Batch Transactions	Supported	Multiple operations in single confirmation
✅ ERC-20 Operations	Supported	Token transfers, approvals, etc.
✅ Multi-chain	Supported	Base, Mainnet, Optimism, Arbitrum, Polygon
✅ Transaction Status	Supported	Real-time status tracking
✅ Error Handling	Supported	Comprehensive error states

🌐 Supported Networks

• Base (recommended for Farcaster apps)
• Ethereum Mainnet
• Optimism
• Arbitrum
• Polygon

❓ FAQ

Q: Why do I see an infinite loading screen?
A: Make sure you're calling sdk.actions.ready() after your app loads.

Q: Can I use this with other wallet libraries?
A: While possible, we recommend sticking with Wagmi + the official connector for the best experience.

Q: How do I test batch transactions?
A: The demo includes working examples. Batch transactions are supported on all EVM chains.

Q: What about transaction failures?
A: The example includes comprehensive error handling for failed transactions.

🚨 Common Issues

Node.js Version

Make sure you're using Node.js 22.11.0 or higher:

node --version

Tunnel URLs for Testing

During development with ngrok/localtunnel:

1. Visit the tunnel URL directly in your browser first
2. Then use it in the Farcaster preview tool
3. Some SDK actions like addMiniApp() won't work with tunnel domains

Production Deployment

For production, you'll need:

• A proper domain (not a tunnel URL)
• HTTPS enabled
• A manifest file at /.well-known/farcaster.json

📚 Additional Resources

• Farcaster Mini Apps Documentation
• miniapp-wagmi-connector NPM Package
• Wagmi Documentation
• Viem Documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

• Farcaster Developer Chat
• GitHub Issues
• Farcaster Protocol Docs

---

Built with ❤️ for the Farcaster ecosystem