CoinPay 🚀

A non-custodial cryptocurrency payment gateway for e-commerce that enables merchants to accept crypto payments with automatic fee handling and real-time transaction monitoring.

🌟 Features

Core Payment Features

• Multi-Chain Support: Bitcoin, Bitcoin Cash, Ethereum, Polygon, Solana, and USDC across major blockchains
• Non-Custodial: Merchants maintain full control of their funds
• Real-Time Processing: Instant payment detection and forwarding (no batching)
• Automatic Fee Handling: 0.5% platform fee automatically deducted during forwarding
• Multi-Business Support: Manage multiple businesses under one merchant account
• Wallet Integration: Connect MetaMask, WalletConnect, or Phantom wallet
• QR Code Payments: Easy-to-integrate payment QR codes
• Webhook Notifications: Real-time payment callbacks for your system
• CLI & SDK: Command-line interface and ESM module for programmatic integration
• Exchange Rates: Real-time crypto/fiat rates via Tatum API

Escrow Service

• On-Chain Escrow: Trustless buyer-seller escrow with automatic settlement
• Multi-Chain: Escrow support across BTC, ETH, POL, SOL
• Auto-Refund: Expired funded escrows automatically refunded on-chain
• Event Logging: Full escrow lifecycle audit trail

DID Reputation Protocol (CPTL)

• Decentralized Identifiers: Claim a did:web:coinpayportal.com:merchant:<id> tied to your merchant account
• 7-Dimension Trust Vectors: Economic, Productivity, Behavioral, Delivery, Reliability, Accountability, Compliance scores
• ActionReceipt Schema: Cryptographically signed receipts from escrow settlements and platform actions
• Cross-Platform Portability: Reputation travels with your DID across integrated platforms
• Embeddable Badges: SVG trust badges for external sites (/api/reputation/badge/[did])
• Platform Action API: Lightweight endpoint for external platforms to submit reputation signals
• Diminishing Returns + Recency Decay: Anti-gaming math with 90-day half-life
• SDK + CLI: Full programmatic access — submitActionReceipt(), getTrustProfile(), coinpay reputation profile <did>

Subscription Plans & Entitlements

• Starter Plan (Free): Up to 100 transactions/month, all supported chains, basic API access, email support
• Professional Plan ($49/month): Unlimited transactions, priority support, advanced analytics, custom webhooks, white-label option
• Crypto Payments for Subscriptions: Pay for upgrades using BTC, BCH, ETH, POL, or SOL
• Usage Tracking: Real-time transaction counting with automatic limit enforcement
• Feature Gating: API-level enforcement of plan-specific features

Business Collection

• Platform Payments: Collect subscription fees and service charges from businesses
• 100% Forwarding: Business collection payments forward entirely to platform wallets
• Multiple Blockchains: Support for BTC, BCH, ETH, POL, SOL

Payment UX

• QR Codes: BIP21/EIP-681/Solana Pay URI-encoded QR codes for one-tap wallet opens
• Copy Buttons: One-click copy for addresses and amounts with success states
• Progress Indicator: 4-step visual flow (Copy → Send → Confirming → Done)
• Countdown Timer: Expiry countdown with red pulse warning at <5 minutes

🏗️ Architecture

CoinPay uses a modern, scalable architecture:

• Frontend: Next.js 14+ with TypeScript and TailwindCSS
• Backend: Next.js API Routes (serverless)
• Database: Supabase (PostgreSQL)
• Blockchain: Self-hosted wallet generation with RPC provider monitoring
• Testing: Vitest for unit and integration tests

See Architecture Documentation for detailed system design.

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm/yarn/pnpm
• Supabase account (free tier available)
• RPC provider accounts (Alchemy, Infura, or public nodes)
• Tatum API key (for exchange rates)

Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Copy environment variables:

cp .env.example .env.local

4. Configure your .env.local file with required credentials:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Encryption
ENCRYPTION_KEY=your_32_byte_encryption_key

# RPC Providers
BITCOIN_RPC_URL=https://your-bitcoin-rpc
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# Platform Fee Wallets
PLATFORM_FEE_WALLET_BTC=your_btc_address
PLATFORM_FEE_WALLET_ETH=your_eth_address
PLATFORM_FEE_WALLET_POL=your_pol_address
PLATFORM_FEE_WALLET_SOL=your_sol_address

# Tatum API
TATUM_API_KEY=your_tatum_api_key

# Webhook
WEBHOOK_SIGNING_SECRET=your_webhook_secret

5. Set up the database:

npm run db:setup

6. Run the development server:

npm run dev

7. Open http://localhost:3000 in your browser.

📖 Documentation

• Architecture Overview
• API Documentation
• Database Schema
• Subscriptions & Entitlements
• Business Collection
• Security Best Practices
• CPTL v2 PRD — Reputation protocol design document
• Platform Integration Guide — Integrate your platform with CPTL reputation

💻 Usage Examples

Creating a Payment Request (API)

const response = await fetch('/api/payments/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    businessId: 'your-business-id',
    amount: 100.00,
    currency: 'USD',
    blockchain: 'eth',
    merchantWalletAddress: '0x...',
    metadata: {
      orderId: 'ORDER-123',
      customerEmail: 'customer@example.com'
    }
  })
});

const payment = await response.json();
// Returns: { id, address, qrCode, amount, expiresAt }

Using the CLI

# Create a payment
coinpay payment create \
  --business-id abc123 \
  --amount 100 \
  --currency USD \
  --blockchain eth \
  --wallet 0x...

# Check payment status
coinpay payment status --id payment_xyz

# List businesses
coinpay business list

# Configure webhook
coinpay webhook set --url https://yoursite.com/webhook

Using the SDK

import { CoinPay } from '@coinpayportal/sdk';

const client = new CoinPay({
  apiKey: 'your-api-key',
  environment: 'production'
});

// Create payment
const payment = await client.payments.create({
  businessId: 'your-business-id',
  amount: 100,
  currency: 'USD',
  blockchain: 'eth',
  merchantWalletAddress: '0x...'
});

// Monitor payment
client.payments.on('confirmed', (payment) => {
  console.log('Payment confirmed:', payment.id);
});

Embedding Payment QR Code

<!-- Simple integration -->
<div id="coinpay-widget"
     data-business-id="your-business-id"
     data-amount="100"
     data-currency="USD"
     data-blockchain="eth">
</div>
<script src="https://coinpayportal.com/widget.js"></script>

🔐 Security

• Private keys are encrypted at rest using AES-256
• All API routes require authentication
• Rate limiting on all endpoints
• Webhook signatures for verification
• Multi-confirmation requirements before forwarding
• See Security Documentation for details

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run E2E tests
npm run test:e2e

📦 Project Structure

coinpayportal/
├── docs/                    # Documentation
│   ├── ARCHITECTURE.md
│   ├── API.md
│   ├── DATABASE.md
│   ├── SUBSCRIPTIONS.md    # Subscription plans & entitlements
│   ├── BUSINESS_COLLECTION.md
│   └── SECURITY.md
├── src/
│   ├── app/                # Next.js app directory
│   │   ├── api/           # API routes
│   │   │   ├── auth/      # Authentication endpoints
│   │   │   ├── payments/  # Payment endpoints
│   │   │   ├── businesses/ # Business management
│   │   │   ├── business-collection/ # Platform payments
│   │   │   ├── escrow/    # Escrow endpoints
│   │   │   ├── reputation/ # DID & trust endpoints
│   │   │   ├── subscriptions/ # Subscription management
│   │   │   └── entitlements/ # Entitlements API
│   │   ├── dashboard/     # Merchant dashboard
│   │   ├── pricing/       # Pricing & upgrade page
│   │   ├── reputation/   # DID claim & trust profile pages
│   │   ├── docs/          # API documentation page
│   │   └── page.tsx       # Landing page
│   ├── components/        # React components
│   │   ├── business/      # Business management components
│   │   └── docs/          # Documentation components
│   ├── lib/              # Utility libraries
│   │   ├── auth/         # Authentication services
│   │   ├── blockchain/   # Blockchain services
│   │   ├── business/     # Business services
│   │   ├── entitlements/ # Entitlements & usage tracking
│   │   ├── payments/     # Payment processing & monitoring
│   │   ├── reputation/   # Trust engine, receipts, DID management
│   │   ├── subscriptions/ # Subscription management
│   │   ├── supabase/     # Supabase client
│   │   └── crypto/       # Encryption utilities
│   └── types/            # TypeScript types
├── supabase/
│   └── migrations/       # Database migrations
├── packages/
│   └── sdk/              # SDK + CLI package (@profullstack/coinpay)
│       ├── src/          # SDK source (payments, reputation, DID)
│       └── bin/          # CLI entry point
└── package.json

🛣️ Roadmap

• Core payment processing
• Multi-chain support (BTC, BCH, ETH, POL, SOL, USDC)
• Merchant dashboard
• Webhook system
• Subscription plans (Starter/Professional)
• Entitlements & usage tracking
• Business collection payments
• Crypto-based subscription payments
• On-chain escrow with auto-refund
• Password reset flow
• Payment UX — QR codes, copy buttons, progress indicator, countdown
• DID Reputation Protocol (CPTL Phase 1) — ActionReceipts, trust vectors, badges
• CPTL Phase 2 — Advanced trust math, diminishing returns, recency decay
• Platform Action API — external platform reputation signals
• CLI & SDK — full reputation, DID, and escrow commands
• CPTL Phase 3 — Anti-collusion engine (graph clustering, burst detection) (coming soon)
• CPTL Phase 4 — ZK proofs, cross-chain anchoring, slashing bonds (future)
• Mobile SDK
• WooCommerce plugin
• Shopify app
• Recurring payments (auto-renewal)
• Fiat off-ramp
• Advanced analytics dashboard

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

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

🆘 Support

• Documentation: coinpayportal.com/docs
• Email: support@coinpayportal.com
• Discord: Join our community
• GitHub Issues: Report a bug

🙏 Acknowledgments

• Next.js - React framework
• Supabase - Backend as a service
• Tatum - Blockchain API and exchange rates
• Alchemy - Blockchain infrastructure
• WalletConnect - Wallet connection protocol

---

Built with ❤️ by Profullstack Inc