Minto - B2B Token Airdrop Platform on Aptos

Enterprise-grade token distribution platform powered by Aptos blockchain

Demo • Documentation • Report Bug

🚀 Overview

Minto is a comprehensive B2B platform that enables Web3 companies to create, manage, and distribute token airdrops efficiently on the Aptos blockchain. Built with modern technologies and best practices, it provides an enterprise-grade solution for token distribution campaigns.

✨ Key Features

• 🔐 Multiple Authentication Methods

  • Google OAuth (Keyless authentication)
  • Wallet connection (Petra, Martian, Pontem)
  • Email/password (coming soon)

• 📊 Campaign Management Dashboard

  • Create and configure airdrop campaigns
  • Real-time analytics and reporting
  • Participant tracking and eligibility management
  • Multi-step campaign creation wizard

• 🎯 Distribution Methods

  • First-Come-First-Serve (FCFS)
  • Lottery system
  • Equal distribution
  • Tiered access
  • Dutch auction
  • Engagement-based rewards

• ✅ Eligibility Criteria

  • Open to all
  • Whitelist-based
  • NFT holder verification
  • Token holder requirements
  • Custom criteria

• 💰 Cost Advantages

  • 100x cheaper gas fees vs Ethereum
  • Sub-second transaction finality
  • Parallel execution engine
  • Minimal infrastructure costs

🏗️ Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Landing   │      │   Frontend   │      │   Backend   │
│   (React)   │ ───▶ │  Dashboard   │ ◀──▶ │  (FastAPI)  │
│             │      │   (React)    │      │             │
└─────────────┘      └──────┬───────┘      └──────┬──────┘
                            │                     │
                            │                     │
                            ▼                     ▼
                     ┌──────────────────────────────┐
                     │     Aptos Blockchain         │
                     │   (Smart Contracts - Move)   │
                     └──────────────────────────────┘

Tech Stack

Frontend

• React 18 + TypeScript
• Vite (Build tool)
• Mantine UI v7 (Component library)
• Zustand (State management)
• React Query (Data fetching)
• Aptos TypeScript SDK
• React Router v6

Backend

• FastAPI (Python 3.11+)
• SQLAlchemy + Alembic (ORM & Migrations)
• PostgreSQL (Database)
• Pydantic (Validation)
• python-jose (JWT)
• Aptos Python SDK

Blockchain

• Move language (Smart contracts)
• Aptos blockchain
• Aptos CLI

📁 Project Structure

minto/
├── backend/              # FastAPI backend API
│   ├── app/
│   │   ├── models/      # SQLAlchemy database models
│   │   ├── schemas/     # Pydantic schemas
│   │   ├── routers/     # API endpoints
│   │   ├── services/    # Business logic
│   │   └── main.py      # FastAPI app entry
│   ├── alembic/         # Database migrations
│   └── requirements.txt
│
├── frontend/            # React dashboard application
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── pages/       # Page components
│   │   ├── hooks/       # Custom React hooks
│   │   ├── services/    # API & blockchain services
│   │   ├── store/       # Zustand stores
│   │   ├── types/       # TypeScript types
│   │   └── utils/       # Utility functions
│   └── package.json
│
├── landing/             # Marketing landing page (TODO)
│   └── ...
│
├── contracts/           # Move smart contracts (TODO)
│   ├── sources/
│   │   └── campaign.move
│   ├── Move.toml
│   └── scripts/
│
└── IMPLEMENTATION_GUIDE.md  # Detailed implementation guide

🚀 Quick Start

Prerequisites

• Node.js 18+ and pnpm
• Python 3.11+
• PostgreSQL 14+
• Aptos CLI (Installation guide)

1. Clone the Repository

git clone https://github.com/yourusername/minto.git
cd minto

2. Set Up Backend

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

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

# Create database
createdb minto

# Run migrations
alembic upgrade head

# Start server
uvicorn app.main:app --reload

Backend runs on http://localhost:8000

API docs available at http://localhost:8000/docs

3. Set Up Frontend

cd frontend

# Install dependencies
pnpm install

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

# Start development server
pnpm dev

Frontend runs on http://localhost:5173

4. Set Up Smart Contracts (Coming Soon)

cd contracts

# Compile contracts
aptos move compile

# Run tests
aptos move test

# Deploy to devnet
aptos move publish --profile devnet

🔧 Configuration

Backend Environment Variables

DATABASE_URL=postgresql://user:password@localhost:5432/minto
SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24
APTOS_NETWORK=devnet
APTOS_NODE_URL=https://fullnode.devnet.aptoslabs.com/v1
APTOS_PRIVATE_KEY=0x...
ALLOWED_ORIGINS=http://localhost:5173
DEBUG=True

Frontend Environment Variables

VITE_APTOS_NETWORK=devnet
VITE_APTOS_NODE_URL=https://fullnode.devnet.aptoslabs.com/v1
VITE_API_BASE_URL=http://localhost:8000
VITE_CONTRACT_ADDRESS=0x...
VITE_GOOGLE_CLIENT_ID=your-google-oauth-client-id

📚 API Documentation

Authentication

POST /auth/login

Login with wallet or Google OAuth

Request (Google Keyless):

{
  "provider": "google",
  "id_token": "eyJhbGc..."
}

Request (Wallet):

{
  "provider": "wallet",
  "wallet_address": "0x1234...",
  "signature": "0xabcd...",
  "message": "Sign this message..."
}

Response:

{
  "user": {
    "id": "uuid",
    "wallet_address": "0x...",
    "email": "user@example.com",
    "role": "user"
  },
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 3600
}

Campaigns

GET /campaigns

List all campaigns with pagination

Query Parameters:

• skip (int): Offset for pagination
• limit (int): Number of items (max 100)
• status (string): Filter by status (draft/live/ended/paused)

POST /campaigns

Create new campaign (requires company role)

Request:

{
  "name": "Summer Token Airdrop",
  "token_address": "0x1::aptos_coin::AptosCoin",
  "total_supply": 1000000,
  "amount_per_claim": 100,
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-12-31T23:59:59Z",
  "eligibility_type": "open",
  "distribution_type": "fixed",
  "max_claims_per_wallet": 1
}

Claims

POST /claims/check-eligibility

Check if wallet is eligible to claim

Request:

{
  "campaign_id": "uuid",
  "wallet_address": "0x..."
}

Response:

{
  "is_eligible": true,
  "max_claimable_amount": 100,
  "remaining_claims": 1
}

POST /claims

Create new claim

See full API documentation at /docs when running the backend.

🎨 Design System

Colors

• Primary Green: #10b981
• Accent Emerald: #059669
• Background: #ffffff (light) / #000000 (dark)
• Sidebar: #0a0a0a (light) / #064e3b (dark)

Typography

• Font: Inter (400, 500, 600, 700)
• Scaling: Fluid with clamp()
• Numbers: Tabular numerals for data

Spacing

• Grid: 8px base unit
• Values: 8, 16, 24, 32, 48, 64px

Components

• Cards: 8px border radius
• Buttons: 6px border radius
• Modals: 12px border radius
• Inputs: 4px border radius

🔐 Security Features

• JWT Authentication with refresh tokens
• Wallet signature verification
• Google OAuth integration
• CORS protection
• SQL injection prevention (SQLAlchemy ORM)
• XSS protection (Input sanitization)
• Rate limiting (TODO)
• HTTPS enforcement (production)

🧪 Testing

Backend Tests

cd backend
pytest

Frontend Tests (TODO)

cd frontend
pnpm test

Smart Contract Tests (TODO)

cd contracts
aptos move test

📊 Database Schema

Users Table

users (
  id UUID PRIMARY KEY,
  wallet_address VARCHAR UNIQUE,
  email VARCHAR UNIQUE,
  display_name VARCHAR,
  avatar_url VARCHAR,
  role VARCHAR,  -- user, company, admin
  auth_provider VARCHAR,  -- wallet, google, apple, twitter
  is_verified BOOLEAN,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

Campaigns Table

campaigns (
  id UUID PRIMARY KEY,
  creator_id UUID REFERENCES users(id),
  name VARCHAR(100),
  contract_address VARCHAR,
  token_address VARCHAR,
  total_supply INTEGER,
  claimed_supply INTEGER,
  amount_per_claim INTEGER,
  start_time TIMESTAMP,
  end_time TIMESTAMP,
  eligibility_type VARCHAR,
  distribution_type VARCHAR,
  status VARCHAR,  -- draft, live, ended, paused
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

Claims Table

claims (
  id UUID PRIMARY KEY,
  campaign_id UUID REFERENCES campaigns(id),
  user_wallet VARCHAR,
  amount INTEGER,
  tx_hash VARCHAR UNIQUE,
  status VARCHAR,  -- pending, processing, completed, failed
  claimed_at TIMESTAMP,
  processed_at TIMESTAMP
)

🚢 Deployment

Backend (Railway / Render / Fly.io)

1. Create PostgreSQL database
2. Set environment variables
3. Deploy with: uvicorn app.main:app --host 0.0.0.0 --port $PORT
4. Run migrations: alembic upgrade head

Frontend (Vercel / Netlify)

1. Build command: pnpm build
2. Output directory: dist
3. Set environment variables (VITE_*)
4. Configure SPA fallback routing

Smart Contracts (Aptos Mainnet)

1. Compile: aptos move compile
2. Test: aptos move test
3. Deploy: aptos move publish --profile mainnet

🛣️ Roadmap

• Backend API with FastAPI
• Google Keyless authentication
• Frontend dashboard with Mantine
• Campaign CRUD operations
• Complete campaign creation wizard
• Smart contract implementation
• Landing page
• NFT-gated airdrops
• Multi-token support
• Analytics dashboard
• Email notifications
• Webhook integrations
• Mobile app

🤝 Contributing

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

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

📄 License

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

🙏 Acknowledgments

• Aptos Labs for the blockchain infrastructure
• Mantine for the amazing UI components
• FastAPI for the backend framework

📞 Contact

• Website: https://minto.xyz
• Twitter: @minto
• Discord: Join our server
• Email: support@minto.xyz

---

Built with ❤️ for the Aptos ecosystem

⬆ back to top