cryptomeacoffee

v1.1.0

Published

9 months ago

Open-source, self-hosted donation widget for accepting cryptocurrency donations via x402 protocol. Zero fees, direct to wallet.

0High
0Medium
0Low

pedronacif

crypto cryptocurrency donations x402 usdc base base-network web3 ethereum payment widget viem self-hosted zero-fees buymeacoffee kofi

☕ CryptoMeACoffee

Accept USDC donations on your website via x402 protocol. Zero fees, self-hosted, fully open-source.

✨ Features

✅ Zero Platform Fees - Direct wallet-to-wallet via USDC
✅ Self-Hosted - You control everything
✅ Gasless for Users - x402 protocol sponsors gas fees
✅ Instant Settlement - Funds arrive immediately
✅ Buy Me a Coffee Style - Floating widget with modern UX
✅ Easy Integration - One script tag or npm install
✅ Message Support - Supporters can include messages (500 chars)

🚀 Quick Start

Via CDN (Easiest - No Build Required)

Add this to your HTML:

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="https://unpkg.com/cryptomeacoffee@1/src/styles.css" />
  </head>
  <body>
    <!-- Auto-initialization from script tag data attributes -->
    <script
      src="https://unpkg.com/cryptomeacoffee@1/dist/widget.umd.js"
      data-wallet="0xYourWalletAddress"
      data-api="https://your-api.com/api/donate"
      data-creator-name="Your Name"
      data-color="#5F7FFF"
    ></script>
  </body>
</html>

Via NPM

npm install cryptomeacoffee

import CryptoMeACoffee from 'cryptomeacoffee';
import 'cryptomeacoffee/styles.css';

const widget = new CryptoMeACoffee({
  walletAddress: '0xYourAddress',
  apiEndpoint: 'https://your-api.com/api/donate',
  creatorName: 'Your Name',
});

widget.render('donation-widget');

⚙️ Configuration

Auto-Initialization (Recommended)

The widget auto-initializes from script tag data attributes:

<script
  src="https://unpkg.com/cryptomeacoffee@1/dist/widget.umd.js"
  data-wallet="0xYourWalletAddress"           <!-- Required -->
  data-api="https://your-api.com/api/donate"  <!-- Required -->
  data-creator-name="Your Name"               <!-- Optional -->
  data-color="#5F7FFF"                        <!-- Optional -->
  data-position="Right"                       <!-- Optional: Left/Right -->
  data-margin-x="18"                          <!-- Optional: pixels -->
  data-margin-y="18">                         <!-- Optional: pixels -->
</script>

Manual Initialization

const widget = new CryptoMeACoffee({
  // Required
  walletAddress: '0x...', // Your wallet address
  apiEndpoint: 'https://...', // Your x402 server endpoint

  // Optional
  creatorName: 'Your Name', // Shown in modal header
  presetAmounts: [1, 3, 5], // Preset donation amounts (USD)
  theme: 'light', // 'light' or 'dark'
  network: 'base-sepolia', // 'base-sepolia' or 'base'
  color: '#5F7FFF', // Primary color
  position: 'Right', // 'Left' or 'Right'
  marginX: 18, // Horizontal margin (px)
  marginY: 18, // Vertical margin (px)
  minAmount: 0.01, // Minimum donation (USD)
  maxAmount: 1000, // Maximum donation (USD)
});

🖥️ Server Setup Required

This widget requires a backend server running x402-express middleware. Choose your deployment method:

Option 1: Vercel (Serverless - Easiest) ⚡

Perfect for low-medium traffic, zero server management:

# Clone and deploy
git clone https://github.com/LazaroNacif/cryptomeacoffee
cd server-examples/vercel
cp .env.example .env
# Edit .env with your WALLET_ADDRESS
npm install
vercel deploy

Benefits:

Deploy in 60 seconds
Free tier: 100k requests/month
Auto-scaling
No server maintenance

See: server-examples/vercel/README.md

Option 2: Netlify (Serverless Alternative) 🌊

Similar to Vercel with excellent Git integration:

# Clone and deploy
git clone https://github.com/LazaroNacif/cryptomeacoffee
cd server-examples/netlify
cp .env.example .env
# Edit .env with your WALLET_ADDRESS
npm install
netlify deploy

Benefits:

Deploy in 60 seconds
Free tier: 125k requests/month
Deploy previews for PRs
Excellent Git workflow

See: server-examples/netlify/README.md

Option 3: Express (Traditional Server) 🖥️

Full control, best for high traffic or custom requirements:

# Clone repository
git clone https://github.com/LazaroNacif/cryptomeacoffee
cd server-examples/express

# Configure environment
cp .env.example .env
# Edit .env with your WALLET_ADDRESS

# Install and run
npm install
npm start

Deploy to: Railway, Render, Fly.io, VPS

See: server-examples/express/README.md

📊 Deployment Comparison

| Feature | Vercel | Netlify | Express | | --------------- | -------------- | -------------- | ------------ | | Setup Time | 1 min | 1 min | 5 min | | Free Tier | 100k req/month | 125k req/month | N/A | | Cold Starts | ~500ms | ~500ms | None | | Max Timeout | 10s (60s Pro) | 10s (26s Pro) | Unlimited | | Scaling | Automatic | Automatic | Manual | | Best For | Quick deploys | Git workflows | High traffic | | Cost (idle) | $0 | $0 | Server cost |

📖 Documentation

Comprehensive guides available in the docs/ directory:

Setup Guide - Complete installation and configuration
API Reference - All widget options and methods
Security Checklist - Pre-launch security validation
FAQ - Frequently asked questions (20+ Q&A)
Customization - Themes, colors, and styling
Vercel Deployment - Serverless deployment guide
Server Examples - Vercel, Netlify, Express templates

🌐 Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Mobile browsers (iOS Safari, Chrome Android)

Requires: MetaMask or Coinbase Wallet browser extension

🏗️ Technical Stack

Frontend: Viem for wallet interaction
Backend: x402-express official middleware
Protocol: x402 (gasless USDC transfers)
Network: Base (Ethereum L2)
Token: USDC

📦 Bundle Size

UMD Bundle: 459 KB (133 KB gzipped)
Includes: viem + x402 client library (no external dependencies)

📁 Project Structure

cryptomeacoffee/
├── src/                  # Source code
│   ├── widget.js         # Main widget class
│   ├── logger.js         # Environment-aware logging
│   └── styles.css        # Widget styles
├── dist/                 # Build output (generated)
│   ├── widget.umd.js     # UMD bundle for CDN
│   ├── widget.es.js      # ES module bundle
│   └── widget.d.ts       # TypeScript definitions
├── tests/                # Test files
│   ├── unit/            # Unit tests (46 tests, 31% coverage)
│   └── integration/     # Integration tests
├── docs/                 # Documentation
│   ├── SETUP-GUIDE.md   # Complete setup instructions
│   ├── API-REFERENCE.md # Full API documentation
│   ├── SECURITY-CHECKLIST.md
│   ├── FAQ.md           # Frequently asked questions
│   └── CUSTOMIZATION.md # Theming and styling
├── examples/            # Usage examples
│   ├── vanilla-html/    # Pure HTML/JS example
│   └── server-examples/ # Backend implementations
│       └── express/     # Express.js server
├── CHANGELOG.md         # Version history
└── CONTRIBUTING.md      # Contribution guidelines

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

Setting up development environment
Code style guidelines
Testing requirements
Pull request process

See also: CHANGELOG.md for version history.

📄 License

MIT - See LICENSE file

🔗 Links

💬 Support

Built with ❤️ using the x402 protocol