🖼️ FarcastMints - NFT Marketplace

A complete NFT marketplace built for the Farcaster ecosystem with MiniKit integration and Base network optimization

🚀 Live Demo • 📖 Documentation • 🎯 Features • 🛠️ Setup

🎯 Features

🖼️ Farcaster Native Experience

• Interactive Frames - Share NFTs directly in Farcaster feeds with purchase buttons
• MiniKit Integration - Seamless wallet connection and social authentication
• Frame Discovery - Browse and test all available NFT frames
• Viral Sharing - One-click sharing to Warpcast and Farcaster clients

🌙 Modern UI/UX

• Dark Mode System - Complete light/dark theme with persistence
• Responsive Design - Perfect experience on mobile and desktop
• Smooth Animations - 60fps transitions with Framer Motion
• Real-time Updates - Live marketplace activity and user counters

⚡ Base Network Optimized

• Gasless Transactions - FREE gas fees sponsored by Base Paymaster (NEW!)
• Smart Accounts - ERC-4337 Account Abstraction for seamless UX
• Low Fees - Leveraging Base L2 for affordable transactions
• Fast Confirmations - Quick NFT purchases and listings
• Wallet Integration - RainbowKit with Base network support
• Chain Validation - Automatic Base network detection and switching

🎮 Advanced Engagement

• Social Proof - Live user counters and trending items
• Activity Feed - Real-time marketplace transactions and interactions
• XMTP Chat - Base App Quick Actions integration
• Progress Tracking - User engagement and achievement system

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Git for version control
• A Farcaster account for testing frames

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/farcaster-nft-marketplace.git
cd farcaster-nft-marketplace

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Start development server
npm run dev

Visit http://localhost:3000 to see the marketplace in action!

Environment Setup

Create a .env.local file with the following variables:

NEXT_PUBLIC_BASE_RPC_URL=https://mainnet.base.org
NEXT_PUBLIC_FARCASTER_HUB_URL=https://nemes.farcaster.xyz:2283
MINIKIT_APP_ID=your-minikit-app-id
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-project-id

🏗️ Tech Stack

Frontend

• Next.js 14 - React framework with App Router
• TypeScript - Type-safe development
• TailwindCSS - Utility-first styling
• Framer Motion - Smooth animations

Web3 Integration

• Wagmi v2 - React hooks for Ethereum
• RainbowKit - Wallet connection UI
• Viem - TypeScript Ethereum library
• Base Network - Ethereum L2 for low fees

Farcaster Ecosystem

• @farcaster/core - Core Farcaster SDK
• @farcaster/hub-nodejs - Hub integration
• Farcaster Frames - Interactive social content
• MiniKit SDK - Native app integration

📁 Project Structure

src/
├── app/
│   ├── page.tsx                 # Main application entry
│   ├── marketplace.tsx          # Core marketplace component  
│   ├── providers.tsx            # Web3 and context providers
│   ├── globals.css              # Global styles + dark mode
│   └── api/
│       ├── frames/              # Farcaster Frame endpoints
│       └── test-frame/          # Frame testing utilities
├── components/
│   ├── Header.tsx              # Navigation with dark mode
│   ├── NFTCard.tsx             # Enhanced NFT display cards
│   ├── DarkModeToggle.tsx      # Theme switching components
│   ├── FrameShare.tsx          # Frame sharing modal
│   ├── SocialProof.tsx         # Activity feed & social widgets
│   ├── GaslessUI.tsx           # Gasless transaction UI components
│   └── ...                     # Additional UI components
├── contexts/
│   └── ThemeContext.tsx        # Dark mode state management
├── hooks/
│   └── useSmartAccount.ts      # Smart Account & gasless transactions
└── lib/
    ├── wagmi.ts                # Web3 configuration
    └── paymaster.ts            # Base Paymaster configuration

✨ Gasless Transactions (NEW!)

Zero gas fees for your users! All transaction costs are sponsored by Base Paymaster.

Quick Setup (5 minutes)

1. Get Paymaster RPC URL

   • Visit Coinbase Developer Platform
   • Go to Paymaster → Configuration
   • Copy your RPC URL

2. Add to Environment

   # .env.local
   NEXT_PUBLIC_PAYMASTER_RPC_URL=https://api.developer.coinbase.com/rpc/v1/base/YOUR_KEY

3. Configure Allowlist

   • Add your NFT contract address in CDP
   • Allowlist functions: mintTo, buy, list

4. Set Spending Limits

   • Per-user: $0.05/month, 1 operation
   • Global: $15,000/month (or your budget)

5. Done! 🎉 Users can now mint, buy, and list NFTs completely free.

📖 Full Guide: GASLESS_QUICKSTART.md
📚 Documentation: GASLESS_TRANSACTIONS.md
📝 Implementation: GASLESS_IMPLEMENTATION_SUMMARY.md

🌐 API Endpoints

Farcaster Frames

• GET /api/frames - Frame discovery page
• GET /api/frames/nft/[tokenId] - Interactive NFT frame
• GET /api/frames/nft/[tokenId]/image - Dynamic frame image
• GET /api/test-frame - Frame testing endpoint

Features Available

• Browse NFTs - Complete marketplace interface
• Dark Mode - Toggle in header (moon/sun icon)
• Frame Sharing - Click "Share Frame" on NFT cards
• Live Activity - Real-time marketplace updates
• Wallet Connect - RainbowKit integration

🎨 Screenshots

Light Mode

Dark Mode

Farcaster Frame

🧪 Testing Frames

Local Testing

# Start the development server
npm run dev

# Test frame endpoints
curl http://localhost:3000/api/frames/nft/1
curl http://localhost:3000/api/frames/nft/1/image

Farcaster Integration

1. Share frame URL in a Farcaster cast
2. View in Warpcast or other Farcaster clients
3. Test interactive buttons and purchasing flow

🚀 Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Configure environment variables in Vercel dashboard
# Set up custom domain and SSL

Manual Deployment

# Build for production
npm run build

# Start production server  
npm start

See DEPLOYMENT_CHECKLIST.md for complete deployment guide.

📖 Documentation

• Implementation Summary - Complete feature overview
• Dark Mode Guide - Theme system documentation
• Activity Feed Guide - Real-time updates system
• Deployment Checklist - Production deployment
• Project Snapshot - Current status and features

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

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

Code Standards

• TypeScript for type safety
• ESLint + Prettier for code formatting
• Conventional commits for commit messages
• Component documentation with JSDoc

🐛 Issues & Support

• Bug Reports: Create an issue
• Feature Requests: Request a feature
• Documentation: Check our docs folder
• Community: Join our Farcaster channel

🎯 Roadmap

✅ Completed (v1.0)

• Complete marketplace interface with dark mode
• Farcaster Frame integration with sharing
• Real-time activity feed with emoji avatars
• Base network integration with wallet support
• XMTP chat and Base App Quick Actions

🚧 In Progress (v1.1)

• NFT creation and minting flow
• Smart contract integration for real transactions
• User authentication with Farcaster profiles
• WebSocket real-time updates

🔮 Future (v2.0)

• Multi-chain support (Ethereum, Polygon)
• Advanced filtering and search
• Auction and bidding system
• Creator royalties and revenue sharing
• Mobile app with MiniKit

📄 License

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

🙏 Acknowledgments

• Farcaster for the decentralized social protocol
• Base for the fast, low-cost L2 network
• Coinbase for MiniKit and developer tools
• Vercel for excellent Next.js hosting
• Community contributors and testers

🌟 Star History

---

Built with ❤️ for the Farcaster and Base ecosystem

🐦 Follow Updates • 🌐 Website • 📧 Contact