Farcaster Mini App Wagmi Connector
View on GitHubA complete example implementation of @farcaster/miniapp-wagmi-connector that demonstrates secure wallet interactions within Farcaster Mini Apps. Shows how to integrate Ethereum wallet functionality without complex wallet selection dialogs or connection issues.
Table of Contents
Overview
This example demonstrates how to integrate the official Farcaster Mini App Wagmi Connector into your applications, providing seamless wallet interactions without the complexity of traditional Web3 dApp wallet connection flows.
Automatic Wallet Connection
No "select your wallet" dialogs needed - seamless integration with Farcaster Mini App context.
✅ SupportedSingle Transactions
Send ETH with user confirmation preview and transaction scanning for security.
✅ SupportedBatch Transactions (EIP-5792)
Multiple operations in one confirmation with comprehensive transaction previews.
✅ SupportedToken Operations
Approve and transfer ERC-20 tokens with full type safety and error handling.
✅ SupportedWhat This Demonstrates
Automatic Wallet Connection
No "select your wallet" dialogs needed - seamless integration with Farcaster Mini App context.
Single Transactions
Send ETH with user confirmation preview and transaction scanning for security.
Batch Transactions (EIP-5792)
Multiple operations in one confirmation with comprehensive transaction previews.
Token Operations
Approve and transfer ERC-20 tokens with full type safety and error handling.
Security First
All transactions scanned by Blockaid and previewed for users before confirmation.
TypeScript Ready
Full type safety throughout the integration with comprehensive error handling.
Quick Start
Prerequisites
- • Node.js 22.11.0 or higher
- • A Farcaster account for testing
Clone the repository
Get the example repository with all integrations
git clone https://github.com/jumpboxtech/farcaster-miniapp-wagmi-connector cd farcaster-miniapp-wagmi-connector
Install dependencies
Install all required packages and dependencies
npm install # or pnpm install # or yarn install
Start development server
Launches the development server with hot reloading
npm run dev
Test in Farcaster
Expose your local server and test in Farcaster Mini App Preview Tool
# Using ngrok (recommended) npx ngrok http 5173
Architecture
This example uses the official Farcaster Mini App stack for maximum compatibility and security:
@farcaster/miniapp-sdk
LatestCore Mini App functionality and Frame integration
@farcaster/miniapp-wagmi-connector
LatestWagmi integration for wallet connections
Wagmi
v2.xReact hooks for Ethereum interactions
Viem
v2.xTypeScript interface for Ethereum
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
Built-in Security
- Transaction Scanning: All transactions automatically scanned by Blockaid
- User Confirmation: Detailed previews before confirming transactions
- No Private Keys: Your app never handles private keys directly
- Secure Connection: Protection against common Web3 vulnerabilities
Enhanced 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 Errors: Specific error messages and real-time feedback
Supported Networks
Supported Networks
FAQ
Q: Why do I see an infinite loading screen?
Make sure you're calling sdk.actions.ready() after your app loads. This is required to hide the splash screen and show your app content.
Q: Can I use this with other wallet libraries?
While possible, we recommend sticking with Wagmi + the official connector for the best experience and compatibility with Farcaster's ecosystem.
Q: How do I test batch transactions?
The demo includes working examples of batch transactions. They're supported on all EVM chains and allow multiple operations in a single user confirmation.
Q: What about transaction failures?
The example includes comprehensive error handling for failed transactions, with specific error messages and retry functionality where appropriate.
Additional Resources
Production Deployment
For production deployment, you'll need:
- • A proper domain (not a tunnel URL)
- • HTTPS enabled
- • A manifest file at
/.well-known/farcaster.json
Built with ❤️ for the Farcaster ecosystem