🧰 CosmosKit Airdrops

Find unclaimed Cosmos airdrops in 5 seconds.

Check 50+ Cosmos chains for unclaimed airdrops with a single wallet address. Built for the Cosmos community.

✨ Features

• 🔍 Instant Checking - Scan all Cosmos chains in 5 seconds
• 🔒 100% Safe - Read-only access, never asks for private keys
• 💰 Real USD Values - See exactly how much you can claim
• ⚡ Smart Caching - Fast repeated lookups
• 🎯 All Major Chains - Juno, Osmosis, Stargaze, and more

🚀 Quick Start

Prerequisites

• Go 1.21+ (Download)
• Node.js 18+ (Download)
• npm or yarn

Backend Setup

# Navigate to backend
cd backend

# Install Go dependencies
go mod download

# Create environment file
cp .env.example .env

# Run the server
go run main.go

The backend will start on http://localhost:8080

Frontend Setup

# Navigate to frontend (in a new terminal)
cd frontend

# Install dependencies
npm install

# Create environment file
cp .env.local.example .env.local

# Run development server
npm run dev

The frontend will start on http://localhost:3000

📁 Project Structure

cosmoskit-airdrops/
├── backend/                  # Go backend
│   ├── main.go              # Entry point
│   ├── handlers/            # HTTP handlers
│   │   └── airdrop.go
│   ├── models/              # Data models
│   │   └── airdrop.go
│   ├── services/            # Business logic
│   │   ├── checker.go       # Airdrop checking logic
│   │   └── cache.go         # Caching service
│   └── data/
│       └── airdrops.json    # Airdrop registry
│
└── frontend/                # Next.js frontend
    ├── pages/
    │   ├── index.tsx        # Landing page
    │   ├── check.tsx        # Checker page
    │   └── _app.tsx
    ├── components/
    │   ├── WalletConnect.tsx
    │   └── AirdropResults.tsx
    └── styles/
        └── globals.css

🔧 API Reference

Check Wallet for Airdrops

POST /api/check
Content-Type: application/json

{
  "address": "cosmos1..."
}

Response:

{
  "address": "cosmos1...",
  "total_usd": 1250.50,
  "total_airdrops": 3,
  "airdrops": [
    {
      "airdrop_id": "juno-wynd",
      "name": "Wynd Airdrop",
      "chain": "juno",
      "amount": "1000",
      "amount_usd": 500.00,
      "claim_url": "https://app.wynddao.com/airdrop",
      "logo": "https://app.wynddao.com/logo.png",
      "expires_at": "2025-12-31"
    }
  ],
  "cached_at": "2024-01-15T10:30:00Z"
}

List All Airdrops

GET /api/airdrops

Response:

{
  "airdrops": [...],
  "total": 50
}

🌍 Adding New Airdrops

Edit backend/data/airdrops.json:

{
  "id": "chain-name",
  "name": "Airdrop Name",
  "chain": "chain",
  "chain_id": "chain-1",
  "contract_addr": "contract_address",
  "rpc": "grpc.endpoint.com:9090",
  "token_denom": "TOKEN",
  "snapshot_date": "2023-01-01T00:00:00Z",
  "claim_end_date": "2025-12-31T23:59:59Z",
  "status": "active",
  "description": "Description here",
  "website": "https://claim-site.com",
  "logo": "https://logo-url.png"
}

Restart the backend to load new airdrops.

🚀 Deployment

Deploy Backend to Railway

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Initialize and deploy
cd backend
railway init
railway up

# Set environment variables in Railway dashboard
PORT=8080

# Get your backend URL (e.g., https://your-app.up.railway.app)

Deploy Frontend to Vercel

# Install Vercel CLI
npm install -g vercel

# Deploy
cd frontend
vercel

# Set environment variable in Vercel dashboard
NEXT_PUBLIC_API_URL=https://your-backend.up.railway.app

# Deploy to production
vercel --prod

Custom Domain Setup

1. Vercel Dashboard → Settings → Domains → Add your domain
2. DNS Provider → Add CNAME record: @ → cname.vercel-dns.com
3. Wait 10-60 minutes for DNS propagation

🧪 Testing

Test Backend

# Check health
curl http://localhost:8080/health

# Check wallet
curl -X POST http://localhost:8080/api/check \
  -H "Content-Type: application/json" \
  -d '{"address":"cosmos1..."}'

# List airdrops
curl http://localhost:8080/api/airdrops

Test Frontend

1. Visit http://localhost:3000
2. Click "Check Airdrops"
3. Connect Keplr or enter address
4. Verify results display correctly

📊 Tech Stack

Backend

• Go - High-performance backend
• Fiber - Fast web framework
• CosmWasm - Smart contract queries
• gRPC - Blockchain communication

Frontend

• Next.js - React framework
• TypeScript - Type safety
• Tailwind CSS - Styling
• Axios - HTTP requests

🤝 Contributing

Contributions welcome! Here's how:

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

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Cosmos community for inspiration
• Keplr wallet for seamless integration
• All the amazing Cosmos projects

📞 Support

• Twitter: @cosmoskit
• Discord: Join our server
• Issues: GitHub Issues

---

Built with 💜 for the Cosmos ecosystem